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

package/dist/services/stage-pause.js

@@ -1,45 +1,55 @@
 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 { publishImmutableInput } from "../storage/immutable-input.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";
+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);
+    publishImmutableInput(questionPath, Buffer.from(question), "hitl_question_conflict");
+    const answerInputPath = prepareAgentOutputFile(path.join(pauseRoot, "answer-input.md"));
     const now = context.now();
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
+    context.db.writeTransaction(() => {
         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`;
+        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,39 +58,56 @@ 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");
-    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`);
+    // 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");
+    context.db.writeTransaction(() => {
+        const 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]);
@@ -90,26 +117,23 @@ export function resumeStageAfterUser(context, input) {
         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");
+        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 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 +142,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 = prepareAgentOutputFile(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 +168,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 +182,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;

package/dist/services/stage-report-renderer.js

@@ -1,14 +1,171 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { withProjectionLock } from "../storage/projection-lock.js";
 import { writeJsonAtomic } from "../storage/paths.js";
 /** Deterministic JSON -> Markdown/HTML projection shared by every stage. */
 export function writeStageReport(root, report) {
     const json = path.join(root, "stage-report.json");
     const markdown = path.join(root, "stage-report.md");
     const html = path.join(root, "stage-report.html");
+    const normalized = normalizeStageReport(report);
+    writeJsonAtomic(json, normalized);
+    const text = renderStageReportMarkdown(normalized);
+    fs.writeFileSync(markdown, text);
+    fs.writeFileSync(html, renderStageReportHtml(normalized, text));
+    return { json, markdown, html };
+}
+export function prepareStageReport(report) {
+    const normalized = normalizeStageReport(report);
+    const json = `${JSON.stringify(normalized, null, 2)}\n`;
+    const markdown = renderStageReportMarkdown(normalized);
+    const html = renderStageReportHtml(normalized, markdown);
+    return { normalized, bytes: { json, markdown, html }, sha256: crypto.createHash("sha256").update(json).digest("hex") };
+}
+export function prepareStagePacket(file, bytes) {
+    if (fs.existsSync(file) && !bytes.equals(fs.readFileSync(file)))
+        throw new AppError("stage_packet_conflict", "An existing Stage packet differs from prepared bytes", 2, { file });
+    return { file, bytes, sha256: crypto.createHash("sha256").update(bytes).digest("hex") };
+}
+export function acceptStagePacket(context, input) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const index = run ? JSON.parse(run.index_json) : null;
+    const attempt = index?.stage_runs?.find((item) => item.stage === input.stage)?.attempt;
+    if (!attempt)
+        throw new AppError("stage_packet_owner_missing", "Stage packet has no owning attempt", 1, { run_id: input.runId, stage: input.stage });
+    const payload = { run_id: input.runId, stage: input.stage, attempt, file: input.prepared.file, sha256: input.prepared.sha256, base64: input.prepared.bytes.toString("base64") };
+    context.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.stage_packet', 0, ?, ?)", [input.projectId, JSON.stringify(payload), context.now()]);
+    context.db.afterCommit(() => publishStagePacket(context, input.projectId, input.runId, input.stage, input.prepared.file));
+}
+export function publishStagePacket(context, projectId, runId, stage, file) {
+    file = resolveStagePublicationPath(context, projectId, runId, file);
+    assertPublicationPath(context, projectId, runId, file);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    withProjectionLock(`${file}.publish-lock`, () => {
+        assertPublicationPath(context, projectId, runId, file);
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const index = run ? JSON.parse(run.index_json) : null;
+        const currentAttempt = index?.stage_runs?.find((item) => item.stage === stage)?.attempt;
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' ORDER BY id DESC", [projectId]);
+        const packet = rows.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.attempt === currentAttempt && resolveStagePublicationPath(context, projectId, runId, item.file) === file);
+        if (!packet)
+            return;
+        const bytes = Buffer.from(packet.base64, "base64");
+        if (crypto.createHash("sha256").update(bytes).digest("hex") !== packet.sha256)
+            throw new AppError("stage_packet_invalid", "Stored Stage packet hash does not match its bytes", 1, { file });
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        try {
+            fs.writeFileSync(file, bytes, { flag: "wx" });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (!bytes.equals(fs.readFileSync(file)))
+                throw new AppError("stage_packet_conflict", "Accepted Stage packet differs from the published file", 1, { file, run_id: runId, stage, attempt: currentAttempt });
+        }
+    });
+}
+/** SQL receipt and exact bytes are committed with the owning Stage transition. */
+export function acceptStageReport(context, input) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const index = run ? JSON.parse(run.index_json) : null;
+    const attempt = index?.stage_runs?.find((item) => item.stage === input.stage)?.attempt;
+    if (!attempt)
+        throw new AppError("stage_report_owner_missing", "Stage report has no owning attempt", 1, { run_id: input.runId, stage: input.stage });
+    const payload = { run_id: input.runId, stage: input.stage, attempt, root: input.root, sha256: input.prepared.sha256, bytes: input.prepared.bytes };
+    context.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.stage_report', 0, ?, ?)", [input.projectId, JSON.stringify(payload), context.now()]);
+    context.db.afterCommit(() => publishStageReport(context, input.projectId, input.runId, input.stage, input.root));
+}
+/** Replays the latest committed receipt, never an obsolete attempt. */
+export function publishStageReport(context, projectId, runId, stage, root) {
+    root = resolveStagePublicationPath(context, projectId, runId, root);
+    assertPublicationPath(context, projectId, runId, root);
+    withProjectionLock(`${root}.report-publish-lock`, () => {
+        assertPublicationPath(context, projectId, runId, root);
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const index = run ? JSON.parse(run.index_json) : null;
+        const currentAttempt = index?.stage_runs?.find((item) => item.stage === stage)?.attempt;
+        const events = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [projectId]);
+        const receipt = events.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.attempt === currentAttempt && resolveStagePublicationPath(context, projectId, runId, item.root) === root);
+        if (!receipt)
+            return;
+        fs.mkdirSync(root, { recursive: true });
+        for (const [name, bytes] of Object.entries(receipt.bytes)) {
+            const file = path.join(root, `stage-report.${name === "json" ? "json" : name === "markdown" ? "md" : "html"}`);
+            assertPublicationPath(context, projectId, runId, file);
+            try {
+                fs.writeFileSync(file, bytes, { flag: "wx" });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (fs.readFileSync(file, "utf8") !== bytes)
+                    throw new AppError("stage_report_conflict", "Accepted Stage report differs from the published file", 1, { run_id: runId, stage, attempt: currentAttempt, file });
+            }
+        }
+    });
+}
+/** Operational destinations follow validated imports, while audit bytes retain
+ * their original locators. SQL-only so readers may also use it in settlement. */
+export function resolveStagePublicationPath(context, projectId, runId, locator) {
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run?.run_root || !path.isAbsolute(locator))
+        throw new AppError("stage_packet_invalid", "Stage publication has no absolute bound RUN locator", 1, { run_id: runId, locator });
+    let destination = path.resolve(locator);
+    const mappings = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.publication_relocation' ORDER BY id", [projectId]);
+    for (const row of mappings) {
+        const mapping = JSON.parse(row.payload_json);
+        if (mapping.run_id !== runId || !path.isAbsolute(mapping.from) || !path.isAbsolute(mapping.to))
+            continue;
+        const relative = path.relative(mapping.from, destination);
+        if (relative && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+            destination = path.resolve(mapping.to, relative);
+    }
+    const relative = path.relative(run.run_root, destination);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        throw new AppError("publication_pending", "Stage publication escaped its bound RUN lineage", 1, { effect: "committed", run_id: runId, locator });
+    return destination;
+}
+/** Recheck the actual destination after preparation: a missing leaf may have
+ * an existing symlink ancestor, and retained packet bytes never authorize it. */
+function assertPublicationPath(context, projectId, runId, file) {
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const root = run?.run_root && path.resolve(run.run_root), destination = path.resolve(file);
+    if (!root || !destination.startsWith(`${root}${path.sep}`))
+        throw new AppError("publication_pending", "Stage publication escaped its RUN", 1, { effect: "committed", run_id: runId, file });
+    let ancestor = destination;
+    while (!fs.existsSync(ancestor) && ancestor !== root)
+        ancestor = path.dirname(ancestor);
+    const actual = fs.realpathSync(ancestor), realRoot = fs.realpathSync(root);
+    if (actual !== realRoot && !actual.startsWith(`${realRoot}${path.sep}`))
+        throw new AppError("publication_pending", "Stage publication escaped its RUN through a symlink", 1, { effect: "committed", run_id: runId, file });
+}
+/** Admission repair for predecessor reports; the stage being retried is archived separately. */
+export function reconcileRunStageReports(context, projectId, runId, exceptStage) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [projectId]);
+    const seen = new Set();
+    for (const row of rows) {
+        const receipt = JSON.parse(row.payload_json);
+        if (receipt.run_id !== runId || typeof receipt.stage !== "string" || typeof receipt.root !== "string" || receipt.stage === exceptStage || seen.has(receipt.stage))
+            continue;
+        seen.add(receipt.stage);
+        publishStageReport(context, projectId, runId, receipt.stage, receipt.root);
+    }
+    const packets = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' ORDER BY id DESC", [projectId]);
+    const packetFiles = new Set();
+    for (const row of packets) {
+        const packet = JSON.parse(row.payload_json);
+        if (packet.run_id !== runId || typeof packet.stage !== "string" || typeof packet.file !== "string" || packet.stage === exceptStage || packetFiles.has(packet.file))
+            continue;
+        packetFiles.add(packet.file);
+        publishStagePacket(context, projectId, runId, packet.stage, packet.file);
+    }
+}
+function normalizeStageReport(report) {
     const semantic = object(report.semantic);
     const sourceArtifacts = object(report.artifacts);
-    const normalized = {
+    return {
         ...report,
         schema_id: "dd-flow/stage-report@2",
         summary: string(report.summary) || string(semantic.result) || "Stage completed.",
@@ -27,11 +184,6 @@ export function writeStageReport(root, report) {
             html: string(sourceArtifacts.html) || "stage-report.html"
         }
     };
-    writeJsonAtomic(json, normalized);
-    const text = renderStageReportMarkdown(normalized);
-    fs.writeFileSync(markdown, text);
-    fs.writeFileSync(html, renderStageReportHtml(normalized, text));
-    return { json, markdown, html };
 }
 export function renderStageReportMarkdown(report) {
     const semantic = object(report.semantic);

package/dist/services/stage-work-graph.js

@@ -0,0 +1,35 @@
+import { AppError } from "../shared/errors.js";
+export function stageAttempt(context, projectId, runId, stage) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run)
+        throw new AppError("not_found", "Stage graph RUN is unavailable", 1);
+    const stages = JSON.parse(run.index_json).stage_runs ?? [];
+    return [...stages].reverse().find(item => item.stage === stage)?.attempt ?? "try-001";
+}
+export function bindStageWork(context, input) {
+    context.db.run("INSERT OR IGNORE INTO stage_work_memberships (project_id, run_id, work_id, stage, attempt, cycle) VALUES (?, ?, ?, ?, ?, ?)", [input.projectId, input.runId, input.workId, input.stage, input.attempt ?? stageAttempt(context, input.projectId, input.runId, input.stage), input.cycle ?? stageCycle(context, input.projectId, input.runId, input.stage)]);
+}
+export function stageCycle(context, projectId, runId, stage) {
+    if (stage !== "code" && stage !== "code-review")
+        return "";
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const cycle = row ? JSON.parse(row.index_json).variables?.["merge.source_repair"]?.cycle : undefined;
+    return typeof cycle === "string" ? cycle : stage === "code-review" ? "initial" : "";
+}
+export function stageWorkIds(context, projectId, runId, stage) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'stage_work_memberships'"))
+        throw new AppError("stage_graph_compatibility_required", "Stage Work membership is unavailable; use the RUN's pinned engine", 1);
+    return new Set(context.db.all("SELECT work_id FROM stage_work_memberships WHERE project_id = ? AND run_id = ? AND stage = ? AND attempt = ? AND cycle = ?", [projectId, runId, stage, stageAttempt(context, projectId, runId, stage), stageCycle(context, projectId, runId, stage)]).map(row => row.work_id));
+}
+/** Generic Work APIs also serve non-stage runs; null preserves that contract. */
+export function currentStageWorkIds(context, projectId, runId) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!row)
+        return null;
+    const index = JSON.parse(row.index_json);
+    const stage = [...(index.stage_runs ?? [])].reverse().find(item => item.status === "running")?.stage;
+    return stage ? stageWorkIds(context, projectId, runId, stage) : null;
+}
+export function stageGraphScope(context, projectId, runId, stage) {
+    return { project_id: projectId, run_id: runId, attempt: stageAttempt(context, projectId, runId, stage), cycle: stageCycle(context, projectId, runId, stage) };
+}

