@deksden-com/dd-flow-cli 0.9.0-beta.13 → 0.9.0-beta.134

package/dist/harness-runtime/lib/zcode-usage.mjs

@@ -0,0 +1,55 @@
+/** Accounting policy over native evidence; the bridge only exposes native RPCs. */
+export function normalizeZcodeUsage(usage, read) {
+  const result = { ...usage, requestUsageStatus: "unavailable" };
+  const totals = { requestTotalTokens: 0, requestInputTokens: 0, requestOutputTokens: 0,
+    requestReasoningTokens: 0, requestCacheCreationTokens: 0, requestCacheReadTokens: 0, requestCount: 0 };
+  const seen = new Map();
+  let incomplete = !Array.isArray(read?.messages);
+  for (const message of Array.isArray(read?.messages) ? read.messages : []) {
+    const info = message?.info;
+    if (info?.role !== "assistant") continue;
+    // Native history includes system timeline markers with role=assistant and
+    // zero token placeholders, but no model request (and no total counter).
+    if (info.semantics?.origin === "system" && info.semantics?.kind === "timeline_event") continue;
+    if (!info.tokens) { incomplete = true; continue; }
+    const tokens = info.tokens;
+    const id = info.messageId ?? info.id ?? message.id;
+    if (id) {
+      const signature = JSON.stringify(tokens);
+      if (seen.has(id)) { if (seen.get(id) !== signature) incomplete = true; continue; }
+      seen.set(id, signature);
+    }
+    const values = [tokens.total, tokens.input, tokens.output];
+    if (!values.every(valid)) { incomplete = true; continue; }
+    totals.requestTotalTokens += tokens.total;
+    totals.requestInputTokens += tokens.input;
+    totals.requestOutputTokens += tokens.output;
+    for (const [key, value] of [["requestReasoningTokens", tokens.reasoning],
+      ["requestCacheCreationTokens", tokens.cache?.write], ["requestCacheReadTokens", tokens.cache?.read]]) {
+      if (value == null) totals[key] = null;
+      else if (!valid(value)) incomplete = true;
+      else if (totals[key] !== null) totals[key] += value;
+    }
+    totals.requestCount++;
+  }
+  if (totals.requestCount && !incomplete) Object.assign(result, totals, { requestUsageStatus: "measured" });
+  if (incomplete) result.usageIsIncomplete = true;
+  return result;
+}
+
+function valid(value) { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+
+export async function readZcodeUsage(bridge, sessionId) {
+  const usage = await bridge.request("zcode/session/usage", { sessionId });
+  // Compatibility with immutable @1 bridges: they already expose this projection.
+  if (usage?.requestUsageStatus === "measured") return usage;
+  try {
+    // Unbounded native read is intentional: accounting needs the full history,
+    // unlike turn liveness reads which may use messageLimit: 1.
+    const read = await bridge.request("zcode/session/read", { sessionId });
+    return normalizeZcodeUsage(usage, read);
+  } catch (error) {
+    return { ...usage, requestUsageStatus: "unavailable", usageIsIncomplete: true,
+      requestUsageError: { code: error.code ?? "usage_evidence_failed", message: error.message, ...(error.details ? { details: error.details } : {}) } };
+  }
+}

package/dist/protocol/local-files.js

@@ -62,16 +62,12 @@ export function ensureProtocolFiles(input) {
     writeState(statePath, { ...state, flow_contract: flowContract, updated_at: input.now });
     return { ...state, flow_contract: flowContract, updated_at: input.now };
 }
-export function ensureRuntimeProtocolFiles(input) {
+/** Read legacy state and prepare a registration without publishing files. */
+export function prepareRuntimeProtocolFiles(input) {
     const currentFlowContract = loadProjectFlowContract(input.projectRoot);
     const statePath = path.join(input.runtimeDir, "state.json");
     const existing = readStateIfExists(statePath);
     const flowContract = existing?.flow_contract ?? currentFlowContract;
-    ensureDir(input.runtimeDir);
-    const metadataPath = path.join(input.runtimeDir, "metadata.json");
-    if (!fs.existsSync(metadataPath)) {
-        fs.writeFileSync(metadataPath, `${JSON.stringify({ protocol_id: input.protocolId, handshake_id: input.handshakeId, project_root: input.projectRoot }, null, 2)}\n`);
-    }
     const state = existing ??
         {
             schema_version: schemaVersion,
@@ -103,9 +99,22 @@ export function ensureRuntimeProtocolFiles(input) {
             updated_at: input.now
         };
     const workspace = input.workspacePath ? { ...state.workspace, worktree_path: input.workspacePath } : state.workspace;
-    const nextState = { ...state, workspace, flow_contract: flowContract, updated_at: input.now };
-    writeState(statePath, nextState);
-    return nextState;
+    return { ...state, workspace, flow_contract: flowContract, updated_at: input.now };
+}
+/** Metadata is a retained write-once compatibility artifact, never authority. */
+export function publishRuntimeProtocolMetadata(input) {
+    ensureDir(input.runtimeDir);
+    const metadataPath = path.join(input.runtimeDir, "metadata.json");
+    if (fs.existsSync(metadataPath))
+        return;
+    const bytes = `${JSON.stringify({ protocol_id: input.protocolId, handshake_id: input.handshakeId, project_root: input.projectRoot }, null, 2)}\n`;
+    try {
+        fs.writeFileSync(metadataPath, bytes, { flag: "wx" });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
 }
 export function readState(projectRoot, protocolId) {
     return readStateFile(stateJsonPath(projectRoot, protocolId), protocolId);

package/dist/runtime/context.js

@@ -1,18 +1,22 @@
 import { getDatabase } from "../storage/database.js";
 import { resolveDdFlowHome } from "../storage/paths.js";
-export function createRouterContext(env) {
+import { assertImportAdmission } from "../storage/import-guard.js";
+export function createRouterContext(env, deadlineAt) {
     const ddFlowHome = resolveDdFlowHome(env);
     return {
         ddFlowHome,
-        db: getDatabase(ddFlowHome, "read_existing"),
+        db: getDatabase(ddFlowHome, "read_existing", undefined, deadlineAt),
         now: () => new Date().toISOString()
     };
 }
-export function createContext(env, mode = "initialize") {
+export function createContext(env, mode = "initialize", importPermitId, options = {}) {
     const ddFlowHome = resolveDdFlowHome(env);
+    if (options.resourceDatabaseMode === "prepared_existing" || options.resourceDatabaseMode === "initialize")
+        assertImportAdmission(ddFlowHome, importPermitId);
     return {
         ddFlowHome,
-        db: getDatabase(ddFlowHome, mode),
+        db: getDatabase(ddFlowHome, mode, importPermitId, options.databaseDeadlineAt ?? (mode === "hook" && env.DD_FLOW_HOOK_DEADLINE_AT ? Number(env.DD_FLOW_HOOK_DEADLINE_AT) : undefined)),
+        ...options,
         env,
         now: () => new Date().toISOString()
     };

package/dist/schemas/agent-profile.schema.json

@@ -7,7 +7,7 @@
   "properties": {
     "schema_id": {"const": "dd-flow/agent-profile@1"},
     "id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"},
-    "harness": {"enum": ["codex", "zcode", "agy", "opencode", "grok"]},
+    "harness": {"enum": ["codex", "zcode", "agy", "opencode", "grok", "droid"]},
     "provider": {"type": "string", "minLength": 1},
     "model": {"type": "string", "minLength": 1},
     "reasoning": {"type": "string", "minLength": 1},

package/dist/schemas/code-review-result.schema.json

@@ -8,7 +8,7 @@
     "schema_id": {"const": "dd-flow/code-review-result@1"},
     "verdict": {"enum": ["pass", "findings", "blocked"]},
     "summary": {"type": "string", "minLength": 1},
-    "aspects": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["aspect_id", "verdict", "summary", "evidence_refs"], "properties": {"aspect_id": {"type": "string", "minLength": 1}, "verdict": {"enum": ["pass", "findings", "blocked"]}, "summary": {"type": "string", "minLength": 1}, "evidence_refs": {"type": "array", "items": {"type": "string"}}}}},
+    "aspects": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["aspect_id", "verdict", "summary", "evidence_refs"], "properties": {"aspect_id": {"type": "string", "minLength": 1}, "verdict": {"enum": ["pass", "findings", "blocked"]}, "summary": {"type": "string", "minLength": 1}, "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}}}},
     "findings": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["finding_id", "aspect_id", "priority", "problem", "impact", "required_outcome", "evidence_refs", "obligation_refs"], "properties": {"finding_id": {"type": "string", "pattern": "^FIND-[0-9]{3}$"}, "aspect_id": {"type": "string", "minLength": 1}, "priority": {"enum": ["p0", "p1", "p2", "p3"]}, "problem": {"type": "string", "minLength": 1}, "impact": {"type": "string", "minLength": 1}, "required_outcome": {"type": "string", "minLength": 1}, "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, "obligation_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}}}}
   }
 }

package/dist/schemas/code-verification.schema.json

@@ -1,14 +1,16 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "dd-flow/code-verification@2",
+  "$id": "dd-flow/code-verification@3",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_id", "verdict", "summary", "unresolved", "deviations"],
   "properties": {
-    "schema_id": {"const": "dd-flow/code-verification@2"},
-    "verdict": {"enum": ["passed", "needs_repair", "blocked"]},
+    "schema_id": {"enum": ["dd-flow/code-verification@2", "dd-flow/code-verification@3"]},
+    "verdict": {"enum": ["passed", "needs_repair", "needs_checks", "blocked"]},
     "summary": {"type": "string", "minLength": 1},
     "unresolved": {"type": "array", "items": {"type": "string", "minLength": 1}},
-    "deviations": {"type": "array", "items": {"type": "string", "minLength": 1}}
-  }
+    "deviations": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "document_updates": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}
+  },
+  "allOf": [{"if": {"properties": {"schema_id": {"const": "dd-flow/code-verification@2"}}}, "then": {"properties": {"verdict": {"enum": ["passed", "needs_repair", "blocked"]}}, "not": {"required": ["document_updates"]}}}]
 }

