bitterblossom

name

bitterblossom

description

Operate Bitterblossom's `bb` event-plane CLI for agent workloads. Use when Codex needs to inspect or run `bb`, configure `plane.toml`, `agents/`, or `tasks/`, dispatch or audit tasks, handle runs, dead letters, recovery, parked tasks, submissions, gates, review-factory workflows, or help another repo consume Bitterblossom. Trigger phrases: "Bitterblossom", "bb", "event plane", "agent workload", "run a task", "inspect runs", "DLQ", "parked task", "submission loop", "review factory".

Bitterblossom

Operate the event plane. Do not move workload judgment into the plane.

Bitterblossom is bb: tasks + agents + triggers as files, with a durable run ledger, budgets, retries, dead letters, and optional webhook/cron serving. Agents are CLI users, so prefer stable --json surfaces over prose parsing. When working in the Bitterblossom source checkout, read VISION.md for the runtime-vs-workload boundary before adding or reshaping tasks.

Stance

• Treat bb as runtime and ledger, not an agent brain.
• Workloads are config: plane.toml, agents/<name>.toml, tasks/<name>/task.toml, and tasks/<name>/card.md.
• New workload behavior should be a task/card/agent change, not a Rust branch.
• Use --config <plane> explicitly unless the user has set BB_PLANE_DIR.
• Use --json for agent-readable output. Text is for humans.
• Human-mode bb run prints an early run id and periodic stderr heartbeats; bb run --json stays quiet until it emits the final run bundle.
• If bb is not on PATH, use cargo run --quiet -- from the source repo or ./target/debug/bb after cargo build.

First Probe

Run these before changing or dispatching anything:

bb --config <plane> check
bb --config <plane> task list --json
bb --config <plane> runs list --json

Read the output for:

• loaded tasks and agent versions;
• parked tasks and budget ceilings;
• recent failures, dead letters, in-flight cap kills, and costs;
• whether a task is reflex (webhook/cron) or dispatch (manual).

Authority And Readiness

Classify the run before dispatch. Mode B work belongs in Bitterblossom, but the allowed authority depends on trigger source, auth class, and task policy.

Mode	Allowed	Refuse	Readiness
Supervised dispatch	Operator-initiated bb run/submission work with the task's declared side effects; subscription-auth builders only when the task is manual and the operator asked for that authority.	Hidden cron/webhook dispatch, unbounded continuation, merge/deploy/recovery authority not named by the task or operator.	bb --config <plane> check; bb --config <plane> task list --json; bb --config <plane> preflight <task> --json; bb --config <plane> status --json.
Unsupervised reflex	Webhook/cron API-auth work inside declared repo/org filters, budgets, required artifacts, authority, and side-effect policy.	Subscription auth, broad repo discovery, secret values in payloads, merge/deploy/run-resolution authority, or any action beyond the task card.	bb --config <plane> check; inspect task policy and budget in task list --json; run preflight; inspect status --json, dlq list --json, and notify list --json.
Read-only inspection	MCP/CLI/API reads for status, config, runs, gates, dead letters, and artifacts.	Any tools/call mutation, dispatch, replay, resolve, park/unpark, submit, merge, or credential provisioning over MCP.	Prefer MCP tools when available; fall back to bb ... --json; use bb_artifacts_list/bb_artifact_read or bb artifacts list/read for evidence.

A closeout receipt is incomplete until it names the exact command/surface used, run id or submission id, ledger state, cost/budget status, side effects, artifact reads via MCP or bb artifacts list/read, and residual risk.

Rollout Scorecards

Autonomous task families ship at less than full authority (read-only, report-only, dry-run, PR-only) and climb an authority ladder only on evidence. The single reusable scorecard template and promotion doctrine live in docs/rollout-scorecards.md. When a task declares [rollout] in task.toml, inspect bb --config <plane> status --json or bb --config <plane> task list --json for rollout.authority and rollout.scorecard; this field is visibility metadata, not permission to promote.