package/dist/services/tooling.js

@@ -2,7 +2,8 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawnSync } from "node:child_process";
+import { commandResult, commandText } from '../harness-runtime/lib/process-json.mjs';
+import { publishSetup, SETUP_STARTUP_MS } from '../harness-runtime/lib/setup-progress.mjs';
 import { AppError } from "../shared/errors.js";
 import { ensureDir } from "../storage/paths.js";
 const manifestRelativePath = path.join("tools", "worktrunk-manifest.json");
@@ -71,7 +72,7 @@ export function inspectManagedWorktrunk(context) {
         };
     }
 }
-export function ensureManagedWorktrunk(context) {
+export async function ensureManagedWorktrunk(context) {
     const manifest = worktrunkManifest();
     const platform = worktrunkPlatform();
     const cachedRoot = worktrunkCacheRoot(context, platform);
@@ -92,14 +93,14 @@ export function ensureManagedWorktrunk(context) {
                 next_action: "Place the verified official artifact in the managed tool cache and retry."
             });
         }
-        installWorktrunkArtifact(manifest, platform, cachedRoot);
+        await installWorktrunkArtifact(manifest, platform, cachedRoot);
         return verifyCachedWorktrunk(context, manifest, platform);
     }
     finally {
         fs.rmSync(lockDir, { recursive: true, force: true });
     }
 }