package/dist/schemas/code-work-batch.schema.json

@@ -16,10 +16,10 @@
     "spine": {"type": "object", "additionalProperties": false, "required": ["user_outcome", "component_responsibility", "must_preserve", "non_goals", "acceptance_contribution"], "properties": {"user_outcome": {"type": "string", "minLength": 1}, "component_responsibility": {"type": "string", "minLength": 1}, "must_preserve": {"$ref": "#/$defs/strings"}, "non_goals": {"$ref": "#/$defs/stringList"}, "acceptance_contribution": {"type": "string", "minLength": 1}}},
     "obligation": {"type": "object", "additionalProperties": false, "required": ["id", "statement"], "properties": {"id": {"type": "string", "minLength": 1}, "statement": {"type": "string", "minLength": 1}}},
     "acceptance": {"type": "object", "additionalProperties": false, "required": ["criterion_id", "path", "environment", "fixtures", "cleanup", "check_refs", "expected_evidence", "proof_limits", "gate"], "properties": {"criterion_id": {"type": "string", "pattern": "^AC-[0-9]+$"}, "path": {"type": "string", "minLength": 1}, "environment": {"type": "string", "minLength": 1}, "fixtures": {"$ref": "#/$defs/stringList"}, "cleanup": {"type": "string", "minLength": 1}, "check_refs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "expected_evidence": {"$ref": "#/$defs/strings"}, "proof_limits": {"$ref": "#/$defs/strings"}, "gate": {"type": "string", "minLength": 1}}},
-    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "minLength": 1}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}]},
+    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "minLength": 1}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}, "inputs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "reuse": {"const": "deterministic"}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}]},
     "documentUpdate": {"type": "object", "additionalProperties": false, "required": ["path", "action", "owner", "reason", "baseline_sha256"], "properties": {"path": {"type": "string", "minLength": 1}, "action": {"enum": ["create", "update"]}, "owner": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}, "baseline_sha256": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}}},
     "reviewFinding": {"type": "object", "additionalProperties": false, "required": ["finding_ref", "priority", "problem", "impact", "required_outcome", "evidence_refs", "obligation_refs", "decision_reason", "check_refs"], "properties": {"finding_ref": {"type": "string", "minLength": 1}, "priority": {"enum": ["p0", "p1", "p2", "p3"]}, "problem": {"type": "string", "minLength": 1}, "impact": {"type": "string", "minLength": 1}, "required_outcome": {"type": "string", "minLength": 1}, "evidence_refs": {"$ref": "#/$defs/strings"}, "obligation_refs": {"$ref": "#/$defs/strings"}, "decision_reason": {"type": "string", "minLength": 1}, "check_refs": {"$ref": "#/$defs/strings"}}},
