@deksden-com/dd-flow-cli 0.9.0-beta.52 → 0.9.0-beta.54

package/dist/services/lifecycle-invocations.js

@@ -0,0 +1,371 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { quote } from "shell-quote";
+import { setTimeout as delay } from "node:timers/promises";
+import { AppError } from "../shared/errors.js";
+import { commandOption, parseLifecycleCommand, shellSuffixOffset } from "./lifecycle-command.js";
+import { requireProjectByRoot } from "./projects.js";
+import { assertRunMutationAllowed, assertStageSettlementAllowed, assertWorkSettlementAllowed, recoveryGuard } from "./run-recovery.js";
+import { requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+// Conclusive result/check rejections, never transport, ownership, registry or
+// unknown-effect failures. These validators reject before accepting the result.
+export function isRetryableLifecycleRejection(code, details = {}) {
+    return ["validation", "schema_validation", "work_checks_failed", "code_review_gate_failed",
+        "review_repair_incomplete", "plan_review_incomplete", "semantic_result_invalid",
+        "review_evidence_invalid", "evidence_obligation_unknown", "invalid_evidence_ref",
+        "evidence_ref_missing", "evidence_line_out_of_range", "document_update_missing",
+        "document_update_not_materialized", "review_repair_no_change"].includes(code)
+        || (code === "invalid_work_state" && details.retryable_no_effect === true);
+}
+function storage(context) {
+    context.db.execSchema(`CREATE TABLE IF NOT EXISTS lifecycle_invocations (
+    id TEXT PRIMARY KEY, scope_json TEXT NOT NULL, command TEXT NOT NULL,
+    fingerprint TEXT NOT NULL, status TEXT NOT NULL,
+    event_key TEXT UNIQUE, identity_json TEXT, deadline INTEGER, outcome_json TEXT,
+    created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+  )`);
+}
+function invocation(command) {
+    const parsed = parseLifecycleCommand(command);
+    if (parsed.kind !== "standalone" || parsed.invocation.wrapped) {
+        throw new AppError("invocation_command_invalid", "A lifecycle attempt requires one direct standalone command", 1);
+    }
+    return parsed.invocation;
+}
+// Input data may be supplied later (stdin/file contents); authority is bound to
+// the exact operation and literal argv. Existing lifecycle validation owns data.
+function fingerprint(parsed) {
+    const options = [...parsed.args.options].filter(([key]) => !["invocation-id", "hook-event-id", "json", "progress-jsonl", "response-file"].includes(key))
+        .map(([key, values]) => [key, key === "reason" ? ["<semantic-reason>"] : values])
+        .sort(([a], [b]) => a.localeCompare(b));
+    return crypto.createHash("sha256").update(JSON.stringify([parsed.operation, parsed.args.positional, options])).digest("hex");
+}
+function load(context, id) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'")) {
+        throw new AppError("invocation_unknown", "This runtime has no issued lifecycle attempts", 1, { invocation_id: id });
+    }
+    const row = context.db.get("SELECT * FROM lifecycle_invocations WHERE id = ?", [id]);
+    if (!row)
+        throw new AppError("invocation_unknown", "Lifecycle attempt was not issued by this runtime", 1, { invocation_id: id });
+    return row;
+}
+export function lifecycleInvocationScope(context, id) {
+    return JSON.parse(load(context, id).scope_json);
+}
+/** Current, explicitly-issued replacements for commands from the resumed stage.
+ * Original prompts remain immutable evidence; callers may present this small
+ * overlay after a state transition made an earlier no-effect rejection retryable. */
+export function lifecycleRetryCommands(context, stage) {
+    const scope = context.env.DD_FLOW_INVOCATION_SCOPE;
+    if (!scope || !context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'"))
+        return [];
+    return context.db.all("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND status = 'settled' ORDER BY rowid", [scope])
+        .flatMap((row) => {
+        try {
+            const outcome = row.outcome_json ? JSON.parse(row.outcome_json) : null;
+            const retry = outcome?.error?.details?.retry_command;
+            const parsed = invocation(row.command);
+            if (typeof retry !== "string" || parsed.operation !== "stage_finish" || commandOption(parsed, "stage") !== stage)
+                return [];
+            const successor = load(context, commandOption(invocation(retry), "invocation-id") ?? "");
+            const latest = context.db.get("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? ORDER BY rowid DESC LIMIT 1", [row.scope_json, row.fingerprint]);
+            return successor.id === latest?.id && successor.status === "issued" ? [retry] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function managedInvocationContext(context, input) {
+    const env = { ...context.env, DD_FLOW_CURRENT_INVOCATION: undefined, DD_FLOW_INVOCATION_SCOPE: undefined };
+    if (input.harness !== "zcode-acp")
+        return { ...context, env };
+    const project = requireProjectByRoot(context, input.projectRoot);
+    const { state, process: daemon } = requireManagedDaemonBinding(context, { stateDir: input.stateDir, projectId: project.id, runId: input.runId });
+    if (JSON.parse(daemon.metadata_json).run_generation !== input.generation)
+        throw new AppError("invocation_generation_stale", "Managed daemon belongs to another RUN generation", 1);
+    const session = state.sessions?.find(session => session.adapter_session_id === input.sessionId || session.provider_session_id === input.sessionId);
+    if (!state.daemon_id || !session?.root_provider_session_id)
+        throw new AppError("invocation_scope_unproven", "Managed ZCode Session has no persisted native root binding", 1);
+    const scope = { projectRoot: project.root, daemonId: state.daemon_id, rootSessionId: session.root_provider_session_id, runId: input.runId, generation: input.generation };
+    env.DD_FLOW_INVOCATION_SCOPE = JSON.stringify(scope);
+    return { ...context, env };
+}
+/** Generated commands retain their attempt across repeated rendering. Only a
+ * currently executing command can emit its own successor with the same argv. */
+export function managedLifecycleCommand(context, command) {
+    const configured = context.env.DD_FLOW_INVOCATION_SCOPE;
+    if (!configured)
+        return command;
+    const scope = JSON.parse(configured);
+    const parsed = invocation(command);
+    if (commandOption(parsed, "invocation-id"))
+        return command;
+    if (!context.db.writable || context.env.DD_FLOW_INVOCATION_READONLY === "1") {
+        const retained = context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'")
+            ? context.db.get("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? ORDER BY rowid DESC LIMIT 1", [JSON.stringify(scope), fingerprint(parsed)]) : undefined;
+        if (!retained)
+            throw new AppError("invocation_command_unprepared", "Read-only inspection has no retained lifecycle command", 1);
+        return renderInvocationCommand(retained, command);
+    }
+    storage(context);
+    context.db.exec("SAVEPOINT invocation_command");
+    try {
+        const prior = context.db.get("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? ORDER BY rowid DESC LIMIT 1", [JSON.stringify(scope), fingerprint(parsed)]);
+        if (prior && prior.id !== context.env.DD_FLOW_CURRENT_INVOCATION) {
+            const rendered = renderInvocationCommand(prior, command);
+            context.db.exec("RELEASE invocation_command");
+            return rendered;
+        }
+        if (context.env.DD_FLOW_INVOCATION_READONLY === "1")
+            throw new AppError("invocation_command_unprepared", "No prepared lifecycle command is available; read-only inspection cannot issue one", 1);
+        const prepared = issueLifecycleInvocation(context, command, scope);
+        context.db.exec("RELEASE invocation_command");
+        return prepared.command;
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK TO invocation_command");
+        context.db.exec("RELEASE invocation_command");
+        throw error;
+    }
+}
+export function retryLifecycleInvocationCommand(context, id) {
+    const prior = load(context, id);
+    if (prior.status !== "executing")
+        throw new AppError("invocation_retry_not_authorized", "Only the executing lifecycle operation can publish its next attempt", 1);
+    const marker = ` --invocation-id ${id}`;
+    if (!prior.command.includes(marker))
+        throw new AppError("invocation_command_invalid", "Retained issued command lost its invocation marker", 1);
+    return managedLifecycleCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: prior.scope_json, DD_FLOW_CURRENT_INVOCATION: id } }, prior.command.replace(marker, ""));
+}
+/** Settle a conclusive rejection and publish its only legal successor atomically.
+ * A crash must leave either the old attempt executing, or both the settled
+ * outcome and its successor; never a usable successor beside an unknown effect. */
+export function settleLifecycleRejection(context, id, error) {
+    storage(context);
+    const details = { ...error.details };
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const prior = load(context, id);
+        if (prior.status !== "executing")
+            throw new AppError("invocation_settlement_conflict", "Attempt is no longer executing", 1, { invocation_id: id });
+        if (isRetryableLifecycleRejection(error.code, error.details)) {
+            const retry = retryLifecycleInvocationCommand(context, id);
+            details.retry_command = retry;
+            details.retry_instruction = "Correct only the evidenced defect, then use retry_command with the required result input. Reissuing the old command only reads its retained outcome.";
+        }
+        settleLifecycleInvocation(context, id, { error: { ...error, details } });
+        context.db.exec("COMMIT");
+        Object.assign(error.details, details);
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
+/** Recovery preserves the original packet as evidence. Only its retained,
+ * never-executed commands receive new authority; unknown effects never replay. */
+export function recoverLifecycleCommands(context, originalPrompt, scope) {
+    const ids = [...new Set([...originalPrompt.matchAll(/--invocation-id ([0-9a-f-]{36})\b/g)].map(match => match[1]))];
+    const recovered = [];
+    for (const id of ids) {
+        let prior = load(context, id);
+        const oldScope = JSON.parse(prior.scope_json);
+        if (oldScope.projectRoot !== scope.projectRoot || oldScope.runId !== scope.runId
+            || oldScope.rootSessionId !== scope.rootSessionId || oldScope.generation >= scope.generation) {
+            throw new AppError("invocation_recovery_scope_mismatch", "Retained command does not belong to the recovered root and an earlier generation", 1, { invocation_id: id });
+        }
+        // The immutable prompt can predate several recoveries. Follow the newest
+        // retained attempt, including an unknown successor, rather than reviving
+        // an older unexecuted command after the successor already produced effects.
+        prior = context.db.get(`SELECT * FROM lifecycle_invocations WHERE fingerprint = ?
+      AND json_extract(scope_json, '$.projectRoot') = ? AND json_extract(scope_json, '$.runId') IS ?
+      AND json_extract(scope_json, '$.rootSessionId') = ? AND json_extract(scope_json, '$.generation') < ?
+      ORDER BY json_extract(scope_json, '$.generation') DESC, rowid DESC LIMIT 1`, [prior.fingerprint, scope.projectRoot, scope.runId, scope.rootSessionId, scope.generation]);
+        if (prior.status === "executing" || prior.status === "settled") {
+            const outcome = prior.outcome_json ? JSON.parse(prior.outcome_json) : null;
+            recovered.push({ invocation_id: id, status: prior.status, outcome,
+                instruction: prior.status === "executing" ? "Outcome unknown: reconcile retained operation evidence; do not reissue this command." : "Read the retained outcome; do not repeat completed effects." });
+            continue;
+        }
+        const parsed = invocation(prior.command);
+        const argv = [...parsed.argv];
+        const at = argv.indexOf("--invocation-id");
+        if (at < 0 || argv[at + 1] !== prior.id)
+            throw new AppError("invocation_command_invalid", "Retained command lost its exact invocation marker", 1);
+        argv.splice(at, 2);
+        const env = { ...parsed.env, DD_FLOW_INVOCATION_SCOPE: JSON.stringify(scope) };
+        const command = `${Object.entries(env).map(([key, value]) => `${key}=${quote([value])}`).join(" ")} ${quote([parsed.executable, ...argv])} ${prior.command.slice(shellSuffixOffset(prior.command))}`.trim();
+        const prepared = managedLifecycleCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: JSON.stringify(scope), DD_FLOW_CURRENT_INVOCATION: undefined } }, command);
+        recovered.push({ invocation_id: id, status: "replaced_unexecuted", command: prepared });
+    }
+    return recovered;
+}
+export function assertLifecycleInvocationCurrent(context, scope, command) {
+    const parsed = invocation(command);
+    if (!scope.runId) {
+        if ((parsed.operation === "stage_start" && parsed.args.options.has("bootstrap")) || parsed.operation === "session_register")
+            return;
+        throw new AppError("invocation_scope_invalid", "This lifecycle operation requires an issued RUN scope", 1);
+    }
+    const project = requireProjectByRoot(context, scope.projectRoot);
+    let workId;
+    if (parsed.operation.startsWith("work_")) {
+        const target = parsed.args.positional[0] ?? "";
+        const works = context.db.all("SELECT work_id, run_id FROM works WHERE project_id = ? AND (work_id = ? OR (? = 1 AND work_id LIKE ?))", [project.id, target, /^WRK-\d{3,}$/.test(target) ? 1 : 0, `${target}-%`]);
+        if (works.length !== 1 || works[0].run_id !== scope.runId)
+            throw new AppError("invocation_scope_mismatch", "Work does not belong to the issued RUN scope", 1);
+        workId = works[0].work_id;
+    }
+    else if (parsed.operation !== "session_register" && !parsed.args.options.has("bootstrap")) {
+        const target = parsed.args.positional[0];
+        const run = context.db.get("SELECT id FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [project.id, target ?? null, target ?? null]);
+        if (run?.id !== scope.runId)
+            throw new AppError("invocation_scope_mismatch", "Command does not belong to the issued RUN scope", 1);
+    }
+    const guard = recoveryGuard(context, project.id, scope.runId);
+    // A cooperative pause advances the fence but explicitly admits settlement
+    // of the captured WorkSession/Stage attempt. Reuse that exact authority;
+    // never turn the invocation layer into a stricter, divergent pause policy.
+    if (guard?.status === "draining" && guard.generation === scope.generation + 1) {
+        if (workId && ["work_finish", "work_fail"].includes(parsed.operation))
+            return assertWorkSettlementAllowed(context, project.id, scope.runId, workId);
+        if (parsed.operation === "stage_finish")
+            return assertStageSettlementAllowed(context, project.id, scope.runId, commandOption(parsed, "stage") ?? "");
+    }
+    if ((guard?.generation ?? 0) !== scope.generation)
+        throw new AppError("invocation_generation_stale", "Lifecycle attempt belongs to another recovery generation", 1);
+    if (parsed.operation !== "recovery_accept")
+        assertRunMutationAllowed(context, project.id, scope.runId);
+}
+function checkCommand(row, command) {
+    const parsed = invocation(command);
+    const scope = JSON.parse(row.scope_json);
+    if (commandOption(parsed, "invocation-id") !== row.id || fingerprint(parsed) !== row.fingerprint
+        || path.resolve(commandOption(parsed, "project-root") ?? "") !== scope.projectRoot) {
+        throw new AppError("invocation_command_mismatch", "Lifecycle attempt belongs to another command or project", 1, { invocation_id: row.id });
+    }
+}
+/** Explicit issuance; callers retain this command. Read-only show/status must
+ * return that retained value, not issue a replacement on every observation. */
+export function issueLifecycleInvocation(context, command, scope) {
+    storage(context);
+    const parsed = invocation(command);
+    if (!scope.daemonId || !scope.rootSessionId || !Number.isInteger(scope.generation) || scope.generation < 0
+        || !path.isAbsolute(scope.projectRoot) || commandOption(parsed, "project-root") !== scope.projectRoot
+        || commandOption(parsed, "invocation-id") || commandOption(parsed, "hook-event-id")) {
+        throw new AppError("invocation_scope_invalid", "Lifecycle issuance requires explicit managed scope and a new command", 1);
+    }
+    const id = crypto.randomUUID();
+    const prepared = commandWithInvocationId(command, id);
+    // Validate the actual inserted argv, including quoted heredoc boundaries.
+    const row = { id, scope_json: JSON.stringify(scope), fingerprint: fingerprint(parsed) };
+    checkCommand(row, prepared);
+    context.db.run("INSERT INTO lifecycle_invocations (id, scope_json, command, fingerprint, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'issued', ?, ?)", [id, row.scope_json, prepared, row.fingerprint, context.now(), context.now()]);
+    return { id, command: prepared };
+}
+function commandWithInvocationId(command, id) {
+    const at = shellSuffixOffset(command);
+    return `${command.slice(0, at).trimEnd()} --invocation-id ${id} ${command.slice(at)}`.trimEnd();
+}
+/** The attempt owns authority; the caller owns presentation-only shell input.
+ * Preserve current stdin/heredoc/response-file text while validating that it
+ * still names the exact persisted operation and project. */
+function renderInvocationCommand(row, command) {
+    const parsed = invocation(command);
+    if (commandOption(parsed, "invocation-id"))
+        throw new AppError("invocation_command_invalid", "Rendered lifecycle command already has an invocation id", 1);
+    const rendered = commandWithInvocationId(command, row.id);
+    checkCommand(row, rendered);
+    return rendered;
+}
+/** Native observer and receipt writer commit together. Never await I/O inside
+ * this transaction; the callback must write to this same SQLite connection. */
+export function observeLifecycleInvocation(context, input) {
+    const initial = load(context, input.id);
+    checkCommand(initial, input.command);
+    // A completed invocation is a read, even from a new native tool call after
+    // reattach. Do not manufacture a new receipt or reject that read as a second
+    // executor; the CLI returns the immutable stored outcome without dispatch.
+    if (initial.status === "settled")
+        return { eventKey: initial.event_key, duplicate: true };
+    const scope = JSON.parse(initial.scope_json);
+    const identity = input.identity;
+    if (identity.daemonId !== scope.daemonId || identity.rootSessionId !== scope.rootSessionId
+        || !identity.sessionId || !identity.toolCallId
+        || (identity.sessionId === scope.rootSessionId ? identity.parentSessionId !== null : !identity.parentSessionId)) {
+        throw new AppError("invocation_identity_mismatch", "Native identity does not belong to the issued managed scope", 1, { invocation_id: input.id });
+    }
+    const identityJson = JSON.stringify([identity.daemonId, identity.rootSessionId, identity.sessionId, identity.parentSessionId, identity.toolCallId]);
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const row = context.db.get("SELECT * FROM lifecycle_invocations WHERE id = ?", [input.id]);
+        if (row.status === "settled") {
+            context.db.exec("COMMIT");
+            return { eventKey: row.event_key, duplicate: true };
+        }
+        if (row.status === "expired" || (row.deadline !== null && row.deadline <= Date.now() && !row.event_key)) {
+            throw new AppError("invocation_expired", "Late observation cannot revive an expired lifecycle attempt", 1, { invocation_id: input.id });
+        }
+        if (row.identity_json) {
+            if (row.identity_json !== identityJson)
+                throw new AppError("invocation_identity_conflict", "Another native tool call already owns this attempt", 1, { invocation_id: input.id });
+            context.db.exec("COMMIT");
+            return { eventKey: row.event_key, duplicate: true };
+        }
+        const eventKey = input.recordReceipt();
+        const receipt = eventKey && context.db.get("SELECT provider_session_id, daemon_id, status FROM hook_events WHERE event_key = ? AND harness = 'zcode-acp' AND cwd = ?", [eventKey, scope.projectRoot]);
+        if (!receipt || receipt.provider_session_id !== identity.sessionId || receipt.daemon_id !== identity.daemonId || receipt.status !== "observed") {
+            throw new AppError("invocation_receipt_missing", "Native observer did not persist the matching unclaimed receipt", 1);
+        }
+        context.db.run("UPDATE lifecycle_invocations SET identity_json = ?, event_key = ?, status = 'observed', updated_at = ? WHERE id = ? AND status = 'issued'", [identityJson, eventKey, context.now(), input.id]);
+        context.db.exec("COMMIT");
+        return { eventKey, duplicate: false };
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
+/** One caller owns execution; a lost process leaves an explicit unknown
+ * outcome, never an automatic replay. Existing recovery decides the next step. */
+export async function awaitLifecycleInvocation(context, input) {
+    const initial = load(context, input.id);
+    checkCommand(initial, input.command);
+    const timeoutMs = input.timeoutMs ?? 30000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60000)
+        throw new AppError("invocation_timeout_invalid", "Receipt timeout must be within 1..60000 ms", 1);
+    context.db.run("UPDATE lifecycle_invocations SET deadline = COALESCE(deadline, ?), updated_at = ? WHERE id = ? AND status = 'issued'", [Date.now() + timeoutMs, context.now(), input.id]);
+    for (;;) {
+        const row = load(context, input.id);
+        if (row.status === "settled")
+            return { outcome: JSON.parse(row.outcome_json), replay: true };
+        if (row.status === "executing")
+            throw new AppError("invocation_outcome_pending", "This attempt already started; inspect its retained operation outcome before retrying", 1, { invocation_id: input.id });
+        input.assertCurrent(JSON.parse(row.scope_json));
+        if (row.status === "observed") {
+            const claimed = context.db.run("UPDATE lifecycle_invocations SET status = 'executing', updated_at = ? WHERE id = ? AND status = 'observed'", [context.now(), input.id]);
+            if (claimed.changes === 1)
+                return { eventKey: row.event_key, replay: false };
+            continue;
+        }
+        if (row.status === "expired" || (row.deadline !== null && row.deadline <= Date.now())) {
+            const expired = context.db.run("UPDATE lifecycle_invocations SET status = 'expired', updated_at = ? WHERE id = ? AND status = 'issued'", [context.now(), input.id]);
+            if (!expired.changes && row.status !== "expired")
+                continue;
+            throw new AppError("invocation_receipt_timeout", "No native confirmation before the receipt deadline; lifecycle state was not changed", 1, { invocation_id: input.id });
+        }
+        await delay(Math.min(25, Math.max(1, (row.deadline ?? Date.now() + 25) - Date.now())));
+    }
+}
+export function settleLifecycleInvocation(context, id, outcome) {
+    const encoded = JSON.stringify(outcome);
+    if (encoded === undefined)
+        throw new AppError("invocation_outcome_invalid", "Invocation outcome must be JSON", 1);
+    const changed = context.db.run("UPDATE lifecycle_invocations SET status = 'settled', outcome_json = ?, updated_at = ? WHERE id = ? AND status = 'executing'", [encoded, context.now(), id]);
+    if (changed.changes !== 1) {
+        const row = load(context, id);
+        if (row.status !== "settled" || row.outcome_json !== encoded)
+            throw new AppError("invocation_settlement_conflict", "Attempt cannot be settled with a different outcome", 1, { invocation_id: id });
+    }
+}

package/dist/services/merge-server.js

@@ -1,3 +1,4 @@
+import { managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -7,7 +8,7 @@ import { flowCommand } from "./stage-pause.js";
 import { adapterSessionId, prepareHarnessFlowExecutable, runHarnessAdapter } from "./harness-adapter.js";
 import { harnessRuntimeArguments, resolveHarnessCommand } from "./harness-config.js";
 import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
-import { loadAgentProfile, resolveExecutionPolicy } from "./execution-policy.js";
+import { loadAgentProfile, resolveExecutionPolicy, runtimeHarness } from "./execution-policy.js";
 /** A deterministic dispatcher; only the launched harness Session performs agent work. */
 export async function serveMergeRequests(context, input) {
     const running = context.db.get("SELECT server_id, pid FROM merge_servers WHERE status IN ('running','stopping') ORDER BY started_at LIMIT 1");
@@ -103,9 +104,7 @@ async function dispatch(context, input) {
     const promptFile = path.join(stateDir, "launch.md");
     const adapterJournal = path.join(stateDir, "adapter.events.jsonl");
     const flowExecutable = prepareHarnessFlowExecutable(context, stateDir);
-    const runtimeContext = { ...context, env: { ...context.env, DD_FLOW_BIN: flowExecutable } };
-    const stageCommand = `${flowCommand(runtimeContext)} stage start ${input.request.run_id} --stage merge --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`;
-    fs.writeFileSync(promptFile, `Start the assigned MERGE stage now. Your first tool call must be this exact standalone command:\n\n${stageCommand}\n\nTrust and follow the complete stage packet it returns. Continue through merge apply and stage finish. Stop only when the stage reaches a terminal result or explicitly requests user/operator action.\n`);
+    let runtimeContext = { ...context, env: { ...context.env, DD_FLOW_BIN: flowExecutable } };
     const runtimeOwner = { schema_id: "dd-flow/runtime-owner@1", owner_id: `run:${input.request.run_id}:merge:${input.request.merge_request_id}`, role: "merge", project_id: input.request.project_id, run_id: input.request.run_id, work_id: input.request.executor_work_id, operation_id: `${input.request.merge_request_id}:${token}`, state_dir: stateDir, dd_flow_home: context.ddFlowHome, dd_flow_bin: flowExecutable, resource_home: context.env.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome, budget: runtimeBudgetForRun(context, input.request.project_id, input.request.run_id) };
     event(input.journal, { type: "launch_intent", server_id: input.serverId, request_id: input.request.merge_request_id, token, profile: input.profile, prompt_file: promptFile, at: context.now() });
     input.progress?.(`launching ${input.request.merge_request_id} with ${input.profile.id}`);
@@ -126,6 +125,9 @@ async function dispatch(context, input) {
             throw new AppError("merge_adapter_invalid", "Harness adapter did not return a Session id", 1, { harness: input.profile.harness, response: created });
         Object.assign(retained, { session_id: sessionId, create: created });
         retain();
+        runtimeContext = managedInvocationContext(runtimeContext, { harness: runtimeHarness(input.profile), stateDir, sessionId, projectRoot: run.project_root, runId: input.request.run_id, generation });
+        const stageCommand = managedLifecycleCommand(runtimeContext, `${flowCommand(runtimeContext)} stage start ${input.request.run_id} --stage merge --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`);
+        fs.writeFileSync(promptFile, `Start the assigned MERGE stage now. Your first tool call must be this exact standalone command:\n\n${stageCommand}\n\nTrust and follow the complete stage packet it returns. Continue through merge apply and stage finish. Stop only when the stage reaches a terminal result or explicitly requests user/operator action.\n`);
         const prompted = await adapterCall(["session", "prompt", "--session-id", sessionId, "--prompt-file", promptFile, ...common], 45 * 60 * 1000, `MERGE ${input.request.merge_request_id} Session ${sessionId} is still running`);
         Object.assign(retained, { response: prompted });
         retain();

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

@@ -26,6 +26,9 @@ export function captureRecoveryDatabase(source, output, projectId, runId, protoc
             throw new AppError("snapshot_scope_conflict", "Selected Work refers to a Session currently bound to another RUN", 1);
         const sessions = `SELECT session_id FROM sessions WHERE ${ownProject} AND (run_id IN (SELECT run_id FROM capture_scope) OR session_id IN (SELECT session_id FROM work_sessions WHERE work_id IN (${works})))`;
         const nativeSessions = `SELECT harness, provider_session_id FROM sessions WHERE ${ownProject} AND session_id IN (${sessions})`;
+        const invocations = "json_extract(scope_json, '$.runId') IN (SELECT run_id FROM capture_scope) AND json_extract(scope_json, '$.projectRoot') IN (SELECT root FROM projects WHERE id IN (SELECT project_id FROM capture_scope))";
+        const invocationReceipts = db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'lifecycle_invocations'").get()
+            ? ` OR event_key IN (SELECT event_key FROM lifecycle_invocations WHERE ${invocations})` : "";
         const protocols = `SELECT id FROM capture_protocols UNION SELECT subject_id FROM runs WHERE (project_id, id) IN (SELECT * FROM capture_scope) UNION SELECT value FROM merge_requests, json_each(merge_requests.protocol_ids_json) WHERE ${ownRun} UNION SELECT protocol_id FROM flow_jobs WHERE ${ownRun}`;
         const rules = {
             dd_flow_writer_contract: "1",
@@ -36,7 +39,8 @@ export function captureRecoveryDatabase(source, output, projectId, runId, protoc
             work_sessions: `work_id IN (${works})`, work_launches: `work_id IN (${works})`,
             work_recovery_segments: `work_id IN (${works})`,
             run_recovery_bindings: `recovery_id IN (SELECT recovery_id FROM run_recovery_guards WHERE ${ownRun})`,
-            hook_events: `${ownProject} AND (session_id IN (${sessions}) OR (harness, provider_session_id) IN (${nativeSessions}))`,
+            lifecycle_invocations: invocations,
+            hook_events: `${ownProject} AND (session_id IN (${sessions}) OR (harness, provider_session_id) IN (${nativeSessions})${invocationReceipts})`,
             harness_usage_snapshots: `${ownProject} AND (harness, provider_session_id) IN (${nativeSessions})`,
             protocols: `${ownProject} AND id IN (${protocols})`,
             project_config: ownProject,

package/dist/services/run-controller-recovery.js

@@ -15,6 +15,7 @@ import { requireRun, requireController, controllerReceipt, appendEvent, saveStat
 import { controllerAdapter, sessionArguments } from "./run-controller-adapter.js";
 import { spawnController, recordControllerLauncher } from "./run-controller-process.js";
 import { readNativeDaemonState, requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+import { managedInvocationContext } from "./lifecycle-invocations.js";
 import { runControlStatus } from "./run-control.js";
 import { runtimeBudgetStatus, waitForRuntimeScopeRecovery } from "./runtime-budget.js";
 /** CLI observation is bounded; the physical controller owns the recovery work. */
@@ -123,7 +124,7 @@ export async function resumeControllerSession(context, row, manifest, state, ass
     const session = state.current_session === null ? undefined : state.sessions[state.current_session];
     if (!session?.id)
         throw new AppError("recovery_owner_missing", "Recovery lost its retained coordinator Session", 1);
-    const executionContext = { ...context, env: { ...context.env, DD_FLOW_BIN: manifest.flow_executable, DD_FLOW_RESOURCE_HOME: manifest.resource_home } };
+    let executionContext = { ...context, env: { ...context.env, DD_FLOW_BIN: manifest.flow_executable, DD_FLOW_RESOURCE_HOME: manifest.resource_home } };
     const scopeControl = manifest.budget ? runtimeBudgetStatus(executionContext, manifest.budget.scope_id).control : null;
     const assertRecoveryOwner = () => {
         assertPhysicalOwner();
@@ -156,6 +157,8 @@ export async function resumeControllerSession(context, row, manifest, state, ass
     const daemon = readDaemon(), daemonId = daemon.daemon_id ?? daemon.config?.daemonId;
     if (!daemonId || daemonId === (retired.daemon_id ?? retired.config?.daemonId) || started.daemon_id !== daemonId || started.already_running === true)
         throw new AppError("recovery_daemon_stale", "Recovery requires a fresh daemon, not reuse of the retired physical owner", 1);
+    executionContext = managedInvocationContext(executionContext, { harness: runtimeHarness(session.profile), stateDir: session.state_dir, sessionId: session.id,
+        projectRoot: manifest.request.project_root, runId: row.run_id, generation: row.generation });
     assertRecoveryOwner();
     const scope = { projectRoot: manifest.request.project_root, runId: row.run_id, recoveryId: recovery.recovery_id };
     resumeRunRecovery(executionContext, { ...scope, daemonId, harness: runtimeHarness(session.profile), nativeSessionId: session.id });

package/dist/services/run-controller.js

@@ -1,3 +1,4 @@
+import { managedInvocationContext, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -345,7 +346,11 @@ export function supplyRunControllerContext(context, input) {
 async function executeController(context, row, manifest, state, assertOwner, assertPhysicalOwner) {
     const policy = manifest.execution_profile.settings.execution;
     const profiles = manifest.execution_profile.agent_profiles;
-    const executionContext = { ...context, env: { ...context.env, DD_FLOW_BIN: manifest.flow_executable, DD_FLOW_RESOURCE_HOME: manifest.resource_home, DD_FLOW_RUNTIME_BUDGET: manifest.budget ? JSON.stringify(manifest.budget) : undefined } };
+    let executionContext = { ...context, env: { ...context.env, DD_FLOW_BIN: manifest.flow_executable, DD_FLOW_RESOURCE_HOME: manifest.resource_home, DD_FLOW_RUNTIME_BUDGET: manifest.budget ? JSON.stringify(manifest.budget) : undefined } };
+    const bindInvocationScope = (session) => {
+        executionContext = managedInvocationContext(executionContext, { harness: runtimeHarness(session.profile), stateDir: session.state_dir, sessionId: session.id,
+            projectRoot: manifest.request.project_root, runId: row.run_id, generation: row.generation });
+    };
     let lastCapture = null;
     const setStatus = (status) => {
         const changed = context.db.run("UPDATE run_controllers SET status = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status <> ?", [status, context.now(), row.controller_id, row.owner_token, status]);
@@ -394,6 +399,8 @@ async function executeController(context, row, manifest, state, assertOwner, ass
     };
     for (;;) {
         assertOwner();
+        if (state.current_session !== null && !state.sessions[state.current_session].stopped)
+            bindInvocationScope(state.sessions[state.current_session]);
         const run = requireRun(context, row.project_id, row.run_id);
         const view = getFlowRunStatus(executionContext, { projectRoot: run.project_root, runId: run.id });
         const next = view.continuation;
@@ -433,7 +440,7 @@ async function executeController(context, row, manifest, state, assertOwner, ass
             assertOwner();
             // The accepted answer is logical intent; only its generation-bound
             // adapter operation represents a physical dispatch that stop must drain.
-            const command = `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${JSON.stringify(run.project_root)} --answer-stdin --json < ${JSON.stringify(input.file)}`;
+            const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage resume ${run.id} --stage ${next.stage} --work ${input.work_id} --project-root ${JSON.stringify(run.project_root)} --answer-stdin --json < ${JSON.stringify(input.file)}`);
             const receipt = await prompt(state.sessions[state.current_session], `The user supplied the raw answer for pause ${pause.id}. Your first tool call must be this exact standalone command:\n\n${command}\n\nDo not alter the answer. Follow the returned packet, then stop at this Stage boundary.`, `${answer.operation_id}:prompt:${row.generation}`);
             context.db.run("UPDATE run_controller_operations SET status = 'completed', receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ delivered: true, session_id: adapterSessionId(receipt) }), context.now(), answer.operation_id]);
             state.last_continuation = null;
@@ -497,6 +504,7 @@ async function executeController(context, row, manifest, state, assertOwner, ass
                     throw new AppError("harness_adapter_invalid", "Managed adapter did not return its Session id", 1);
                 session.id = sessionId;
                 saveState(context, row, state);
+                bindInvocationScope(session);
                 if (next.stage === "merge" && state.merge_claim)
                     context.db.run("UPDATE merge_requests SET adapter_receipt_json = ?, updated_at = ? WHERE merge_request_id = ? AND dispatch_owner = ? AND dispatch_lease_token = ?", [JSON.stringify({ controller_id: row.controller_id, profile: session.profile, session_id: session.id, state_dir: session.state_dir, create: created }), context.now(), state.merge_claim.request_id, row.controller_id, state.merge_claim.token]);
                 appendEvent(context, row.controller_id, "session_created", { stage: next.stage, session_id: sessionId, harness: runtimeHarness(session.profile), profile: session.profile });
@@ -507,7 +515,7 @@ async function executeController(context, row, manifest, state, assertOwner, ass
             saveState(context, row, state);
             setStatus("running");
             const responseFile = path.join(row.state_dir, `${next.stage}-${next.attempt ?? 1}.stage-start-response.json`);
-            const command = `${flowCommand(executionContext)} stage start ${run.id} --stage ${next.stage} --project-root ${JSON.stringify(run.project_root)} --context-file ${JSON.stringify(stageContext.file)} --context-sha256 ${stageContext.sha256} --require-session-binding --response-file ${JSON.stringify(responseFile)} --json --progress-jsonl`;
+            const command = managedLifecycleCommand(executionContext, `${flowCommand(executionContext)} stage start ${run.id} --stage ${next.stage} --project-root ${JSON.stringify(run.project_root)} --context-file ${JSON.stringify(stageContext.file)} --context-sha256 ${stageContext.sha256} --require-session-binding --response-file ${JSON.stringify(responseFile)} --json --progress-jsonl`);
             appendEvent(context, row.controller_id, "stage_entered", { stage: next.stage, session_id: session.id, context_sha256: stageContext.sha256 });
             await prompt(session, `Start the assigned ${next.stage} Stage now. Your first tool call must be this exact standalone command:\n\n${command}\n\nRead the complete authoritative packet saved to ${JSON.stringify(responseFile)}, including worker_prompt_markdown. If a read is truncated, continue until the entire packet has been read before doing Stage work. Stop at this Stage boundary or a declared HITL/Work-graph boundary; do not start a successor Stage yourself.`);
             continue;

package/dist/services/run-recovery.js

@@ -1,3 +1,4 @@
+import { managedLifecycleCommand, recoverLifecycleCommands } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -42,7 +43,7 @@ function rootRecoveryPacket(context, run, guard, owner) {
     });
 }
 export function acceptanceCommand(context, runId, recoveryId, projectRoot) {
-    return `${flowCommand(context)} run recovery accept ${JSON.stringify(runId)} --recovery-id ${JSON.stringify(recoveryId)} --project-root ${JSON.stringify(projectRoot)} --json`;
+    return managedLifecycleCommand(context, `${flowCommand(context)} run recovery accept ${JSON.stringify(runId)} --recovery-id ${JSON.stringify(recoveryId)} --project-root ${JSON.stringify(projectRoot)} --json`);
 }
 export function requireRecoveryRun(context, projectId, runId) {
     const run = context.db.get("SELECT r.id, r.run_root, r.workspace_root, p.root AS project_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE r.project_id = ? AND r.id = ?", [projectId, runId]);
@@ -258,6 +259,15 @@ export function acceptRunRecovery(context, input) {
         if (!guard || guard.recovery_id !== input.recoveryId || !binding || binding.session_id !== identity.sessionId || binding.harness !== identity.harness || binding.provider_session_id !== identity.providerSessionId || binding.daemon_id !== identity.daemonId || hook?.match_key !== matchKey)
             throw new AppError("recovery_binding_mismatch", "Recovery acknowledgement does not belong to the authorized physical Session and generation", 1);
         packetReceipt = recoveryPacketReceipt(binding);
+        if (binding.harness === "zcode-acp") {
+            const retained = packetReceipt.packet;
+            const scope = { projectRoot: run.project_root, daemonId: binding.daemon_id, rootSessionId: binding.provider_session_id, runId: run.id, generation: guard.generation };
+            packetReceipt.lifecycle_recovery = {
+                commands: retained.continuation === "stage_boundary" ? [] : recoverLifecycleCommands(context, retained.original_prompt.text, scope),
+                instruction: "original_prompt is immutable historical evidence. Do not execute its old invocation IDs or scope. Use only replacement commands below; reconcile unknown outcomes before continuing. At a completed stage boundary return control to the runner.",
+                work_list_command: `${flowCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: JSON.stringify(scope) } })} work ls --run ${run.id} --ready --project-root ${JSON.stringify(run.project_root)} --json`
+            };
+        }
         if (guard.status === "recovered" && binding.status === "accepted" && binding.hook_event_key === eventKey && hook.status === "claimed") {
             context.db.exec("COMMIT");
             return { ok: true, accepted: true, recovery_id: guard.recovery_id, generation: guard.generation, reused: true, ...packetReceipt };

package/dist/services/stage-pause.js

@@ -2,6 +2,8 @@ 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 { resolveProjectRoot } from "../storage/paths.js";
 import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
@@ -71,16 +73,22 @@ export function resumeStageAfterUser(context, input) {
         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 });
+    const answerPath = path.join(path.dirname(stage.pause.question_path), `answer-${crypto.createHash("sha256").update(`${stage.pause.id}\0${input.answer}`).digest("hex")}.md`);
     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 });
+        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]);
@@ -99,6 +107,7 @@ 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 retryCommands = lifecycleRetryCommands(context, stage.stage);
     const continuation = [
         prompt.trimEnd(),
         "",
@@ -107,6 +116,7 @@ export function resumeStageAfterUser(context, input) {
         `- 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.",
+        ...(retryCommands.length ? ["- A prior no-effect lifecycle rejection now has these authoritative replacement commands; use only these replacements, never invent an invocation id:", ...retryCommands.map(command => `  ${command}`)] : []),
         "",
         "<user_question>",
         fs.readFileSync(stage.pause.question_path, "utf8"),
@@ -121,7 +131,7 @@ export function resumeStageAfterUser(context, input) {
     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}` };
 }
 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, `${flowCommand(context)} stage pause ${input.runId} --stage ${input.stage} --work ${input.workId} --question-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`);
 }
 /**
  * The only shell form allowed for an agent-owned HITL pause.  Supplying a
@@ -147,9 +157,11 @@ Effect on scope or acceptance:
 USER_QUESTION`;
 }
 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`;
+    return managedLifecycleCommand(context, `${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 scope = context.env.DD_FLOW_INVOCATION_SCOPE;
+    const prefix = scope ? `DD_FLOW_INVOCATION_SCOPE=${quote([scope])} ` : "";
     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
@@ -158,13 +170,13 @@ export function flowCommand(context) {
     // 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)}`;
+        return `${prefix}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 `${prefix}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 context.ddFlowHome === defaultHome ? `${prefix}dd-flow` : `${prefix}DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
 }
 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]);