@deksden-com/dd-flow-cli 0.9.0-beta.9 → 0.9.0-beta.91

package/dist/services/protocols.js

@@ -6,9 +6,8 @@ import { canTransition } from "../domain/contracts.js";
 import { defaultFlowContract, flowContractForState, loadProjectFlowContract } from "../domain/flow-contract.js";
 import { requireStage } from "../domain/validation.js";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
-import { ensureReadableFile } from "../storage/database.js";
-import { ensureDir, planJsonPath, resolveProjectRoot, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
+import { ensureDir, planJsonPath, resolveProjectRoot, resolveProtocolPlanPath, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit, getAuditEvents } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
 import { ensureRuntimeProtocolFiles, readStateFile, writeState } from "../protocol/local-files.js";
@@ -17,14 +16,20 @@ import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProje
 import { buildProtocolFlowGuidance } from "./flow-guidance.js";
 import { lifecycleIsTerminalFailure, lifecycleIsTerminalSuccess, normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
 import { getProtocolBranchContext } from "./branch-context.js";
-export function registerProtocol(context, input) {
+export function prepareProtocolRegistration(context, input) {
+    if (typeof input.handshakeId !== "string" || !input.handshakeId.trim() || /[/\\\0]/.test(input.handshakeId) || [".", ".."].includes(input.handshakeId))
+        throw new AppError("validation", "Protocol handshake must be a non-empty identifier, not a path", 2);
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
-    const now = context.now();
     const workspacePath = input.workspacePath ? resolveProjectRoot(input.workspacePath) : undefined;
     const idRoot = workspacePath ?? projectRoot;
     const protocolId = inferProtocolId(idRoot, input.handshakeId);
     const runtimeDir = runtimeProtocolDir(context.ddFlowHome, project.id, protocolId);
+    return { projectRoot, project, workspacePath, protocolId, runtimeDir };
+}
+export function registerProtocol(context, input) {
+    const { projectRoot, project, workspacePath, protocolId, runtimeDir } = prepareProtocolRegistration(context, input);
+    const now = context.now();
     const state = ensureRuntimeProtocolFiles({
         runtimeDir,
         protocolId,
@@ -243,7 +248,22 @@ export function implementProtocol(context, input) {
         }
     };
 }
-export function transitionProtocol(context, input) {
+export function prepareProtocolTransition(context, input) {
+    const { value } = prepareJsonFile(input.jsonFile, "Protocol transition payload");
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("validation", "Protocol transition payload must be an object", 2);
+    const payload = value;
+    for (const [key, field] of Object.entries(payload)) {
+        const valid = key === "next_action" ? typeof field === "string"
+            : ["route", "workspace"].includes(key) ? Boolean(field && typeof field === "object" && !Array.isArray(field))
+                : ["blockers", "active_def"].includes(key) && Array.isArray(field);
+        if (!valid)
+            throw new AppError("validation", `Unsupported field or invalid value in protocol transition: ${key}`, 2, { file: input.jsonFile, parameter: key });
+    }
+    protocolTransitionState(context, input);
+    return payload;
+}
+function protocolTransitionState(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const protocol = requireProtocol(context, input.protocolId, project.id);
     const state = readProtocolRuntimeState(context, protocol).state;
@@ -256,8 +276,10 @@ export function transitionProtocol(context, input) {
     if (input.force && (!input.reason || input.reason.trim().length === 0)) {
         throw new AppError("validation", "Forced transitions require --reason", 2);
     }
-    ensureReadableFile(input.jsonFile);
-    const payload = parseJsonObject(fs.readFileSync(input.jsonFile, "utf8"), input.jsonFile);
+    return { project, protocol, state, flowContract, from, to };
+}
+export function transitionProtocol(context, input, payload = prepareProtocolTransition(context, input)) {
+    const { project, protocol, state, flowContract, from, to } = protocolTransitionState(context, input);
     const nextState = {
         ...state,
         stage: to,
@@ -416,7 +438,7 @@ export function syncProtocolFromRun(context, input) {
         next_action: nextActionForSyncedTarget(targetStage),
         updated_at: now
     };
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         persistProtocolState(context, protocol, nextState);
         if (targetStage === "ready_for_merge") {
@@ -486,7 +508,7 @@ export function cancelProtocol(context, input) {
     const now = context.now();
     const worktree = context.db.get("SELECT worktree_path, status FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
     const worktreeRemoval = input.worktree === "remove" ? removeProtocolWorktreeBeforeCancel(protocol, state, worktree, input.force) : undefined;
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         const nextState = {
             ...state,
@@ -579,7 +601,10 @@ export function requireProtocol(context, protocolId, projectId) {
             candidates: matches.map((protocol) => ({ project_id: protocol.project_id, project_root: protocol.project_root }))
         });
     }
-    return matches[0];
+    return resolvedProtocolRecord(matches[0]);
+}
+function resolvedProtocolRecord(protocol) {
+    return { ...protocol, plan_path: resolveProtocolPlanPath(protocol.project_root, protocol.id, protocol.plan_path) };
 }
 function cancelQueueForProtocol(context, protocol, reason, force) {
     const job = context.db.get("SELECT id, status, claimed_by_session_id FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
@@ -733,9 +758,26 @@ function releaseRelatedMergeLocks(context, protocol, reason) {
     return { ok: true, released: released.length, locks: released };
 }
 export function readProtocolRuntimeState(context, protocol) {
+    const expected = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+    if (protocol.state_path !== expected)
+        throw new AppError("protocol_state_migration_required", "Protocol runtime path requires explicit cleanup scan/apply before use", 1, { protocol_id: protocol.id, path: protocol.state_path, expected_path: expected });
+    return resolveProtocolRuntimeState(context, { ...protocol }, false);
+}
+/** Explicit cleanup migration; productive readers accept only the current path. */
+export function repairProtocolRuntimeState(context, protocol) {
+    // Readers project the canonical plan path without migrating storage. Repair
+    // must start from the stored locations, not that already-normalized view.
+    const stored = context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [protocol.project_id, protocol.id]);
+    if (stored)
+        Object.assign(protocol, stored);
+    return resolveProtocolRuntimeState(context, protocol, true);
+}
+function resolveProtocolRuntimeState(context, protocol, repair) {
     const diagnostics = [];
-    normalizeProtocolPlanPath(context, protocol, diagnostics);
+    normalizeProtocolPlanPath(context, protocol, diagnostics, repair);
     try {
+        if (protocol.state_path !== runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id))
+            throw new AppError("protocol_state_migration_required", "Retired state files are not runtime authority", 1);
         return { state: readStateFile(protocol.state_path, protocol.id), diagnostics };
     }
     catch {
@@ -750,7 +792,8 @@ export function readProtocolRuntimeState(context, protocol) {
                 recommended_action: "legacy protocol state_path was moved to stable runtime storage"
             });
             const stablePlanPath = planJsonPath(protocol.project_root, protocol.id);
-            context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [stableStatePath, stablePlanPath, protocol.project_id, protocol.id]);
+            if (repair && context.db.writable)
+                context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [stableStatePath, stablePlanPath, protocol.project_id, protocol.id]);
             protocol.state_path = stableStatePath;
             protocol.plan_path = stablePlanPath;
             return { state: readStateFile(stableStatePath, protocol.id), diagnostics };
@@ -783,7 +826,7 @@ export function readProtocolRuntimeState(context, protocol) {
         flow_contract: flowContract,
         updated_at: protocol.updated_at
     };
-    if (!context.db.writable) {
+    if (!repair || !context.db.writable) {
         return { state, diagnostics };
     }
     const stableStatePath = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
@@ -802,9 +845,9 @@ export function readProtocolRuntimeState(context, protocol) {
     });
     return { state, diagnostics };
 }
-function normalizeProtocolPlanPath(context, protocol, diagnostics) {
-    const canonicalPlanPath = planJsonPath(protocol.project_root, protocol.id);
-    if (protocol.plan_path === canonicalPlanPath || !fs.existsSync(canonicalPlanPath))
+function normalizeProtocolPlanPath(context, protocol, diagnostics, repair) {
+    const canonicalPlanPath = resolveProtocolPlanPath(protocol.project_root, protocol.id, protocol.plan_path);
+    if (protocol.plan_path === canonicalPlanPath)
         return;
     diagnostics.push({
         code: "protocol_plan_relocated",
@@ -814,7 +857,7 @@ function normalizeProtocolPlanPath(context, protocol, diagnostics) {
         source: "project_canonical_plan",
         recommended_action: "use the project canonical plan as the sole semantic plan source"
     });
-    if (context.db.writable) {
+    if (repair && context.db.writable) {
         context.db.run("UPDATE protocols SET plan_path = ?, updated_at = ? WHERE project_id = ? AND id = ?", [canonicalPlanPath, context.now(), protocol.project_id, protocol.id]);
     }
     protocol.plan_path = canonicalPlanPath;
@@ -875,10 +918,11 @@ export function persistProtocolState(context, protocol, state) {
 }
 function findProtocol(context, protocolId, projectId) {
     if (projectId) {
-        return context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocolId]);
+        const protocol = context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocolId]);
+        return protocol ? resolvedProtocolRecord(protocol) : undefined;
     }
     const matches = context.db.all("SELECT * FROM protocols WHERE id = ? ORDER BY project_id", [protocolId]);
-    return matches.length === 1 ? matches[0] : undefined;
+    return matches.length === 1 ? resolvedProtocolRecord(matches[0]) : undefined;
 }
 function protocolDocumentsForProject(projectRoot) {
     const protocolRoot = path.join(projectRoot, ".memory-bank", "protocol");

package/dist/services/recovery-observation-budget.js

@@ -0,0 +1,61 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { AppError } from "../shared/errors.js";
+export const recoveryObservationBudgetMs = 120_000;
+const activeObservation = new AsyncLocalStorage();
+export const withRecoveryObservation = (budget, action) => activeObservation.run(budget, action);
+export const recoveryRpcTimeout = (maximum) => {
+    const observation = activeObservation.getStore();
+    // An unbounded productive transport wait is still bounded while recovery is
+    // actively reconciling. Outside recovery, its owner policy decides when to
+    // stop rather than a hidden adapter timer.
+    if (maximum === null)
+        return observation ? observation.timeout() : null;
+    return observation?.timeout(maximum ?? 30_000) ?? maximum ?? 30_000;
+};
+/** Call only while holding the existing owner-claim transaction. A replay of
+ * an explicit request never replenishes time, even after another request. */
+export function renewRecoveryObservation(snapshot, requestId) {
+    if (typeof requestId !== "string" || !requestId.trim() || requestId.length > 200)
+        throw new AppError("usage", "Reconciliation requires a nonempty request ID of at most 200 characters", 2);
+    const previous = snapshot.recovery_observation;
+    const ids = previous?.reconciliation_ids ?? [];
+    if (!Array.isArray(ids) || ids.some(id => typeof id !== "string"))
+        throw new AppError("recovery_observation_invalid", "Retained reconciliation identities are malformed", 1);
+    if (ids.includes(requestId))
+        return snapshot;
+    return { ...snapshot, recovery_observation: { budget_ms: recoveryObservationBudgetMs, remaining_ms: recoveryObservationBudgetMs, reconciliation_ids: [...ids, requestId], poll_index: 0 } };
+}
+/**
+ * Measures only time this owner can actually observe. Large scheduler gaps
+ * reset the sample instead of turning host sleep into evidence about a remote
+ * process. Persisting the remaining budget makes a recovered owner continue
+ * reconciliation rather than silently receiving a new unlimited wait.
+ */
+export function recoveryObservationBudget(saved, monotonic = () => performance.now()) {
+    const prior = saved && typeof saved === "object" ? saved.recovery_observation : null;
+    let remaining = typeof prior?.remaining_ms === "number" && Number.isFinite(prior.remaining_ms)
+        ? Math.max(0, Math.min(recoveryObservationBudgetMs, prior.remaining_ms))
+        : prior == null ? recoveryObservationBudgetMs : 0;
+    let last = monotonic();
+    let pollIndex = Number.isSafeInteger(prior?.poll_index) && prior.poll_index >= 0 ? prior.poll_index : 0;
+    const observation = {
+        exhausted: () => {
+            const current = monotonic();
+            const elapsed = current - last;
+            last = current;
+            // A gap means this process was not observing; it never proves progress
+            // or death and therefore does not consume the reconciliation budget.
+            if (elapsed >= 0 && elapsed <= 60_000)
+                remaining = Math.max(0, remaining - elapsed);
+            return remaining === 0;
+        },
+        state: () => ({ budget_ms: recoveryObservationBudgetMs, remaining_ms: Math.ceil(remaining), reconciliation_ids: prior?.reconciliation_ids ?? [], poll_index: pollIndex }),
+        timeout: (maximum = 30_000) => {
+            if (observation.exhausted())
+                throw new AppError("recovery_observation_budget_exhausted", "Recovery observation budget exhausted; explicit reconciliation is required", 1);
+            return Math.max(1, Math.min(maximum, Math.ceil(remaining)));
+        },
+        nextDelay: () => Math.min([1000, 2000, 5000, 10000][Math.min(pollIndex++, 3)], Math.ceil(remaining)),
+    };
+    return observation;
+}

package/dist/services/recovery-snapshot-database.js

@@ -0,0 +1,107 @@
+import { DatabaseSync } from "node:sqlite";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { registerStoreWriter } from "../storage/writer-contract.js";
+import { managedProcessRuntimeHome } from "./managed-processes.js";
+/** Export one RUN's relational evidence, never mutate the live authority. */
+export function captureRecoveryDatabase(source, output, projectId, runId, protocolIds = []) {
+    source.exec(`VACUUM INTO '${output.replace(/'/g, "''")}'`);
+    const db = new DatabaseSync(output);
+    let complete = false;
+    try {
+        registerStoreWriter(db);
+        db.exec("PRAGMA foreign_keys = OFF; PRAGMA secure_delete = ON; BEGIN IMMEDIATE");
+        db.exec("CREATE TEMP TABLE capture_scope (project_id TEXT, run_id TEXT)");
+        db.prepare("INSERT INTO capture_scope VALUES (?, ?)").run(projectId, runId);
+        db.exec("CREATE TEMP TABLE capture_protocols (id TEXT)");
+        for (const id of protocolIds)
+            db.prepare("INSERT INTO capture_protocols VALUES (?)").run(id);
+        if (!db.prepare("SELECT 1 FROM runs WHERE (project_id, id) IN (SELECT * FROM capture_scope)").get())
+            throw new AppError("snapshot_run_missing", "Recovery export requires the selected RUN", 1);
+        const ownRun = "(project_id, run_id) IN (SELECT * FROM capture_scope)";
+        const ownProject = "project_id IN (SELECT project_id FROM capture_scope)";
+        const works = `SELECT work_id FROM works WHERE ${ownRun}`;
+        if (db.prepare(`SELECT 1 FROM sessions WHERE ${ownProject} AND run_id IS NOT NULL AND run_id NOT IN (SELECT run_id FROM capture_scope) AND session_id IN (SELECT session_id FROM work_sessions WHERE work_id IN (${works})) LIMIT 1`).get())
+            throw new AppError("snapshot_scope_conflict", "Selected Work refers to a Session currently bound to another RUN", 1);
+        const sessions = `SELECT session_id FROM sessions WHERE ${ownProject} AND (run_id IN (SELECT run_id FROM capture_scope) OR session_id IN (SELECT session_id FROM work_sessions WHERE work_id IN (${works})))`;
+        const nativeSessions = `SELECT harness, provider_session_id FROM sessions WHERE ${ownProject} AND session_id IN (${sessions})`;
+        const invocations = "json_extract(scope_json, '$.runId') IN (SELECT run_id FROM capture_scope) AND json_extract(scope_json, '$.projectRoot') IN (SELECT root FROM projects WHERE id IN (SELECT project_id FROM capture_scope))";
+        const invocationReceipts = db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'lifecycle_invocations'").get()
+            ? ` OR event_key IN (SELECT event_key FROM lifecycle_invocations WHERE ${invocations})` : "";
+        const protocols = `SELECT id FROM capture_protocols UNION SELECT subject_id FROM runs WHERE (project_id, id) IN (SELECT * FROM capture_scope) UNION SELECT value FROM merge_requests, json_each(merge_requests.protocol_ids_json) WHERE ${ownRun} UNION SELECT protocol_id FROM flow_jobs WHERE ${ownRun}`;
+        const rules = {
+            dd_flow_writer_contract: "1",
+            dd_flow_writer_migrations: "0",
+            projects: "id IN (SELECT project_id FROM capture_scope)",
+            runs: "(project_id, id) IN (SELECT * FROM capture_scope)",
+            sessions: `${ownProject} AND session_id IN (${sessions})`,
+            work_sessions: `work_id IN (${works})`, work_launches: `work_id IN (${works})`,
+            work_recovery_segments: `work_id IN (${works})`,
+            run_recovery_bindings: `recovery_id IN (SELECT recovery_id FROM run_recovery_guards WHERE ${ownRun})`,
+            lifecycle_invocations: invocations,
+            hook_events: `${ownProject} AND (session_id IN (${sessions}) OR (harness, provider_session_id) IN (${nativeSessions})${invocationReceipts})`,
+            harness_usage_snapshots: `${ownProject} AND (harness, provider_session_id) IN (${nativeSessions})`,
+            protocols: `${ownProject} AND id IN (${protocols})`,
+            project_config: ownProject,
+            // Host installations, caches, queue owners and leases are not portable RUN authority.
+            runtime_config: "0", hook_installations: "0", codex_home_profiles: "0", codex_session_bindings: "0",
+            merge_servers: "0", merge_sessions: "0", merge_queue: "0", lanes: "0", lane_locks: "0", lane_waiters: "0",
+            sqlite_sequence: "0"
+        };
+        for (const table of ["works", "stage_work_memberships", "repair_intents", "check_receipts", "merge_requests", "flow_run_flag_mutations", "usage", "flow_session_segments", "flow_jobs", "run_recovery_guards", "run_controllers", "run_controls"])
+            rules[table] = ownRun;
+        for (const table of ["plan_bindings", "plan_progress", "worktree_records", "audit_events"])
+            rules[table] = `${ownProject} AND protocol_id IN (${protocols})`;
+        for (const table of ["run_controller_events", "run_controller_operations"])
+            rules[table] = `controller_id IN (SELECT controller_id FROM run_controllers WHERE ${ownRun})`;
+        for (const table of ["run_control_admissions", "run_control_stage_admissions", "run_control_operations", "run_control_workers"])
+            rules[table] = `control_id IN (SELECT control_id FROM run_controls WHERE ${ownRun})`;
+        const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table'").all();
+        const quote = (name) => `"${name.replaceAll('"', '""')}"`;
+        // Evaluate every relationship before deleting parents, including historical bindings.
+        for (const { name } of tables) {
+            const predicate = rules[name];
+            if (predicate === undefined && db.prepare(`SELECT 1 FROM ${quote(name)} LIMIT 1`).get())
+                throw new AppError("snapshot_scope_unknown", "Recovery export has no scope rule for a populated table", 1, { table: name });
+            db.exec(`CREATE TEMP TABLE ${quote(`keep_${name}`)} AS SELECT rowid AS retained_id FROM ${quote(name)} WHERE ${predicate ?? "0"}`);
+        }
+        for (const { name } of tables)
+            db.exec(`DELETE FROM ${quote(name)} WHERE rowid NOT IN (SELECT retained_id FROM ${quote(`keep_${name}`)})`);
+        const issues = db.prepare("PRAGMA foreign_key_check").all();
+        if (issues.length)
+            throw new AppError("snapshot_scope_inconsistent", "Scoped recovery export has unresolved relational references", 1, { issues });
+        db.exec("COMMIT; VACUUM");
+        complete = true;
+    }
+    finally {
+        db.close();
+        if (!complete)
+            fs.rmSync(output, { force: true });
+    }
+}
+/** Physical leases are evidence, not authority to resurrect on another host. */
+export function readRecoveryResourceEvidence(resourceHome, projectId, runId, authority) {
+    const file = path.join(resourceHome, "runtime.sqlite");
+    const scope = { schema_id: "dd-flow/recovery-resource-evidence@1", source_home: resourceHome, dd_flow_home: authority.ddFlowHome, project_id: projectId, run_id: runId };
+    if (!fs.existsSync(file))
+        return { ...scope, database_present: false, processes: [], resources: [] };
+    const db = new DatabaseSync(file, { readOnly: true });
+    try {
+        db.exec("PRAGMA busy_timeout = 4000; BEGIN");
+        const candidates = db.prepare("SELECT * FROM managed_processes WHERE project_id = ? AND run_id = ? ORDER BY id").all(projectId, runId).map(record => ({ record, home: managedProcessRuntimeHome(record, authority) }));
+        if (candidates.some(item => item.home === null))
+            throw new AppError("snapshot_resource_scope_unproven", "A retained process has no proven runtime-home identity", 1, { resource_home: resourceHome });
+        const processes = candidates.filter(item => item.home === authority.ddFlowHome).map(item => item.record);
+        const ids = new Set(processes.map(record => record.id)), owners = new Set(processes.map(record => record.owner_id));
+        const resources = db.prepare("SELECT r.* FROM managed_resources r JOIN managed_processes p ON p.id = r.process_id WHERE p.project_id = ? AND p.run_id = ? ORDER BY r.resource_kind, r.resource_key").all(projectId, runId).filter(row => typeof row.process_id === "string" && ids.has(row.process_id));
+        const unbound = db.prepare("SELECT owner_id FROM managed_resources WHERE process_id IS NULL AND owner_id IN (SELECT owner_id FROM managed_processes WHERE project_id = ? AND run_id = ?)").all(projectId, runId).some(row => typeof row.owner_id === "string" && owners.has(row.owner_id));
+        if (unbound)
+            throw new AppError("snapshot_resource_scope_unproven", "A retained resource has no process binding proving its RUN scope", 1, { resource_home: resourceHome });
+        db.exec("COMMIT");
+        return { ...scope, database_present: true, processes, resources };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/services/repair-intents.js

@@ -0,0 +1,40 @@
+import crypto from "node:crypto";
+import { stageAttempt, stageCycle, bindStageWork } from "./stage-work-graph.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { AppError } from "../shared/errors.js";
+/** Checks finish before entering this synchronous registration transaction. */
+export function ensureAggregateRepair(context, input, create) {
+    if (!input.failures.length || input.failures.some(receipt => receipt.status !== "failed" && receipt.status !== "aborted"))
+        throw new AppError("repair_intent_invalid", "Repair requires settled failed receipts", 1);
+    const causes = input.failures.map(receipt => ({ id: receipt.id, epoch: receipt.verification_epoch, fingerprint: receipt.workspace_fingerprint })).sort((a, b) => a.id.localeCompare(b.id));
+    return ensureRepairIntent(context, { ...input, causes: { receipts: causes, origins: [...(input.origins ?? [])].sort() } }, create);
+}
+export function ensureRepairIntent(context, input, create) {
+    return context.db.writeTransaction(() => {
+        assertRunMutationAllowed(context, input.projectId, input.runId, input.generation);
+        const attempt = stageAttempt(context, input.projectId, input.runId, input.stage);
+        const payload = JSON.stringify({ project_id: input.projectId, run_id: input.runId, stage: input.stage, attempt, cycle: stageCycle(context, input.projectId, input.runId, input.stage), causes: input.causes });
+        const identity = crypto.createHash("sha256").update(payload).digest("hex");
+        const prior = context.db.get("SELECT work_id, payload_json FROM repair_intents WHERE identity = ?", [identity]);
+        if (prior && prior.payload_json !== payload)
+            throw new AppError("repair_intent_conflict", "Repair identity has different causes", 1);
+        const workId = prior?.work_id ?? create();
+        if (!prior) {
+            bindStageWork(context, { projectId: input.projectId, runId: input.runId, workId, stage: input.stage, attempt });
+            context.db.run("INSERT INTO repair_intents (identity, project_id, run_id, stage, attempt, payload_hash, payload_json, work_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)", [identity, input.projectId, input.runId, input.stage, attempt, identity, payload, workId, context.now()]);
+        }
+        return { schema_id: "dd-flow/continuation@1", kind: "repair_required", project_id: input.projectId, run_id: input.runId, stage: input.stage, attempt, identity, work_id: workId };
+    });
+}
+export function isRegisteredRepair(context, value, scope) {
+    if (!value || typeof value !== "object")
+        return false;
+    const receipt = value;
+    if (receipt.schema_id !== "dd-flow/continuation@1" || receipt.kind !== "repair_required")
+        return false;
+    if (scope && (receipt.project_id !== scope.projectId || receipt.run_id !== scope.runId))
+        return false;
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'repair_intents'"))
+        return false;
+    return Boolean(context.db.get("SELECT 1 FROM repair_intents i JOIN works w ON w.work_id = i.work_id AND w.project_id = i.project_id AND w.run_id = i.run_id WHERE i.identity = ? AND i.project_id = ? AND i.run_id = ? AND i.stage = ? AND i.attempt = ? AND i.work_id = ?", [receipt.identity, receipt.project_id, receipt.run_id, receipt.stage, receipt.attempt, receipt.work_id]));
+}

package/dist/services/run-control-receipt.js

@@ -0,0 +1,56 @@
+import crypto from "node:crypto";
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const records = (value) => Array.isArray(value) ? value.map(object) : [];
+const text = (value) => typeof value === "string" && value.length ? value : null;
+/** Pure projection of durable evidence. Never infer quiescence from an ACK,
+ * a terminal RUN label, or a settlement captured before a subsequent resume. */
+export function controlStatusReceipt(observation, request = {}) {
+    const control = object(observation.control), worker = object(observation.worker), resume = object(observation.resume_operation);
+    const present = Boolean(control.control_id), current = control.current === true;
+    const activeResume = Boolean(resume.operation_id);
+    const historical = !current || activeResume || ["resuming", "resumed"].includes(String(control.status));
+    const settlement = object(control.settlement);
+    const snapshot = historical ? {} : control.admission === "sealed" ? settlement : object(worker.snapshot);
+    const nodes = records(snapshot.nodes).map((node, index) => {
+        const identity = Object.fromEntries(["operation_id", "controller_id", "process_id", "check_id", "merge_request_id", "work_id", "work_session_id", "session_id", "harness", "state_dir", "resource_home"].filter(key => node[key] !== undefined).map(key => [key, node[key]]));
+        const settled = node.status === "completed";
+        const role = ["subject", "worker", "merge", "judge", "probe", "check", "process"].includes(String(node.role)) ? node.role : node.check_id ? "check" : node.merge_request_id ? "merge" : node.process_id ? "process" : "unknown";
+        return { id: `node:${crypto.createHash("sha256").update(JSON.stringify(Object.keys(identity).length ? identity : { index, reason: node.reason })).digest("hex")}`, role, status: settled ? "completed" : node.status === "outcome_unknown" ? "unknown" : "pending", acknowledged: settled || object(node.receipt).cancelled === true, settled, reason: settled ? null : text(node.reason) ?? "node_settlement_required", details: node };
+    });
+    const settled = present && current && !historical && control.status === "settled" && control.admission === "sealed" && Boolean(control.capture_path) && settlement.settled === true && Array.isArray(settlement.nodes) && nodes.every(node => node.settled);
+    let state;
+    if (!present)
+        state = request.action && ["done", "failed", "cancelled"].includes(String(observation.run_status)) ? "terminal_noop" : "not_requested";
+    else if (!current)
+        state = "superseded";
+    else if (resume.status === "failed" || worker.status === "failed")
+        state = "recovery_required";
+    else if (control.status === "resumed" && control.admission === "recovered" && resume.status === "completed")
+        state = "running";
+    else if (activeResume || control.status === "resuming")
+        state = "resuming";
+    else if (settled)
+        state = control.requested_mode === "pause" ? "paused" : "stopped";
+    else
+        state = control.requested_mode === "pause" ? "pause_requested" : "stop_requested";
+    const reasons = settled ? [] : [...new Set([
+            ...nodes.filter(node => !node.settled).map(node => node.reason),
+            ...(Array.isArray(snapshot.pending_reasons) ? snapshot.pending_reasons.filter((reason) => typeof reason === "string" && Boolean(reason)) : []),
+            ...(!present ? [state === "terminal_noop" ? "terminal_settlement_not_observed" : "control_not_requested"]
+                : !current ? ["control_superseded"]
+                    : state === "running" ? ["run_active"]
+                        : state === "resuming" ? ["recovery_acceptance_pending"]
+                            : state === "recovery_required" ? [text(object(resume.error).code) ?? text(object(worker.error).code) ?? "control_recovery_required"]
+                                : control.admission === "sealed" ? ["recovery_capture_required"] : ["settlement_observation_required"])
+        ])];
+    return {
+        ...observation, schema_id: "dd-flow/run-control-receipt@1", ok: true,
+        request_id: request.requestId ?? text(resume.request_id) ?? text(control.request_id), control_id: text(control.control_id),
+        generation: Number.isSafeInteger(control.generation) ? control.generation : 0,
+        requested_mode: request.action ?? (activeResume ? "resume" : text(control.requested_mode)),
+        applied_mode: settled ? control.requested_mode : state === "running" ? "resume" : null,
+        state, settled, nodes, unsettled_reasons: reasons,
+        resumability: settled || state === "recovery_required" ? "recovery_required" : ["running", "not_requested", "terminal_noop", "superseded"].includes(state) ? "not_applicable" : "pending",
+        recovery_id: text(control.recovery_id)
+    };
+}