-    "repair": {"type": "object", "additionalProperties": false, "required": ["origin_work_ids"], "anyOf": [{"required": ["check_receipt_id", "failure_receipt_path"]}, {"required": ["review_findings"]}, {"required": ["semantic_unresolved", "verification_path"]}], "properties": {"origin_work_ids": {"$ref": "#/$defs/strings"}, "check_receipt_id": {"type": "string", "minLength": 1}, "failure_receipt_path": {"type": "string", "minLength": 1}, "review_findings": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/reviewFinding"}}, "semantic_unresolved": {"$ref": "#/$defs/strings"}, "verification_path": {"type": "string", "minLength": 1}}},
+    "repair": {"type": "object", "additionalProperties": false, "required": ["origin_work_ids", "verification_check_refs"], "anyOf": [{"required": ["check_receipt_id", "failure_receipt_path"]}, {"required": ["review_findings"]}, {"required": ["semantic_unresolved", "verification_path"]}], "properties": {"origin_work_ids": {"$ref": "#/$defs/strings"}, "check_receipt_id": {"type": "string", "minLength": 1}, "failure_receipt_path": {"type": "string", "minLength": 1}, "review_findings": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/reviewFinding"}}, "semantic_unresolved": {"$ref": "#/$defs/strings"}, "verification_path": {"type": "string", "minLength": 1}, "verification_check_refs": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/check"}}}},
     "work": {"type": "object", "additionalProperties": false, "required": ["schema_id", "key", "launch_policy", "source", "task", "semantic_spine", "requirements", "acceptance", "document_updates", "required_read", "discovery_boundary", "planned_write_areas", "checks", "provides_checks", "stop_conditions", "depends_on", "result_schema"], "properties": {"schema_id": {"const": "dd-flow/code-work-packet@5"}, "key": {"type": "string", "minLength": 1}, "launch_policy": {"const": "fresh_agent_required"}, "source": {"$ref": "#/$defs/source"}, "repair": {"$ref": "#/$defs/repair"}, "task": {"type": "string", "minLength": 1}, "semantic_spine": {"$ref": "#/$defs/spine"}, "requirements": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/obligation"}}, "acceptance": {"type": "array", "items": {"$ref": "#/$defs/acceptance"}}, "document_updates": {"type": "array", "items": {"$ref": "#/$defs/documentUpdate"}}, "required_read": {"$ref": "#/$defs/strings", "description": "Mandatory starting sources, not a read allowlist."}, "discovery_boundary": {"$ref": "#/$defs/strings", "description": "Likely discovery areas; additional project-local reads are allowed."}, "planned_write_areas": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Soft coordination hints only. A worker may change any necessary project file inside the RUN workspace."}, "checks": {"type": "array", "items": {"$ref": "#/$defs/check"}}, "provides_checks": {"type": "array", "items": {"$ref": "#/$defs/check"}}, "stop_conditions": {"$ref": "#/$defs/strings", "description": "Hard semantic or external stop conditions; path prediction drift is not a stop condition."}, "depends_on": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "result_schema": {"const": "dd-flow/code-work-result@3"}}}
   }
 }

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

@@ -12,6 +12,8 @@
     "project": {"$ref": "#/definitions/identity"},
     "subject": {"$ref": "#/definitions/identity"},
     "flow_kind": {"type": "string", "minLength": 1},
+    "verification_matrix_contract": {"const": "dd-flow/verification-matrix@1"},
+    "final_check_coverage_contract": {"const": "dd-flow/final-check-coverage@1"},
     "status": {"enum": ["created", "running", "paused", "waiting_for_user", "done", "failed", "blocked", "cancelled", "discarded"]},
     "verdict": {"type": ["string", "null"]},
     "started_at": {"type": "string", "format": "date-time"},

package/dist/schemas/plan-review-decision.schema.json

@@ -1,14 +1,14 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/plan-review-decision@3",
+  "$id": "dd-flow/plan-review-decision@4",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_id", "outcome", "summary", "finding_decisions", "correction"],
   "properties": {
-    "schema_id": {"const": "dd-flow/plan-review-decision@3"},
+    "schema_id": {"const": "dd-flow/plan-review-decision@4"},
     "outcome": {"enum": ["accepted", "failed", "cancelled"]},
     "summary": {"type": "string", "minLength": 1},
-    "finding_decisions": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["finding_ref", "decision", "reason"], "properties": {"finding_ref": {"type": "string", "pattern": "^WRK-[^/]+/FIND-[0-9]{3}$"}, "decision": {"enum": ["accepted_fix", "rejected", "deferred_as_DEF", "requires_user", "duplicate"]}, "reason": {"type": "string", "minLength": 1}}}},
+    "finding_decisions": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["finding_ref", "decision", "reason"], "properties": {"finding_ref": {"type": "string", "pattern": "^WRK-[^/]+/FIND-[0-9]{3}$"}, "decision": {"enum": ["accepted_fix", "rejected", "deferred_as_DEF", "requires_user", "duplicate"]}, "reason": {"type": "string", "minLength": 1}, "duplicate_of": {"type": "string", "pattern": "^WRK-[^/]+/FIND-[0-9]{3}$"}, "def_id": {"type": "string", "pattern": "^DEF-[A-Za-z0-9][A-Za-z0-9_-]*$"}}}},
     "correction": {"type": "object", "additionalProperties": false, "required": ["status", "previous_plan_revision", "changed_paths", "summary"], "properties": {"status": {"enum": ["applied", "not_required"]}, "previous_plan_revision": {"type": "integer", "minimum": 1}, "changed_paths": {"type": "array", "items": {"type": "string", "minLength": 1}}, "summary": {"type": "string", "minLength": 1}}}
   }
 }

