@deksden-com/dd-flow-cli 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.6.0
+
+### Minor Changes
+
+- 47cd270: Add SPC-006 bootstrap stage start/context packets and sealed stage finish, while repairing Memory Bank upgrade stage routing, Codex hook event identity, PATH-stable per-home hook installation, canonical Codex session registration, session coverage projections, terminal orchestrator closure, and safe reconciliation of runs whose legacy authority and workspace are gone.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -75,10 +75,10 @@ dd-flow protocol register HANDSHAKE-001 --project-root "$PWD" --json
 dd-flow protocol status PRT-HANDSHAKE-001 --project-root "$PWD" --json
 ```
 
-Attach and update a plan:
+Inspect the canonical plan and update its SQLite progress projection:
 
 ```bash
-dd-flow plan set PRT-HANDSHAKE-001 --project-root "$PWD" --file plan.json --json
+dd-flow plan status PRT-HANDSHAKE-001 --project-root "$PWD" --json
 dd-flow plan item start PRT-HANDSHAKE-001 P1 --project-root "$PWD" --json
 dd-flow plan item done PRT-HANDSHAKE-001 P1 --project-root "$PWD" --summary "Implemented" --evidence "pnpm test" --json
 ```

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.5.0",
-  "cli_commit": "64b75acbb2e62c9e80eb29c501f5f3481f86cf20",
-  "built_at": "2026-08-11T10:20:58.455Z",
+  "cli_version": "0.6.0",
+  "cli_commit": "22cf9c8f5293168dae76212c9a4b74b90a1efeab",
+  "built_at": "2026-08-12T05:09:56.163Z",
   "built_with_canon": {
-    "version": "3.0.0",
-    "commit": "1e8c39078ed7a34adde93315a9cdcf2bbfc15374",
+    "version": "3.1.0",
+    "commit": "c201167b896a039ff4881d6d816b9735fba2f799",
     "flow_contract": "dd-flow-canonical-2026-08",
     "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
     "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",

package/dist/cli/help.js

@@ -143,7 +143,7 @@ Usage:
   dd-flow id next --type protocol|run --project-root <root> --slug <slug> --json
   dd-flow run status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run list --project-root <root> --json
-  dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> [--hide stages|events|sessions|usage|artifacts] --json
+  dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run usage <RUN-ID|RUN-short-id> --project-root <root> [--group-by session|role|stage|aspect|plan-item] --json
   dd-flow run flags status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run flags revise <RUN-ID|RUN-short-id> --project-root <root> --expected-revision <n> --idempotency-key <key> [--preset <name>] [--flag key=value] [--flag key=value] [--allow-downgrade --reason <text>] --json
@@ -165,9 +165,10 @@ Examples:
 
 Usage:
   dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] --json
-  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--status done|blocked|failed] [--semantic-file <RUN-local-json>] --json
+  dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> [--intake-file <path>] --json
+  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--outcome done|blocked|failed] [--semantic-file <RUN-local-json>] --json
 
-stage start attaches the stage, archives an earlier attempt when needed and writes one RUN-local stage-prompt.md. stage finish derives a bounded report and always generates validated JSON, Markdown, template-backed HTML and a durable protocol-summary projection. Raw intake and telemetry remain RUN-local.`
+stage start is the worker's first practical flow command. It performs deterministic setup and returns a ready-to-use, stage-specific work packet with trusted runtime facts, compatibility and permission preflight, aliases, write boundary and exact finish command. The same packet is written to RUN-local stage-prompt.md and stage-prompt.json. --bootstrap creates the initial protocol/RUN envelope and copies the supplied intake into the RUN home before starting specify. stage finish defaults to @stage/stage-input.json, accepts semantic --outcome and always generates validated JSON, Markdown, template-backed HTML and a durable protocol-summary projection. Raw intake and telemetry remain RUN-local.`
     ],
     [
         "id",

package/dist/cli/run-cli.js

@@ -541,23 +541,28 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
     }
     if (family === "stage" && command === "start") {
         const dir = optionalOption(parsed, "dir");
+        const bootstrap = hasOption(parsed, "bootstrap");
+        const subject = optionalOption(parsed, "subject");
+        const intakeFile = optionalOption(parsed, "intake-file");
+        const sessionId = optionalOption(parsed, "session-id");
         return startStage(context, {
             projectRoot: requiredOption(parsed, "project-root"),
-            runId: requiredPosition(parsed, 0, "run-id"),
+            ...(bootstrap ? { bootstrap: { subject: subject ?? requiredOption(parsed, "subject"), ...(intakeFile ? { intakeFile } : {}) } } : { runId: requiredPosition(parsed, 0, "run-id") }),
             stage: requiredOption(parsed, "stage"),
+            ...(sessionId ? { sessionId } : {}),
             ...(dir ? { dir } : {})
         });
     }
     if (family === "stage" && command === "finish") {
         const dir = optionalOption(parsed, "dir");
-        const status = optionalOption(parsed, "status");
+        const outcome = optionalOption(parsed, "outcome") ?? optionalOption(parsed, "status");
         const semanticFile = optionalOption(parsed, "semantic-file") ?? optionalOption(parsed, "data");
         return finishStage(context, {
             projectRoot: requiredOption(parsed, "project-root"),
             runId: requiredPosition(parsed, 0, "run-id"),
             stage: requiredOption(parsed, "stage"),
             ...(dir ? { dir } : {}),
-            ...(status ? { status } : {}),
+            ...(outcome ? { outcome } : {}),
             ...(semanticFile ? { semanticFile } : {})
         });
     }
