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

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

@@ -0,0 +1,121 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { AppError } from "../shared/errors.js";
+import { validateObservationDuration } from "../harness-runtime/lib/observation-clock.mjs";
+export const recoveryObservationBudgetMs = 120_000;
+const activeObservation = new AsyncLocalStorage();
+export const withRecoveryObservation = (budget, action, retainActive = false) => activeObservation.run(retainActive ? activeObservation.getStore() ?? budget : budget, action);
+export const recoveryRpcTimeout = (maximum) => {
+    if (maximum != null)
+        validateObservationDuration(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: { policy_id: "settlement-inactivity@1", observer_started: false, budget_ms: recoveryObservationBudgetMs, remaining_ms: recoveryObservationBudgetMs, progress_markers: [], observation_gaps: 0, reconciliation_ids: [...ids, requestId], poll_index: 0 } };
+}
+/**
+ * New episodes measure silence between confirmed retirement facts; legacy
+ * receipts keep cumulative active-observer accounting. A gap never proves
+ * native death, and repeated gaps exhaust observation rather than grant time.
+ * Remaining time and seen proofs survive owner replacement.
+ */
+export function recoveryObservationBudget(saved, monotonic = () => performance.now()) {
+    const prior = saved && typeof saved === "object" ? saved.recovery_observation : null;
+    if (prior?.policy_id !== undefined && prior.policy_id !== "settlement-inactivity@1")
+        throw new AppError("recovery_observation_invalid", "Unknown retained observation policy", 1);
+    const sliding = !prior || prior.policy_id === "settlement-inactivity@1";
+    if (prior?.progress_markers !== undefined && (!Array.isArray(prior.progress_markers) || prior.progress_markers.some(marker => typeof marker !== "string"))
+        || prior?.observation_gaps !== undefined && (!Number.isSafeInteger(prior.observation_gaps) || prior.observation_gaps < 0)
+        || prior?.observer_started !== undefined && typeof prior.observer_started !== "boolean")
+        throw new AppError("recovery_observation_invalid", "Retained observation progress is malformed", 1);
+    const markers = new Set(prior?.progress_markers ?? []);
+    let gaps = prior?.observation_gaps ?? 0;
+    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;
+    // A restored observer cannot know what happened while it was absent. Retain
+    // one bounded uncertainty episode; repeated reconstruction never grants time.
+    if (sliding && prior && prior.observer_started !== false && ++gaps > 1)
+        remaining = 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);
+            else if (sliding && ++gaps > 1)
+                remaining = 0;
+            return remaining === 0;
+        },
+        observe: snapshot => {
+            observation.exhausted();
+            if (!sliding || remaining === 0)
+                return;
+            const proof = settlementProgressMarkers(snapshot);
+            const advanced = proof.some(marker => !markers.has(marker));
+            proof.forEach(marker => markers.add(marker));
+            if (advanced) {
+                remaining = recoveryObservationBudgetMs;
+                gaps = 0;
+            }
+        },
+        state: () => ({ ...(sliding ? { policy_id: "settlement-inactivity@1", observer_started: true, progress_markers: [...markers].sort(), observation_gaps: gaps } : {}), budget_ms: recoveryObservationBudgetMs, remaining_ms: Math.ceil(remaining), reconciliation_ids: prior?.reconciliation_ids ?? [], poll_index: pollIndex }),
+        timeout: (maximum = 30_000) => {
+            validateObservationDuration(maximum);
+            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;
+}
+/** Only confirmed settlement facts advance recovery. Polls, errors, timestamps,
+ * and native model activity cannot replenish physical retirement observation. */
+export function settlementProgressMarkers(snapshot) {
+    const result = [];
+    const visit = (value, prefix, depth) => {
+        if (!value || typeof value !== "object" || depth > 12)
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, prefix, depth + 1);
+            return;
+        }
+        const object = value;
+        const identity = ["operation_id", "process_id", "session_id", "run_id", "control_id", "scope_id", "id"].map(key => typeof object[key] === "string" ? `${key}:${object[key]}` : "").filter(Boolean).join("|");
+        const location = `${prefix}/${identity}`;
+        for (const key of ["physical_settled", "native_settled", "settled", "retired", "published", "committed"])
+            if (object[key] === true)
+                result.push(`${location}/${key}`);
+        if (["completed", "released", "sealed", "verified", "retired"].includes(String(object.status)))
+            result.push(`${location}/status:${String(object.status)}`);
+        if (object.state === "settled")
+            result.push(`${location}/state:settled`);
+        for (const [key, item] of Object.entries(object))
+            if (key !== "recovery_observation" && key !== "error" && key !== "metadata" && key !== "capture_error")
+                visit(item, `${location}/${key}`, depth + 1);
+    };
+    visit(snapshot, "", 0);
+    return [...new Set(result)].sort();
+}

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