package/dist/schemas/plan-review-result.schema.json

@@ -20,7 +20,7 @@
           "aspect_id": {"type": "string", "minLength": 1},
           "verdict": {"enum": ["pass", "watch", "needs_changes", "blocked"]},
           "summary": {"type": "string", "minLength": 1},
-          "evidence_refs": {"type": "array", "items": {"type": "string", "minLength": 1}},
+          "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
           "findings": {
             "type": "array",
             "items": {
@@ -31,7 +31,7 @@
                 "finding_id": {"type": "string", "pattern": "^FIND-[0-9]{3}$"},
                 "severity": {"enum": ["blocker", "high", "medium", "low", "info"]},
                 "summary": {"type": "string", "minLength": 1},
-                "evidence_refs": {"type": "array", "items": {"type": "string", "minLength": 1}}
+                "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
               }
             }
           }

package/dist/schemas/run-control-receipt.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dd-flow/run-control-receipt@1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "ok", "request_id", "control_id", "scope", "generation", "requested_mode", "applied_mode", "state", "settled", "nodes", "unsettled_reasons", "resumability"],
+  "properties": {
+    "schema_id": { "const": "dd-flow/run-control-receipt@1" },
+    "ok": { "const": true },
+    "request_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 128 },
+    "control_id": { "type": ["string", "null"], "pattern": "^CTL-[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "scope": {
+      "type": "object", "additionalProperties": false,
+      "required": ["project_id", "run_id"],
+      "properties": {
+        "project_id": { "type": "string", "minLength": 1 },
+        "run_id": { "type": "string", "pattern": "^RUN-[A-Za-z0-9][A-Za-z0-9._-]*$" }
+      }
+    },
+    "generation": { "type": "integer", "minimum": 0 },
+    "requested_mode": { "enum": [null, "pause", "stop", "resume"] },
+    "applied_mode": { "enum": [null, "pause", "stop", "resume"] },
+    "state": { "enum": ["not_requested", "pause_requested", "paused", "stop_requested", "stopped", "resuming", "running", "terminal_noop", "superseded", "recovery_required"] },
+    "settled": { "type": "boolean" },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["id", "role", "status", "acknowledged", "settled", "reason"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "role": { "enum": ["subject", "worker", "merge", "judge", "probe", "check", "process", "unknown"] },
+          "status": { "enum": ["pending", "unknown", "idle", "stopped", "completed"] },
+          "acknowledged": { "type": "boolean" },
+          "settled": { "type": "boolean" },
+          "reason": { "type": ["string", "null"] },
+          "receipt_path": { "type": "string", "minLength": 1 },
+          "details": { "type": "object" }
+        },
+        "allOf": [{
+          "if": { "properties": { "settled": { "const": true } } },
+          "then": { "properties": { "status": { "enum": ["idle", "stopped", "completed"] } } }
+        }]
+      }
+    },
+    "unsettled_reasons": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "resumability": { "enum": ["pending", "same_session", "replacement_allowed", "recovery_required", "not_applicable"] },
+    "recovery_id": { "type": ["string", "null"] },
+    "reused": { "type": "boolean" },
+    "next_cursor": { "type": "integer", "minimum": 0 },
+    "run_status": { "type": "string" },
+    "finalization": {
+      "type": ["object", "null"], "additionalProperties": false,
+      "required": ["schema_id", "issuer", "phase", "project_root", "run_id", "controller_id", "generation", "controller_status", "run_status", "status", "owner", "capture", "error"],
+      "properties": {
+        "schema_id": { "const": "dd-flow/terminal-finalization@1" },
+        "issuer": { "const": "dd-flow" },
+        "phase": { "const": "terminal_finalization" },
+        "project_root": { "type": "string", "minLength": 1 },
+        "run_id": { "type": "string", "minLength": 1 },
+        "controller_id": { "type": "string", "minLength": 1 },
+        "generation": { "type": "integer", "minimum": 0 },
+        "controller_status": { "enum": ["recovery_required", "capture_failed"] },
+        "run_status": { "enum": ["done", "failed", "cancelled"] },
+        "status": { "enum": ["pending", "blocked"] },
+        "owner": { "enum": ["live", "absent", "unknown"] },
+        "capture": { "enum": ["recorded", "missing"] },
+        "error": { "type": "object" }
+      }
+    },
+    "control": { "type": ["object", "null"] },
+    "operations": { "type": "array", "items": { "type": "object" } },
+    "worker": { "type": ["object", "null"] },
+    "resume_operation": { "type": ["object", "null"] },
+    "controller": { "type": "object" },
+    "operation_id": { "type": "string", "minLength": 1 },
+    "status": { "type": "string" },
+    "action": { "enum": ["pause", "stop", "resume"] },
+    "progress": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": false, "required": ["phase", "message", "at"], "properties": { "phase": { "enum": ["start", "running", "done", "failed"] }, "message": { "type": "string" }, "at": { "type": "string" }, "detail": { "type": "object" } } }
+    },
+    "warnings": { "type": "array", "items": { "type": "object" } },
+    "response_file": { "type": "string", "minLength": 1 },
+    "response_file_error": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "not": { "enum": ["not_requested", "terminal_noop"] } } } },
+      "then": { "properties": { "control_id": { "type": "string" }, "request_id": { "type": "string" }, "requested_mode": { "type": "string" } } }
+    },
+    {
+      "if": { "properties": { "state": { "enum": ["paused", "stopped"] } } },
+      "then": { "properties": { "settled": { "const": true } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "paused" } } },
+      "then": { "properties": { "applied_mode": { "const": "pause" } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "stopped" } } },
+      "then": { "properties": { "applied_mode": { "const": "stop" } } }
+    },
+    {
+      "if": { "properties": { "settled": { "const": true } } },
+      "then": {
+        "properties": {
+          "nodes": { "items": { "properties": { "settled": { "const": true } } } },
+          "unsettled_reasons": { "maxItems": 0 }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "settled": { "const": false } } },
+      "then": { "properties": { "unsettled_reasons": { "minItems": 1 }, "resumability": { "enum": ["pending", "recovery_required", "not_applicable"] } } }
+    }
+  ]
+}

