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

package/dist/services/stage-lifecycle.js

@@ -5,19 +5,31 @@ import { spawnSync } from "node:child_process";
 import { requireProjectByRoot } from "./projects.js";
 import { appendAudit } from "./audit.js";
 import { persistProtocolState, requireProtocol, readProtocolRuntimeState } from "./protocols.js";
-import { attachFlowRunStage, completeFlowRunStage, getFlowRunStatus, startFlowRun } from "./runs.js";
+import { attachFlowRunStage, prepareFlowRunStart, prepareFlowRunStageAttachment, prepareStageDirectory, completeFlowRunStage, getFlowRunStatus, startFlowRun } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
 import { reconcileSessionCoverage, registerFlowSession } from "./sessions.js";
-import { usageForRun } from "./usage.js";
-import { boundCanonicalPlan } from "./plan-runtime.js";
+import { recalculateRunUsage, usageForRun } from "./usage.js";
+import { boundCanonicalPlan, prepareCanonicalPlan } from "./plan-runtime.js";
+import { prepareJsonFile, prepareJsonSchema, prepareOutputDirectory, prepareOutputFile, prepareTextFile } from "../cli/input-preparation.js";
 import { AppError } from "../shared/errors.js";
-import { planJsonPath, resolveProjectRoot } from "../storage/paths.js";
+import { planJsonPath, projectHome, resolveProjectRoot } from "../storage/paths.js";
 import { resolveCanonRoot } from "./canon.js";
 import { preflightMemoryPermissions } from "./memory-permissions.js";
 import { registerProject } from "./projects.js";
 import { registerProtocol } from "./protocols.js";
 import { previewNextEntityId } from "./ids.js";
 import { hookSessionIdentity, sessionIdForHookEvent } from "./hooks.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+function stageUsageProjection(context, view, stage, startedAt) {
