@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/stage-pause.js

@@ -1,45 +1,67 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { quote } from "shell-quote";
+import { lifecycleRetryCommands, managedLifecycleCommand, rebindAssignedCoordinatorCommands } from "./lifecycle-invocations.js";
+import { currentAssignedLifecycle, assertAssignedSettlementCurrent } from "./assigned-lifecycle.js";
 import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants, shortEntityReference } from "../shared/entity-references.js";
 import { resolveProjectRoot } from "../storage/paths.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { acceptStagePacket, prepareStagePacket } from "./stage-report-renderer.js";
+import { resolveWorkReference } from "../storage/work-references.js";
 import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
 import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, pauseFlowRunStage, resumeFlowRunStage } from "./runs.js";
 import { bindSessionForResume, refreshRunWorkProjection } from "./work-registry.js";
-export function pauseStageForUser(context, input) {
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { runtimeCommand } from "./runtime-command.js";
+import { prepareAgentOutputFile } from "../storage/agent-output.js";
+import { latestRunVerificationMatrix } from "./verification-matrix.js";
+import { acceptedIntentReviewFingerprint, prepareAcceptedIntentSources, validatePreparedAcceptedIntentReview } from "./accepted-intent.js";
+export { flowCommand } from "./runtime-command.js";
+export function stageResumeSourcePath(pause, answer) {
+    return path.join(path.dirname(pause.question_path), `resume-${crypto.createHash("sha256").update(`${pause.id}\0${answer}`).digest("hex")}.json`);
+}
+export function prepareStagePause(context, input) {
+    if (typeof input.question !== "string" || !input.question.trim())
+        throw new AppError("validation", "stage pause requires a non-empty user question", 2);
+    safeStage(input.stage);
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const work = requireWork(context, project.id, run.id, input.workId);
     if (work.status !== "running")
         throw new AppError("invalid_work_state", "Only a running Work can pause", 1, { work_id: work.work_id, status: work.status });
     const question = input.question;
-    if (!question.trim())
-        throw new AppError("validation", "stage pause requires a non-empty user question", 2);
+    if (Buffer.byteLength(question) > 1024 * 1024)
+        throw new AppError("accepted_intent_source_invalid", "HITL question exceeds the bounded source contract", 2);
     const stage = requireStage(run, input.stage, "running");
+    requireRunHome(run);
+    return { projectRoot, project, run, work, question, stage };
+}
+export function pauseStageForUser(context, input) {
+    const { projectRoot, project, run, work, question, stage } = prepareStagePause(context, input);
     const pauseId = nextPauseId(requireRunHome(run));
     const pauseRoot = path.join(requireRunHome(run), "intake", "hitl", `${pauseId}-${safeStage(input.stage)}`);
     const questionPath = path.join(pauseRoot, "question.md");
     fs.mkdirSync(pauseRoot, { recursive: true });
-    fs.writeFileSync(questionPath, question);
+    publishImmutableInput(questionPath, Buffer.from(question), "hitl_question_conflict");
+    const questionPacket = prepareStagePacket(questionPath, Buffer.from(question));
+    const answerInputPath = prepareAgentOutputFile(path.join(pauseRoot, "answer-input.md"));
     const now = context.now();
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
+    context.db.writeTransaction(() => {
+        assertAssignedSettlementCurrent(context);
         const paused = context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
         if (paused.changes !== 1)
             throw new AppError("invalid_work_state", "Work changed before pause could be accepted", 1, { work_id: work.work_id });
         pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
-    refreshRunWorkProjection(context, project.id, run.id);
-    const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot });
-    const resumeTemplate = `${resume} <<'USER_ANSWER'\n<paste the complete user answer exactly>\nUSER_ANSWER`;
+        acceptStagePacket(context, { projectId: project.id, runId: run.id, stage: stage.stage, prepared: questionPacket });
+        context.db.afterCommit(() => refreshRunWorkProjection(context, project.id, run.id));
+    });
+    const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, answerInputPath });
+    const resumeTemplate = `Write the complete user answer exactly to ${quote([answerInputPath])}, then run:\n${resume}`;
     return {
         ok: true,
         outcome: "paused",
@@ -48,88 +70,204 @@ export function pauseStageForUser(context, input) {
         stage: stage.stage,
         pause: { id: pauseId, reason: "waiting_for_user", question_path: questionPath, user_message: question },
         next_action: "ask_user_then_resume_same_stage",
-        agent_instruction: "Send user_message to the user and stop this Turn. When the user answers, do not interpret or edit the answer first: make resume_command the first flow command, pass the complete raw answer on stdin, then follow the returned continuation prompt. Do not create a RUN, Work, attempt, or stage start.",
+        agent_instruction: `Send user_message to the user and stop this Turn. When the user answers, write the complete raw answer without interpretation to ${answerInputPath}, then make resume_command the first flow command and follow the returned continuation prompt. Do not create a RUN, Work, attempt, or stage start.`,
         resume_command: resume,
         resume_command_template: resumeTemplate
     };
 }