@@ -1327,11 +1332,15 @@ function dispatchCodexHome(context, parsed) {
 function dispatchCodexHook(context, parsed, stdin) {
     const action = requiredPosition(parsed, 0, "codex hook action");
     if (action === "handle") {
-        return handleCodexHook(context, {
+        const result = handleCodexHook(context, {
             event: requiredOption(parsed, "event"),
             projectRoot: optionalOption(parsed, "project-root"),
             stdin
         });
+        if (result && typeof result === "object" && !Array.isArray(result) && "hookSpecificOutput" in result) {
+            return { hookSpecificOutput: result.hookSpecificOutput };
+        }
+        return {};
     }
     throw new AppError("usage", `Unknown codex hook action: ${action}`, 2);
 }

package/dist/domain/flow-contract.js

@@ -332,7 +332,6 @@ function flagStrength(key, value, definition) {
         "subagents.route": ["self_check", "grouped_subagent", "focused_subagent", "mixed"],
         "subagents.grouping": ["off", "allowlisted"],
         "subagents.pool_fallback": ["one", "runtime"],
-        "observability.detail": ["compact", "normal", "full"],
         "knowledge.extract": ["skip", "conditional", "required"],
         "knowledge.promote": ["skip", "conditional", "required"],
         "workspace.bootstrap.mode": ["not_required", "revalidate", "required"],
@@ -362,10 +361,10 @@ function numberValue(value) {
 export function normalizeFlowContract(value) {
     const version = requireNumber(value.version, "/version");
     const id = requireString(value.id, "/id");
-    if (version === 4 || version === 5) {
+    if (version === 4 || version === 5 || version === 6) {
         return normalizeCanonicalRuntimeContract(value, id, version);
     }
-    if (version > 5)
+    if (version > 6)
         fail("/version", `unsupported flow-contract version: ${version}`);
     if (version === 3 && !/^dd-flow-canonical-[0-9]{4}-[0-9]{2}$/.test(id)) {
         fail("/id", "must identify a canonical version 3 flow contract");
@@ -462,7 +461,8 @@ function normalizeCanonicalRuntimeContract(value, id, version) {
             "flow_run_snapshot.v1",
             "session_coverage_units.v1",
             "privacy_safe_observability.v1",
-            ...(version === 5 ? ["canonical_protocol_plan.v1"] : [])
+            ...(version >= 5 ? ["canonical_protocol_plan.v1"] : []),
+            ...(version >= 6 ? ["stage_bootstrap_context_packet.v1"] : [])
         ],
         stages,
         transitions,

package/dist/domain/session-coverage.js

@@ -0,0 +1,88 @@
+export function reconcileSessionCoverageRows(sessions) {
+    const sessionCounts = countValues(sessions.map((session) => session.session_id));
+    const duplicateSessionIds = duplicates(sessionCounts);
+    const invalidSessionIds = [];
+    const parsed = sessions.map((session) => {
+        try {
+            return { session, units: normalizeCoverageUnits(JSON.parse(session.coverage_units_json || "[]")) };
+        }
+        catch {
+            invalidSessionIds.push(session.session_id);
+            return { session, units: [] };
+        }
+    });
+    const orchestrators = parsed.filter(({ session }) => session.session_kind === "orchestrator");
+    const workers = parsed.filter(({ session }) => session.session_kind !== "orchestrator");
+    const expectedCounts = countValues(orchestrators.flatMap(({ units }) => units.map((unit) => unit.unit_id)));
+    const expectedUnitIds = [...expectedCounts.keys()].sort();
+    const duplicateExpectedUnitIds = duplicates(expectedCounts);
+    const observedOwners = new Map();
+    for (const { session, units } of workers) {
+        for (const unit of units) {
+            const owners = observedOwners.get(unit.unit_id) ?? [];
+            owners.push(session.session_id);
+            observedOwners.set(unit.unit_id, owners);
+        }
+    }
+    const observedUnitIds = [...observedOwners.keys()].sort();
+    const missingUnitIds = expectedUnitIds.filter((unitId) => !observedOwners.has(unitId));
+    const duplicateUnitIds = [...observedOwners.entries()]
+        .filter(([, owners]) => new Set(owners).size > 1)
+        .map(([id]) => id)
+        .sort();
+    const diagnostics = [];
+    if (orchestrators.length === 0)
+        diagnostics.push("orchestrator_session_missing");
+    if (orchestrators.length > 1)
+        diagnostics.push("multiple_orchestrator_sessions");
+    if (workers.length > 0 && expectedUnitIds.length === 0)
+        diagnostics.push("expected_worker_units_missing");
+    if (missingUnitIds.length > 0)
+        diagnostics.push("expected_worker_units_unobserved");
+    if (duplicateUnitIds.length > 0 || duplicateExpectedUnitIds.length > 0)
+        diagnostics.push("duplicate_coverage_binding");
+    if (duplicateSessionIds.length > 0)
+        diagnostics.push("duplicate_session_binding");
+    if (invalidSessionIds.length > 0)
+        diagnostics.push("invalid_coverage_units");
+    const unavailable = orchestrators.length === 0 || invalidSessionIds.length > 0;
+    const partial = orchestrators.length !== 1
+        || (workers.length > 0 && expectedUnitIds.length === 0)
+        || missingUnitIds.length > 0
+        || duplicateUnitIds.length > 0
+        || duplicateExpectedUnitIds.length > 0
+        || duplicateSessionIds.length > 0;
+    return {
+        status: unavailable ? "unavailable" : partial ? "partial" : "complete",
+        expected_unit_ids: expectedUnitIds,
+        observed_unit_ids: observedUnitIds,
+        missing_unit_ids: missingUnitIds,
+        duplicate_unit_ids: duplicateUnitIds,
+        duplicate_expected_unit_ids: duplicateExpectedUnitIds,
+        duplicate_session_ids: duplicateSessionIds,
+        orchestrator_session_ids: orchestrators.map(({ session }) => session.session_id).sort(),
+        invalid_session_ids: [...new Set(invalidSessionIds)].sort(),
+        diagnostics
+    };
+}
+function normalizeCoverageUnits(value) {
+    if (!Array.isArray(value))
+        throw new Error("coverage_units must be an array");
+    return value.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            throw new Error("coverage unit must be an object");
+        const unitId = item.unit_id;
+        if (typeof unitId !== "string" || unitId.length === 0)
+            throw new Error("coverage unit requires unit_id");
+        return { unit_id: unitId };
+    });
+}
+function countValues(values) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    return counts;
+}
+function duplicates(counts) {
+    return [...counts.entries()].filter(([, count]) => count > 1).map(([id]) => id).sort();
+}

package/dist/schemas/flow-contract.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/flow-contract@5",
+  "$id": "dd-flow/flow-contract@6",
   "title": "dd-flow canonical runtime contract",
-  "description": "Structural contract for the SPC-004 v0.2 and SPC-005 runtime/PLAN cutover. Dynamic command and cross-repository checks belong to companion projects.",
+  "description": "Structural contract for the SPC-004/005/006 runtime, PLAN and deterministic stage-context cutover. Dynamic command and cross-repository checks belong to companion projects.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -25,21 +25,21 @@
     "policy"
   ],
   "properties": {
-    "schema_id": {"const": "dd-flow/flow-contract@5"},
+    "schema_id": {"const": "dd-flow/flow-contract@6"},
     "id": {"const": "dd-flow-canonical-2026-08"},
     "contract_id": {"type": "string", "pattern": "^dd-flow-canonical-[0-9]{4}-[0-9]{2}$"},
-    "version": {"const": 5},
+    "version": {"const": 6},
     "status": {"const": "active"},
     "source": {"const": ".memory-bank/dd-flow/common/runtime-contract.md"},
     "specifications": {
       "type": "array",
-      "minItems": 2,
+      "minItems": 3,
       "items": {
         "type": "object",
         "additionalProperties": false,
         "required": ["id", "version", "sha256"],
         "properties": {
-          "id": {"enum": ["SPC-004", "SPC-005"]},
+          "id": {"enum": ["SPC-004", "SPC-005", "SPC-006"]},
           "version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"},
           "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}
         }
@@ -73,21 +73,23 @@
     "stageLifecycle": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["actions", "start_command", "finish_command", "prompt_sections", "current_write_alias", "archive_pattern"],
+      "required": ["actions", "start_command", "bootstrap_command", "finish_command", "prompt_sections", "current_write_alias", "archive_pattern"],
       "properties": {
         "actions": {
           "const": ["stage_start", "stage_finish"]
         },
         "start_command": {"const": "dd-flow stage start <RUN> --stage <stage> --json"},
-        "finish_command": {"const": "dd-flow stage finish <RUN> --stage <stage> --status done --json"},
+        "bootstrap_command": {"const": "dd-flow stage start --bootstrap --stage specify --project-root <root> --subject <label> --intake-file <path> --json"},
+        "finish_command": {"const": "dd-flow stage finish <RUN> --stage <stage> --outcome <outcome> --json"},
         "prompt_sections": {
           "const": [
             "stage_identity",
-            "runtime_context",
-            "intake",
+            "authoritative_runtime_facts",
+            "preflight",
+            "task_intake",
             "applicable_instructions",
-            "stage_cli",
-            "file_boundaries",
+            "required_context",
+            "work_contract",
             "completion_contract"
           ]
         },
@@ -112,7 +114,7 @@
       "required": ["finish_outputs", "model_input", "mechanical_facts"],
       "properties": {
         "finish_outputs": {"const": ["stage-report.json", "stage-report.md", "stage-report.html", "summary.md"]},
-        "model_input": {"const": "semantic-only"},
+        "model_input": {"const": "semantic-only; outcome flag"},
         "mechanical_facts": {"const": "cli-owned"}
       }
     },

package/dist/schemas/stage-prompt.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/stage-prompt@1",
+  "$id": "dd-flow/stage-prompt@2",
   "title": "Generated stage prompt",
   "type": "object",
   "additionalProperties": false,
@@ -16,16 +16,20 @@
       }
     }
   ],
-  "required": ["schema_id", "run_id", "stage", "generated_at", "prompt_path", "sections", "aliases", "write_boundary", "source_fragments"],
+  "required": ["schema_id", "run_id", "stage", "generated_at", "prompt_path", "sections", "aliases", "write_boundary", "source_fragments", "authoritative_facts", "preflight", "required_context", "worker_prompt_markdown"],
   "properties": {
-    "schema_id": {"const": "dd-flow/stage-prompt@1"},
+    "schema_id": {"const": "dd-flow/stage-prompt@2"},
     "run_id": {"type": "string", "minLength": 1},
     "stage": {"type": "string", "minLength": 1},
     "generated_at": {"type": "string", "format": "date-time"},
     "prompt_path": {"type": "string", "minLength": 1},
-    "sections": {"type": "array", "minItems": 7, "maxItems": 7, "items": {"enum": ["stage_identity", "runtime_context", "intake", "applicable_instructions", "stage_cli", "file_boundaries", "completion_contract"]}},
+    "sections": {"type": "array", "minItems": 8, "maxItems": 8, "items": {"enum": ["stage_identity", "authoritative_runtime_facts", "preflight", "task_intake", "applicable_instructions", "required_context", "work_contract", "completion_contract"]}},
     "aliases": {"type": "object", "required": ["project", "workspace", "run", "stage", "protocol", "intake"], "additionalProperties": {"type": "string"}},
     "write_boundary": {"type": "object", "required": ["current", "archive", "archive_writable"], "properties": {"current": {"const": "@stage"}, "archive": {"pattern": "try-[0-9]{3}"}, "archive_writable": {"const": false}}, "additionalProperties": false},
-    "source_fragments": {"type": "array", "items": {"type": "string", "minLength": 1}}
+    "source_fragments": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "authoritative_facts": {"type": "object", "additionalProperties": true},
+    "preflight": {"type": "object", "additionalProperties": true},
+    "required_context": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "worker_prompt_markdown": {"type": "string", "minLength": 1}
   }
 }

package/dist/schemas/stage-start-response.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/stage-start-response@1",
+  "$id": "dd-flow/stage-start-response@2",
   "title": "Stage start response",
   "type": "object",
   "additionalProperties": false,
@@ -10,9 +10,9 @@
       "then": {"required": ["plan_ref", "aspect_map_ref"]}
     }
   ],