-function installWorktrunkArtifact(manifest, platform, targetRoot) {
+async function installWorktrunkArtifact(manifest, platform, targetRoot) {
     const artifact = artifactFor(manifest, platform);
     const parent = path.dirname(targetRoot);
     ensureDir(parent);
@@ -107,8 +108,17 @@ function installWorktrunkArtifact(manifest, platform, targetRoot) {
     const archivePath = path.join(tempRoot, `worktrunk.${artifact.archive}`);
     const extractedRoot = path.join(tempRoot, "extracted");
     try {
-        const download = spawnSync("curl", ["--fail", "--location", "--silent", "--show-error", "--max-time", "120", "-o", archivePath, artifact.url], { encoding: "utf8" });
-        if (download.status !== 0) {
+        let observedBytes = 0;
+        publishSetup('probe_started', 'worktrunk-download');
+        const download = await commandResult("curl", ["--fail", "--location", "--silent", "--show-error", "-o", archivePath, artifact.url], { startupMs: SETUP_STARTUP_MS, progress: () => {
+                const bytes = fs.existsSync(archivePath) ? fs.statSync(archivePath).size : 0;
+                if (bytes > observedBytes) {
+                    observedBytes = bytes;
+                    publishSetup('transfer_progress', `worktrunk-transfer:${bytes}`);
+                }
+                return observedBytes;
+            } });
+        if (download.exit_code !== 0) {
             throw new AppError("tool_unavailable", "Unable to download the pinned Worktrunk artifact", 1, {
                 tool: manifest.tool,
                 version: manifest.version,
@@ -118,6 +128,7 @@ function installWorktrunkArtifact(manifest, platform, targetRoot) {
                 stderr: sanitize(download.stderr)
             });
         }
+        publishSetup('probe_completed', 'worktrunk-download');
         const archiveChecksum = sha256File(archivePath);
         if (archiveChecksum !== artifact.sha256) {
             throw new AppError("tool_integrity_failed", "Pinned Worktrunk artifact checksum mismatch", 1, {
@@ -129,12 +140,12 @@ function installWorktrunkArtifact(manifest, platform, targetRoot) {
             });
         }
         ensureDir(extractedRoot);
-        extractArchive(archivePath, extractedRoot, artifact.archive);
+        await extractArchive(archivePath, extractedRoot, artifact.archive);
         const extractedBinary = findBinary(extractedRoot);
         if (!extractedBinary)
             throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive does not contain wt", 1, { platform });
         fs.chmodSync(extractedBinary, 0o755);
-        verifyWorktrunkVersion(extractedBinary, manifest.version);
+        await verifyWorktrunkVersion(extractedBinary, manifest.version);
         const binaryChecksum = sha256File(extractedBinary);
         const stagedRoot = path.join(tempRoot, "managed");
         ensureDir(stagedRoot);
@@ -186,7 +197,7 @@ function verifyCachedWorktrunk(context, manifest, platform) {
             actual_binary_sha256: actualBinaryChecksum
         });
     }
-    verifyWorktrunkVersion(bin, manifest.version);
+    // The admitted binary checksum binds the version probe performed at install.
     return {
         bin,
         version: manifest.version,
@@ -195,23 +206,23 @@ function verifyCachedWorktrunk(context, manifest, platform) {
         binary_sha256: actualBinaryChecksum
     };
 }
-function extractArchive(archive, destination, format) {
+async function extractArchive(archive, destination, format) {
     if (format === "tar.xz") {
-        const listing = spawnSync("tar", ["-tJf", archive], { encoding: "utf8" });
-        if (listing.status !== 0 || listing.stdout.split("\n").some(unsafeArchivePath)) {
+        const listing = await commandResult("tar", ["-tJf", archive], { startupMs: SETUP_STARTUP_MS });
+        if (listing.exit_code !== 0 || listing.stdout.split("\n").some(unsafeArchivePath)) {
             throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe or unreadable file list", 1);
         }
-        const extracted = spawnSync("tar", ["-xJf", archive, "-C", destination], { encoding: "utf8" });
-        if (extracted.status !== 0)
+        const extracted = await commandResult("tar", ["-xJvf", archive, "-C", destination], { startupMs: SETUP_STARTUP_MS });
+        if (extracted.exit_code !== 0)
             throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { stderr: sanitize(extracted.stderr) });
         return;
     }
-    const listing = spawnSync("unzip", ["-Z1", archive], { encoding: "utf8" });
-    if (listing.status !== 0 || listing.stdout.split("\n").some(unsafeArchivePath)) {
+    const listing = await commandResult("unzip", ["-Z1", archive], { startupMs: SETUP_STARTUP_MS });
+    if (listing.exit_code !== 0 || listing.stdout.split("\n").some(unsafeArchivePath)) {
         throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe or unreadable file list", 1);
     }
-    const extracted = spawnSync("unzip", ["-q", archive, "-d", destination], { encoding: "utf8" });
-    if (extracted.status !== 0)
+    const extracted = await commandResult("unzip", [archive, "-d", destination], { startupMs: SETUP_STARTUP_MS });
+    if (extracted.exit_code !== 0)
         throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { stderr: sanitize(extracted.stderr) });
 }
 function findBinary(root) {
@@ -229,13 +240,11 @@ function findBinary(root) {
     }
     return null;
 }
-function verifyWorktrunkVersion(bin, expected) {
-    const result = spawnSync(bin, ["--version"], { encoding: "utf8" });
-    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
-    if (result.status !== 0 || !output.includes(expected)) {
+async function verifyWorktrunkVersion(bin, expected) {
+    const output = await commandText(bin, ['--version'], { startupMs: SETUP_STARTUP_MS, phase: 'native-version' });
+    if (!output.includes(expected)) {
         throw new AppError("tool_integrity_failed", "Managed Worktrunk version verification failed", 1, {
             expected_version: expected,
-            status: result.status,
             output: sanitize(output)
         });
     }