@@ -0,0 +1,145 @@
+import { DatabaseSync } from "node:sqlite";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { registerStoreWriter } from "../storage/writer-contract.js";
+import { managedProcessRuntimeHome } from "./managed-processes.js";
+import { cleanupScopeWriters } from "./scope-writer-cleanup.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, held = false, failed = false, primary;
+    try {
+        registerStoreWriter(db);
+        db.exec("PRAGMA foreign_keys = OFF; PRAGMA secure_delete = ON; BEGIN IMMEDIATE");
+        held = true;
+        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,
+            lifecycle_packet_assignments: `invocation_id IN (SELECT id FROM lifecycle_invocations WHERE ${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})`;
+        // Relocation proofs are RUN-owned provenance needed to map unchanged context
+        // bytes through subsequent recovery generations, not portable live authority.
+        rules.audit_events = `${ownProject} AND (protocol_id IN (${protocols}) OR (event_type = 'flow_run.publication_relocation' AND json_extract(payload_json, '$.run_id') IN (SELECT run_id FROM capture_scope)))`;
+        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");
+        held = false;
+        db.exec("VACUUM");
+        complete = true;
+    }
+    catch (error) {
+        primary = error;
+        failed = true;
+    }
+    const cleanup = cleanupScopeWriters([{ name: output, db, rollback: held, close: "always" }]);
+    if (!complete) {
+        try {
+            fs.rmSync(output, { force: true });
+        }
+        catch (error) {
+            cleanup.push({ target: output, phase: "remove_incomplete_output", message: String(error), error: errorRecord(error) });
+        }
+    }
+    if (failed || cleanup.length) {
+        if (primary instanceof AppError) {
+            if (cleanup.length)
+                primary.details.snapshot_cleanup_errors = cleanup;
+            throw primary;
+        }
+        throw new AppError("snapshot_database_failed", primary instanceof Error ? primary.message : "Snapshot database cleanup failed", 1, { ...(failed ? { cause: errorRecord(primary) } : {}), snapshot_cleanup_errors: cleanup });
+    }
+}
+/** 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 });
+    let held = false, failed = false, primary, result;
+    try {
+        db.exec("PRAGMA busy_timeout = 4000; BEGIN");
+        held = true;
+        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");
+        held = false;
+        result = { ...scope, database_present: true, processes, resources };
+    }
+    catch (error) {
+        primary = error;
+        failed = true;
+    }
+    const cleanup = cleanupScopeWriters([{ name: file, db, rollback: held, close: "always" }]);
+    if (failed || cleanup.length) {
+        if (primary instanceof AppError) {
+            if (cleanup.length)
+                primary.details.snapshot_cleanup_errors = cleanup;
+            throw primary;
+        }
+        throw new AppError("snapshot_resource_evidence_failed", primary instanceof Error ? primary.message : "Resource evidence cleanup failed", 1, { ...(failed ? { cause: errorRecord(primary) } : {}), snapshot_cleanup_errors: cleanup });
+    }
+    return result;
+}

package/dist/services/repair-intents.js

@@ -0,0 +1,42 @@
+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";
+import { assertSourceRepairEligible } from "./code-checks.js";
+/** Checks finish before entering this synchronous registration transaction. */
+export function ensureAggregateRepair(context, input, create) {
+    if (!input.failures.length)
+        throw new AppError("repair_intent_invalid", "Repair requires assertion-backed failed receipts", 1);
+    assertSourceRepairEligible(input.failures);
+    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/review-copy.js

@@ -0,0 +1,157 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { ignoredWorkspacePaths } from "./code-checks.js";
+import { localEnvironmentAllowed, ownedWorkspaceHookPath, projectServicePathFilter, workspaceGitFiles } from "./workspace-files.js";
+export function reviewerSourceInputs(root, aspectIds) {
+    const criteria = [...new Set(aspectIds)].sort().map(id => {
+        if (!/^[a-z][a-z0-9_-]*$/.test(id))
+            throw new AppError("review_criterion_invalid", "Assigned aspect has an invalid identity", 1, { aspect_id: id });
+        return `.memory-bank/dd-flow/mb-sdlc/plan-aspects/aspects/${id}.md`;
+    });
+    const orientation = [".memory-bank/index.md", ".memory-bank/spec/engineering/index.md", ".memory-bank/spec/engineering/coding-standards.md"].filter(relative => fs.existsSync(path.join(root, relative)));
+    return [...criteria, ...orientation].map(relative => {
+        const file = path.join(root, relative);
+        if (!fs.existsSync(file))
+            throw new AppError("review_criterion_missing", "Assigned reviewer criterion is missing", 1, { path: relative });
+        const inside = path.relative(fs.realpathSync(root), fs.realpathSync(file));
+        if (inside === ".." || inside.startsWith(`..${path.sep}`) || !fs.statSync(file).isFile())
+            throw new AppError("review_criterion_invalid", "Reviewer source must be a file in its workspace", 1, { path: relative });
+        return { path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") };
+    });
+}
+export function reviewerSourceInstruction(root, aspectIds) {
+    const inputs = reviewerSourceInputs(root, aspectIds);
+    return ["Read the assigned canonical criterion files and the available project orientation below before independent review. Apply each criterion's scope; a small behavior change is not by itself a reason to omit testing or evidence. These starting inputs do not limit relevant project investigation. Do not edit them.", ...inputs.map(input => `- ${path.join(root, input.path)} (SHA256 ${input.sha256})`)].join("\n");
+}
+export function reviewEnvironmentAllowed(file) {
+    return localEnvironmentAllowed(file);
+}
+export function reviewSourcePaths(root, explicitInputs = [], base = "HEAD") {
+    const inventory = workspaceGitFiles(root, ["--cached", "--others", "--exclude-standard"]);
+    if (inventory === null)
+        return null;
+    const serviceAllowed = projectServicePathFilter(root, explicitInputs);
+    const hasBase = base !== "HEAD" || spawnSync("git", ["-C", root, "rev-parse", "--verify", "HEAD"], { encoding: "utf8" }).status === 0;
+    const changes = hasBase ? spawnSync("git", ["-C", root, "diff", "--name-status", "-z", "--find-renames", base, "--"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }) : null;
+    if (changes && (changes.status !== 0 || changes.error))
+        throw new AppError("review_git_evidence_failed", "Could not classify renamed review paths", 1, { workspace_root: root, cause: changes.error?.message ?? changes.stderr });
+    const fields = changes?.stdout.split("\0").filter(Boolean) ?? [], tainted = new Set();
+    for (let index = 0; index < fields.length;) {
+        const status = fields[index++];
+        if (/^[RC]/.test(status)) {
+            const before = fields[index++], after = fields[index++];
+            if (!reviewEnvironmentAllowed(before) || !reviewEnvironmentAllowed(after)) {
+                tainted.add(before);
+                tainted.add(after);
+            }
+        }
+        else
+            index += 1;
+    }
+    return [...new Set([...inventory, ...explicitInputs])]
+        .filter(relative => reviewEnvironmentAllowed(relative) && !tainted.has(relative) && serviceAllowed(path.join(root, relative)))
+        .sort();
+}
+export function reviewSourceFilter(root, explicitInputs = [], base = "HEAD") {
+    const selected = reviewSourcePaths(root, explicitInputs, base);
+    const serviceAllowed = projectServicePathFilter(root, explicitInputs);
+    const retained = new Set(selected?.map(relative => path.resolve(root, relative)) ?? []);
+    const branches = new Set();
+    for (const file of retained)
+        for (let directory = path.dirname(file); directory !== path.dirname(directory); directory = path.dirname(directory))
+            branches.add(directory);
+    return file => {
+        const parts = path.relative(root, file).split(path.sep);
+        if (parts.some(part => [".git", "node_modules", ".dd-flow"].includes(part)) || !reviewEnvironmentAllowed(file))
+            return false;
+        return selected === null ? serviceAllowed(file) : retained.has(path.resolve(file)) || branches.has(path.resolve(file));
+    };
+}
+export function reviewSourceHash(root, explicitInputs = [], base = "HEAD") {
+    const allowed = reviewSourceFilter(root, explicitInputs, base), ownedHook = ownedWorkspaceHookPath(root);
+    return reviewCopyHash(root, file => path.relative(root, file) !== ownedHook && allowed(file));
+}
+/** The copied project has no Git index. Apply the source's exact service-file
+ * policy to it, while retaining only our frozen Git evidence under .dd-flow. */
+export function reviewExecutionCopyHash(copyRoot, sourceRoot, includeEvidence = true, explicitInputs = [], base = "HEAD") {
+    if (ownedWorkspaceHookPath(sourceRoot) && !ownedWorkspaceHookPath(copyRoot))
+        throw new AppError("read_only_input_changed", "Qualified review hook differs between execution copy and source", 2, { copy_root: copyRoot });
+    const sourceAllowed = reviewSourceFilter(sourceRoot, explicitInputs, base);
+    const serviceAllowed = projectServicePathFilter(sourceRoot, explicitInputs);
+    const ownedHook = ownedWorkspaceHookPath(sourceRoot);
+    const verifySelection = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const file = path.join(directory, entry.name), relative = path.relative(copyRoot, file);
+            const parts = relative.split(path.sep);
+            if (parts[0] === ".dd-flow" || parts.some(part => [".git", "node_modules"].includes(part)))
+                continue;
+            if (!reviewEnvironmentAllowed(file))
+                throw new AppError("read_only_input_changed", "Read-only execution copy contains a local environment file", 2, { path: relative });
+            if (!serviceAllowed(path.join(sourceRoot, relative)))
+                continue;
+            if (!sourceAllowed(path.join(sourceRoot, relative)) && ignoredWorkspacePaths(sourceRoot, [relative]).includes(relative.split(path.sep).join("/")))
+                continue;
+            if (!sourceAllowed(path.join(sourceRoot, relative)))
+                throw new AppError("read_only_input_changed", "Read-only execution copy contains an unselected product input", 2, { path: relative });
+            if (entry.isDirectory())
+                verifySelection(file);
+        }
+    };
+    verifySelection(copyRoot);
+    return reviewCopyHash(copyRoot, file => {
+        const relative = path.relative(copyRoot, file);
+        const parts = relative.split(path.sep);
+        if (parts[0] === ".dd-flow")
+            return includeEvidence && (parts.length === 1 || parts[1] === "review-evidence");
+        return relative !== ownedHook && sourceAllowed(path.join(sourceRoot, relative));
+    });
+}
+/** Exact bytes visible in a read-only execution copy, including symlink targets. */
+export function reviewCopyHash(root, allowed = () => true) {
+    const hash = crypto.createHash("sha256");
+    let canonicalRoot;
+    try {
+        canonicalRoot = fs.realpathSync(root);
+    }
+    catch {
+        throw new AppError("read_only_input_changed", "Read-only execution copy is missing", 2, { root });
+    }
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(directory, entry.name);
+            if (!allowed(file))
+                continue;
+            const relative = path.relative(root, file).split(path.sep).join("/");
+            const stat = fs.lstatSync(file);
+            const record = (kind, value = "") => hash.update(`${JSON.stringify([relative, kind, stat.mode & 0o111, value])}\n`);
+            if (entry.isDirectory()) {
+                record("directory");
+                visit(file);
+                continue;
+            }
+            if (entry.isSymbolicLink()) {
+                const link = fs.readlinkSync(file);
+                let target;
+                try {
+                    target = fs.realpathSync(file);
+                }
+                catch {
+                    throw new AppError("read_only_workspace_escape", "Read-only copy contains an unresolved symlink", 1, { path: relative });
+                }
+                const inside = path.relative(canonicalRoot, target);
+                if (path.isAbsolute(link) || inside === ".." || inside.startsWith(`..${path.sep}`))
+                    throw new AppError("read_only_workspace_escape", "Read-only copy contains a symlink outside its workspace", 1, { path: relative });
+                record("symlink", link);
+            }
+            else if (entry.isFile())
+                record("file", crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"));
+            else
+                throw new AppError("read_only_workspace_unsupported", "Read-only copy contains an unsupported file type", 1, { path: relative });
+        }
+    };
+    visit(root);
+    return hash.digest("hex");
+}