package/dist/schemas/run-control-request.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dd-flow/run-control-request@1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "request_id", "project_root", "run_id", "action"],
+  "properties": {
+    "schema_id": { "const": "dd-flow/run-control-request@1" },
+    "request_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" },
+    "project_root": { "type": "string", "minLength": 1, "pattern": "^(?:/|[A-Za-z]:[\\\\/]|\\\\\\\\)" },
+    "run_id": { "type": "string", "pattern": "^RUN-[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "action": { "enum": ["pause", "stop", "resume"] },
+    "wait_ms": { "type": "integer", "minimum": 0, "maximum": 60000, "default": 0 },
+    "grace_ms": { "type": "integer", "minimum": 0, "maximum": 3600000, "default": 30000 },
+    "escalate": { "const": "interrupt" },
+    "force": { "type": "boolean" },
+    "from": { "type": "string", "pattern": "^CTL-[A-Za-z0-9][A-Za-z0-9._-]*$" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "action": { "const": "pause" } } },
+      "then": { "not": { "anyOf": [{ "required": ["force"] }, { "required": ["from"] }] } }
+    },
+    {
+      "if": { "properties": { "action": { "const": "stop" } } },
+      "then": { "not": { "anyOf": [{ "required": ["grace_ms"] }, { "required": ["escalate"] }, { "required": ["from"] }] } }
+    },
+    {
+      "if": { "properties": { "action": { "const": "resume" } } },
+      "then": {
+        "required": ["from"],
+        "not": { "anyOf": [{ "required": ["grace_ms"] }, { "required": ["escalate"] }, { "required": ["force"] }] }
+      }
+    }
+  ]
+}

