Orchestrate engine proceeds silently when MCP server is unavailable

[williamthorsen]

Problem

The orchestrate engine (orchestrate/SKILL.md) calls MCP tools (init_run, emit_event, register_artifact, complete_run, get_run_state) throughout its pipeline. If the MCP server is not configured or not running, these calls fail silently and the engine continues without producing any structured run state — no run-index.json, no run-log.jsonl, no artifact registration.

This was discovered during ticket #152: a full strict-mode orchestrated run (architecture → planning → implementation → review cycle with 4 reviewers → holistic review) completed successfully, but the run directory contained only markdown artifacts. Zero structured state was persisted. The MCP server had never been registered with Claude Code — the configuration step was omitted during the PR #133 migration.

Root cause

init_run (Run Initialization step 4) is a hard dependency — it returns { runDir, runId, ticketId, timestamp } that all downstream operations depend on. When it fails, the engine falls back to ad-hoc behavior (manually creating directories, tracking state in conversation) without informing the developer. The only MCP call with an explicit fallback is get_run_state (documented at line 485).

Impact

• Run telemetry is completely lost — no run-index.json for Factory visualization, no run-log.jsonl for event replay
• Artifact files exist on disk but are not catalogued
• The developer has no indication that anything is wrong unless they inspect the run directory afterward
• This is a regression from pre-MCP behavior, where run-index.json was written directly by the orchestrator

Proposed solution

Add an MCP availability guard to the orchestrate engine's Run Initialization step 4, with a preference-controlled policy:

MCP policy (orchestration.mcp_policy)

Value	Behavior
prompt (default)	Ask the developer: "MCP server unavailable — continue without run tracking?" Default answer: abort.
required	Abort immediately with a message explaining how to configure MCP or change the policy.
optional	Continue silently with a one-line notice. No run-index.json or run-log.jsonl produced.

Guard mechanism

1. The existing init_run call in step 4 serves as the probe — if it fails because the tool is not found or the server is not connected, the guard activates
2. The resolved policy determines whether to abort, prompt, or continue
3. When continuing without MCP, set {mcp-available} = false and skip all subsequent MCP calls silently (one policy, no per-call-site changes)
4. Generate run context locally as fallback: resolve {base-dir} from artifact conventions, create {run-dir} via mkdir -p, derive timestamps and IDs locally

Changes scoped to two skill files

• packages/agents/content/skills/orchestrate/SKILL.md — guard logic, MCP call policy, preference resolution, error handling, constraints update
• packages/agents/content/skills/orchestrate/modules/review-cycle.md — add {mcp-available} to module Inputs table

No code changes. The MCP server itself is correct.

Acceptance criteria

• When MCP is unavailable and mcp_policy is prompt (default), the orchestrator asks the developer before proceeding
• When MCP is unavailable and mcp_policy is required, the orchestrator aborts with a clear message
• When MCP is unavailable and mcp_policy is optional, the orchestrator continues with a one-line notice
• When MCP is available, behavior is unchanged (no prompt, no notice)
• When continuing without MCP, run context is generated locally: {run-dir}, {runId}, {ticketId}, {file-timestamp} are all populated
• When continuing without MCP, all emit_event, register_artifact, and complete_run calls are skipped silently
• When continuing without MCP, get_run_state uses its existing conversation-tracked fallback
• The {change-summary-path} resolution falls back to scanning {run-dir} for *_coder_change-summary.md when MCP is unavailable
• The MCP availability check is documented as a second exception to the autonomous execution constraint
• review-cycle.md Inputs table includes {mcp-available}
• pnpm run check passes at root

[williamthorsen]

<details>
<summary>Implementation plan</summary>

# Plan: Add MCP availability guard to orchestrate engine

## Context

The orchestrate engine calls MCP tools (`init_run`, `emit_event`, `register_artifact`, `complete_run`, `get_run_state`) during runs. If the MCP server isn't configured, these calls fail silently and no `run-index.json` or `run-log.jsonl` is produced. This session demonstrated the problem: a full strict-mode orchestration completed but produced zero structured run state because the MCP server was never registered with Claude Code.

The fix is a skill-only change (no code changes) that adds a guard at the `init_run` call site and a preference-controlled policy for how to handle MCP unavailability.

## Changes