package/dist/services/review-deferral.js

@@ -0,0 +1,23 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { assertPortableArtifactRef } from "./portable-refs.js";
+/** A deferral names one project-local file, never an arbitrary path. */
+export function reviewDefEvidence(workspaceRoot, defId) {
+    try {
+        if (!defId || !/^DEF-[A-Za-z0-9][A-Za-z0-9_-]*$/.test(defId))
+            throw new Error("invalid DEF identifier");
+        const relative = `.memory-bank/defs/${defId}.md`;
+        const file = assertPortableArtifactRef(relative, { workspaceRoot, runHome: workspaceRoot, runId: "" });
+        const directory = fs.realpathSync(path.join(workspaceRoot, ".memory-bank", "defs"));
+        const root = fs.realpathSync(workspaceRoot);
+        const directoryRelative = path.relative(root, directory);
+        if (directoryRelative === ".." || directoryRelative.startsWith(`..${path.sep}`) || path.isAbsolute(directoryRelative) || path.dirname(file) !== directory || !fs.statSync(file).isFile())
+            throw new Error("DEF must be a regular file in the project defs directory");
+        return { def_id: defId, path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") };
+    }
+    catch (error) {
+        throw new AppError("deferral_invalid", "A deferral requires a readable project-local named DEF", 2, { def_id: defId ?? null, cause: error instanceof Error ? error.message : String(error) });
+    }
+}

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: ["done", "failed", "cancelled"].includes(String(observation.run_status)) ? "not_applicable" : settled || state === "recovery_required" ? "recovery_required" : ["running", "not_requested", "terminal_noop", "superseded"].includes(state) ? "not_applicable" : "pending",
+        recovery_id: text(control.recovery_id)
+    };
+}