@deksden-com/dd-flow-cli 0.9.0-beta.156 → 0.9.0-beta.159

package/dist/services/controller-fanout.js

@@ -12,8 +12,42 @@ import { requireProjectByRoot } from "./projects.js";
 import { stageAttempt, stageWorkIds } from "./stage-work-graph.js";
 import { runtimeCommand } from "./runtime-command.js";
 import { promptDeliveryInstruction } from "./prompt-delivery.js";
-import { currentStageFinishAuthority } from "./lifecycle-invocations.js";
+import { committedSuccessor, currentStageFinishAuthority } from "./lifecycle-invocations.js";
 import { acceptedChildWork } from "./controller-result-authority.js";
+import { explicitWorkFailure } from "./controller-work-failure.js";
+import { commandOption, parseLifecycleCommand } from "./lifecycle-command.js";
+/** A new transport ID is not progress. Read only the current assignment's
+ * committed transition and its check inputs; never inspect mutable files here. */
+export function controllerSemanticCheckpoint(context, input) {
+    const scopeJson = context.env.DD_FLOW_INVOCATION_SCOPE;
+    const scope = scopeJson ? JSON.parse(scopeJson) : null;
+    const project = scope && context.db.get("SELECT id FROM projects WHERE root=?", [scope.projectRoot]);
+    const attempt = project && scope ? stageAttempt(context, project.id, scope.runId, input.stage) : null;
+    const receipt = (id) => typeof id === "string" && project && scope
+        ? context.db.get("SELECT declaration_id,input_hash,status FROM check_receipts WHERE id=? AND project_id=? AND run_id=?", [id, project.id, scope.runId]) ?? null : null;
+    const stableSet = (values) => [...new Set(values.map(value => JSON.stringify(value)))].sort().map(value => JSON.parse(value));
+    const parsed = input.command ? parseLifecycleCommand(input.command) : null;
+    const operation = parsed && parsed.kind !== "none" ? {
+        operation: parsed.invocation.operation, positional: parsed.invocation.args.positional,
+        options: [...parsed.invocation.args.options].filter(([key]) => !["invocation-id", "hook-event-id", "json", "progress-jsonl", "response-file", "reason"].includes(key))
+            .sort(([a], [b]) => a.localeCompare(b)).map(([key, values]) => [key, key === "retry-check" ? values.map(receipt) : values])
+    } : null;
+    const transitions = scopeJson && input.invocationId ? stableSet(context.db.all("SELECT * FROM lifecycle_invocations WHERE scope_json=? AND status='settled' AND json_extract(outcome_json,'$.successor_invocation_id')=?", [scopeJson, input.invocationId]).flatMap(row => {
+        const prior = parseLifecycleCommand(row.command);
+        if (prior.kind === "none" || commandOption(prior.invocation, "stage") !== input.stage)
+            return [];
+        const outcome = JSON.parse(row.outcome_json ?? "null");
+        if (committedSuccessor(context, row, outcome)?.id !== input.invocationId)
+            return [];
+        const result = outcome.result, error = outcome.error;
+        const references = result?.receipts ?? error?.details?.failures ?? [];
+        return [{ outcome: result?.outcome ?? null, verification: result?.verification?.verdict ?? null,
+                error: error ? { code: error.code, rejection_signature: error.details?.rejection_signature ?? null, input_key: error.details?.input_key ?? null } : null,
+                receipts: stableSet((Array.isArray(references) ? references : []).map(value => receipt(value?.id))) }];
+    })) : [];
+    const memoryChecks = project && scope && input.reviewInputSha256 ? stableSet(context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.correction_checks' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.wave')=? AND json_extract(payload_json,'$.review_input_sha256')=?", [project.id, scope.runId, input.wave ?? 0, input.reviewInputSha256]).map(row => { const value = JSON.parse(row.payload_json); return { corrected_input: value.corrected_input_sha256, completed_correction: value.completed_correction_sha256, receipts: stableSet((value.checks ?? []).map((check) => receipt(check.id))) }; })) : [];
+    return { phase: input.phase, ...(input.wave === undefined ? {} : { wave: input.wave }), attempt, generation: scope?.generation ?? null, operation, transitions, ...(input.reviewInputSha256 ? { memory_checks: memoryChecks } : {}) };
+}
 function semanticCompletionPrompt(stage, completed, command) {
     const task = stage === "plan-review"
         ? "Classify the reviewer findings, apply every accepted correction in the current PLAN-REVIEW Work, and write the authoritative review decision."
@@ -93,27 +127,34 @@ export async function nextControllerFanout(context, input) {
         if (fanout.state === "dispatch_required" || fanout.state === "capacity_required")
             return { kind: "wait", reason: "qualified_capacity_required" };
     }
-    const prompt = (action, text) => ({ kind: "prompt", action, prompt: action === "dispatch_work" ? text : `${text}\n\n${lifecycleCommandCompletionInstruction}`, fingerprint: JSON.stringify({ stage: input.stage, parent: fanout.parent_work_id, state: fanout.state, graph: fanout.graph_revision }) });
+    const prompt = (action, text, checkpoint) => ({ kind: "prompt", action, prompt: action === "dispatch_work" ? text : `${text}\n\n${lifecycleCommandCompletionInstruction}`, ...(checkpoint ? { checkpoint } : {}), fingerprint: JSON.stringify({ stage: input.stage, action, parent: fanout.parent_work_id, state: fanout.state, graph: fanout.graph_revision, ...(checkpoint ? { semantic: checkpoint } : {}) }) });
     if (fanout.state === "coordinator_required")
         return prompt("materialize_graph", `Continue the current ${input.stage} Stage using its authoritative packet. Materialize only its required Work graph, declaring real dependencies at registration. If the packet's CLI command registers the graph, use its returned Work graph unchanged: do not add or alter dependencies after registration. Accepted predecessor Stages already fence their completed producers; do not add cross-stage edges merely to restate input provenance. Do not launch children, finish the Stage, or start a successor. Return after registering the graph; the runtime will dispatch its ready Work.`);
     if (fanout.works.failed || fanout.works.cancelled) {
         const projectId = requireProjectByRoot(context, input.projectRoot).id;
         const members = stageWorkIds(context, projectId, input.runId, input.stage);
-        const failures = context.db.all("SELECT work_id,status,result FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ? AND status IN ('failed','cancelled')", [projectId, input.runId, fanout.parent_work_id]).filter(work => members.has(work.work_id)).map(work => {
-            let receipt = {};
-            try {
-                const value = work.result ? JSON.parse(work.result) : null;
-                if (value && typeof value === "object" && !Array.isArray(value))
-                    receipt = value;
-            }
-            catch { /* Missing legacy metadata is unknown. */ }
-            const providerError = safeNativeFailure(receipt.provider_error);
-            const nativeBinding = verifiedNativeWorkFailure(context, { projectRoot: input.projectRoot, runId: input.runId, stage: input.stage, parentSessionId: input.sessionId, parentWorkId: fanout.parent_work_id, workId: work.work_id, receipt });
-            return { work_id: work.work_id, status: work.status, ...(providerError ? { provider_error: providerError } : {}),
-                ...(nativeBinding ? { native_binding: nativeBinding } : {}),
-                ...Object.fromEntries(["terminal_turn_id", "terminal_observed_at"].filter(key => typeof receipt[key] === "string" && receipt[key].length <= 256).map(key => [key, receipt[key]])) };
-        });
-        throw new AppError("fanout_child_failed", "A child Work failed or was cancelled; no retry authority has been issued", 1, { stage: input.stage, run_id: input.runId, parent_work_id: fanout.parent_work_id, failed: fanout.works.failed, cancelled: fanout.works.cancelled, failures, effect: "unknown" });
+        const failedIds = context.db.all("SELECT work_id FROM works WHERE project_id=? AND run_id=? AND parent_work_id=? AND status='failed' ORDER BY work_id", [projectId, input.runId, fanout.parent_work_id]).filter(work => members.has(work.work_id));
+        const explicit = !input.dispatchFence && !fanout.works.cancelled ? failedIds.map(work => explicitWorkFailure(context, projectId, input.runId, work.work_id)) : [];
+        const failure = explicit.length === failedIds.length && explicit.length ? explicit[0] : null;
+        if (failure && !(input.deferredFailure === failure.work_id && fanout.works.ready.length))
+            return { kind: "failure", failure, ready: fanout.works.ready.length > 0 };
+        if (!failure) {
+            const failures = context.db.all("SELECT work_id,status,result FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ? AND status IN ('failed','cancelled')", [projectId, input.runId, fanout.parent_work_id]).filter(work => members.has(work.work_id)).map(work => {
+                let receipt = {};
+                try {
+                    const value = work.result ? JSON.parse(work.result) : null;
+                    if (value && typeof value === "object" && !Array.isArray(value))
+                        receipt = value;
+                }
+                catch { /* Missing legacy metadata is unknown. */ }
+                const providerError = safeNativeFailure(receipt.provider_error);
+                const nativeBinding = verifiedNativeWorkFailure(context, { projectRoot: input.projectRoot, runId: input.runId, stage: input.stage, parentSessionId: input.sessionId, parentWorkId: fanout.parent_work_id, workId: work.work_id, receipt });
+                return { work_id: work.work_id, status: work.status, ...(providerError ? { provider_error: providerError } : {}),
+                    ...(nativeBinding ? { native_binding: nativeBinding } : {}),
+                    ...Object.fromEntries(["terminal_turn_id", "terminal_observed_at"].filter(key => typeof receipt[key] === "string" && receipt[key].length <= 256).map(key => [key, receipt[key]])) };
+            });
+            throw new AppError("fanout_child_failed", "A child Work failed or was cancelled; no retry authority has been issued", 1, { stage: input.stage, run_id: input.runId, parent_work_id: fanout.parent_work_id, failed: fanout.works.failed, cancelled: fanout.works.cancelled, failures, effect: "unknown" });
+        }
     }
     if (fanout.works.ready.length) {
         const choices = fanout.works.ready.map(work => {
@@ -190,7 +231,7 @@ export async function nextControllerFanout(context, input) {
         const run = context.db.get("SELECT flow_kind,run_root,run_dir FROM runs WHERE project_id=? AND id=?", [projectId, input.runId]);
         if (run?.flow_kind === "mb-init" || run?.flow_kind === "mb-upgrade") {
             const attempt = stageAttempt(context, projectId, input.runId, "review");
-            const repair = context.db.get(`SELECT CASE event_type WHEN 'memory.second_repair_registration' THEN 2 ELSE 1 END AS wave
+            const repair = context.db.get(`SELECT CASE event_type WHEN 'memory.second_repair_registration' THEN 2 ELSE 1 END AS wave,json_extract(payload_json,'$.scope.input_sha256') AS input_sha256
         FROM audit_events WHERE project_id=? AND event_type IN ('memory.repair_registration','memory.second_repair_registration')
         AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=?
         AND json_extract(payload_json,'$.scope.parent_work_id')=? ORDER BY wave DESC LIMIT 1`, [projectId, input.runId, attempt, fanout.parent_work_id]);
@@ -198,7 +239,7 @@ export async function nextControllerFanout(context, input) {
         AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=?
         AND json_extract(payload_json,'$.scope.parent_work_id')=? AND json_extract(payload_json,'$.wave')=?`, [projectId, input.runId, attempt, fanout.parent_work_id, repair.wave])) {
                 const args = ["--run", input.runId, "--project-root", input.projectRoot, "--wave", String(repair.wave), "--json"];
-                return prompt("semantic_completion", `Correction wave ${repair.wave} Work has settled. Before Stage finish, run ${runtimeCommand(context, ["memory", "corrections", "checks", ...args])}, then ${runtimeCommand(context, ["memory", "review", "selective-register", ...args])}. Read both complete responses, then end this Turn so the controller can dispatch the independent selective reviewers. Do not finish the Stage or treat repair Work completion as independent acceptance.`);
+                return prompt("semantic_completion", `Correction wave ${repair.wave} Work has settled. Before Stage finish, run ${runtimeCommand(context, ["memory", "corrections", "checks", ...args])}, then ${runtimeCommand(context, ["memory", "review", "selective-register", ...args])}. Read both complete responses, then end this Turn so the controller can dispatch the independent selective reviewers. Do not finish the Stage or treat repair Work completion as independent acceptance.`, controllerSemanticCheckpoint(context, { stage: input.stage, phase: "memory_correction_checks_register", wave: repair.wave, reviewInputSha256: repair.input_sha256 }));
             }
             const wave = repair?.wave ?? 0;
             const runHome = run.run_root ?? run.run_dir;
@@ -214,7 +255,7 @@ export async function nextControllerFanout(context, input) {
                     ? `If the outcome is needs_repair, use the returned canonical findings and correction_plan_binding to author substantive repair tasks with exact owned write_paths. Register that plan with the packet's issued memory corrections register command for wave ${wave + 1}, then end this Turn so the controller can dispatch it. Do not invoke Stage finish before corrections, checks and independent selective review complete.`
                     : "If the outcome is needs_repair or blocked, the two correction waves are exhausted. Use the issued pause command for the concrete unresolved blocker; do not mark it accepted.",
                 "For blocked collection, use the issued pause command. Do not calculate finding hashes, merge or drop findings, edit project files in the coordinator, create speculative Work or start a successor Stage."
-            ].join("\n\n"));
+            ].join("\n\n"), controllerSemanticCheckpoint(context, { stage: input.stage, phase: "memory_collection", wave, command: collect }));
         }
     }
     const finish = currentStageFinishAuthority(context, input.stage);