-  "required": ["schema_id", "run_id", "stage", "attempt_number", "stage_root", "prompt_path", "aliases", "next_command"],
+  "required": ["schema_id", "run_id", "stage", "attempt_number", "stage_root", "prompt_path", "aliases", "next_command", "worker_prompt_markdown"],
   "properties": {
-    "schema_id": {"const": "dd-flow/stage-start-response@1"},
+    "schema_id": {"const": "dd-flow/stage-start-response@2"},
     "run_id": {"type": "string", "minLength": 1},
     "stage": {"type": "string", "minLength": 1},
     "attempt_number": {"type": "integer", "minimum": 1},
@@ -23,7 +23,8 @@
     "resolved_context": {"type": "object", "additionalProperties": true},
     "plan_ref": {"type": "string", "pattern": "^\\.memory-bank/protocol/[^/]+/plan\\.json$"},
     "aspect_map_ref": {"type": "string", "minLength": 1},
-    "next_command": {"const": "dd-flow stage finish"},
-    "permission_probe": {"type": "object", "additionalProperties": true}
+    "next_command": {"type": "string", "pattern": "^dd-flow stage finish "},
+    "permission_probe": {"type": "object", "additionalProperties": true},
+    "worker_prompt_markdown": {"type": "string", "minLength": 1}
   }
 }

package/dist/services/cleanup.js

@@ -12,6 +12,7 @@ const actionKinds = new Set([
     "repair_protocol_state",
     "cancel_queue_job",
     "close_flow_session",
+    "discard_stale_run",
     "expire_lane_lock",
     "expire_lane_waiter",
     "close_worktree_record"
@@ -86,6 +87,36 @@ export function cleanupScan(context, input) {
             });
         }
     }