Refuse autonomy expansion from vibes. Do not recommend or take a higher authority action (open a branch/PR, merge, deploy, resolve, unpark) for a task family unless that level's scorecard is green and an operator has approved the promotion. "It has been working" is not evidence; the scorecard is. Green metrics only make the next-level ticket eligible for explicit operator approval; they never flip authority by themselves. Merge, unpark, production mutation, and broad rollout stay operator authority until a scorecard plus an operator decision says otherwise.

Route

Need	Use
Validate config and see loaded agents/tasks	bb --config <plane> check
Decision-ready task/run/DLQ health	bb --config <plane> status --json
Task inventory, parked state, budgets	bb --config <plane> task list --json
Trigger manual work	bb --config <plane> run <task> --payload '<json>' --json
Dispatch a manual builder lane	bb --config <plane> run build --payload '{"backlog":"<id-or-path>"}' --json
Diagnose failed CI	bb --config <plane> run ci-diagnose --payload '{"repo":"owner/repo","head_sha":"<sha>"}' --json
Run a report-only lifecycle reflex	bb --config <plane> run <reflex> --payload-file EVENT.json --json where <reflex> is fix-prompt, deploy-prod-verify, canary-triage, or lifecycle-orchestrator (each writes REPORT.json, no mutation; see docs/rollout-scorecards.md)
Compare candidate model configs	Run at least three candidate tasks, then bb --config <plane> run model-eval --payload '<json>' --json
Inspect ledger	bb --config <plane> runs list --json; bb --config <plane> runs show <id> --json
Export run telemetry	bb --config <plane> runs export (bb.run_telemetry.v1 JSONL)
Inspect or export run artifacts	bb --config <plane> artifacts list <run-id> --json (top-level artifact files); bb --config <plane> artifacts read <run-id> REPORT.json (safe text/JSON read, including known nested relative paths; binary, oversized, and traversal paths refused); bb --config <plane> artifacts bundle <run-id> --out <dir> (portable manifest.json directory; small text copied, binary/oversized/symlink artifacts manifest-only)
Handle pre-execute failures	bb --config <plane> dlq list --json; bb --config <plane> dlq replay <id> --json; bb --config <plane> dlq ack <id> --reason <text> --json to close a superseded DLQ
Handle notification failures	bb --config <plane> notify list --json; bb --config <plane> notify retry --json; bb --config <plane> notify ack <id> --reason <text> --json
Provision scoped OpenRouter child keys	bb --config <plane> keys mint <agent> --json; bb --config <plane> keys rotate <agent> --json; bb --config <plane> keys revoke <agent> --json; bb --config <plane> keys list --remote --json; bb --config <plane> keys sync --all --check --json
Park or unpark workload dispatch	`bb --config task park
Classify inherited running rows after host restart	bb --config <plane> recover
Run webhook/cron plane	bb --config <plane> serve
Submission storm / review factory	bb submit ..., verdict bb run <kind> ..., then bb gate --json
Read-only inspection for agents over MCP	bb --config <plane> mcp serve (stdio JSON-RPC; bb_status, bb_check, bb_tasks, bb_runs_list, bb_runs_show, bb_artifacts_list, bb_artifact_read, bb_dlq_list, bb_preflight, bb_gate)

Detailed command recipes: references/operator-recipes.md. Authority-promotion rules and per-task scorecards: docs/rollout-scorecards.md.

Dispatch Rules

• A bb run can have external side effects. Do not blindly re-run a successful or executing task.
• Secrets travel through declared env/secrets and stdin plumbing. Never put tokens in argv, task cards, or payload JSON unless the task contract explicitly says the value is non-secret.
• For GitHub-backed operator-dispatch runs, prefer GH_TOKEN=$(gh auth token) bb ... over copying tokens into shell history. Cerberus review is the exception: it posts with CERBERUS_REVIEW_GH_TOKEN, a bot/app or least-privilege machine-user token, per references/operator-recipes.md.
• Reflex triggers must use API-auth agents. Subscription-auth agents belong to manual dispatch only.
• The checked-in build task is a manual API-auth OMP/GLM builder lane. Use it for shaped implementation work only; it creates/pushes a branch and report but does not merge or replace the submission gate.
• For uncertain model fit, run a cohort: at least three materially different candidate tasks for the same flow and payload, then the model-eval task. First-class cohorts for build, review, gardener, ci-diagnose, and submission-storm members are listed under docs/model-evals/. Record accepted findings there before promoting a new default.
• A parked task is intentionally blocked. Inspect the reason before unpark.
• Dead letters are pre-execute failures. At/after execute, use operator resolution paths because the run may have side effects.
• Streaming harness usage is metered while the run is executing. If max_cost_per_run_usd is breached, the agent policy chooses kill, quarantine, or log; kill and quarantine must emit notification outbox rows such as run_in_flight_cap_killed.

Credential Refusal Is A Boundary

A 401/403 (or any authorization refusal) on a credential a run declares is a STOP-and-report condition, never a prompt to locate a stronger credential. The lane writes a blocked REPORT.json naming the refused operation and the refused credential by name (never value bytes), then ends the run without completing the task. Never search the environment, keychain, 1Password/op, config files, or another agent for a credential with more authority than the run declares; if the operation truly needs more authority, that is an operator decision surfaced through the blocked report. Full doctrine, substrate isolation review, and the repeatable drill: docs/credential-refusal-doctrine.md.

Submission Storm

Verdict tasks (correctness, security, product, simplification, arbiter, verify) expect a submission payload. Do not call them with an arbitrary repo/rev payload.

Shape:

bb --config <plane> submit open --change <change> --rev <rev> --json
bb --config <plane> run correctness --payload '{"submission":"<submission>"}' --json
bb --config <plane> gate --submission <submission> --json

If a verdict task fails with payload has no 'submission' field, the plane is correct; the invocation was wrong.

If bb gate --json reports a canonical member as run:failure, read that member's safe_next_command. Replays prove the failed pre-execute path can run, but they do not count for the canonical gate key; the safe recovery is a clean replacement submission after fixing the operator or infrastructure issue. The command includes the loaded plane's --config path so an agent can run it from another cwd.

Recovery

• bb recover classifies inherited running rows after a host restart.
• bb recover --json exposes probe_state, probe_reason, lease_disposition, and operator_action; unknown probes retain the host lease.
• bb runs resolve is for awaiting_recovery after side-effect inspection.
• bb status --json marks awaiting_recovery older than one hour as escalate_stale_recovery, with age fields, but the operator still resolves the run only after inspecting side effects.
• bb dlq replay --json mints a new run linked to a pre-execute dead letter and returns the replayed run bundle.
• bb dlq ack <id> --reason <text> --json acknowledges a superseded pre-execute dead letter without replaying it, recording reason + timestamp. Acknowledged DLQs cannot be replayed; bb status --json no longer counts them as open operator work.
• bb preflight <task> | --storm --json checks missing declared secrets, missing policy-bound provider keys, and unspawnable command-harness binaries before dispatch creates run rows.

Serving

bb serve exposes webhook ingress, cron scheduling, the HTML operator view, and read APIs. Do not bind publicly without BB_API_TOKEN; the server refuses non-loopback binds without it.

Useful API mirrors:

• GET /api/tasks
• GET /api/status
• GET /api/runs
• GET /api/runs/<id>
• GET /api/dlq
• GET /api/notify
• GET /api/submissions

MCP (read-only by default, one opt-in mutating tool)

bb --config <plane> mcp serve runs an MCP stdio server: JSON-RPC 2.0 over stdin/stdout, no network listener, no external credentials for local-plane inspection. Consume it MCP-first where a host agent supports it; fall back to bb ... --json for anything the MCP tool table does not yet cover. The registered read tools (bb_status, bb_check, bb_tasks, bb_runs_list, bb_runs_show, bb_artifacts_list, bb_artifact_read, bb_dlq_list, bb_preflight, bb_gate) return the same shapes as their CLI/API counterparts — MCP is a typed adapter, not a second implementation. These ten tools are always registered; no environment variable weakens that.

bb_dispatch (bitterblossom-116) is the one mutating exception, and it is opt-in only: set BB_MCP_ENABLE_DISPATCH=1 on the bb mcp serve process to enable it. With the env var unset, it is absent from tools/list and any tools/call for it is rejected the same way an unknown tool name is. Enabled, it takes repo, prompt, and optional model/label/branch_slug/ base_ref/force, builds the identical bb.dispatch_job.v1 payload the CLI bb dispatch command builds, and enqueues it through the same Ledger::ingest door every other trigger uses. It never merges, deploys, or runs anything synchronously — a running bb serve drains the enqueued run, exactly as with bb dispatch. A repeat call with the same (repo, label, branch_slug, base_ref) is refused (returns the original run id, duplicate: true) unless force: true is set. See docs/mcp-dispatch-authority.md for the full authority boundary. No other mutating tool exists; bb runs cancel, bb dlq replay, and submission/gate mutations remain CLI/API only.

Routing:

Need	First choice	Fallback
Decision-ready plane health	MCP bb_status	bb status --json
Config/task inventory	MCP bb_check, MCP bb_tasks	bb check --json; bb task list --json
Runs	MCP bb_runs_list, MCP bb_runs_show	bb runs list --json; bb runs show <id> --json
Run artifacts	MCP bb_artifacts_list, MCP bb_artifact_read	bb artifacts list <id> --json; bb artifacts read <id> <path> --json; bb artifacts bundle <id> --out <dir>
Dead letters	MCP bb_dlq_list	bb dlq list --json
Pre-dispatch readiness	MCP bb_preflight	bb preflight <task> --json
Submission gate evaluation	MCP bb_gate	bb gate --change <key> --json
Submission mutation	(not yet MCP)	bb submit ... --json
Ad hoc bounded dispatch	MCP bb_dispatch (opt-in: BB_MCP_ENABLE_DISPATCH=1)	bb dispatch --repo <path> --brief <file> [--model] [--label]

Operator Dispatch Loop

Use the ergonomic dispatch surface when the operator wants bb to own a supervised lane instead of running a bare shell:

bb --config <plane> dispatch --repo <path> --brief <file> [--model <slug>] [--label <text>]
bb --config <plane> logs -f <run-id>

dispatch prints only the accepted run id and exits. It chooses the task from BB_DISPATCH_TASK, then dispatch, then build, then a single manual task if that is the only unambiguous option. The brief file is read at dispatch time and persisted into the run payload as bb.dispatch_job.v1 with repo, canonical prompt, optional model, label, and branch_slug; the brief file path itself is not persisted. model, when provided, overrides the selected task agent's model for that run. It does not run synchronously; a running local or deployed plane drains the pending run. logs -f follows ledger events plus released text artifacts until the run reaches a terminal state.

Distribution

The portable artifact is this whole folder: skills/bitterblossom/. Consumers should copy or symlink the folder, not just SKILL.md, so references and agent metadata travel with it.

Roster integration keeps one source of truth: vendor this whole folder at a pinned Bitterblossom commit in primitives/skills/.external/registry.yaml, then include that source-qualified skill in the roles that need it. Validate the catalog with roster check; inspect or launch composed agents with roster show and roster dispatch. Do not maintain a manual copied skill that can drift. The original distribution decision is documented in docs/adr/006-skill-projection.md.

Closeout Evidence

When using Bitterblossom, report:

• exact plane path and bb binary used;
• commands run and relevant run ids;
• ledger state, costs, parked/DLQ status, and external side effects;
• generated artifacts, inspected through bb artifacts list/read rather than local path spelunking, plus any API/CLI JSON read;
• residual risk, including failed probes that remain in the ledger.