-export function resumeStageAfterUser(context, input) {
+export function prepareStageResume(context, input) {
+    if (typeof input.answer !== "string" || !input.answer.trim())
+        throw new AppError("validation", "stage resume requires a non-empty user answer", 2);
+    safeStage(input.stage);
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
     const work = requireWork(context, project.id, run.id, input.workId);
     if (work.status !== "paused")
         throw new AppError("invalid_work_state", "stage resume requires its paused Work", 1, { work_id: work.work_id, status: work.status });
     const stage = requireStage(run, input.stage, "paused");
     if (!stage.pause || stage.pause.work_id !== work.work_id || stage.pause.answer_path)
         throw new AppError("invalid_stage_state", "Stage has no unanswered pause for this Work", 1, { run_id: run.id, stage: stage.stage, work_id: work.work_id });
-    if (!input.answer.trim())
-        throw new AppError("validation", "stage resume requires a non-empty user answer", 2);
-    const hookEventId = input.hookEventId ?? findRecentMatchingHookEvent(context, {
+    const workSession = context.db.get("SELECT id, session_id, prompt_path, result_path, status FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
+    if (!workSession)
+        throw new AppError("runtime_missing", "Paused Work has no open Session link", 1, { work_id: work.work_id });
+    let evidence = input.evidence;
+    if (evidence && (evidence.pauseId !== stage.pause.id || evidence.promptPath !== workSession.prompt_path || evidence.questionPath !== stage.pause.question_path))
+        throw new AppError("runtime_state_changed", "Paused Work changed after resume preparation", 1, { work_id: work.work_id });
+    if (!evidence) {
+        try {
+            evidence = { pauseId: stage.pause.id, promptPath: workSession.prompt_path, questionPath: stage.pause.question_path, prompt: fs.readFileSync(workSession.prompt_path, "utf8"), question: fs.readFileSync(stage.pause.question_path, "utf8") };
+        }
+        catch (error) {
+            throw new AppError("runtime_missing", "Paused Work continuation artifacts cannot be read", 1, { work_id: work.work_id, cause: String(error) });
+        }
+    }
+    return { projectRoot, project, run, work, stage, pause: stage.pause, workSession, evidence };
+}
+export function resumeStageAfterUser(context, input) {
+    const { projectRoot, project, run, work, stage, pause, workSession, evidence } = prepareStageResume(context, input);
+    const assigned = currentAssignedLifecycle(context);
+    const hookEventId = input.hookEventId ?? (assigned ? undefined : findRecentMatchingHookEvent(context, {
         projectId: project.id,
-        matchKey: stageResumeMatchKey(run.id, stage.stage, work.work_id, projectRoot),
+        matchKey: entityReferenceVariants(run.id).flatMap((runReference) => entityReferenceVariants(work.work_id).map((workReference) => stageResumeMatchKey(runReference, stage.stage, workReference, projectRoot))),
         errorCode: "trusted_stage_resume_required",
         operation: "stage resume"
-    }).eventKey;
-    const answerPath = path.join(path.dirname(stage.pause.question_path), "answer.md");
-    fs.writeFileSync(answerPath, input.answer);
+    }).eventKey);
     const now = context.now();
-    const workSession = context.db.get("SELECT id, session_id, prompt_path, result_path, status FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
-    if (!workSession)
-        throw new AppError("runtime_missing", "Paused Work has no open Session link", 1, { work_id: work.work_id });
-    context.db.exec("BEGIN IMMEDIATE");
-    let identity;
-    try {
-        identity = claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
+    const answerPath = path.join(path.dirname(pause.question_path), `answer-${crypto.createHash("sha256").update(`${pause.id}\0${input.answer}`).digest("hex")}.md`);
+    if (Buffer.byteLength(input.answer) > 1024 * 1024)
+        throw new AppError("accepted_intent_source_invalid", "Delivered user answer exceeds the bounded source contract", 2);
+    // The answer is an immutable, content-addressed input. Prepare it before
+    // reserving SQLite's writer; an unreferenced candidate has no flow authority.
+    publishImmutableInput(answerPath, Buffer.from(input.answer), "hitl_answer_conflict");
+    const answerPacket = prepareStagePacket(answerPath, Buffer.from(input.answer));
+    // Capture the exact continuation inputs and already-issued commands before
+    // accepting the answer. A publication retry must not issue new authority.
+    const retryCommands = [...lifecycleRetryCommands(context, stage.stage), ...rebindAssignedCoordinatorCommands(context)];
+    // Prepare the output outside the writer. A new question gets a distinct
+    // literal input path, hence ordinary lifecycle authority rather than replay
+    // of the successful pause that this answer just resolved.
+    const nextQuestion = preparePauseCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot }, pause.id);
+    const resumeSourcePath = stageResumeSourcePath(pause, input.answer);
+    let review;
+    let reviewPreparationError;
+    const previousAnswer = context.db.get("SELECT MAX(id) AS id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ?", [project.id, run.id])?.id ?? 0;
+    if (["plan-review", "code-review"].includes(stage.stage)) {
+        try {
+            const home = requireRunHome(run), source = latestRunVerificationMatrix(context, project.id, run.id, stage.stage, "input");
+            const reviewContext = path.join(home, stage.stage === "plan-review" ? "04-plan-review/work-context.json" : "06-code-review/review-context.json");
+            const retainedContext = fs.existsSync(reviewContext) ? JSON.parse(fs.readFileSync(reviewContext, "utf8")) : null;
+            const currentSources = acceptedIntentReviewFingerprint(source?.metadata.accepted_sources) ? prepareAcceptedIntentSources(context, { projectId: project.id, runId: run.id, home, stageDirectory: "intake", marked: true }).sources : [];
+            review = { home, source, retainedContext, currentSources };
+        }
+        catch (error) {
+            if (!(error instanceof AppError))
+                throw error;
+            reviewPreparationError = error;
+        }
+    }
+    return context.db.writeTransaction(() => {
+        assertAssignedSettlementCurrent(context, workSession.id);
+        const currentAnswer = context.db.get("SELECT MAX(id) AS id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ?", [project.id, run.id])?.id ?? 0;
+        if (currentAnswer !== previousAnswer)
+            throw new AppError("runtime_state_changed", "Accepted inputs changed during resume preparation", 1);
+        const identity = assigned?.identity ?? claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
         if (workSession.session_id !== identity.sessionId) {
             bindSessionForResume(context, work.work_id, identity, now);
             context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
-            context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)", [`WSES-${crypto.randomUUID()}`, work.work_id, identity.sessionId, identity.hookEventId, workSession.prompt_path, workSession.result_path, now, now]);
+            const prior = context.db.get("SELECT start_receipt_json,start_publication_status FROM work_sessions WHERE id=?", [workSession.id]);
+            context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, start_receipt_json, start_publication_status, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, ?, ?, NULL)", [`WSES-${crypto.randomUUID()}`, work.work_id, identity.sessionId, hookEventId ?? null, workSession.prompt_path, workSession.result_path,
+                JSON.stringify({ ...(prior?.start_receipt_json ? JSON.parse(prior.start_receipt_json) : {}), resumed_from_work_session_id: workSession.id }), prior?.start_publication_status ?? null, now, now]);
         }
         const resumed = context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
         if (resumed.changes !== 1)
             throw new AppError("invalid_work_state", "Work changed before resume could be accepted", 1, { work_id: work.work_id });
         resumeFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, answerPath });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