+    const staleRuns = context.db.all(`SELECT id, runtime_path, run_dir, workspace_root FROM flow_runs
+     WHERE project_id = ? AND status = 'running'
+     ORDER BY updated_at ASC, id ASC`, [project.id]);
+    for (const run of staleRuns) {
+        const missingAuthority = !fs.existsSync(run.runtime_path);
+        const missingRunHome = !fs.existsSync(run.run_dir);
+        const missingWorkspace = !fs.existsSync(run.workspace_root);
+        if (!missingAuthority)
+            continue;
+        const details = {
+            code: "stale_run_missing_authority",
+            severity: "warning",
+            run_id: run.id,
+            runtime_path: run.runtime_path,
+            missing_run_home: missingRunHome,
+            missing_workspace: missingWorkspace
+        };
+        if (missingRunHome && missingWorkspace) {
+            pushFinding(findings, actions, details.code, details.severity, {
+                run_id: run.id,
+                runtime_path: run.runtime_path,
+                missing_run_home: missingRunHome,
+                missing_workspace: missingWorkspace,
+                action: { kind: "discard_stale_run", project_id: project.id, run_id: run.id }
+            });
+        }
+        else {
+            findings.push({ ...details, action: null, reason: "manual_reconciliation_required" });
+        }
+    }
     const now = context.now();
     const expiredLocks = context.db.all(`SELECT id, lane, worker_id, expires_at FROM lane_locks
      WHERE project_id = ? AND status = 'active' AND expires_at <= ?
@@ -289,6 +320,41 @@ function applyAction(context, action, reason, force, now) {
         });
         return { kind: action.kind, changed: true, session_id: action.session_id };
     }
+    if (action.kind === "discard_stale_run" && action.run_id) {
+        const run = context.db.get("SELECT status, runtime_path, run_dir, workspace_root, index_json FROM flow_runs WHERE project_id = ? AND id = ?", [action.project_id, action.run_id]);
+        if (!run) {
+            return { kind: action.kind, changed: false, skipped: true, reason: "run_not_found", run_id: action.run_id };
+        }
+        if (run.status === "discarded") {
+            const index = discardedRunIndex(run.index_json, reason, now);
+            context.db.run("UPDATE flow_runs SET verdict = 'discarded', next_action = ?, index_json = ?, updated_at = ?, completed_at = COALESCE(completed_at, ?) WHERE project_id = ? AND id = ?", [reason, JSON.stringify(index), now, now, action.project_id, action.run_id]);
+            if (fs.existsSync(run.runtime_path))
+                fs.writeFileSync(run.runtime_path, `${JSON.stringify(index, null, 2)}\n`);
+            return { kind: action.kind, changed: true, run_id: action.run_id };
+        }
+        if (run.status !== "running") {
+            return { kind: action.kind, changed: false, skipped: true, reason: `already_${run.status}`, run_id: action.run_id };
+        }
+        if (fs.existsSync(run.runtime_path) || fs.existsSync(run.run_dir) || fs.existsSync(run.workspace_root)) {
+            return { kind: action.kind, changed: false, skipped: true, reason: "runtime_or_workspace_reappeared", run_id: action.run_id };
+        }
+        const index = discardedRunIndex(run.index_json, reason, now);
+        context.db.run(`UPDATE flow_runs SET status = 'discarded', verdict = 'discarded', next_action = ?, index_json = ?, updated_at = ?, completed_at = ?
+       WHERE project_id = ? AND id = ? AND status = 'running'`, [reason, JSON.stringify(index), now, now, action.project_id, action.run_id]);
+        fs.mkdirSync(run.run_dir, { recursive: true });
+        fs.writeFileSync(run.runtime_path, `${JSON.stringify(index, null, 2)}\n`);
+        context.db.run(`UPDATE flow_sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
+       WHERE project_id = ? AND run_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, action.project_id, action.run_id]);
+        context.db.run("UPDATE flow_session_segments SET ended_at = ? WHERE project_id = ? AND run_id = ? AND ended_at IS NULL", [now, action.project_id, action.run_id]);
+        appendAudit(context, {
+            projectId: action.project_id,
+            eventType: "flow_run.discarded",
+            reason,
+            forced: force,
+            payload: { run_id: action.run_id, source: "cleanup.apply", authority_missing: true }
+        });
+        return { kind: action.kind, changed: true, run_id: action.run_id };
+    }
     if (action.kind === "expire_lane_lock" && typeof action.lock_id === "number") {
         const result = context.db.run("UPDATE lane_locks SET status = 'expired', reason = ?, updated_at = ? WHERE project_id = ? AND id = ? AND status = 'active'", [reason, now, action.project_id, action.lock_id]);
         return {
@@ -330,6 +396,17 @@ function applyAction(context, action, reason, force, now) {
     }
     return { kind: action.kind, changed: false, skipped: true, reason: "invalid_action" };
 }
+function discardedRunIndex(indexJson, reason, now) {
+    const index = JSON.parse(indexJson);
+    index.schema_id = "dd-flow/flow-run@2";
+    index.status = "discarded";
+    index.verdict = "discarded";
+    index.next_action = reason;
+    index.updated_at = now;
+    index.completed_at ??= now;
+    index.finished_at ??= now;
+    return index;
+}
 function dirtyGit(worktreePath) {
     if (!fs.existsSync(worktreePath)) {
         return false;

package/dist/services/hooks.js

@@ -196,7 +196,7 @@ export function getCodexHooksStatus(context, input) {
         };
     }
     const status = hookFileStatus(location.hooksPath, project.root);
-    const recorded = hookInstallation(context, project.id, installationScope(target, location.profile));
+    const recorded = hookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath));
     const driftStatus = status.installed ? "none" : recorded?.installed === 1 ? "drifted" : status.drift_status;
     return {
         ok: true,
@@ -224,7 +224,7 @@ export function installCodexHooks(context, input) {
     const nextConfig = mergeHooksConfig(existing, project.root);
     ensureDir(path.dirname(location.hooksPath));
     writeJsonFile(location.hooksPath, nextConfig);
-    recordHookInstallation(context, project.id, installationScope(target, location.profile), location.hooksPath, true, "none");
+    recordHookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath), location.hooksPath, true, "none");
     appendAudit(context, {
         projectId: project.id,
         eventType: "codex_hooks.installed",
@@ -256,7 +256,7 @@ export function removeCodexHooks(context, input) {
     const nextConfig = removeManagedHooks(existing, project.root);
     ensureDir(path.dirname(location.hooksPath));
     writeJsonFile(location.hooksPath, nextConfig);
-    recordHookInstallation(context, project.id, installationScope(target, location.profile), location.hooksPath, false, "not_installed");
+    recordHookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath), location.hooksPath, false, "not_installed");
     appendAudit(context, {
         projectId: project.id,
         eventType: "codex_hooks.removed",
@@ -277,13 +277,16 @@ export function handleCodexHook(context, input) {
     if (!command)
         return { ok: true, observed: false, reason: "non_bash_tool" };
     const flowPayload = flowSessionPayloadFromRegisterCommand(command);
-    if (!flowPayload)
+    const bootstrapStageStart = /\bdd-flow\s+stage\s+start\b/.test(command) && /(?:^|\s)--bootstrap(?:\s|$)/.test(command);
+    if (!flowPayload && !bootstrapStageStart)
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
     const project = projectForHook(context, input.projectRoot, stringValue(payload.cwd));
     if (!project)
         return { ok: true, observed: false, reason: "unrelated_cwd" };
     const binding = sessionId ? upsertSessionBindingFromPayload(context, project, sessionId, payload) : undefined;
-    const observedSession = bindObservedFlowSession(context, project, flowPayload, sessionId ?? flowPayload.session_id ?? undefined);
+    const observedSession = flowPayload
+        ? bindObservedFlowSession(context, project, flowPayload, sessionId ?? flowPayload.session_id ?? undefined)
+        : undefined;
     const effectiveSessionId = observedSession?.session_id ?? sessionId ?? null;
     const protocolId = observedSession?.protocol_id ?? binding?.protocol_id ?? null;
     const eventKey = hookEventKey(payload, eventName, toolName, command);
@@ -315,9 +318,23 @@ export function handleCodexHook(context, input) {
         duplicate: !inserted,
         event_key: eventKey,
         session_id: effectiveSessionId,
-        protocol_id: protocolId
+        protocol_id: protocolId,
+        ...(sessionId
+            ? {
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "allow",
+                    updatedInput: { command: commandWithSessionId(command, sessionId) }
+                }
+            }
+            : {})
     };
 }
+function commandWithSessionId(command, sessionId) {
+    if (/(?:^|\s)--session-id(?:=|\s)/.test(command))
+        return command;
+    return `${command} --session-id ${JSON.stringify(sessionId)}`;
+}
 export function hookStatusForProject(context, projectId) {
     return context.db.all(`SELECT scope, config_path, content_hash, installed, drift_status, updated_at
      FROM hook_installations WHERE project_id = ? ORDER BY updated_at DESC`, [projectId]);
@@ -460,7 +477,7 @@ function commandHook(command, statusMessage) {
     return { type: "command", command, timeout: 5, statusMessage };
 }
 function hookCommand(event) {
-    return `dd-flow codex hook handle --event ${event} --json`;
+    return `PATH="\${HOME}/Library/pnpm:/opt/homebrew/bin:/usr/local/bin:\${PATH}" dd-flow codex hook handle --event ${event} --json`;
 }
 function resolveHookTarget(target) {
     if (!target || target === "isolated") {
@@ -632,8 +649,8 @@ function recordHookInstallation(context, projectId, scope, configPath, installed
        drift_status = excluded.drift_status,
        updated_at = excluded.updated_at`, [projectId, scope, configPath, hashObject(readJsonIfExists(configPath) ?? {}), installed ? 1 : 0, driftStatus, now, now]);
 }
-function installationScope(target, profile) {
-    return target === "isolated" ? `isolated:${profile}` : "default";
+function installationScope(target, profile, hooksPath) {
+    return target === "isolated" ? `isolated:${profile}` : `default:${path.dirname(hooksPath)}`;
 }
 function upsertSessionBindingFromPayload(context, project, sessionId, payload) {
     const existing = sessionBinding(context, project.id, sessionId);
@@ -688,7 +705,7 @@ function projectForHook(context, explicitRoot, cwd) {
         .sort((left, right) => right.root.length - left.root.length)[0];
 }
 function hookEventKey(payload, eventName, toolName, command) {
-    const explicit = stringValue(payload.event_id) ?? stringValue(payload.delivery_id) ?? stringValue(payload.id);
+    const explicit = stringValue(payload.tool_use_id) ?? stringValue(payload.event_id) ?? stringValue(payload.delivery_id) ?? stringValue(payload.id);
     if (explicit)
         return explicit;
     return crypto.createHash("sha256").update(JSON.stringify({

package/dist/services/migrations.js

@@ -232,7 +232,7 @@ function adjacentMigrationChain(source, target) {
 function activeStateSummary(context, projectId) {
     return {
         protocols: context.db.all("SELECT id, status, stage FROM protocols WHERE project_id = ? AND status NOT IN ('closed', 'cancelled') ORDER BY updated_at DESC", [projectId]),
-        runs: context.db.all("SELECT id, status, verdict FROM flow_runs WHERE project_id = ? AND status NOT IN ('done', 'cancelled', 'failed') ORDER BY updated_at DESC", [projectId]),
+        runs: context.db.all("SELECT id, status, verdict FROM flow_runs WHERE project_id = ? AND status = 'running' ORDER BY updated_at DESC", [projectId]),
         merge_queue: context.db.all("SELECT protocol_id, status FROM merge_queue WHERE project_id = ? AND status IN ('ready', 'claimed', 'requeued') ORDER BY updated_at DESC", [projectId]),
         lane_locks: context.db.all("SELECT lane, worker_id, status FROM lane_locks WHERE project_id = ? AND status = 'active' ORDER BY updated_at DESC", [projectId])
     };

package/dist/services/run-projection.js

@@ -1,21 +1,33 @@
 import fs from "node:fs";
 import path from "node:path";
+import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
 export function refreshRunSessionProjection(context, projectId, runId) {
-    const run = context.db.get("SELECT id, project_root, subject_type, subject_id, runtime_path, run_index_path, index_json FROM flow_runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const run = context.db.get("SELECT id, status, project_root, subject_type, subject_id, runtime_path, run_index_path, index_json FROM flow_runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run)
         return;
     const index = JSON.parse(run.index_json);
-    const sessions = context.db.all(`SELECT session_id, parent_session_id, role, session_kind, worker_id, current_stage, status,
+    const sessionRows = context.db.all(`SELECT session_id, parent_session_id, role, session_kind, worker_id, current_stage, status,
             created_at, updated_at, stopped_at, coverage_units_json
-       FROM flow_sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id`, [projectId, runId]).map(sessionProjection);
+       FROM flow_sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id`, [projectId, runId]);
+    const sessions = sessionRows.map(sessionProjection);
+    const coverage = reconcileSessionCoverageRows(sessionRows);
+    const sessionCoverage = {
+        status: coverage.status,
+        expected: coverage.expected_unit_ids,
+        observed: coverage.observed_unit_ids,
+        missing: coverage.missing_unit_ids,
+        diagnostics: coverage.diagnostics
+    };
     const plan = run.subject_type === "protocol" ? planProjection(context, projectId, run.subject_id, run.project_root) : {};
     const workers = workerProjection(context, projectId, runId);
     if (JSON.stringify(index.sessions ?? []) === JSON.stringify(sessions)
+        && JSON.stringify(index.session_coverage) === JSON.stringify(sessionCoverage)
         && JSON.stringify(index.plan_ref) === JSON.stringify(plan.plan_ref)
         && JSON.stringify(index.plan_progress) === JSON.stringify(plan.plan_progress)
         && JSON.stringify(index.workers ?? {}) === JSON.stringify(workers))
         return;
     index.sessions = sessions;
+    index.session_coverage = sessionCoverage;
     if (plan.plan_ref)
         index.plan_ref = plan.plan_ref;
     if (plan.plan_progress)
@@ -31,6 +43,7 @@ export function refreshRunSessionProjection(context, projectId, runId) {
     index.runtime_revision = runtimeRevision;
     const authoritative = runtime ?? { ...index, schema_id: "dd-flow/flow-run@2" };
     authoritative.sessions = sessions;
+    authoritative.session_coverage = sessionCoverage;
     if (plan.plan_ref)
         authoritative.plan_ref = plan.plan_ref;
     if (plan.plan_progress)
@@ -38,7 +51,8 @@ export function refreshRunSessionProjection(context, projectId, runId) {
     authoritative.workers = workers;
     authoritative.updated_at = index.updated_at;
     authoritative.runtime_revision = runtimeRevision;
-    writeJson(run.runtime_path, authoritative);
+    if (run.status !== "discarded" || fs.existsSync(run.runtime_path))
+        writeJson(run.runtime_path, authoritative);
     context.db.run("UPDATE flow_runs SET index_json = ?, updated_at = ? WHERE project_id = ? AND id = ?", [JSON.stringify(index), index.updated_at, projectId, runId]);
 }
 function planProjection(context, projectId, protocolId, projectRoot) {

package/dist/services/runs.js

@@ -428,6 +428,7 @@ export function completeFlowRun(context, input) {
         };
     }
     persistRunState(context, project, run, index);
+    closeRunOrchestrators(context, project.id, run, status, now);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
@@ -439,6 +440,30 @@ export function completeFlowRun(context, input) {
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+function closeRunOrchestrators(context, projectId, run, status, now) {
+    if (!["done", "blocked", "cancelled", "failed"].includes(status))
+        return;
+    const active = context.db.all(`SELECT session_id FROM flow_sessions
+     WHERE project_id = ? AND run_id = ? AND session_kind = 'orchestrator'
+       AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [projectId, run.id]);
+    if (active.length === 0)
+        return;
+    const reason = `run_${status}`;
+    context.db.run(`UPDATE flow_sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
+     WHERE project_id = ? AND run_id = ? AND session_kind = 'orchestrator'
+       AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, projectId, run.id]);
+    context.db.run(`UPDATE flow_session_segments SET ended_at = ?
+     WHERE project_id = ? AND run_id = ? AND session_id IN (${active.map(() => "?").join(", ")}) AND ended_at IS NULL`, [now, projectId, run.id, ...active.map((session) => session.session_id)]);
+    for (const session of active) {
+        appendRunTimeline(runArtifactRoot(run), {
+            at: now,
+            type: "session_stopped",
+            run_id: run.id,
+            session_id: session.session_id,
+            reason
+        });
+    }
+}
 const timelineSections = ["stages", "events", "sessions", "usage", "artifacts"];
 export function getFlowRunTimeline(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -511,6 +536,14 @@ export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
     appendRunTimeline(runArtifactRoot(run), { run_id: run.id, ...event });
 }
 function guidanceForRun(context, run, index) {
+    if (run.status === "discarded") {
+        return buildRunFlowGuidance({
+            stageRuns: index.stage_runs,
+            protocolStage: "cancelled",
+            runId: run.id,
+            runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id)
+        });
+    }
     if (run.subject_type === "protocol") {
         try {
             const protocol = requireProtocol(context, run.subject_id, run.project_id);

package/dist/services/sessions.js

@@ -8,6 +8,7 @@ import { appendAudit } from "./audit.js";
 import { cancelLaneWaitersForWorker } from "./lanes.js";
 import { checkpointSessionUsage } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
+import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
 export function recordFlowSessionObservation(context, input) {
     const duplicate = context.db.get("SELECT id FROM flow_session_segments WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
@@ -99,68 +100,7 @@ export function getFlowSessionStatus(context, input) {
     };
 }
 export function reconcileSessionCoverage(sessions) {
-    const sessionCounts = countValues(sessions.map((session) => session.session_id));
-    const duplicateSessionIds = [...sessionCounts.entries()].filter(([, count]) => count > 1).map(([id]) => id).sort();
-    const invalidSessionIds = [];
-    const parsed = sessions.map((session) => {
-        try {
-            return { session, units: normalizeCoverageUnits(JSON.parse(session.coverage_units_json || "[]")) };
-        }
-        catch {
-            invalidSessionIds.push(session.session_id);
-            return { session, units: [] };
-        }
-    });
-    const orchestrators = parsed.filter(({ session }) => session.session_kind === "orchestrator");
-    const expectedCounts = countValues(orchestrators.flatMap(({ units }) => units.map((unit) => unit.unit_id)));
-    const expectedUnitIds = [...expectedCounts.keys()].sort();
-    const duplicateExpectedUnitIds = [...expectedCounts.entries()].filter(([, count]) => count > 1).map(([id]) => id).sort();
-    const observedOwners = new Map();
-    for (const { session, units } of parsed) {
-        if (session.session_kind === "orchestrator")
-            continue;
-        for (const unit of units) {
-            const owners = observedOwners.get(unit.unit_id) ?? [];
-            owners.push(session.session_id);
-            observedOwners.set(unit.unit_id, owners);
-        }
-    }
-    const observedUnitIds = [...observedOwners.keys()].sort();
-    const missingUnitIds = expectedUnitIds.filter((unitId) => !observedOwners.has(unitId));
-    const duplicateUnitIds = [...observedOwners.entries()].filter(([, owners]) => new Set(owners).size > 1).map(([id]) => id).sort();
-    const diagnostics = [];
-    if (orchestrators.length === 0)
-        diagnostics.push("orchestrator_session_missing");
-    if (orchestrators.length > 1)
-        diagnostics.push("multiple_orchestrator_sessions");
-    if (expectedUnitIds.length === 0)
-        diagnostics.push("expected_worker_units_missing");
-    if (missingUnitIds.length > 0)
-        diagnostics.push("expected_worker_units_unobserved");
-    if (duplicateUnitIds.length > 0 || duplicateExpectedUnitIds.length > 0)
-        diagnostics.push("duplicate_coverage_binding");
-    if (duplicateSessionIds.length > 0)
-        diagnostics.push("duplicate_session_binding");
-    if (invalidSessionIds.length > 0)
-        diagnostics.push("invalid_coverage_units");
-    const unavailable = orchestrators.length === 0 || expectedUnitIds.length === 0 || invalidSessionIds.length > 0;
-    const partial = orchestrators.length !== 1
-        || missingUnitIds.length > 0
-        || duplicateUnitIds.length > 0
-        || duplicateExpectedUnitIds.length > 0
-        || duplicateSessionIds.length > 0;
-    return {
-        status: unavailable ? "unavailable" : partial ? "partial" : "complete",
-        expected_unit_ids: expectedUnitIds,
-        observed_unit_ids: observedUnitIds,
-        missing_unit_ids: missingUnitIds,
-        duplicate_unit_ids: duplicateUnitIds,
-        duplicate_expected_unit_ids: duplicateExpectedUnitIds,
-        duplicate_session_ids: duplicateSessionIds,
-        orchestrator_session_ids: orchestrators.map(({ session }) => session.session_id).sort(),
-        invalid_session_ids: [...new Set(invalidSessionIds)].sort(),
-        diagnostics
-    };
+    return reconcileSessionCoverageRows(sessions);
 }
 export function stopFlowSession(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -245,9 +185,10 @@ export function updateFlowSessionContinuation(context, projectId, sessionId, act
     return nextCount;
 }
 export function flowSessionPayloadFromRegisterCommand(command) {
-    if (!/\bdd-flow\s+session\s+register\b/.test(command)) {
+    if (/\bdd-flow\s+stage\s+start\b/.test(command))
+        return flowSessionPayloadFromStageStartCommand(command);
+    if (!/\bdd-flow\s+session\s+register\b/.test(command))
         return undefined;
-    }
     const payloadBase64 = optionFromCommand(command, "payload-base64");
     const payloadJson = optionFromCommand(command, "payload-json");
     const payloadFile = optionFromCommand(command, "payload-file");
@@ -256,6 +197,25 @@ export function flowSessionPayloadFromRegisterCommand(command) {
     }
     return decodeFlowSessionPayload({ payloadBase64, payloadJson, payloadFile });
 }
+function flowSessionPayloadFromStageStartCommand(command) {
+    const projectRoot = optionFromCommand(command, "project-root");
+    const stage = optionFromCommand(command, "stage");
+    const run = command.match(/\bdd-flow\s+stage\s+start\s+([^\s]+)/)?.[1];
+    if (!projectRoot || !stage || !run || run.startsWith("--"))
+        return undefined;
+    return {
+        project_root: projectRoot,
+        flow_kind: ["code", "implementation", "readiness", "merge"].includes(stage) ? "implementation" : "planning",
+        run_id: run,
+        protocol_id: null,
+        worker_id: null,
+        workspace_path: null,
+        continuation_policy: "go_router",
+        session_kind: "orchestrator",
+        current_stage: stage,
+        coverage_units: []
+    };
+}
 function decodeFlowSessionPayload(input) {
     if (input.payloadFile) {
         return normalizeFlowSessionPayload(parseJsonObject(fs.readFileSync(input.payloadFile, "utf8"), "session payload"));
@@ -485,9 +445,8 @@ function sessionKind(payload) {
 function normalizeCoverageUnits(value) {
     if (value === undefined || value === null)
         return [];
-    if (!Array.isArray(value)) {
+    if (!Array.isArray(value))
         throw new AppError("validation", "coverage_units must be an array", 2);
-    }
     return value.map((item, index) => {
         if (!item || typeof item !== "object" || Array.isArray(item)) {
             throw new AppError("validation", `coverage_units[${index}] must be an object`, 2);
@@ -496,16 +455,17 @@ function normalizeCoverageUnits(value) {
         if (typeof object.unit_id !== "string" || object.unit_id.length === 0) {
             throw new AppError("validation", `coverage_units[${index}].unit_id is required`, 2);
         }
-        const optional = (key) => object[key] === undefined || object[key] === null ? null : typeof object[key] === "string" ? object[key] : (() => { throw new AppError("validation", `coverage_units[${index}].${key} must be a string`, 2); })();
+        const optional = (key) => {
+            const field = object[key];
+            if (field === undefined || field === null)
+                return null;
+            if (typeof field === "string")
+                return field;
+            throw new AppError("validation", `coverage_units[${index}].${key} must be a string`, 2);
+        };
         return { unit_id: object.unit_id, group_id: optional("group_id"), job_id: optional("job_id"), kind: optional("kind") };
     });
 }
-function countValues(values) {
-    const counts = new Map();
-    for (const value of values)
-        counts.set(value, (counts.get(value) ?? 0) + 1);
-    return counts;
-}
 function requiredStringField(payload, key) {
     const value = stringField(payload, key, true);
     if (!value) {

package/dist/services/stage-lifecycle.js

@@ -5,20 +5,106 @@ import { spawnSync } from "node:child_process";
 import { requireProjectByRoot } from "./projects.js";
 import { appendAudit } from "./audit.js";
 import { persistProtocolState, requireProtocol, readProtocolRuntimeState } from "./protocols.js";
-import { attachFlowRunStage, completeFlowRunStage, getFlowRunStatus } from "./runs.js";
+import { attachFlowRunStage, completeFlowRunStage, getFlowRunStatus, startFlowRun } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
-import { reconcileSessionCoverage } from "./sessions.js";
+import { reconcileSessionCoverage, registerFlowSession } from "./sessions.js";
 import { usageForRun } from "./usage.js";
 import { boundCanonicalPlan } from "./plan-runtime.js";
 import { AppError } from "../shared/errors.js";
 import { planJsonPath, resolveProjectRoot } from "../storage/paths.js";
+import { resolveCanonRoot } from "./canon.js";
+import { preflightMemoryPermissions } from "./memory-permissions.js";
+import { registerProject } from "./projects.js";
+import { registerProtocol } from "./protocols.js";
+import { previewNextEntityId } from "./ids.js";
+const stagePromptSections = [
+    "stage_identity",
+    "authoritative_runtime_facts",
+    "preflight",
+    "task_intake",
+    "applicable_instructions",
+    "required_context",
+    "work_contract",
+    "completion_contract"
+];
+function bootstrapStageRun(context, projectRoot, input) {
+    if (input.stage !== "specify") {
+        throw new AppError("validation", "--bootstrap currently starts the initial specify stage only", 2, { stage: input.stage });
+    }
+    const subject = input.bootstrap?.subject.trim();
+    if (!subject)
+        throw new AppError("usage", "--bootstrap requires --subject", 2);
+    registerProject(context, { root: projectRoot });
+    const preview = previewNextEntityId(context, { projectRoot, type: "protocol", slug: subject });
+    const protocolId = preview.entity.id;
+    registerProtocol(context, { handshakeId: protocolId, projectRoot });
+    const started = startFlowRun(context, {
+        projectRoot,
+        flowKind: "mb_sdlc",
+        subjectType: "protocol",
+        subjectId: protocolId,
+        slug: subject,
+        nextAction: "run_specify"
+    });
+    const intakeFile = input.bootstrap?.intakeFile;
+    if (intakeFile) {
+        const source = path.resolve(intakeFile);
+        if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+            throw new AppError("not_found", "--intake-file must point to an existing file", 1, { intake_file: intakeFile });
+        }
+        const intakeDir = path.join(started.run.run_home_path ?? path.dirname(started.run.id), "intake");
+        fs.mkdirSync(intakeDir, { recursive: true });
+        fs.copyFileSync(source, path.join(intakeDir, "user-request.md"));
+    }
+    return started.run.id;
+}
+function stagePreflight(projectRoot, stageRoot) {
+    const memoryBank = preflightMemoryPermissions({
+        root: projectRoot,
+        memoryBank: ".memory-bank",
+        flow: "custom",
+        mode: "write",
+        targets: [{ path: ".memory-bank", mode: "read" }]
+    });
+    const probe = path.join(stageRoot, `.dd-flow-permission-${crypto.randomUUID()}`);
+    try {
+        fs.writeFileSync(probe, "");
+        fs.renameSync(probe, `${probe}.renamed`);
+        fs.rmSync(`${probe}.renamed`);
+        return { ...memoryBank, ok: memoryBank.ok === true, stage_workspace: { path: stageRoot, status: "passed" } };
+    }
+    catch (error) {
+        for (const candidate of [probe, `${probe}.renamed`]) {
+            try {
+                fs.rmSync(candidate, { force: true });
+            }
+            catch { /* best effort */ }
+        }
+        return { ...memoryBank, ok: false, stage_workspace: { path: stageRoot, status: "failed", message: String(error) } };
+    }
+}
+function flowKindForStage(stage) {
+    return ["code", "implementation", "readiness", "merge"].includes(stage) ? "implementation" : "planning";
+}
+function runtimeFacts(view, projectRoot) {
+    return {
+        project_root: projectRoot,
+        workspace_root: view.run.workspace_root,
+        run_id: view.run.id,
+        protocol_id: view.run.subject.id,
+        git: view.index.execution?.git ?? { branch: null, head: null, status: "unavailable" }
+    };
+}
 export function startStage(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const before = runView(getFlowRunStatus(context, { projectRoot, runId: input.runId }));
-    const dir = input.dir ?? defaultStageDir(input.stage);
+    const runId = input.bootstrap ? bootstrapStageRun(context, projectRoot, input) : input.runId;
+    if (!runId)
+        throw new AppError("usage", "stage start requires a RUN id or --bootstrap", 2);
+    const before = runView(getFlowRunStatus(context, { projectRoot, runId }));
+    const dir = input.dir ?? defaultStageDir(input.stage, before.run.flow_kind);
     const attached = runView(attachFlowRunStage(context, {
         projectRoot,
-        runId: input.runId,
+        runId,
         stage: input.stage,
         dir,
         status: "running",
@@ -28,9 +114,29 @@ export function startStage(context, input) {
     const stageRoot = path.join(runHome, dir);
     ensureWithin(runHome, stageRoot, "stage root");
     fs.mkdirSync(stageRoot, { recursive: true });
+    const preflight = stagePreflight(projectRoot, stageRoot);
+    if (preflight.ok !== true)
+        throw new AppError("permission_preflight_failed", "Stage workspace is not writable", 1, { preflight });
     syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
+    if (input.sessionId) {
+        registerFlowSession(context, {
+            sessionId: input.sessionId,
+            payloadJson: JSON.stringify({
+                project_root: projectRoot,
+                flow_kind: flowKindForStage(input.stage),
+                run_id: attached.run.id,
+                protocol_id: attached.run.subject.id,
+                worker_id: null,
+                workspace_path: attached.run.workspace_root,
+                continuation_policy: "go_router",
+                session_kind: "orchestrator",
+                current_stage: input.stage,
+                cwd: attached.run.workspace_root
+            })
+        });
+    }
     const promptPath = path.join(stageRoot, "stage-prompt.md");
-    const prompt = composeStagePrompt(context, projectRoot, before, attached, input.stage, dir);
+    const prompt = composeStagePrompt(context, projectRoot, before, attached, input.stage, dir, preflight);
     atomicWrite(promptPath, prompt);
     const promptDataPath = path.join(stageRoot, "stage-prompt.json");
     const planPath = planJsonPath(projectRoot, attached.run.subject.id);
@@ -38,12 +144,12 @@ export function startStage(context, input) {
     const attempt = attached.index.stage_runs?.find((stage) => stage.stage === input.stage)?.attempt ?? "try-001";
     const attemptNumber = Number(attempt.replace("try-", "")) || 1;
     atomicWrite(promptDataPath, {
-        schema_id: "dd-flow/stage-prompt@1",
+        schema_id: "dd-flow/stage-prompt@2",
         run_id: attached.run.id,
         stage: input.stage,
         generated_at: context.now(),
         prompt_path: promptPath,
-        sections: ["stage_identity", "runtime_context", "intake", "applicable_instructions", "stage_cli", "file_boundaries", "completion_contract"],
+        sections: stagePromptSections,
         aliases: {
             project: projectRoot,
             workspace: attached.run.workspace_root,
@@ -54,11 +160,15 @@ export function startStage(context, input) {
             ...(input.stage === "plan" ? { plan: planPath, "aspect-map": aspectMapPath } : {})
         },
         write_boundary: { current: "@stage", archive: attempt, archive_writable: false },
-        source_fragments: input.stage === "plan" ? [".memory-bank/dd-flow/plan.md"] : [".memory-bank/dd-flow/code.md", ".memory-bank/dd-flow/mb-sdlc/code/implement.md"]
+        source_fragments: stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage).map((source) => source.label),
+        authoritative_facts: runtimeFacts(attached, projectRoot),
+        preflight,
+        required_context: stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage).map((source) => source.label),
+        worker_prompt_markdown: prompt
     });
     validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot });
     atomicWrite(path.join(stageRoot, "stage-start.json"), {
-        schema_id: "dd-flow/stage-start@1",
+        schema_id: "dd-flow/stage-start@2",
         run_id: attached.run.id,
         stage: input.stage,
         dir,
@@ -68,7 +178,7 @@ export function startStage(context, input) {
     });
     return {
         ok: true,
-        schema_id: "dd-flow/stage-start-response@1",
+        schema_id: "dd-flow/stage-start-response@2",
         run_id: attached.run.id,
         stage: input.stage,
         attempt_number: attemptNumber,
@@ -86,32 +196,33 @@ export function startStage(context, input) {
         },
         ...(input.stage === "plan" ? { plan_ref: planPath, aspect_map_ref: aspectMapPath } : {}),
         resolved_context: { run: attached.run, stage: { name: input.stage, dir, status: "running" } },
-        next_command: "dd-flow stage finish",
-        permission_probe: { status: "known_targets_only", project_root: projectRoot },
+        next_command: `dd-flow stage finish ${attached.run.id} --stage ${input.stage} --outcome done --project-root ${JSON.stringify(projectRoot)} --json`,
+        permission_probe: preflight,
         run: attached.run,
         prompt: { path: promptPath, data_path: promptDataPath },
+        worker_prompt_markdown: prompt,
         lifecycle: "stage start -> semantic work -> stage finish"
     };
 }
 export function finishStage(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const view = runView(getFlowRunStatus(context, { projectRoot, runId: input.runId }));
+    if (!input.runId)
+        throw new AppError("usage", "stage finish requires a RUN id", 2);
+    const runId = input.runId;
+    const view = runView(getFlowRunStatus(context, { projectRoot, runId }));
     const existing = view.index.stage_runs?.find((stage) => stage.stage === input.stage);
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${input.stage}`, 1, { run_id: view.run.id, stage: input.stage });
     }
-    const dir = existing.dir ?? input.dir ?? defaultStageDir(input.stage);
+    const dir = existing.dir ?? input.dir ?? defaultStageDir(input.stage, view.run.flow_kind);
     const runHome = runHomePath(view.run);
     const stageRoot = path.join(runHome, dir);
     ensureWithin(runHome, stageRoot, "stage root");
     fs.mkdirSync(stageRoot, { recursive: true });
-    if (!input.semanticFile) {
-        throw new AppError("stage_finish_input_required", "Stage finish requires --semantic-file with dd-flow/stage-finish-input@1", 2);
-    }
-    const semanticFile = resolveStageFile(input.semanticFile, stageRoot, runHome);
+    const semanticFile = resolveStageFile(input.semanticFile ?? "@stage/stage-input.json", stageRoot, runHome);
     validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot });
     const semantic = readSemanticFile(semanticFile, runHome);
-    const status = input.status ?? "done";
+    const status = input.outcome ?? "done";
     if (!["done", "blocked", "failed"].includes(status)) {
         throw new AppError("validation", "Stage finish status must be done, blocked, or failed", 2, { status });
     }
@@ -135,7 +246,7 @@ export function finishStage(context, input) {
     const summaryPath = updateProtocolSummary(context, projectRoot, view, report, dataPath, htmlPath, reportPath);
     const completed = completeFlowRunStage(context, {
         projectRoot,
-        runId: input.runId,
+        runId,
         stage: input.stage,
         status,
         stageReport: htmlPath,
@@ -223,8 +334,20 @@ function nextActionForProtocolStage(stage) {
 function runHomePath(run) {
     return run.run_home_path ?? path.dirname(run.run_index_path);
 }
-function defaultStageDir(stage) {
+export function defaultStageDir(stage, flowKind) {
     const normalized = stage === "implementation" ? "code" : stage;
+    if (flowKind === "mb-upgrade") {
+        const upgrade = {
+            preflight: "01-preflight",
+            "diff-analysis": "02-diff-analysis",
+            upgrade: "03-upgrade",
+            lint: "04-lint",
+            review: "05-review",
+            merge: "06-merge"
+        };
+        if (upgrade[normalized])
+            return upgrade[normalized];
+    }
     const known = { specify: "01-specify", plan: "02-plan", code: "03-code", readiness: "03-code", merge: "04-merge" };
     return known[normalized] ?? `03-${normalized.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
 }
@@ -237,54 +360,96 @@ function dataSchemaForStage(stage) {
         return "dd-flow/merge-stage-report@2";
     return "dd-flow/code-stage-report@2";
 }
-function composeStagePrompt(context, projectRoot, before, current, stage, dir) {
+function composeStagePrompt(context, projectRoot, before, current, stage, dir, preflight) {
     const project = requireProjectByRoot(context, projectRoot);
     const runHome = runHomePath(current.run);
-    const flowFiles = stage === "plan"
-        ? [".memory-bank/dd-flow/plan.md"]
-        : [".memory-bank/dd-flow/code.md", ".memory-bank/dd-flow/mb-sdlc/code/implement.md"];
-    const instructions = flowFiles.map((file) => {
-        const absolute = path.join(projectRoot, file);
-        return fs.existsSync(absolute) ? `### ${file}\n\n${fs.readFileSync(absolute, "utf8").trim()}` : `### ${file}\n\n(unavailable)`;
+    const instructions = stageInstructionSources(context, projectRoot, current.run.flow_kind, stage).map(({ label, absolute }) => {
+        return fs.existsSync(absolute) ? `### ${label}\n\n${fs.readFileSync(absolute, "utf8").trim()}` : `### ${label}\n\n(unavailable)`;
     }).join("\n\n");
     const protocol = safeProtocolState(context, current.run.project_id, current.run.subject.id);
+    const requiredContext = stageInstructionSources(context, projectRoot, current.run.flow_kind, stage)
+        .map(({ label }) => `- Read: \`${label}\``).join("\n");
     return [
-        "# Stage Prompt",
-        "",
-        "## Identity",
+        "<stage_identity>",
+        "# Stage work packet",
         `- Project: ${project.id}`,
         `- Run: ${current.run.id}`,
         `- Protocol: ${current.run.subject.id}`,
         `- Stage: ${stage}`,
         `- Attempt: ${current.index.stage_runs?.find((item) => item.stage === stage)?.attempt ?? "try-001"}`,
+        "</stage_identity>",
         "",
-        "## Runtime",
+        "<authoritative_runtime_facts>",
+        "These facts were collected by dd-flow. Trust them; do not re-run CLI, Git, compatibility, or permission discovery unless the semantic work changes the relevant state.",
         `- Project root: ${projectRoot}`,
         `- Workspace root: ${current.run.workspace_root}`,
         `- Run home: ${runHome}`,
         `- Stage root: ${path.join(runHome, dir)}`,
         `- Git branch: ${current.index.execution?.git?.branch ?? "unknown"}`,
         `- Git head: ${current.index.execution?.git?.head ?? "unknown"}`,
+        "</authoritative_runtime_facts>",
+        "",
+        "<preflight>",
+        `- Permission probe: ${String(preflight.ok === true ? "passed" : "failed")}.`,
+        "- CLI compatibility was checked before this state-changing command.",
+        "</preflight>",
         "",
-        "## Intake",
+        "<task_intake>",
         "Raw intake and provider telemetry stay under the RUN home. Promote only durable decisions to the protocol summary.",
         `- Protocol next action: ${protocol?.next_action ?? "not recorded"}`,
         `- Previous stage: ${before.index.stage_runs?.map((item) => `${item.stage}:${item.status}`).join(", ") || "none"}`,
+        "</task_intake>",
         "",
-        "## Instructions",
+        "<applicable_instructions>",
         instructions,
+        "</applicable_instructions>",
         "",
-        "## CLI",
-        "Use the project-compatible dd-flow CLI for state transitions and artifact registration. Keep paths inside the selected workspace and RUN home.",
+        "<required_context>",
+        requiredContext || "- No additional stage-specific source is required.",
+        "</required_context>",
         "",
-        "## Boundaries",
-        "Do not use raw Git as a workspace manager, unverified tools, PATH/latest fallbacks, recursive unrelated validation, or model-supplied session identity.",
+        "<work_contract>",
+        "Perform only the semantic work for this stage. Write current-stage artifacts to `@stage`; `@stage/try-NNN` is read-only archive history.",
+        "Do not repeat deterministic preflight, global CLI help, runtime/Git inspection, session registration, report rendering, summary generation, or state transition work.",
+        "</work_contract>",
         "",
-        "## Completion Contract",
-        `Finish with: dd-flow stage finish ${current.run.id} --stage ${stage} --project-root <project-root> --semantic-file @stage/stage-input.json --json`,
+        "<completion_contract>",
+        `Write semantic output to \`@stage/stage-input.json\`, then run: \`dd-flow stage finish ${current.run.id} --stage ${stage} --outcome done --project-root ${JSON.stringify(projectRoot)} --json\`.`,
         "The CLI must generate validated JSON, Markdown, HTML and protocol-summary evidence.",
+        "</completion_contract>",
     ].join("\n");
 }
+function stageInstructionSources(context, projectRoot, flowKind, stage) {
+    if (flowKind === "mb-upgrade") {
+        const canon = resolveCanonRoot(context);
+        if (!canon.ok || !canon.canon) {
+            throw new AppError("canon_unavailable", "mb-upgrade stage prompt requires the canonical Memory Bank", 1, {
+                blockers: canon.blockers,
+                bootstrap: canon.bootstrap
+            });
+        }
+        const flowRoot = canon.canon.flow_root;
+        const stageSupport = {
+            "diff-analysis": "mb-upgrade/diff-analysis.md",
+            lint: "mb-upgrade/lint-verification.md",
+            review: "mb-upgrade/review/index.md",
+            merge: "mb-upgrade/merge.md"
+        };
+        return ["mb-upgrade.md", "mb-upgrade/index.md", stageSupport[stage]]
+            .filter((file) => Boolean(file))
+            .map((file) => ({ label: `canonical:${file}`, absolute: path.join(flowRoot, file) }));
+    }
+    const filesByStage = {
+        specify: [".memory-bank/dd-flow/mb-sdlc/specify/stage.md"],
+        plan: [".memory-bank/dd-flow/plan.md"],
+        code: [".memory-bank/dd-flow/code.md", ".memory-bank/dd-flow/mb-sdlc/code/implement.md"],
+        implementation: [".memory-bank/dd-flow/code.md", ".memory-bank/dd-flow/mb-sdlc/code/implement.md"],
+        readiness: [".memory-bank/dd-flow/mb-sdlc/code/readiness.md"],
+        merge: [".memory-bank/dd-flow/merge.md"]
+    };
+    const files = filesByStage[stage] ?? [".memory-bank/dd-flow/mb-sdlc/specify/stage.md"];
+    return files.map((file) => ({ label: file, absolute: path.join(projectRoot, file) }));
+}
 function safeProtocolState(context, projectId, protocolId) {
     try {
         const protocol = requireProtocol(context, protocolId, projectId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {