@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

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/run-engine-binding.schema.json

@@ -10,7 +10,7 @@
     "run_id": {"type": "string", "pattern": "^RUN-[0-9]+-[a-z0-9][a-z0-9-]*$"},
     "project_root": {"type": "string", "minLength": 1},
     "bound_at": {"type": "string", "format": "date-time"},
-    "source": {"enum": ["run_creation", "legacy_recovery"]},
+    "source": {"enum": ["run_creation", "legacy_recovery", "fork_upgrade"]},
     "reason": {"type": "string", "minLength": 1},
     "engine": {
       "type": "object",

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

@@ -19,6 +19,10 @@
     "stage_root": {"type": "string", "minLength": 1},
     "archive_path": {"type": ["string", "null"]},
     "prompt_path": {"type": "string", "minLength": 1},
+    "prompt_delivery": {
+      "type": "object", "additionalProperties": false, "required": ["path", "sha256"],
+      "properties": {"path": {"type": "string", "minLength": 1}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}}
+    },
     "aliases": {"type": "object", "additionalProperties": {"type": "string"}},
     "resolved_context": {"type": "object", "additionalProperties": true},
     "plan_ref": {"type": "string", "pattern": "^\\.memory-bank/protocol/[^/]+/plan\\.json$"},

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/accepted-intent.js

@@ -0,0 +1,139 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { assertPathWithin } from "../storage/paths.js";
+import { acceptStagePacket, prepareStagePacket, resolveStagePublicationPath } from "./stage-report-renderer.js";
+export const acceptedIntentContract = "dd-flow/accepted-intent@1";
+const digest = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+export function acceptedIntentSourceRole(role) { return role === "accepted_intake" || role.startsWith("accepted_hitl:"); }
+export function acceptedIntentReviewFingerprint(sources) {
+    const inputs = sources?.filter(source => acceptedIntentSourceRole(source.role)).map(({ role, sha256 }) => ({ role, sha256 })).sort((a, b) => a.role < b.role ? -1 : a.role > b.role ? 1 : 0);
+    return inputs?.length ? digest(Buffer.from(JSON.stringify(inputs))) : null;
+}
+/** An independent review covers its retained inputs only. An own-stage user
+ * clarification may use the existing coordinator correction, explicitly named
+ * as such; it never retroactively expands the independent review's coverage. */
+export function validateAcceptedIntentReview(context, scope, reviewedSources, contextFingerprint, acknowledgement) {
+    // Keep file validation outside callers' SQL writer; the prepared validator
+    // below consumes only accepted bytes/ordered SQL events.
+    const reviewed = acceptedIntentReviewFingerprint(reviewedSources);
+    if (!reviewed)
+        return null;
+    if (contextFingerprint !== reviewed)
+        throw new AppError("accepted_intent_review_stale", "Review context does not bind the retained accepted inputs", 1, { stage: scope.stage });
+    const currentSources = prepareAcceptedIntentSources(context, { ...scope, stageDirectory: "intake", marked: true }).sources;
+    return validatePreparedAcceptedIntentReview(context, scope, reviewedSources, contextFingerprint, currentSources, acknowledgement);
+}
+export function validatePreparedAcceptedIntentReview(context, scope, reviewedSources, contextFingerprint, currentSources, acknowledgement) {
+    const reviewed = acceptedIntentReviewFingerprint(reviewedSources);
+    if (!reviewed)
+        return null; // Historical source contract has no new authority.
+    if (contextFingerprint !== reviewed)
+        throw new AppError("accepted_intent_review_stale", "Review context does not bind the retained accepted inputs", 1, { stage: scope.stage });
+    if (currentSources.length > 256)
+        throw new AppError("accepted_intent_source_invalid", "Accepted intent source count exceeds its bound", 1);
+    const current = acceptedIntentReviewFingerprint(currentSources);
+    const reviewedEvent = Math.max(0, ...(reviewedSources ?? []).filter(source => source.role.startsWith("accepted_hitl:")).map(source => Number(source.role.split(":")[1])));
+    const rows = context.db.all("SELECT id, payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? AND id > ? ORDER BY id LIMIT 256", [scope.projectId, scope.runId, reviewedEvent]);
+    const additions = rows.map(row => ({ id: row.id, ...JSON.parse(row.payload_json) }));
+    const refs = additions.map(answer => answer.pause_id);
+    const evidence = { reviewed_fingerprint: reviewed, current_fingerprint: current, independent_coverage: "reviewed_sources_only", coordinator_clarification_refs: refs,
+        source_event_id: Math.max(reviewedEvent, ...additions.map(answer => answer.id)) };
+    if (current === reviewed) {
+        if (acknowledgement && (acknowledgement.reviewed_fingerprint !== reviewed || acknowledgement.current_fingerprint !== current || acknowledgement.clarification_refs.length))
+            throw new AppError("accepted_intent_review_ack_required", "Accepted-input acknowledgement differs from the retained review", 2, { ...evidence, phase: "prepare", effect: "no_effect", recoverable: true });
+        return evidence;
+    }
+    if (!additions.length || additions.some(answer => answer.stage !== scope.stage))
+        throw new AppError("accepted_intent_review_stale", "Independent review cannot cover newly accepted upstream decisions; use a supported upstream revision", 1, { ...evidence, stage: scope.stage });
+    if (!acknowledgement || acknowledgement.reviewed_fingerprint !== reviewed || acknowledgement.current_fingerprint !== current || JSON.stringify(acknowledgement.clarification_refs) !== JSON.stringify(refs)) {
+        if (scope.decisionFrozen)
+            throw new AppError("accepted_intent_review_stale", "New answer cannot alter an already frozen review decision; use a supported upstream revision", 1, evidence);
+        throw new AppError("accepted_intent_review_ack_required", "Own-stage clarification requires an explicit coordinator acknowledgement, not reuse of old independent coverage", 2, { ...evidence, phase: "prepare", effect: "no_effect", recoverable: true, accepted_intent_acknowledgement: { reviewed_fingerprint: reviewed, current_fingerprint: current, clarification_refs: refs }, instruction: "Apply/classify this clarification through the existing coordinator correction/repair route; include the exact acknowledgement in the decision. Independent review covers only the earlier retained inputs." });
+    }
+    return evidence;
+}
+export function assertAcceptedIntentReviewCurrent(context, scope, evidence) {
+    if (!evidence)
+        return;
+    const row = context.db.get("SELECT MAX(id) AS id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ?", [scope.projectId, scope.runId]);
+    if ((row?.id ?? 0) !== evidence.source_event_id)
+        throw new AppError("accepted_intent_review_stale", "Accepted answers changed during review settlement", 1);
+}
+export function assertDeliveredHitlReferences(context, scope, references) {
+    if (!references.length)
+        return;
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [scope.projectId, scope.runId]);
+    if (JSON.parse(run.index_json).accepted_intent_contract !== acceptedIntentContract)
+        return;
+    for (const reference of new Set(references)) {
+        const answered = context.db.get("SELECT id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.pause_id') = ? LIMIT 1", [scope.projectId, scope.runId, reference]);
+        if (!answered)
+            throw new AppError("validation", "Obligation amendment must reference an actually delivered answer in this RUN", 2, { hitl_ref: reference });
+    }
+}
+/** Retain only inputs actually delivered to this RUN, never agent recommendations
+ * or hidden evaluation expectations. Reuse the existing publication custody. */
+export function retainAcceptedIntake(context, scope) {
+    if (!scope.bytes.length || scope.bytes.length > 1024 * 1024)
+        throw new AppError("accepted_intent_source_invalid", "Accepted intake exceeds the bounded source contract", 2);
+    const prepared = prepareStagePacket(scope.file, scope.bytes);
+    context.db.writeTransaction(() => {
+        acceptStagePacket(context, { ...scope, stage: "specify", prepared });
+        const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [scope.projectId, scope.runId]);
+        const index = JSON.parse(row.index_json);
+        index.accepted_intent_contract = acceptedIntentContract;
+        context.db.run("UPDATE runs SET index_json = ? WHERE project_id = ? AND id = ?", [JSON.stringify(index), scope.projectId, scope.runId]);
+    });
+}
+export function prepareAcceptedIntentSources(context, input) {
+    if (!input.marked)
+        return { sources: [], packets: [] };
+    const fail = (reason) => { throw new AppError("accepted_intent_source_gap", "Original accepted input is unavailable; SPECIFY is not a substitute", 1, { reason, run_id: input.runId }); };
+    const rows = context.db.all("SELECT id, payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? ORDER BY id LIMIT 256", [input.projectId, input.runId]);
+    const entries = [{ role: "accepted_intake", file: path.join(input.home, "intake/discussion.md") }, ...rows.flatMap(row => {
+            const value = JSON.parse(row.payload_json);
+            const identity = `accepted_hitl:${String(row.id).padStart(12, "0")}:${value.pause_id}`;
+            return [{ role: `${identity}:0-question`, file: path.join(path.dirname(value.answer_path), "question.md") }, { role: `${identity}:1-answer`, file: value.answer_path }];
+        })];
+    if (entries.length > 256)
+        fail("source_count_exceeds_bound");
+    let total = 0;
+    const retained = entries.map(entry => {
+        const file = resolveStagePublicationPath(context, input.projectId, input.runId, entry.file);
+        const relative = path.relative(input.home, file);
+        if (path.isAbsolute(relative) || relative.startsWith(`..${path.sep}`) || relative === "..")
+            fail("source_outside_run");
+        const suffix = `/${relative.split(path.sep).join("/")}`;
+        const packetRows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' AND json_extract(payload_json, '$.run_id') = ? AND substr(json_extract(payload_json, '$.file'), -length(?)) = ? LIMIT 33", [input.projectId, input.runId, suffix, suffix]);
+        if (packetRows.length > 32 || packetRows.some(row => Buffer.byteLength(row.payload_json) > 2 * 1024 * 1024))
+            fail(`unbounded_custody:${relative}`);
+        const candidates = packetRows.map(row => ({ value: JSON.parse(row.payload_json) })).filter(packet => resolveStagePublicationPath(context, input.projectId, input.runId, packet.value.file) === file);
+        if (!candidates.length)
+            fail(`missing_custody:${relative}`);
+        const bytes = Buffer.from(candidates[0].value.base64, "base64"), sha256 = digest(bytes);
+        total += bytes.length;
+        if (!bytes.length || bytes.length > 1024 * 1024 || total > 16 * 1024 * 1024 || candidates.some(packet => packet.value.sha256 !== sha256 || !Buffer.from(packet.value.base64, "base64").equals(bytes) || Buffer.from(packet.value.base64, "base64").toString("base64") !== packet.value.base64))
+            fail(`invalid_custody:${relative}`);
+        // An unavailable or replaced published source is an explicit evidence gap,
+        // rather than silent use of a later summary or arbitrary local file.
+        if (!fs.existsSync(file) || !fs.lstatSync(file).isFile() || fs.statSync(file).size !== bytes.length)
+            fail(`source_unavailable:${relative}`);
+        const actual = path.relative(fs.realpathSync(input.home), fs.realpathSync(file));
+        if (path.isAbsolute(actual) || actual === ".." || actual.startsWith(`..${path.sep}`) || !fs.readFileSync(file).equals(bytes))
+            fail(`source_unavailable:${relative}`);
+        const snapshot = `${input.stageDirectory}/verification/sources/${sha256}/accepted-input.md`;
+        const destination = path.join(input.home, snapshot);
+        try {
+            assertPathWithin(input.home, destination, "accepted_source_snapshot");
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || error.code !== "validation")
+                throw error;
+            throw new AppError("verification_matrix_path_invalid", "Accepted source snapshot escapes its RUN", 1, { path: snapshot });
+        }
+        return { source: { role: entry.role, root: "run", path: snapshot, sha256 }, packet: prepareStagePacket(destination, bytes) };
+    });
+    return { sources: retained.map(item => item.source), packets: [...new Map(retained.map(item => [item.packet.file, item.packet])).values()] };
+}

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,32 @@
 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";
+import { resolveDdFlowHome } from "../storage/paths.js";
+import { readSetupStatus } from "./setup.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
@@ -38,16 +43,21 @@ export function getCanonStatus(context, input = {}) {
 export function resolveCanonRoot(context, input = {}) {
     return resolveCanonCandidates(canonCandidates(context, input));
 }
-/** Read only: resolve an explicit/environment/nearby canon without opening DD_FLOW_HOME. */
+/** Read only: resolve canonical data without opening SQLite or running migrations. */
 export function resolveCanonRootBeforeContext(env, input = {}) {
     const candidates = [];
     if (input.explicitRoot)
         candidates.push(validateCanonCandidate("explicit", input.explicitRoot));
     else if (env.DD_MEMORYBANK)
         candidates.push(validateCanonCandidate("env", env.DD_MEMORYBANK));
-    else
-        for (const known of knownCanonRoots())
-            candidates.push(validateCanonCandidate("known", known));
+    else {
+        const installed = installedCanonCandidate(resolveDdFlowHome(env));
+        if (installed)
+            candidates.push(installed);
+        else
+            for (const known of knownCanonRoots())
+                candidates.push(validateCanonCandidate("known", known));
+    }
     return resolveCanonCandidates(uniqueBy(candidates, (candidate) => `${candidate.source}:${candidate.root}`));
 }
 function resolveCanonCandidates(candidates) {
@@ -64,7 +74,7 @@ function resolveCanonCandidates(candidates) {
         const memorybankRoot = candidate.memorybank_root ?? root;
         const mbbRoot = candidate.mbb_root ?? path.join(memorybankRoot, "mbb");
         const layout = candidate.layout ?? "legacy_root";
-        const metadata = readCanonMetadata(root, flowRoot);
+        const metadata = candidate.metadata ?? readCanonMetadata(root, flowRoot);
         return {
             ok: true,
             canon: {
@@ -111,6 +121,30 @@ function resolveCanonCandidates(candidates) {
         ]
     };
 }
+/** Archive provenance belongs to the selected release, not an ancestor Git
+ * checkout. A damaged installation is not permission to select nearby code. */
+function installedCanonCandidate(home) {
+    if (!fs.existsSync(path.join(home, "installation.json")))
+        return null;
+    const status = readSetupStatus(home), installation = status.installation;
+    const invalid = (root, reason) => ({
+        source: "installed", root, realpath: null, valid: false, blockers: [reason]
+    });
+    if (!installation || status.installation_readiness !== "installed")
+        return invalid(home, "Installed canonical release is degraded; reconcile setup before selecting its canon.");
+    const roots = fs.readdirSync(installation.canon_root);
+    if (roots.length !== 1)
+        return invalid(installation.canon_root, "Installed canonical archive has no unique root.");
+    const candidate = validateCanonCandidate("installed", path.join(installation.canon_root, roots[0]));
+    if (!candidate.valid)
+        return candidate;
+    const version = readTrimmed(path.join(candidate.root, "VERSION"));
+    const flowContract = readFlowContractId(candidate.flow_root);
+    if (version !== installation.manifest.canon.version || !flowContract)
+        return invalid(candidate.root, "Installed canonical metadata differs from its release selection.");
+    return { ...candidate, metadata: { version, commit: installation.manifest.canon.commit,
+            flow_contract: flowContract, status: "present", diagnostics: [] } };
+}
 function canonCandidates(context, input) {
     const candidates = [];
     if (input.explicitRoot) {
@@ -126,8 +160,13 @@ function canonCandidates(context, input) {
             candidates.push(validateCanonCandidate("registered", registered.root));
         }
     }
-    for (const known of knownCanonRoots()) {
-        candidates.push(validateCanonCandidate("known", known));
+    if (!candidates.length) {
+        const installed = installedCanonCandidate(context.ddFlowHome);
+        if (installed)
+            return [installed];
+        for (const known of knownCanonRoots()) {
+            candidates.push(validateCanonCandidate("known", known));
+        }
     }
     return uniqueBy(candidates, (candidate) => `${candidate.source}:${candidate.root}`);
 }

package/dist/services/check-environment.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+export function validateCheckEnvironment(value) {
+    if (value === undefined)
+        return undefined;
+    const entries = value && typeof value === "object" && !Array.isArray(value) ? Object.entries(value) : [];
+    if (!entries.length || entries.some(([key, selected]) => !["CODEX_HOME", "PLAYWRIGHT_BROWSERS_PATH"].includes(key)
+        || typeof selected !== "string" || !selected || selected.length > 4096 || selected.includes("\0") || !path.isAbsolute(selected)))
+        throw new AppError("invalid_check_environment", "Owned checks require absolute known resource paths", 2, { effect: "no_effect" });
+    return { ...value };
+}
+export function retainedBrowserEnvironment(environment) {
+    return environment.PLAYWRIGHT_BROWSERS_PATH === undefined ? undefined
+        : validateCheckEnvironment({ PLAYWRIGHT_BROWSERS_PATH: environment.PLAYWRIGHT_BROWSERS_PATH });
+}
+export function ownedCheckEnvironment(environment, requested) {
+    const selected = validateCheckEnvironment(requested), retained = retainedBrowserEnvironment(environment);
+    if (retained?.PLAYWRIGHT_BROWSERS_PATH && selected?.PLAYWRIGHT_BROWSERS_PATH && retained.PLAYWRIGHT_BROWSERS_PATH !== selected.PLAYWRIGHT_BROWSERS_PATH)
+        throw new AppError("invalid_check_environment", "Owned browser resource cannot be rebound", 2, { effect: "no_effect" });
+    return retained || selected ? { ...retained, ...selected } : undefined;
+}