package/dist/schemas/vnext-protocol-plan.schema.json

@@ -29,9 +29,9 @@
     "documentUpdate": {"type": "object", "additionalProperties": false, "required": ["path", "action", "owner", "reason"], "properties": {"path": {"type": "string", "minLength": 1}, "action": {"enum": ["create", "update"]}, "owner": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}}},
     "spine": {"type": "object", "additionalProperties": false, "required": ["user_outcome", "component_responsibility", "must_preserve", "non_goals", "acceptance_contribution"], "properties": {"user_outcome": {"type": "string", "minLength": 1}, "component_responsibility": {"type": "string", "minLength": 1}, "must_preserve": {"$ref": "#/$defs/strings"}, "non_goals": {"type": "array", "items": {"type": "string", "minLength": 1}}, "acceptance_contribution": {"type": "string", "minLength": 1}}},
     "execution": {"type": "object", "additionalProperties": false, "required": ["required_read", "discovery_boundary", "planned_write_areas", "stop_conditions"], "properties": {"required_read": {"$ref": "#/$defs/strings", "description": "Mandatory starting sources. This is not a read allowlist."}, "discovery_boundary": {"$ref": "#/$defs/strings", "description": "Likely discovery areas. A worker may inspect other project-local sources when necessary."}, "planned_write_areas": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Optional file or directory hints used only to coordinate concurrent Works. They never grant or deny write permission."}, "stop_conditions": {"$ref": "#/$defs/strings", "description": "Semantic contradictions or external blockers that require the worker to stop."}}},
-    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "pattern": "^P[0-9]+$"}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}, {"if": {"properties": {"command": {"pattern": "^@check/"}}}, "then": {"required": ["definition"]}}]},
+    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "pattern": "^P[0-9]+$"}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}, "inputs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "reuse": {"const": "deterministic"}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}, {"if": {"properties": {"command": {"pattern": "^@check/"}}}, "then": {"required": ["definition"]}}]},
     "verification": {"type": "object", "additionalProperties": false, "required": ["check_refs"], "properties": {"check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}}}},
     "item": {"type": "object", "additionalProperties": false, "required": ["id", "title", "summary", "details", "depends_on", "requirement_refs", "semantic_spine", "execution_context", "verification"], "properties": {"id": {"type": "string", "pattern": "^P[0-9]+$"}, "title": {"type": "string", "minLength": 1}, "summary": {"type": "string", "minLength": 1}, "details": {"type": "string", "minLength": 1}, "depends_on": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "requirement_refs": {"$ref": "#/$defs/strings"}, "semantic_spine": {"$ref": "#/$defs/spine"}, "execution_context": {"$ref": "#/$defs/execution"}, "verification": {"$ref": "#/$defs/verification"}}},
-    "acceptance": {"type": "object", "additionalProperties": false, "required": ["criterion_id", "plan_item_ids", "changed_surfaces", "path", "environment", "fixtures", "cleanup", "check_refs", "expected_evidence", "proof_limits", "gate"], "properties": {"criterion_id": {"type": "string", "pattern": "^AC-[0-9]+$"}, "plan_item_ids": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "changed_surfaces": {"$ref": "#/$defs/strings"}, "path": {"type": "string", "minLength": 1}, "environment": {"type": "string", "minLength": 1}, "fixtures": {"type": "array", "items": {"type": "string", "minLength": 1}}, "cleanup": {"type": "string", "minLength": 1}, "check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}}, "expected_evidence": {"$ref": "#/$defs/strings"}, "proof_limits": {"$ref": "#/$defs/strings"}, "gate": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}}}
+    "acceptance": {"type": "object", "additionalProperties": false, "required": ["criterion_id", "plan_item_ids", "changed_surfaces", "path", "environment", "fixtures", "cleanup", "check_refs", "expected_evidence", "proof_limits", "gate"], "properties": {"criterion_id": {"type": "string", "pattern": "^AC-[0-9]+$"}, "plan_item_ids": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "changed_surfaces": {"$ref": "#/$defs/strings"}, "path": {"type": "string", "minLength": 1}, "environment": {"type": "string", "minLength": 1}, "fixtures": {"type": "array", "items": {"type": "string", "minLength": 1}}, "cleanup": {"type": "string", "minLength": 1}, "check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}}, "expected_evidence": {"$ref": "#/$defs/strings"}, "proof_limits": {"$ref": "#/$defs/strings"}, "gate": {"enum": ["work", "code", "readiness", "merge", "release"]}}}
   }
 }

package/dist/services/branch-context.js

@@ -166,11 +166,11 @@ function gitFacts(workspacePath) {
     if (!fs.existsSync(workspacePath)) {
         return { status: "missing_workspace", actual_branch: null, dirty: null, path: workspacePath };
     }
-    const branch = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+    const branch = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8", timeout: 5000 });
     if (branch.status !== 0) {
-        return { status: "not_git_checkout", actual_branch: null, dirty: null, path: workspacePath };
+        return { status: branch.error || branch.signal ? "observation_unavailable" : "not_git_checkout", actual_branch: null, dirty: null, path: workspacePath };
     }
-    const status = spawnSync("git", ["-C", workspacePath, "status", "--porcelain"], { encoding: "utf8" });
+    const status = spawnSync("git", ["-C", workspacePath, "status", "--porcelain"], { encoding: "utf8", timeout: 5000 });
     return {
         status: "ok",
         actual_branch: branch.stdout.trim() || null,

package/dist/services/canon.js

@@ -1,27 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { prepareError } from "../cli/input-preparation.js";
 const canonRootKey = "canon.root";
-export function registerCanonRoot(context, input) {
+export function prepareCanonRegistration(context, input) {
+    if (typeof input.root !== "string" || !input.root.trim())
+        return prepareError(new AppError("validation", "Canon root must be a non-empty path", 2));
     const resolution = resolveCanonRoot(context, { explicitRoot: input.root, allowRegistered: false });
     if (!resolution.ok || !resolution.canon) {
-        return {
-            ...resolution,
-            action: "register",
-            exit_code: 1
-        };
+        return prepareError(new AppError("validation", "Canon root cannot be registered", 2, { root: input.root, blockers: resolution.blockers, candidates: resolution.candidates, bootstrap: resolution.bootstrap }));
     }
+    return resolution.canon;
+}
+export function registerCanonRoot(context, input, canon = prepareCanonRegistration(context, input)) {
     const now = context.now();
     context.db.run(`INSERT INTO runtime_config (key, value_json, created_at, updated_at)
      VALUES (?, ?, ?, ?)
      ON CONFLICT(key) DO UPDATE SET
        value_json = excluded.value_json,
-       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: resolution.canon.root }), now, now]);
+       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: canon.root }), now, now]);
     return {
         ok: true,
         action: "register",
         canon: {
-            ...resolution.canon,
+            ...canon,
             source: "registered"
         },
         db_path: context.db.path