Probe current subscription usage (current session + current week) via a headless /cost call and persist it to USAGE_STATE_PATH.

Show the resolved (provider, model) for every pipeline role - overlord, planner, dispatch, review, decompose - given the current env vars and model_registry.json, optionally layered with a specific plan's role_config (pass plan_name to include it). Lets you check what a plan will actually run on before executing it. Pure read; makes no changes.

"planner" here reports its own explicit configuration layer (env var / plan role_config / registry) using the same "claude" bottom-of-chain default as the other roles - it does NOT reproduce the extra "mirror dispatch's own backend when nothing else is configured" fallback that _resolve_planner_backend applies at actual dispatch time (that fallback depends on a specific story's already-resolved dispatch backend, which doesn't exist outside of a real dispatch call).

Read-only diagnostic snapshot of the pipeline's effective configuration: every role in config_provenance.PIPELINE_ROLES with its resolved (provider, model) and provenance, every cataloged env var's resolved value and provenance, any unrecognized/ignored env vars present, and which config-source files were actually consulted (and whether each exists). Pure read - makes no changes and writes nothing.

"restart_required" on a role/env entry means that entry's winning value came from an env var or the launchd plist/mcp_server_env layer, so a change there only takes effect after the scheduler/MCP server is restarted. By contrast, a plan's role_config and model_registry.json are both read fresh on every call, so edits to either are live immediately with no restart needed.

A role entry carrying a non-None "error" key is misconfigured (e.g. no model configured for it anywhere, or its provider/model pairing isn't declared in model_registry.json) - never raises for this; the bad role just reports its error inline while the rest of the roles resolve normally.

Pass plan_name to additionally layer in that plan's role_config overrides (same effect as get_role_config's plan_name); a plan_name whose manifest doesn't exist degrades to "no plan overrides" rather than raising.

Turn a raw goal/feature request into epics/stories JSON via the product-analyst persona, run on whichever provider the "decompose" role is configured for (PIPELINE_BACKEND_DECOMPOSE env var, or a "decompose" entry in model_registry.json - defaults to Claude when neither is set). This is a separate, additional path from the interactive product-analyst subagent (invoked via the Agent tool, which is always Claude) - that path remains available and is still the default choice for Claude-quality decomposition; this tool exists so decomposition can also run on a local provider when desired.

Does NOT call save_plan itself - review the returned plan the same way you would review the interactive subagent's output, then save_plan it yourself.

Returns {"ok": True, "plan": {...}} on success. On failure, returns {"ok": False, "error": ...}, with "raw": included whenever the backend actually returned text that failed to parse (never raises).

Save a generated project plan to disk. Plan should be JSON matching the schema: { "epics": [ { "summary", "stories": [...] } ] }. Call this after generating a plan so the user can review before ingestion.

workspace is optional. When supplied, it is validated and (WS-11) the model-authored repo_root in plan_json is OVERWRITTEN with the server-validated resolved path (the server overwrites the model-authored value; this tool never resolves or rewrites plan_json itself). When omitted, the plan's own repo_root is trusted, exactly as before. The tool deliberately does NOT fall back to the dashboard's persisted active workspace: the MCP server and the dashboard are separate processes, and silently coupling them through shared durable state is out of scope (that fallback lives only in the dashboard HTTP route).

Push a saved plan into Plane. Creates epics first, then issues linked to their parent epic. Optionally restrict to specific epic summaries via only_epics. Returns a manifest mapping local IDs to Plane UUIDs.

Re-ingesting an already-ingested plan merges into the existing manifest rather than replacing it: epics/stories not touched this call (including everything only_epics excludes) are preserved verbatim, a story whose key already exists gets its authored fields (summary, agent_instructions, dependencies, persona, model, acceptance, risk) refreshed while its runtime state (status, pr_url, ...) is kept, and top-level manifest keys outside epics/stories/repo_root (paused, local_model_fallback, final_rework_escalation, ...) carry over untouched. Pass overwrite=True to restore the old wholesale-replace behavior (drops anything not produced by this call).

Return stories whose dependencies are satisfied and that are still in To Do. Use this to decide what to dispatch next.

Spawn a headless Claude Code agent to work on a single story.

For a fresh story, creates a git worktree on a new branch. For a story left "interrupted" (or whose worktree already exists from a prior run), reuses the existing worktree/branch instead and seeds the agent's prompt with the checkpoint journal so it continues rather than starting over. Transitions the Plane issue to In Progress. Returns the subprocess PID; completion is async.

Acquires _plan_lock so direct MCP tool calls serialize across MCP server processes - without this guard, two Claude sessions (each with their own MCP server PID) can both call dispatch_story on the same story in the same window, and the second one treats the first one's half-built worktree as resumable and spawns a second agent into the same directory. That race is what produced the repeated zero-output agent deaths logged in 2026-06-27's e2e-decentralized-messaging run.

Stop a dispatched agent and leave its story resumable.