-    refreshRunWorkProjection(context, project.id, run.id);
-    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
-    const prompt = fs.readFileSync(workSession.prompt_path, "utf8");
-    const continuation = [
-        prompt.trimEnd(),
-        "",
-        "<hitl_resume>",
-        `- Pause: ${stage.pause.id}`,
-        `- Question source: ${stage.pause.question_path}`,
-        `- Answer source: ${answerPath}`,
-        "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
-        "",
-        "<user_question>",
-        fs.readFileSync(stage.pause.question_path, "utf8"),
-        "</user_question>",
-        "",
-        "<user_answer>",
-        input.answer,
-        "</user_answer>",
-        "</hitl_resume>",
-        ""
-    ].join("\n");
-    return { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: stage.pause.id, question_path: stage.pause.question_path, answer_path: answerPath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
+        acceptStagePacket(context, { projectId: project.id, runId: run.id, stage: stage.stage, prepared: answerPacket });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
+        context.db.afterCommit(() => refreshRunWorkProjection(context, project.id, run.id));
+        const prompt = evidence.prompt;
+        const intentInstructions = [];
+        if (["plan-review", "code-review"].includes(stage.stage)) {
+            try {
+                if (reviewPreparationError)
+                    throw reviewPreparationError;
+                if (review) {
+                    const id = context.db.get("SELECT id FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.pause_id') = ? ORDER BY id DESC LIMIT 1", [project.id, run.id, pause.id]).id;
+                    const identity = `accepted_hitl:${String(id).padStart(12, "0")}:${pause.id}`;
+                    const sources = [...review.currentSources, { role: `${identity}:0-question`, sha256: crypto.createHash("sha256").update(evidence.question).digest("hex") }, { role: `${identity}:1-answer`, sha256: crypto.createHash("sha256").update(input.answer).digest("hex") }];
+                    validatePreparedAcceptedIntentReview(context, { projectId: project.id, runId: run.id, home: review.home, stage: stage.stage, decisionFrozen: Boolean(review.retainedContext?.accepted_decision) }, review.source?.metadata.accepted_sources, review.retainedContext?.accepted_intent_review_fingerprint, sources);
+                }
+            }
+            catch (error) {
+                if (!(error instanceof AppError))
+                    throw error;
+                intentInstructions.push(`Accepted-input review boundary: ${error.code}: ${error.message}`);
+                if (error.code === "accepted_intent_review_ack_required")
+                    intentInstructions.push(`Apply/classify this own-stage clarification through the existing coordinator correction/repair route. Include this exact field in the decision: ${JSON.stringify({ accepted_intent_acknowledgement: error.details.accepted_intent_acknowledgement })}. Independent reviewer results prove only the earlier retained inputs; do not claim they reviewed the new answer.`);
+                else
+                    intentInstructions.push("Do not accept stale independent review as coverage of this answer; report the actionable upstream revision/evidence blocker.");
+            }
+        }
+        const pauseCommand = managedLifecycleCommand(context, nextQuestion);
+        const continuation = [
+            prompt.trimEnd(),
+            "",
+            "<hitl_resume>",
+            `- Pause: ${pause.id}`,
+            `- Question source: ${pause.question_path}`,
+            `- Answer source: ${answerPath}`,
+            "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
+            "- If another material user question is needed, write it to the new question-file below and use this replacement pause command. It supersedes earlier pause commands; do not repeat the already settled pause:",
+            pauseCommand,
+            ...intentInstructions,
+            ...(retryCommands.length ? ["- A prior no-effect lifecycle rejection now has these authoritative replacement commands; correct the rejected input and use only these replacements:", ...retryCommands.map(command => `  ${command}`)] : []),
+            "",
+            "<user_question>",
+            evidence.question,
+            "</user_question>",
+            "",
+            "<user_answer>",
+            input.answer,
+            "</user_answer>",
+            "</hitl_resume>",
+            ""
+        ].join("\n");
+        const result = { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: pause.id, question_path: pause.question_path, answer_path: answerPath, resume_source_path: resumeSourcePath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, pause_command: pauseCommand, next_action: `continue_${stage.stage}` };
+        const scope = context.env.DD_FLOW_INVOCATION_SCOPE ? JSON.parse(context.env.DD_FLOW_INVOCATION_SCOPE) : null;
+        const bytes = Buffer.from(`${JSON.stringify({ invocation_id: context.env.DD_FLOW_CURRENT_INVOCATION ?? null, generation: scope?.generation ?? null, result })}\n`);
+        acceptStagePacket(context, { projectId: project.id, runId: run.id, stage: stage.stage, prepared: { file: resumeSourcePath, bytes, sha256: crypto.createHash("sha256").update(bytes).digest("hex") } });
+        return result;
+    });
 }
 export function stagePauseCommand(context, input) {
-    return `${flowCommand(context)} stage pause ${input.runId} --stage ${input.stage} --work ${input.workId} --question-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`;
+    return managedLifecycleCommand(context, preparePauseCommand(context, input));
 }