### 1. Add MCP policy resolution (`SKILL.md` line ~104)

Insert a new `### Resolving MCP policy` subsection after the example preferences block (line 104), before the `## Visibility` section.

Three values: `required` (abort immediately), `optional` (continue silently), `prompt` (ask developer, default to abort). Default: `prompt`.

Resolution cascade:
1. Preference: `orchestration.mcp_policy` in `.agents/preferences.yaml` then `~/.agents/preferences.yaml`
2. Default: `prompt`

### 2. Add `mcp_policy` to example preferences (`SKILL.md` line ~96)

Add `mcp_policy: prompt` to the existing example preferences YAML block:

```yaml
orchestration:
  mcp_policy: prompt # required | optional | prompt (default: prompt)
  approval_threshold: low
  budget_threshold: low
  models:
    default: sonnet
    coder: opus
    holistic_reviewer: opus

3. Expand step 4 with availability guard (SKILL.md lines 141-164)

Modify the existing "Initialize run via MCP" step to handle init_run failure:

• Success path (unchanged): set {mcp-available} = true, store returned context variables
• Failure path (new): if init_run fails due to MCP unavailability (tool not found / server not connected), apply the resolved policy:
  • required: abort with clear message
  • prompt: ask developer "Continue without MCP tracking? (yes / no)" — abort on decline
  • optional: continue silently with a one-line notice
• Fallback init (new): when {mcp-available} = false, generate run context locally:
  • Resolve {base-dir} from artifact conventions
  • Generate {timestamp} from current UTC time (ISO 8601)
  • Derive {file-timestamp} by stripping punctuation: YYYYMMDD-HHMMSSZ
  • Use {ticket-id} from step 1 if available, otherwise auto-generate as {YYYYMMDD}-{4 random hex}
  • Set {runId} to {file-timestamp}-orchestrated
  • Set {run-dir} to {base-dir}/projects/{slug}/tickets/{ticket-id}/{runId}
  • Create {run-dir} via mkdir -p
  • Do not write run-index.json or run-log.jsonl
• Runtime errors (new): if init_run fails for non-MCP reasons (bad args, disk error), abort — not an MCP policy issue

4. Add MCP call policy subsection (SKILL.md after step 8)

New subsection ### MCP call policy that establishes a single rule: when {mcp-available} is false, skip all emit_event, register_artifact, and complete_run calls silently. No per-call-site edits needed — one policy covers all call sites. get_run_state retains its existing fallback.

Also covers mid-run disconnection: if an individual MCP call fails after a successful init_run, log a warning but don't abort.

5. Update error handling (SKILL.md line ~480)

Add two new bullets:

• MCP server unavailable at init → handled by step 4 guard
• MCP server disconnects mid-run → warn and continue

6. Update constraints (SKILL.md line 489)

Add MCP availability check as a second exception to the autonomous execution constraint (alongside Phase 6 wrap-up).

7. Add {mcp-available} to review-cycle module inputs (review-cycle.md line ~9)

Add {mcp-available} to the module's Inputs table so the flag is explicitly documented as a passed context variable.

8. Update {change-summary-path} resolution (SKILL.md line ~319)

The review-cycle: resolving {change-summary-path} section calls get_run_state. Add a fallback: when {mcp-available} is false, locate the change-summary by scanning {run-dir} for files matching *_coder_change-summary.md instead.

Files modified

File	Change type
packages/agents/content/skills/orchestrate/SKILL.md	Skill: MCP guard, policy, fallback
packages/agents/content/skills/orchestrate/modules/review-cycle.md	Skill: add {mcp-available} input

Files NOT modified

• packages/mcp/ — no code changes; the MCP server itself is correct
• packages/agents/content/skills/orchestrate-dev/SKILL.md — the wrapper doesn't call MCP tools; the guard belongs in the engine
• .agents/preferences.yaml — documenting the new key in the skill is sufficient; no need to add it to this project's preferences yet

Verification

1. Read the modified SKILL.md end-to-end to verify coherence
2. Confirm the preference resolution cascade is consistent with existing patterns
3. Run pnpm run ws test in packages/agents to ensure no test regressions
4. Manual verification: in a session without MCP configured, invoke /orchestrate-dev and confirm the guard activates with the prompt

```