+    if (!startedAt)
+        return { status: "unavailable", input_tokens: null, cached_input_tokens: null, output_tokens: null, total_tokens: null, session_count: 0, observed_at: context.now() };
+    const value = recalculateRunUsage(context, { projectId: view.run.project_id, runId: view.run.id, stage: { name: stage, startedAt, completedAt: context.now() } });
+    const totals = value.totals, coverage = value.coverage;
+    const count = (name) => typeof coverage?.[name] === "number" ? coverage[name] : 0;
+    const measured = count("measured"), other = Object.values(coverage ?? {}).reduce((total, item) => total + (typeof item === "number" ? item : 0), 0) - measured;
+    const tokens = (name) => typeof totals?.[name] === "number" ? totals[name] : null;
+    return { status: measured === 0 ? "unavailable" : other > 0 || ["input_tokens", "cache_read_input_tokens", "output_tokens", "total_tokens"].some(name => tokens(name) === null) ? "partial" : "measured", input_tokens: tokens("input_tokens"), cached_input_tokens: tokens("cache_read_input_tokens"), output_tokens: tokens("output_tokens"), total_tokens: tokens("total_tokens"), session_count: Array.isArray(value.sessions) ? value.sessions.length : 0, observed_at: typeof value.observed_at === "string" ? value.observed_at : context.now() };
+}
 const stagePromptSections = [
     "stage_identity",
     "authoritative_runtime_facts",
@@ -28,63 +40,30 @@ const stagePromptSections = [
     "work_contract",
     "completion_contract"
 ];
-function bootstrapStageRun(context, projectRoot, input) {
-    if (input.stage !== "specify") {
-        throw new AppError("validation", "--bootstrap currently starts the initial specify stage only", 2, { stage: input.stage });
-    }
-    const subject = input.bootstrap?.subject.trim();
-    if (!subject)
-        throw new AppError("usage", "--bootstrap requires --subject", 2);
+function bootstrapStageRun(context, projectRoot, bootstrap, intakeMarkdown) {
     registerProject(context, { root: projectRoot });
-    const preview = previewNextEntityId(context, { projectRoot, type: "protocol", slug: subject });
-    const protocolId = preview.entity.id;
-    registerProtocol(context, { handshakeId: protocolId, projectRoot });
-    const started = startFlowRun(context, {
-        projectRoot,
-        flowKind: "mb_sdlc",
-        subjectType: "protocol",
-        subjectId: protocolId,
-        slug: subject,
-        nextAction: "run_specify"
-    });
-    const intakeFile = input.bootstrap?.intakeFile;
-    if (intakeFile) {
-        const source = path.resolve(intakeFile);
-        if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
-            throw new AppError("not_found", "--intake-file must point to an existing file", 1, { intake_file: intakeFile });
-        }
+    registerProtocol(context, { handshakeId: bootstrap.protocolId, projectRoot });
+    const started = startFlowRun(context, bootstrap.startInput, bootstrap.start);
+    if (intakeMarkdown !== undefined) {
         if (!started.run.run_root)
             throw new AppError("runtime_missing", "New RUN has no artifact root", 1, { run_id: started.run.id });
         const intakeDir = path.join(started.run.run_root, "intake");
         fs.mkdirSync(intakeDir, { recursive: true });
-        fs.copyFileSync(source, path.join(intakeDir, "user-request.md"));
+        fs.writeFileSync(path.join(intakeDir, "user-request.md"), intakeMarkdown);
     }
     return started.run.id;
 }
-function stagePreflight(projectRoot, stageRoot) {
+function stagePreflight(projectRoot) {
     const memoryBank = preflightMemoryPermissions({
         root: projectRoot,
         memoryBank: ".memory-bank",
         flow: "custom",
-        mode: "write",
+        mode: "read",
         targets: [{ path: ".memory-bank", mode: "read" }]
     });
-    const probe = path.join(stageRoot, `.dd-flow-permission-${crypto.randomUUID()}`);
-    try {
-        fs.writeFileSync(probe, "");
-        fs.renameSync(probe, `${probe}.renamed`);
-        fs.rmSync(`${probe}.renamed`);
-        return { ...memoryBank, ok: memoryBank.ok === true, stage_workspace: { path: stageRoot, status: "passed" } };
-    }
-    catch (error) {
-        for (const candidate of [probe, `${probe}.renamed`]) {
-            try {
-                fs.rmSync(candidate, { force: true });
-            }
-            catch { /* best effort */ }
-        }
-        return { ...memoryBank, ok: false, stage_workspace: { path: stageRoot, status: "failed", message: String(error) } };
-    }
+    if (memoryBank.ok !== true)
+        throw new AppError("permission_preflight_failed", "Stage project context is not readable", 1, { preflight: memoryBank });
+    return memoryBank;
 }
 function flowKindForStage(stage) {
     return ["code", "implementation", "readiness", "merge"].includes(stage) ? "implementation" : "planning";
@@ -103,23 +82,57 @@ function runtimeFacts(view, projectRoot) {
         git: view.index.execution?.git ?? { branch: null, head: null, status: "unavailable" }
     };
 }
-export function startStage(context, input) {
+export function prepareLegacyStageStart(context, input, intakeMarkdown) {
+    if (input.bootstrap && input.stage !== "specify")
+        throw new AppError("validation", "--bootstrap currently starts the initial specify stage only", 2);
+    if (input.bootstrap && !input.bootstrap.subject?.trim())
+        throw new AppError("usage", "--bootstrap requires --subject", 2);
+    if (!input.bootstrap && !input.runId)
+        throw new AppError("usage", "stage start requires a RUN id or --bootstrap", 2);
+    if (input.dir !== undefined)
+        prepareStageDirectory(input.dir);
+    const intake = intakeMarkdown ?? (input.bootstrap?.intakeFile ? prepareTextFile(input.bootstrap.intakeFile, "SPECIFY intake").text : undefined);
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const retained = !input.bootstrap && input.runId ? runView(getFlowRunStatus(context, { projectRoot, runId: input.runId })) : null;
+    const dir = input.dir ?? defaultStageDir(input.stage, retained?.run.flow_kind ?? "mb_sdlc");
+    if (retained) {
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: retained.run.id, stage: input.stage, dir, status: "running", dataSchemaId: dataSchemaForStage(input.stage) });
+        const root = path.join(runHomePath(retained.run), dir);
+        for (const name of ["stage-prompt.md", "stage-prompt.json", "stage-start.json", "stage-input.json"])
+            prepareOutputFile(path.join(root, name));
+        if (retained.run.subject.type === "protocol")
+            readProtocolRuntimeState(context, requireProtocol(context, retained.run.subject.id, retained.run.project_id));
+    }
+    const preflight = stagePreflight(projectRoot);
+    const sources = stageInstructionSources(context, projectRoot, retained?.run.flow_kind ?? "mb_sdlc", input.stage).map(source => ({ ...source, text: fs.existsSync(source.absolute) ? fs.readFileSync(source.absolute, "utf8").trim() : "(unavailable)" }));
+    let bootstrap;
+    if (input.bootstrap) {
+        const project = context.db.get("SELECT id FROM projects WHERE root = ?", [projectRoot]);
+        prepareOutputDirectory(project ? projectHome(context.ddFlowHome, project.id) : path.join(context.ddFlowHome, "projects"));
+        const preview = previewNextEntityId(context, { projectRoot, type: "protocol", slug: input.bootstrap.subject });
+        const startInput = { projectRoot, flowKind: "mb_sdlc", subjectType: "protocol", subjectId: preview.entity.id, slug: input.bootstrap.subject, nextAction: "run_specify" };
+        bootstrap = { protocolId: preview.entity.id, startInput, start: prepareFlowRunStart(context, startInput) };
+    }
+    return { intakeMarkdown: intake, projectRoot, retained, dir, preflight, sources, bootstrap };
+}
+export function startStage(context, input, prepared = prepareLegacyStageStart(context, input)) {
     if (input.requireSessionBinding && !input.hookEventId) {
         throw new AppError("trusted_session_binding_required", "This stage requires a trusted harness lifecycle binding; run it from a controlled Session with the dd-flow adapter enabled", 1);
     }
-    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const { projectRoot, retained, dir, preflight, sources } = prepared;
+    if (retained)
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: retained.run.id, stage: input.stage, dir: input.dir ?? defaultStageDir(input.stage, retained.run.flow_kind), status: "running", dataSchemaId: dataSchemaForStage(input.stage) });
     let requiredSessionId = null;
     let requiredIdentity = null;
     if (input.requireSessionBinding) {
-        registerProject(context, { root: projectRoot });
         requiredIdentity = hookSessionIdentity(context, requireProjectByRoot(context, projectRoot).id, input.hookEventId);
         requiredSessionId = requiredIdentity.sessionId;
     }
-    const runId = input.bootstrap ? bootstrapStageRun(context, projectRoot, input) : input.runId;
+    const runId = prepared.bootstrap ? bootstrapStageRun(context, projectRoot, prepared.bootstrap, prepared.intakeMarkdown) : input.runId;
     if (!runId)
         throw new AppError("usage", "stage start requires a RUN id or --bootstrap", 2);
-    const before = runView(getFlowRunStatus(context, { projectRoot, runId }));
-    const dir = input.dir ?? defaultStageDir(input.stage, before.run.flow_kind);
+    const before = retained ?? runView(getFlowRunStatus(context, { projectRoot, runId }));
+    assertRunMutationAllowed(context, before.run.project_id, before.run.id);
     const attached = runView(attachFlowRunStage(context, {
         projectRoot,
         runId,
@@ -132,9 +145,6 @@ export function startStage(context, input) {
     const stageRoot = path.join(runHome, dir);
     ensureWithin(runHome, stageRoot, "stage root");
     fs.mkdirSync(stageRoot, { recursive: true });
-    const preflight = stagePreflight(projectRoot, stageRoot);
-    if (preflight.ok !== true)
-        throw new AppError("permission_preflight_failed", "Stage workspace is not writable", 1, { preflight });
     if (attached.run.subject.type === "protocol") {
         syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
     }
@@ -142,7 +152,7 @@ export function startStage(context, input) {
     if (sessionId) {
         const identity = requiredIdentity ?? (input.hookEventId ? hookSessionIdentity(context, attached.run.project_id, input.hookEventId) : null);
         registerFlowSession(context, {
-            sessionId,
+            hookEventId: input.hookEventId,
             payloadJson: JSON.stringify({
                 project_root: projectRoot,
                 harness: identity?.harness ?? "codex-desktop",
@@ -167,7 +177,7 @@ export function startStage(context, input) {
         });
     }
     const promptPath = path.join(stageRoot, "stage-prompt.md");
-    const prompt = composeStagePrompt(context, projectRoot, before, attached, input.stage, dir, preflight);
+    const prompt = composeStagePrompt(context, projectRoot, before, attached, input.stage, dir, preflight, sources);
     atomicWrite(promptPath, prompt);
     const semanticInputPath = path.join(stageRoot, "stage-input.json");
     if (!fs.existsSync(semanticInputPath)) {
@@ -178,7 +188,6 @@ export function startStage(context, input) {
     const aspectMapPath = path.join(stageRoot, "aspect-map.json");
     const attempt = attached.index.stage_runs?.find((stage) => stage.stage === input.stage)?.attempt ?? "try-001";
     const attemptNumber = Number(attempt.replace("try-", "")) || 1;
-    const sources = stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage);
     atomicWrite(promptDataPath, {
         schema_id: "dd-flow/stage-prompt@2",
         run_id: attached.run.id,
@@ -257,12 +266,13 @@ export function startStage(context, input) {
         lifecycle: "stage start -> semantic work -> stage finish"
     };
 }
-export function finishStage(context, input) {
+export function prepareStageFinish(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     if (!input.runId)
         throw new AppError("usage", "stage finish requires a RUN id", 2);
     const runId = input.runId;
     const view = runView(getFlowRunStatus(context, { projectRoot, runId }));
+    assertRunMutationAllowed(context, view.run.project_id, view.run.id);
     const existing = view.index.stage_runs?.find((stage) => stage.stage === input.stage);
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${input.stage}`, 1, { run_id: view.run.id, stage: input.stage });
@@ -271,31 +281,38 @@ export function finishStage(context, input) {
     const runHome = runHomePath(view.run);
     const stageRoot = path.join(runHome, dir);
     ensureWithin(runHome, stageRoot, "stage root");
-    fs.mkdirSync(stageRoot, { recursive: true });
     const semanticFile = resolveStageFile(input.semanticFile ?? "@stage/stage-input.json", stageRoot, runHome);
-    const receipt = beginFinishReceipt(context, stageRoot, semanticFile, view.run.id, input.stage);
+    ensureWithin(runHome, semanticFile, "semantic file");
+    const source = prepareJsonSchema(semanticFile, "Stage finish input", { schemaName: "stage-finish-input", projectRoot, runId, runRoot: runHome, ddFlowHome: context.ddFlowHome });
+    const semantic = source.value;
+    const status = stringValue(semantic.status) ?? "done";
+    if (!["done", "waiting_for_user", "blocked", "failed"].includes(status)) {
+        throw new AppError("validation", "Stage finish status must be done, waiting_for_user, blocked, or failed", 2, { status });
+    }
+    validateStageOutcome(input.stage, status, semantic);
+    const planFinish = input.stage === "plan" ? preparePlanFinish(context, projectRoot, view, stageRoot) : undefined;
+    return { projectRoot, runId, view, existing, runHome, stageRoot, semanticFile, semantic, status, source, planFinish };
+}
+export function finishStage(context, input, prepared = prepareStageFinish(context, input)) {
+    const { projectRoot, runId, view, existing, runHome, stageRoot, semanticFile, semantic, status, source, planFinish } = prepared;
+    assertRunMutationAllowed(context, view.run.project_id, view.run.id);
+    fs.mkdirSync(stageRoot, { recursive: true });
+    const receipt = beginFinishReceipt(context, stageRoot, semanticFile, view.run.id, input.stage, source.text);
     try {
-        validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot, runId, runRoot: runHome, ddFlowHome: context.ddFlowHome });
-        const semantic = readSemanticFile(semanticFile, runHome);
-        const status = stringValue(semantic.status) ?? "done";
-        if (!["done", "waiting_for_user", "blocked", "failed"].includes(status)) {
-            throw new AppError("validation", "Stage finish status must be done, waiting_for_user, blocked, or failed", 2, { status });
-        }
-        validateStageOutcome(input.stage, status, semantic);
         const coverage = workerCoverage(context, view.run.project_id, view.run.id);
         if (coverage.jobs.missing?.length) {
             throw new AppError("worker_jobs_incomplete", "Stage finish requires all declared worker jobs", 1, { coverage });
         }
         const lint = runTargetedMemoryBankLint(projectRoot);
-        const planFinish = input.stage === "plan"
-            ? preparePlanFinish(context, projectRoot, view, stageRoot)
-            : undefined;
+        if (planFinish)
+            boundCanonicalPlan(context, { projectId: view.run.project_id, protocolId: view.run.subject.id, planPath: planFinish.plan_path }, planFinish.canonical);
+        const stageUsage = stageUsageProjection(context, view, input.stage, existing.started_at);
         const report = buildStageReport(context, view, input.stage, status, semantic, stageRoot, lint, planFinish);
         const dataPath = path.join(stageRoot, "stage-report.json");
         const reportPath = path.join(stageRoot, "stage-report.md");
         const htmlPath = path.join(stageRoot, "stage-report.html");
+        validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, data: report, projectRoot, runId, runRoot: runHome, ddFlowHome: context.ddFlowHome });
         atomicWrite(dataPath, report);
-        validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, projectRoot, runId, runRoot: runHome, ddFlowHome: context.ddFlowHome });
         atomicWrite(reportPath, renderMarkdown(report));
         atomicWrite(htmlPath, renderHtml(projectRoot, report));
         if (view.run.subject.type === "protocol") {
@@ -310,7 +327,8 @@ export function finishStage(context, input) {
             stageReport: htmlPath,
             data: dataPath,
             dataSchemaId: String(report.schema_id),
-            report: reportPath
+            report: reportPath,
+            usage: stageUsage
         });
         finishReceipt(receipt, { outcome: "accepted", result: { status, report: dataPath } });
         appendAudit(context, {
@@ -480,12 +498,10 @@ function semanticInputTemplate(stage) {
         next_action: waiting ? "waiting_for_user: obtain the clarification packet" : "Continue to the next approved stage."
     };
 }
-function composeStagePrompt(context, projectRoot, before, current, stage, dir, preflight) {
+function composeStagePrompt(context, projectRoot, before, current, stage, dir, preflight, sources) {
     const project = requireProjectByRoot(context, projectRoot);
     const runHome = runHomePath(current.run);
-    const instructions = stageInstructionSources(context, projectRoot, current.run.flow_kind, stage).map(({ label, absolute }) => {
-        return fs.existsSync(absolute) ? `### ${label}\n\n${fs.readFileSync(absolute, "utf8").trim()}` : `### ${label}\n\n(unavailable)`;
-    }).join("\n\n");
+    const instructions = sources.map(({ label, text }) => `### ${label}\n\n${text}`).join("\n\n");
     const protocol = safeProtocolState(context, current.run.project_id, current.run.subject.id);
     return [
         "<stage_identity>",
@@ -508,7 +524,7 @@ function composeStagePrompt(context, projectRoot, before, current, stage, dir, p
         "</authoritative_runtime_facts>",
         "",
         "<preflight>",
-        `- Permission probe: ${String(preflight.ok === true ? "passed" : "failed")}.`,
+        `- Read-only permission check: ${String(preflight.ok === true ? "passed" : "failed")}.`,
         "- CLI compatibility was checked before this state-changing command.",
         "</preflight>",
         "",
@@ -581,16 +597,6 @@ function safeProtocolState(context, projectId, protocolId) {
         return undefined;
     }
 }
-function readSemanticFile(file, runHome) {
-    const resolved = path.resolve(file);
-    ensureWithin(runHome, resolved, "semantic file");
-    if (!fs.existsSync(resolved))
-        throw new AppError("not_found", "Semantic input file is missing", 1, { path: file });
-    const value = JSON.parse(fs.readFileSync(resolved, "utf8"));
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new AppError("validation", "Semantic input must be a JSON object", 2);
-    return value;
-}
 function validateStageOutcome(stage, status, semantic) {
     if (stage !== "specify")
         return;
@@ -602,17 +608,12 @@ function validateStageOutcome(stage, status, semantic) {
         throw new AppError("semantic_status_inconsistent", "SPECIFY done cannot contain unresolved structured questions", 2);
     }
 }
-function beginFinishReceipt(context, stageRoot, semanticFile, runId, stage) {
+function beginFinishReceipt(context, stageRoot, semanticFile, runId, stage, raw) {
     const receiptDir = path.join(stageRoot, "finish-receipts");
     fs.mkdirSync(receiptDir, { recursive: true });
     const number = fs.readdirSync(receiptDir).filter((file) => /^\d{3}\.json$/u.test(file)).length + 1;
     const receiptPath = path.join(receiptDir, `${String(number).padStart(3, "0")}.json`);
-    let raw = null;
-    try {
-        raw = fs.readFileSync(semanticFile, "utf8");
-    }
-    catch { /* receipt records the missing input below */ }
-    const semanticSha = raw === null ? null : crypto.createHash("sha256").update(raw).digest("hex");
+    const semanticSha = crypto.createHash("sha256").update(raw).digest("hex");
     atomicWrite(receiptPath, {
         schema_id: "dd-flow/stage-finish-receipt@1",
         run_id: runId,
@@ -775,17 +776,13 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
 }
 function preparePlanFinish(context, projectRoot, view, stageRoot) {
     const planPath = planJsonPath(projectRoot, view.run.subject.id);
-    const canonical = boundCanonicalPlan(context, {
+    const canonical = prepareCanonicalPlan(context, {
         projectId: view.run.project_id,
         protocolId: view.run.subject.id,
         planPath
     });
     const aspectMapPath = path.join(stageRoot, "aspect-map.json");
-    if (!fs.existsSync(aspectMapPath)) {
-        throw new AppError("not_found", "PLAN aspect-map.json is missing", 1, { path: aspectMapPath });
-    }
-    const raw = fs.readFileSync(aspectMapPath, "utf8");
-    const value = JSON.parse(raw);
+    const { text: raw, value } = prepareJsonFile(aspectMapPath, "PLAN aspect map");
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new AppError("validation", "PLAN aspect-map.json must be a JSON object", 2, { path: aspectMapPath });
     }

package/dist/services/stage-pause.js

@@ -1,31 +1,44 @@
 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 } from "./lifecycle-invocations.js";
 import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants, shortEntityReference } from "../shared/entity-references.js";
 import { resolveProjectRoot } from "../storage/paths.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";
+export { flowCommand } from "./runtime-command.js";
+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);
     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);
     const now = context.now();
-    context.db.exec("BEGIN IMMEDIATE");
+    context.db.beginWriteTransaction();
     try {
         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)
@@ -38,8 +51,9 @@ export function pauseStageForUser(context, input) {
         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`;
+    const answerInputPath = path.join(pauseRoot, "answer-input.md");
+    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,39 +62,62 @@ 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 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 hookEventId = input.hookEventId ?? 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);
     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");
+    const answerPath = path.join(path.dirname(pause.question_path), `answer-${crypto.createHash("sha256").update(`${pause.id}\0${input.answer}`).digest("hex")}.md`);
+    context.db.beginWriteTransaction();
     let identity;
     try {
         identity = claimStageResumeHookEvent(context, { projectId: project.id, runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot, eventKey: hookEventId });
+        try {
+            fs.writeFileSync(answerPath, input.answer, { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST" || fs.readFileSync(answerPath, "utf8") !== input.answer)
+                throw error;
+        }
         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]);
@@ -98,18 +135,20 @@ export function resumeStageAfterUser(context, input) {
     }
     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 prompt = evidence.prompt;
+    const retryCommands = lifecycleRetryCommands(context, stage.stage);
     const continuation = [
         prompt.trimEnd(),
         "",
         "<hitl_resume>",
-        `- Pause: ${stage.pause.id}`,
-        `- Question source: ${stage.pause.question_path}`,
+        `- 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.",
+        ...(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>",
-        fs.readFileSync(stage.pause.question_path, "utf8"),
+        evidence.question,
         "</user_question>",
         "",
         "<user_answer>",
@@ -118,18 +157,18 @@ export function resumeStageAfterUser(context, input) {
         "</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}` };
+    return { 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, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
 }
 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`;
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = requireRun(context, project.id, input.runId);
+    const questionInputPath = path.join(requireRunHome(run), "works", input.workId, "question-input.md");
+    return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "pause", shortEntityReference(input.runId), "--stage", input.stage, "--work", shortEntityReference(input.workId), "--question-file", questionInputPath, "--project-root", input.projectRoot, "--json"]));
 }
-/**
- * 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.
- */
+/** 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 +183,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 +197,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;