-/**
- * The only shell form allowed for an agent-owned HITL pause.  Supplying a
- * complete heredoc makes stdin explicit without asking an agent to invent a
- * pipe, a temporary file or a second command.
- */
+function preparePauseCommand(context, input, afterPauseId) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const name = afterPauseId ? `question-input-${crypto.createHash("sha256").update(afterPauseId).digest("hex")}.md` : "question-input.md";
+    const questionInputPath = prepareAgentOutputFile(path.join(requireRunHome(run), "works", input.workId, name));
+    return runtimeCommand(context, ["stage", "pause", shortEntityReference(input.runId), "--stage", input.stage, "--work", shortEntityReference(input.workId), "--question-file", questionInputPath, "--project-root", input.projectRoot, "--json"]);
+}
+/** Recover only the exact resume committed with this invocation; never resume again. */
+export function recoverCommittedStageResume(context, input) {
+    const project = requireProjectByRoot(context, input.projectRoot), run = requireRun(context, project.id, input.runId);
+    const work = requireWork(context, project.id, run.id, input.workId);
+    const index = JSON.parse(run.index_json);
+    const current = index.stage_runs.find(stage => stage.stage === input.stage);
+    if (!current || current.status !== "running" || index.current_stage && index.current_stage !== input.stage || work.status !== "running")
+        return null;
+    const resumed = context.db.get("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_resumed' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.stage') = ? AND json_extract(payload_json, '$.work_id') = ? ORDER BY id DESC LIMIT 1", [project.id, run.id, input.stage, work.work_id]);
+    if (!resumed)
+        return null;
+    const acceptedPause = JSON.parse(resumed.payload_json);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.stage') = ? AND json_extract(payload_json, '$.attempt') = ? AND json_extract(payload_json, '$.file') LIKE '%/resume-%.json' ORDER BY id DESC LIMIT 257", [project.id, run.id, input.stage, current.attempt]);
+    if (rows.length > 256)
+        throw new AppError("stage_resume_receipt_invalid", "Resume receipt count exceeds its bound", 1);
+    let result = null;
+    for (const row of rows) {
+        const packet = JSON.parse(row.payload_json);
+        const bytes = Buffer.from(packet.base64, "base64");
+        if (bytes.length > 8 * 1024 * 1024 || bytes.toString("base64") !== packet.base64 || crypto.createHash("sha256").update(bytes).digest("hex") !== packet.sha256)
+            throw new AppError("stage_resume_receipt_invalid", "Resume receipt custody differs from its committed bytes", 1);
+        const retained = JSON.parse(bytes.toString("utf8"));
+        if (retained.invocation_id !== input.id)
+            continue;
+        const value = retained.result;
+        if (retained.generation !== input.generation || !value || value.run_id !== run.id || value.work_id !== work.work_id || value.stage !== input.stage
+            || value.pause_id !== acceptedPause.pause_id || value.answer_path !== acceptedPause.answer_path || value.resume_source_path !== packet.file || typeof value.worker_prompt_markdown !== "string"
+            || result && JSON.stringify(result) !== JSON.stringify(value))
+            throw new AppError("stage_resume_receipt_invalid", "Resume receipt does not match the current invocation and accepted pause", 1);
+        result = value;
+    }
+    return result;
+}
+/** Render separate file-write and lifecycle-call instructions for HITL. */
 export function stagePauseCommandTemplate(command) {
-    return `${command} <<'USER_QUESTION'
+    const questionFile = command.match(/--question-file\s+(?:'([^']*)'|"([^"]*)"|(\S+))/)?.slice(1).find(Boolean) ?? "<question-file-from-command>";
+    return `Write this text to ${questionFile}:
 ## Q-001 — <short decision title>
 
 Why this decision is required:
@@ -144,27 +282,12 @@ Recommendation:
 
 Effect on scope or acceptance:
 - <one sentence>
-USER_QUESTION`;
+
+Then run this standalone command:
+${command}`;
 }
 function stageResumeCommand(context, input) {
-    return `${flowCommand(context)} stage resume ${input.runId} --stage ${input.stage} --work ${input.workId} --answer-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`;
-}
-export function flowCommand(context) {
-    const defaultHome = path.resolve(path.join(os.homedir(), ".dd-flow"));
-    // Desktop/ACP tool processes are not required to inherit the environment of
-    // the adapter that created their Session.  In an isolated runtime, a bare
-    // `dd-flow` can therefore select the host-global router despite a correct
-    // DD_FLOW_HOME.  The runner supplies an absolute executable for that case;
-    // make every generated lifecycle command self-contained.
-    const executable = context.env.DD_FLOW_BIN;
-    if (executable && path.isAbsolute(executable)) {
-        return `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} ${JSON.stringify(executable)}`;
-    }
-    const isolatedExecutable = path.join(context.ddFlowHome, "bin", "dd-flow");
-    if (context.ddFlowHome !== defaultHome && fs.existsSync(isolatedExecutable)) {
-        return `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} ${JSON.stringify(isolatedExecutable)}`;
-    }
-    return context.ddFlowHome === defaultHome ? "dd-flow" : `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
+    return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "resume", shortEntityReference(input.runId), "--stage", input.stage, "--work", shortEntityReference(input.workId), "--answer-file", input.answerInputPath, "--project-root", input.projectRoot, "--json"]));
 }
 function requireRun(context, projectId, id) {
     const rows = context.db.all("SELECT id, short_id, project_id, project_root, run_root, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, id, id]);
@@ -173,14 +296,19 @@ function requireRun(context, projectId, id) {
     return rows[0];
 }
 function requireWork(context, projectId, runId, workId) {
-    const work = context.db.get("SELECT work_id, project_id, run_id, status FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [projectId, runId, workId]);
-    if (!work)
-        throw new AppError("not_found", "Work does not belong to this RUN", 1, { run_id: runId, work_id: workId });
-    return work;
+    return resolveWorkReference(context, workId, { projectId, runId });
 }
 function requireStage(run, stage, status) {
-    const index = JSON.parse(run.index_json);
-    const found = index.stage_runs?.find((item) => item.stage === stage);
+    let index;
+    try {
+        index = JSON.parse(run.index_json);
+        if (!index || !Array.isArray(index.stage_runs))
+            throw new Error("RUN index must contain stage_runs");
+    }
+    catch (error) {
+        throw new AppError("runtime_state_invalid", "RUN mechanical state in SQLite is missing or invalid", 1, { run_id: run.id, cause: String(error) });
+    }
+    const found = index.stage_runs.find((item) => item.stage === stage);
     if (!found || found.status !== status)
         throw new AppError("invalid_stage_state", `Stage must be ${status}`, 1, { run_id: run.id, stage, status: found?.status ?? "missing" });
     return found;