@@ -222,7 +263,7 @@ export async function nextControllerFanout(context, input) {
         throw new AppError("controller_finish_authority_missing", "Settled child Work has no current Stage finish authority", 1, { stage: input.stage, reconciliation_required: true });
     if (finish.status !== "issued" || !finish.command)
         throw new AppError("controller_finish_authority_pending", "Observe the original Stage finish before another productive dispatch", 1, { stage: input.stage, invocation_id: finish.id, status: finish.status, reconciliation_required: true });
-    return prompt("semantic_completion", semanticCompletionPrompt(input.stage, fanout.works.completed, finish.command));
+    return { ...prompt("semantic_completion", semanticCompletionPrompt(input.stage, fanout.works.completed, finish.command), controllerSemanticCheckpoint(context, { stage: input.stage, phase: "stage_finish", command: finish.command, invocationId: finish.id })), authority: { id: finish.id, status: finish.status } };
 }
 /** Shared pinned runtime normalization; preserve structured errors at the TS boundary. */
 export function controllerNativeChildren(receipt, rootSessionId) {

package/dist/services/controller-result-authority.js

@@ -5,6 +5,7 @@ import { isObservationLoss } from "../harness-runtime/lib/operation-errors.mjs";
 import { terminalProviderRecovery } from "../harness-runtime/lib/provider-overload-policy.mjs";
 import { getVnextFanoutStatus } from "./vnext-fanout.js";
 import { normalizeNativeChildren, nativeTreeReadiness } from "../harness-runtime/lib/native-children.mjs";
+import { failureDecisionReady } from "./controller-work-failure.js";
 /** Disappearance from a truncated child list is not retirement evidence. */
 export function acceptedChildrenRetired(expected, receipt, sessionId, operationId) {
     const children = normalizeNativeChildren(receipt, sessionId);
@@ -37,16 +38,18 @@ export function acceptedTechnicalWorkControl(context, row, controlId) {
         const guard = context.db.get("SELECT recovery_id,generation,status,capture_path FROM run_recovery_guards WHERE project_id=? AND run_id=? ORDER BY generation DESC LIMIT 1", [row.project_id, row.run_id]);
         if (!guard || guard.recovery_id !== control.recovery_id || guard.status !== "sealed" || !guard.capture_path || guard.generation <= row.generation)
             return false;
-        const events = context.db.all("SELECT data_json FROM run_controller_events WHERE controller_id=? AND event_type='technical_dependency_paused' AND json_extract(data_json,'$.control_id')=?", [row.controller_id, controlId]);
-        if (events.length !== 1)
-            return false;
-        const event = JSON.parse(events[0].data_json);
-        if (event.schema_id !== "dd-flow/controller-dependency@1" || event.request_id !== control.request_id || event.generation !== row.generation || typeof event.source_operation_id !== "string")
-            return false;
+        const events = context.db.all("SELECT data_json FROM run_controller_events WHERE controller_id=? AND event_type='technical_dependency_paused' AND json_extract(data_json,'$.control_id')=?", [row.controller_id, controlId]).map(item => JSON.parse(item.data_json));
         const state = JSON.parse(row.state_json), session = state.current_session === null ? null : state.sessions?.[state.current_session];
-        if (!session?.id || !session.owner?.owner_id || event.state_dir !== session.state_dir)
+        if (!session?.id || !session.owner?.owner_id || !events.length || events.some(event => event.schema_id !== "dd-flow/controller-dependency@1"
+            || event.request_id !== control.request_id || event.generation !== row.generation || event.state_dir !== session.state_dir
+            || event.source_operation_id !== undefined && (typeof event.source_operation_id !== "string" || !event.source_operation_id)))
+            return false;
+        // Concurrent observers may add unbound notes to the same immutable control.
+        // They do not revoke one exact accepted source; conflicting sources still do.
+        const sources = [...new Set(events.flatMap(event => event.source_operation_id ? [event.source_operation_id] : []))];
+        if (sources.length !== 1)
             return false;
-        const op = context.db.get("SELECT generation,status,input_json FROM run_controller_operations WHERE controller_id=? AND operation_id=?", [row.controller_id, event.source_operation_id]);
+        const op = context.db.get("SELECT generation,status,input_json FROM run_controller_operations WHERE controller_id=? AND operation_id=?", [row.controller_id, sources[0]]);
         if (!op || op.generation !== row.generation || !["outcome_unknown", "completed"].includes(op.status))
             return false;
         const input = JSON.parse(op.input_json), expected = input.obligation;
@@ -84,6 +87,8 @@ export function controllerObligationAccepted(context, row, expected) {
     const stage = [...stages].reverse().find(item => item.stage === expected.stage && (item.attempt ?? "try-001") === expected.attempt);
     if (!stage || stageCycle(context, row.project_id, row.run_id, expected.stage) !== expected.cycle)
         return false;
+    if (expected.action === "failure_resolution")
+        return Boolean(expected.failure_resolution && failureDecisionReady(expected.failure_resolution));
     if (["done", "skipped"].includes(stage.status))
         return true;
     if (expected.action === "resume")

package/dist/services/controller-work-failure.js

@@ -0,0 +1,198 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { prepareAgentOutputFile } from "../storage/agent-output.js";
+import { parseLifecycleCommand } from "./lifecycle-command.js";
+import { stageAttempt, stageCycle, stageWorkIds } from "./stage-work-graph.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { appendEvent, digest } from "./run-controller-state.js";
+import { retryWork } from "./work-registry.js";
+import { blockStageForRuntime } from "./stage-blocker.js";
+import { pauseStageForUser } from "./stage-pause.js";
+/** SQL settlement provenance, never the worker's prose, distinguishes a semantic refusal. */
+export function explicitWorkFailure(context, projectId, runId, workId) {
+    const work = context.db.get("SELECT w.status,w.result,w.parent_work_id,w.payload_json,r.run_root FROM works w JOIN runs r ON r.project_id=w.project_id AND r.id=w.run_id WHERE w.project_id=? AND w.run_id=? AND w.work_id=?", [projectId, runId, workId]);
+    if (!work || work.status !== "failed" || !work.parent_work_id || work.result === null || !work.run_root)
+        return null;
+    const payload = JSON.parse(work.payload_json ?? "null");
+    if (typeof payload?.kind === "string" && /^(memory|interactive)/.test(payload.kind))
+        return null;
+    if (!context.db.get("SELECT 1 FROM sqlite_schema WHERE name='audit_events'") || !context.db.get("SELECT 1 FROM sqlite_schema WHERE name='lifecycle_invocations'"))
+        return null;
+    const resultHash = digestBytes(work.result);
+    const receipts = context.db.all(`SELECT a.payload_json,l.command,l.status AS invocation_status FROM audit_events a JOIN lifecycle_invocations l ON l.id=json_extract(a.payload_json,'$.invocation_id')
+    WHERE a.project_id=? AND a.event_type='lifecycle.work_settlement' AND json_extract(a.payload_json,'$.run_id')=? AND json_extract(a.payload_json,'$.work_id')=? ORDER BY a.rowid DESC`, [projectId, runId, workId]);
+    for (const row of receipts) {
+        const receipt = JSON.parse(row.payload_json), parsed = parseLifecycleCommand(row.command);
+        if (row.invocation_status !== "settled" || parsed.kind !== "standalone" || parsed.invocation.operation !== "work_fail" || receipt.result_sha256 !== resultHash || receipt.response?.status !== "failed")
+            continue;
+        if (!context.db.get("SELECT 1 FROM work_sessions WHERE id=? AND work_id=? AND status='failed'", [receipt.work_session_id, workId]))
+            continue;
+        return { work_id: workId, work_session_id: receipt.work_session_id, parent_work_id: work.parent_work_id, result_sha256: resultHash, primary_reason: work.result, result_ref: path.join(work.run_root, "works", workId, "result.json") };
+    }
+    return null;
+}
+import { createHash } from "node:crypto";
+const digestBytes = (text) => createHash("sha256").update(text).digest("hex");
+function events(context, row, type) {
+    return context.db.all(`SELECT e.data_json FROM run_controller_events e JOIN run_controllers c ON c.controller_id=e.controller_id WHERE c.project_id=? AND c.run_id=? AND e.event_type=? ORDER BY e.rowid`, [row.project_id, row.run_id, type]).map(e => JSON.parse(e.data_json));
+}
+export function prepareWorkFailureResolution(context, row, stage, failure) {
+    if (!stageWorkIds(context, row.project_id, row.run_id, stage).has(failure.work_id))
+        throw new AppError("work_failure_scope_changed", "Failed Work no longer belongs to this Stage", 1);
+    const current = explicitWorkFailure(context, row.project_id, row.run_id, failure.work_id);
+    if (!current || current.work_session_id !== failure.work_session_id || current.result_sha256 !== failure.result_sha256)
+        throw new AppError("work_failure_scope_changed", "Failed Work receipt changed before resolution", 1);
+    const attempt = stageAttempt(context, row.project_id, row.run_id, stage), cycle = stageCycle(context, row.project_id, row.run_id, stage);
+    const episode = digest([row.project_id, row.run_id, stage, attempt, cycle, failure.work_id, failure.work_session_id, failure.result_sha256]);
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id]);
+    const round = events(context, row, "work_failure_action_applied").filter(e => e.episode_id === episode).length;
+    const root = path.join(run.run_root, "work-failure-resolutions", episode, `round-${round}`);
+    const resolution = { ...failure, episode_id: episode, stage, attempt, cycle, decision_file: path.join(root, "decision-input.json"), accepted_file: path.join(root, "decision.json"), diagnostic_file: path.join(root, "failure.json"),
+        retry_used: events(context, row, "work_failure_action_reserved").some(e => e.action === "retry" && e.work_id === failure.work_id) };
+    fs.mkdirSync(root, { recursive: true });
+    publishImmutableInput(resolution.diagnostic_file, Buffer.from(JSON.stringify({ schema_id: "work-failure-context@1", ...failure, episode_id: episode, stage, attempt, cycle, packet: path.join(run.run_root, "works", failure.work_id, "starts") }, null, 2)), "work_failure_context_changed");
+    if (!fs.existsSync(resolution.decision_file)) {
+        prepareAgentOutputFile(resolution.decision_file);
+        fs.writeFileSync(resolution.decision_file, "", { flag: "wx", mode: 0o600 });
+    }
+    return resolution;
+}
+const text = (value) => typeof value === "string" && value.trim().length > 0;
+export function readFailureDecision(resolution) {
+    const file = fs.existsSync(resolution.accepted_file) ? resolution.accepted_file : resolution.decision_file;
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        throw new AppError("work_failure_decision_invalid", "Expected a regular decision JSON file", 2);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        throw new AppError("work_failure_decision_invalid", "Write one complete decision JSON object", 2);
+    }
+    const keys = ["schema_id", "episode_id", "action", "reason", "evidence_refs", "correction", "blocker", "question"];
+    if (!value || Array.isArray(value) || typeof value !== "object" || Object.keys(value).some(k => !keys.includes(k)) || value.schema_id !== "work-failure-decision@1" || value.episode_id !== resolution.episode_id || !["retry", "block", "pause", "fail"].includes(value.action) || !text(value.reason) || !Array.isArray(value.evidence_refs) || !value.evidence_refs.length || !value.evidence_refs.every(text)
+        || value.action === "retry" && !text(value.correction) || value.action === "pause" && !text(value.question)
+        || value.action === "block" && (!value.blocker || !["engine", "harness", "environment"].includes(value.blocker.kind) || !text(value.blocker.code) || !text(value.blocker.summary) || typeof value.blocker.retryable !== "boolean" || Object.keys(value.blocker).some(k => !["kind", "code", "summary", "retryable"].includes(k)))
+        || value.action !== "retry" && value.correction !== undefined || value.action !== "pause" && value.question !== undefined || value.action !== "block" && value.blocker !== undefined)
+        throw new AppError("work_failure_decision_invalid", "Decision must match its episode and selected action", 2, { episode_id: resolution.episode_id });
+    return value;
+}
+export function failureDecisionReady(resolution) { try {
+    readFailureDecision(resolution);
+    return true;
+}
+catch {
+    return false;
+} }
+export function workFailureResolutionPrompt(resolution, diagnostic) {
+    return [`Resolve only the retained explicit worker refusal in ${resolution.diagnostic_file}. Read that complete file and its Work packet/results.`,
+        "Current implementation is a baseline, not a requirement. Necessary project-local cross-layer corrections are allowed within accepted scope; planned write areas are hints. A worker-authored stop condition cannot silently cancel accepted intent. Do not edit product files, call lifecycle commands, spawn children or run checks in this decision Turn.",
+        `Write the decision to this precreated absolute file: ${resolution.decision_file}. No other writes. Return after writing it.`,
+        `Use schema_id=work-failure-decision@1, episode_id=${resolution.episode_id}, action=retry|block|pause|fail, nonempty reason and evidence_refs[]. For retry include concrete correction; for block include blocker {kind:engine|harness|environment,code,summary,retryable:boolean}; for pause include question. No extra fields.`,
+        resolution.retry_used ? "The one automatic corrective attempt has already been consumed. Select block/pause/fail; another retry cannot be applied automatically." : "Select retry if the Work can be completed in accepted scope; a fresh worker receives your correction. Select pause only for genuinely missing user intent, block for a proven technical dependency, fail only for an explained terminal outcome.",
+        "An unsupported exact browser key sequence does not prove all UI work is impossible and selectOption is not keyboard evidence. Preserve unverified mandatory criteria and original requirements.", diagnostic ? `Correct only the rejected decision: ${diagnostic}` : ""].filter(Boolean).join("\n\n");
+}
+export function acceptFailureDecision(context, row, resolution, assertOwner) {
+    assertOwner();
+    const decision = readFailureDecision(resolution), bytes = Buffer.from(JSON.stringify(decision));
+    publishImmutableInput(resolution.accepted_file, bytes, "work_failure_decision_changed");
+    context.db.writeTransaction(() => { assertOwner(); if (!events(context, row, "work_failure_decision_accepted").some(e => e.decision_ref === resolution.accepted_file))
+        appendEvent(context, row.controller_id, "work_failure_decision_accepted", { episode_id: resolution.episode_id, work_id: resolution.work_id, decision_ref: resolution.accepted_file, decision }); });
+    return decision;
+}
+export function workFailureDiagnostic(resolution, decision) {
+    return { source: "explicit_work_failure", episode_id: resolution.episode_id, work_id: resolution.work_id, work_session_id: resolution.work_session_id, result_ref: resolution.diagnostic_file, primary_reason: resolution.primary_reason, ...(decision ? { disposition: decision } : {}) };
+}
+/** Repair file-before-event and mutation-before-ack crash windows before HITL delivery. */
+export async function reconcilePendingWorkFailure(context, row, state, continuationKind, projectRoot, assertOwner, writerSettled) {
+    const resolution = state.work_failure;
+    if (!resolution || resolution.deferred || !fs.existsSync(resolution.accepted_file) || continuationKind === "terminal")
+        return "none";
+    const session = state.current_session === null ? undefined : state.sessions[state.current_session];
+    if (!session)
+        throw new AppError("work_failure_scope_changed", "Failure resolution lost its coordinator", 1);
+    if (!await writerSettled(session))
+        return "waiting";
+    const decision = acceptFailureDecision(context, row, resolution, assertOwner);
+    applyWorkFailureDecision(context, row, resolution, decision, projectRoot, assertOwner);
+    delete state.work_failure;
+    state.last_continuation = null;
+    return "applied";
+}
+/** Reserve first; a committed retry is recovered through its start authority, never replayed blindly. */
+export function applyWorkFailureDecision(context, row, resolution, decision, projectRoot, assertOwner) {
+    assertOwner();
+    assertRunMutationAllowed(context, row.project_id, row.run_id, row.generation);
+    const index = JSON.parse(context.db.get("SELECT index_json FROM runs WHERE project_id=? AND id=?", [row.project_id, row.run_id])?.index_json ?? "{}");
+    if (resolution.stage !== index.current_stage
+        || resolution.attempt !== stageAttempt(context, row.project_id, row.run_id, resolution.stage) || resolution.cycle !== stageCycle(context, row.project_id, row.run_id, resolution.stage)
+        || !stageWorkIds(context, row.project_id, row.run_id, resolution.stage).has(resolution.work_id))
+        throw new AppError("work_failure_scope_changed", "Failure resolution belongs to a stale Stage attempt", 1);
+    const applied = events(context, row, "work_failure_action_applied").find(e => e.decision_ref === resolution.accepted_file);
+    if (applied)
+        return applied;
+    const reserved = events(context, row, "work_failure_action_reserved").find(e => e.decision_ref === resolution.accepted_file);
+    const current = context.db.get("SELECT status,current_start_invocation_id FROM works WHERE project_id=? AND run_id=? AND work_id=?", [row.project_id, row.run_id, resolution.work_id]);
+    if (!current)
+        throw new AppError("work_failure_scope_changed", "Work disappeared before resolution", 1);
+    let action = decision.action;
+    const used = events(context, row, "work_failure_action_reserved").some(e => e.action === "retry" && e.work_id === resolution.work_id && e.decision_ref !== resolution.accepted_file);
+    const retainedDecision = events(context, row, "work_failure_decision_accepted").find(e => e.decision_ref === resolution.accepted_file);
+    if (!retainedDecision || JSON.stringify(retainedDecision.decision) !== JSON.stringify(decision))
+        throw new AppError("work_failure_scope_changed", "Failure decision was not accepted or changed after acceptance", 1);
+    const exhausted = action === "retry" && used;
+    if (exhausted)
+        action = "block";
+    if (!reserved) {
+        if (current.status !== "failed" || explicitWorkFailure(context, row.project_id, row.run_id, resolution.work_id)?.work_session_id !== resolution.work_session_id)
+            throw new AppError("work_failure_scope_changed", "Failure changed before action reservation", 1);
+        context.db.writeTransaction(() => { assertOwner(); appendEvent(context, row.controller_id, "work_failure_action_reserved", { episode_id: resolution.episode_id, work_id: resolution.work_id, work_session_id: resolution.work_session_id, action, decision_ref: resolution.accepted_file }); });
+    }
+    else if (reserved.action !== action)
+        throw new AppError("work_failure_scope_changed", "Reserved failure action differs", 1);
+    let receipt;
+    if (action === "retry") {
+        receipt = retryWork(context, resolution.work_id, decision.reason, { episode_id: resolution.episode_id, decision_ref: resolution.accepted_file, correction: decision.correction, failed_result_sha256: resolution.result_sha256 });
+    }
+    else if (action === "fail")
+        throw new AppError("work_failure_unresolved", decision.reason, 1, workFailureDiagnostic(resolution, decision));
+    else {
+        const coordinator = context.db.get("SELECT status FROM works WHERE project_id=? AND run_id=? AND work_id=?", [row.project_id, row.run_id, resolution.parent_work_id]);
+        const blocker = exhausted ? { kind: "engine", code: "work_resolution_exhausted", summary: JSON.stringify(workFailureDiagnostic(resolution, decision)), retryable: false } : decision.blocker;
+        const boundBlocker = blocker ? { ...blocker, summary: `${blocker.summary}\n[work-failure:${resolution.episode_id}:${digest(resolution.accepted_file)}]` } : undefined;
+        if (coordinator?.status === "paused" && reserved) {
+            const stage = index.stage_runs?.find((s) => s.stage === resolution.stage);
+            const matches = action === "pause" ? stage?.pause?.work_id === resolution.parent_work_id && typeof stage.pause.question_path === "string" && fs.readFileSync(stage.pause.question_path, "utf8") === decision.question
+                : stage?.blocker?.work_id === resolution.parent_work_id && stage.blocker.code === boundBlocker?.code && stage.blocker.kind === boundBlocker?.kind && stage.blocker.summary === boundBlocker?.summary;
+            if (!matches)
+                throw new AppError("work_failure_scope_changed", "Coordinator pause belongs to another failure action", 1);
+            receipt = { ok: true, reconciled: true, outcome: action === "pause" ? "paused" : "blocked", run_id: row.run_id, stage: resolution.stage, work_id: resolution.parent_work_id, ...(boundBlocker ? { blocker: boundBlocker } : {}) };
+        }
+        else {
+            if (coordinator?.status !== "running")
+                throw new AppError("work_failure_scope_changed", "Failure resolution needs the running coordinator Work", 1);
+            const scope = { projectRoot, runId: row.run_id, stage: resolution.stage, workId: resolution.parent_work_id };
+            receipt = action === "pause" ? pauseStageForUser(context, { ...scope, question: decision.question }) : blockStageForRuntime(context, { ...scope, ...boundBlocker });
+        }
+    }
+    const outcome = { episode_id: resolution.episode_id, decision_ref: resolution.accepted_file, stage: resolution.stage, attempt: resolution.attempt, cycle: resolution.cycle, work_id: resolution.work_id, work_session_id: resolution.work_session_id, action, receipt };
+    context.db.writeTransaction(() => { assertOwner(); appendEvent(context, row.controller_id, "work_failure_action_applied", outcome); });
+    return outcome;
+}
+/** Match only this current bound block; an old unrelated pause must not be hidden. */
+export function workFailureBlockActive(context, row, index) {
+    const stage = index.current_stage;
+    const blocker = index.stage_runs?.find(s => s.stage === stage)?.blocker;
+    if (!stage || !blocker)
+        return false;
+    return events(context, row, "work_failure_action_applied").some(e => {
+        const receipt = e.receipt;
+        if (!receipt)
+            return false;
+        return e.action === "block" && e.stage === stage && e.attempt === stageAttempt(context, row.project_id, row.run_id, stage) && e.cycle === stageCycle(context, row.project_id, row.run_id, stage)
+            && receipt?.work_id === blocker.work_id && receipt.blocker?.summary === blocker.summary && receipt.blocker?.code === blocker.code && receipt.blocker?.kind === blocker.kind;
+    });
+}