Sends SIGTERM to the agent's process (a no-op if it has already exited), commits any uncommitted work in its worktree as a checkpoint, and marks the story "interrupted" rather than "failed" so a later dispatch_story call resumes it instead of starting over. The worktree and branch are left in place.

Acquires _plan_lock for the same reason dispatch_story does - two MCP servers can race here too, with one calling interrupt while the other calls dispatch on the same story, producing a manifest write race that leaves the worktree in an inconsistent state.

Transition the ticket to In Progress and update the local manifest. Use this before writing any code for a story.

Record a durable checkpoint for a dispatched agent's progress. Commits any uncommitted work in the story's worktree as a WIP commit and appends an entry to the story's journal (plan.story.journal.json). Call this after completing each idempotent step of a story so a killed agent can resume from the last checkpoint instead of starting over.

Transition the ticket to Done and update the local manifest. Use after you've reviewed and merged the agent's PR.

Edit a story's plan-authored fields (agent_instructions, model, persona, risk, dependencies, acceptance, pr_url, summary) without hand-editing the manifest JSON.

Hand-editing the manifest directly races the scheduler's 60s advance_all_plans tick - a read-modify-write on either side can silently clobber the other's write. This tool acquires the same _plan_lock the scheduler and dispatch_story use, so the edit is atomic with respect to it. Only the fields above may be set; status transitions go through set_story_status, not this tool.

Transition a story to an explicit status without hand-editing the manifest JSON (e.g. resetting a "parked" story to "interrupted" so the scheduler retries it).

Acquires _plan_lock for the same reason patch_story does. Only accepts the fixed set of statuses the pipeline itself assigns (todo/in_progress/running/interrupted/failed/tests_passed/pr_open/ changes_requested/parked/done) - this is a sanctioned status change, not a way to invent pipeline state the rest of the code doesn't expect.

Escalate a blocking decision to the overlord, which rules on the user's behalf per the decision policy. The ruling is appended to the plan's decisions log (audit trail) and returned. Call this from a story agent when you are blocked on a choice the user would normally make.

Return the overlord decision log for a plan (audit trail).

Run the code-reviewer persona over a dispatched story's branch. On APPROVE, open a PR via gh and set status to pr_open; otherwise set status to changes_requested. Does not merge — merge is the overlord's decision.

Only reviewable when story["status"] == "tests_passed" - any other status (a stale/duplicate call, e.g. a second tick racing an already-merged story) is a no-op skip; see README.md's "Review & merge" section.

Run one orchestration tick: dispatch every ready story (deps satisfied), advance finished stories through test -> review -> PR, and adjudicate merges against the risk threshold. Idempotent; designed to be called repeatedly by a scheduler (/loop or cron). In PIPELINE_AUTONOMY=dry-run it plans and logs only, taking no actions.

Honors a per-backend resource gate: dispatch and review are gated independently by their own backend's resource_status() (see _role_resource_ok). If the dispatch backend is gated, in-progress stories are interrupted (checkpointed, resumable) and no new dispatch starts; if the review backend is gated, review is deferred. Each is independent, so a Claude usage pause no longer freezes local-backed dispatch. Merge adjudication always runs (no model usage). "interrupted" stories are dispatch-eligible like "todo" ones, so they resume automatically once the dispatch backend frees up.

Also honors MAX_CONCURRENT_AGENTS: dispatch is capped to the number of free slots remaining (limit minus agents already in_progress across all plans), so a tick never starts more agents than the configured ceiling. Stories left undispatched this tick stay "todo"/"interrupted" and are picked up on a later tick as slots free up.

Skips entirely (returns {"ok": True, "skipped": "locked"}) if another tick for this same plan is already running - see _plan_lock.

Approve a merge by delegating to PipelineService.

Stop advance_pipeline/advance_all_plans from touching this one plan - no new dispatch, review, or merge - while leaving every other ingested plan's scheduler ticks unaffected. Any story currently in_progress is interrupted (checkpointed and left resumable) so a paused plan isn't quietly burning usage in the background. Resume with resume_plan.

Clear a pause set by pause_plan so this plan's stories are eligible for dispatch/review/merge on the next advance_pipeline tick again.

Run advance_pipeline on every plan that has been ingested (has a manifest), keyed by plan name. Plans saved but not yet ingested (no manifest) are skipped. Intended for a recurring scheduler (cron/launchd or /loop) so newly ingested plans are picked up automatically with no hardcoded plan name to maintain.

NOTE on zombie reaping: the per-plan advance_pipeline polling phase already handles dead-pid in_progress stories via check_story_status (which falls through to test-running on dead pids). Running an external reap pass BEFORE the polling would clobber that and silently leave stories re-dispatching forever without ever running the test (manifest observation 2026-06-28: 3 e2e stories hit dispatch_attempts= MISSING because the reap ate the polling opportunity). The reap helper _reap_zombie_in_progress_stories is kept for callers that need a one-shot cleanup (e.g. tests, ops CLI) but is NOT wired in here.