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

package/dist/services/lifecycle-invocations.js

@@ -0,0 +1,306 @@
+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) {
+    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);
+}
+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);
+}
+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 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) {
+            context.db.exec("RELEASE invocation_command");
+            return prior.command;
+        }
+        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, ""));
+}
+/** 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 at = shellSuffixOffset(command);
+    const prepared = `${command.slice(0, at).trimEnd()} --invocation-id ${id} ${command.slice(at)}`.trimEnd();
+    // 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 };
+}
+/** 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 { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
@@ -121,7 +123,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 +149,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 +162,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]);

package/dist/services/vnext-code-review.js

@@ -1,3 +1,4 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -167,7 +168,7 @@ export async function finishVnextCodeReview(context, input) {
         if (fixIds.length && repairs.length === 0) {
             const repair = addVnextCodeReviewRepair(context, { projectRoot, runId: run.id, findingIds: fixIds, checkRefsByFinding, decisionReasonsByFinding: Object.fromEntries(canonical.decision.findings.map((item) => [item.finding_ref, item.reason])), objective: `Resolve accepted CODE-REVIEW findings: ${fixIds.join(", ")}` });
             fs.writeFileSync(frozenShaFile, `${decisionSha}\n`);
-            return { ok: true, run_id: run.id, stage, outcome: "repair_required", decision_sha256: decisionSha, repair, instruction: "Run the returned repair Work in one fresh child session. When it completes, invoke the same stage finish command again with the unchanged decision file.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
+            return { ok: true, run_id: run.id, stage, outcome: "repair_required", decision_sha256: decisionSha, repair, instruction: "Run the returned repair Work in one fresh child session. When it completes, invoke next.finish_command with the unchanged decision file.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
         }
         repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
         const incompleteRepairs = repairs.filter((work) => work.status !== "completed");
@@ -215,7 +216,7 @@ export async function finishVnextCodeReview(context, input) {
         }
         refreshRunWorkProjection(context, project.id, run.id);
     });
-    return { ok: true, run_id: run.id, stage, outcome, report_path: path.join(root, "stage-report.json"), next_action: nextAction, ...(mergeRequest ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl` } } : {}) };
+    return { ok: true, run_id: run.id, stage, outcome, report_path: path.join(root, "stage-report.json"), next_action: nextAction, ...(mergeRequest ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } } : {}) };
 }
 export function reviewGroups(home) {
     const expected = new Set(baselineAspects);
@@ -260,7 +261,7 @@ export function assertCodeReviewCoverage(groups, reviewers) {
         throw new AppError("reviewer_coverage_invalid", "CODE-REVIEW requires every expected reviewer group", 2, { missing_groups: missing });
 }
 export function reviewerTask(home, group) { return `Read-only independent CODE review for ${group.key}. Assess every assigned aspect exactly once: ${group.aspect_ids.join(", ")}. Read the accepted PLAN, ${path.join(home, "05-code", "stage-report.json")}, and any files needed under the bounded CODE evidence root ${path.join(home, "05-code")}. Verify that universal and exclusive constraints (only, any, all, never, whole) and stated exceptions were not narrowed. For every changed mutation guarded by membership, ownership, authorization or parent lifecycle state, trace the decision to the write boundary: the predicate must remain in the write statement or the guard and write must share one explicit transaction with the needed lock. A separate earlier read is not proof of current authority or lifecycle state; report a material finding when this invariant is broken. Evidence closes a claim only when it exercises the named failure mechanism; a sequential negative test does not prove a concurrency race, and proof limits cannot waive an accepted obligation. Report only material, evidenced defects: a violated obligation or rule, direct evidence, impact, and minimum required outcome. Do not report taste, cosmetics, or untargeted refactoring. Use local finding ids FIND-001, FIND-002, and so on; dd-flow adds the Work-qualified canonical reference. Return dd-flow/code-review-result@1.`; }
-function orchestratorPrompt(context, input) { const template = read(path.join(input.run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code-review.md")); const decision = path.join(input.root, "decision.json"); const checks = acceptedCodeChecks(context, input.run.project_id, input.run.id).map(({ id, purpose }) => ({ id, purpose })); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- root Work: ${input.rootWork.work_id}`, `- stage: ${stage}`, `- mode: ${input.mode}`, "</stage_identity>", "", "<trusted_runtime_context>", `- project root: ${input.projectRoot}`, `- immutable write workspace: ${input.run.workspace_root}`, `- stage workspace: ${input.root}`, `- bounded CODE evidence root: ${path.join(input.run.run_root, "05-code")}`, "CODE is already semantically verified and all declared checks passed. Do not redo CODE verification; conduct independent quality review.", "</trusted_runtime_context>", "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", "Each reviewer Work must run in one fresh child session. The coordinator must never claim a reviewer Work itself. Start each ready Work with its exact start_command from the work graph; it receives the task and result schema. Reviewers are read-only and must not create subagents. Do not interrupt a quiet worker.", `Ready reviewer Works: ${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`, `Finish only after every reviewer Work settles and you have written ${decision}: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer results use local FIND-NNN ids. Classify them by the canonical WRK-.../FIND-NNN finding_ref returned by dd-flow. Fix P0/P1. Fix bounded safe P2 by default; defer only a legitimate P2 with a named DEF. P3 is an observation or a reasoned rejection, not automatic repair/DEF. For every disposition fix, check_refs is mandatory: choose the one or more causal checks from the accepted list below that the repair must rerun. Do not guess a CHK id or copy every check. The first successful Finish freezes this decision and creates one repair Work when needed. Run it, then call the same Finish command again. Review is not repeated.", "If the post-repair aggregate gate fails, do not stop after `code_review_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use the returned repair command with the failed receipt, a relevant completed origin Work ID, and a concise repair objective; then stop so the runner can dispatch the new repair. Do not edit invisibly in the root orchestrator.", `Accepted repair checks: ${JSON.stringify(checks)}`, "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@3", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", check_refs: ["CHK-CAUSAL-CHECK only when disposition is fix"], def_id: "DEF-0001 only for an allowed P2 deferral", duplicate_of: "canonical finding_ref only for duplicate" }] }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n"); }
+function orchestratorPrompt(context, input) { const template = read(path.join(input.run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code-review.md")); const decision = path.join(input.root, "decision.json"); const checks = acceptedCodeChecks(context, input.run.project_id, input.run.id).map(({ id, purpose }) => ({ id, purpose })); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- root Work: ${input.rootWork.work_id}`, `- stage: ${stage}`, `- mode: ${input.mode}`, "</stage_identity>", "", "<trusted_runtime_context>", `- project root: ${input.projectRoot}`, `- immutable write workspace: ${input.run.workspace_root}`, `- stage workspace: ${input.root}`, `- bounded CODE evidence root: ${path.join(input.run.run_root, "05-code")}`, "CODE is already semantically verified and all declared checks passed. Do not redo CODE verification; conduct independent quality review.", "</trusted_runtime_context>", "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", "Each reviewer Work must run in one fresh child session. The coordinator must never claim a reviewer Work itself. Start each ready Work with its exact start_command from the work graph; it receives the task and result schema. Reviewers are read-only and must not create subagents. Do not interrupt a quiet worker.", `Ready reviewer Works: ${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`, `Finish only after every reviewer Work settles and you have written ${decision}: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer results use local FIND-NNN ids. Classify them by the canonical WRK-.../FIND-NNN finding_ref returned by dd-flow. Fix P0/P1. Fix bounded safe P2 by default; defer only a legitimate P2 with a named DEF. P3 is an observation or a reasoned rejection, not automatic repair/DEF. For every disposition fix, check_refs is mandatory: choose the one or more causal checks from the accepted list below that the repair must rerun. Do not guess a CHK id or copy every check. The first successful Finish freezes this decision and creates one repair Work when needed. Run it, then call the returned next.finish_command; do not reuse an earlier invocation-id. Review is not repeated.", "If the post-repair aggregate gate fails, do not stop after `code_review_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use the returned repair command with the failed receipt, a relevant completed origin Work ID, and a concise repair objective; then stop so the runner can dispatch the new repair. Do not edit invisibly in the root orchestrator.", `Accepted repair checks: ${JSON.stringify(checks)}`, "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@3", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", check_refs: ["CHK-CAUSAL-CHECK only when disposition is fix"], def_id: "DEF-0001 only for an allowed P2 deferral", duplicate_of: "canonical finding_ref only for duplicate" }] }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n"); }
 function canonicalReviewEvidence(decision, reviewers) {
     const known = new Set(canonicalCodeFindings(reviewers).map((item) => item.finding_ref));
     const items = new Map(decision.findings.map((item) => [item.finding_ref, item]));
@@ -420,7 +421,7 @@ function requireRun(context, projectId, runId) { const run = context.db.get("SEL
     throw new AppError("not_found", "RUN is not registered", 1); return run; }
 function requireHome(run) { if (!run.run_root)
     throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
-function finishCommand(context, runId, projectRoot, decision) { return `${flowCommand(context)} stage finish ${runId} --stage code-review --decision-file ${JSON.stringify(decision)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`; }
+function finishCommand(context, runId, projectRoot, decision) { return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code-review --decision-file ${JSON.stringify(decision)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`); }
 function findFiles(root, name) { if (!fs.existsSync(root))
     return []; const out = []; for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
     const file = path.join(root, entry.name);

package/dist/services/vnext-code.js

@@ -1,3 +1,4 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import fs from "node:fs";
@@ -267,7 +268,7 @@ export async function finishVnextCode(context, input) {
         outcome: "accepted",
         report_path: path.join(root, "stage-report.json"),
         next_action: next,
-        ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: `${flowCommand(context)} stage start ${run.id} --stage code-review --project-root ${JSON.stringify(projectRoot)} --json` } } : next === "start_merge" ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl` } } : {})
+        ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage code-review --project-root ${JSON.stringify(projectRoot)} --json`) } } : next === "start_merge" ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } } : {})
     };
 }
 export function addVnextCodeRepair(context, input) {
@@ -604,7 +605,7 @@ function requireHome(run) {
     return run.run_root;
 }
 function finishCommand(context, runId, projectRoot, verificationFile) {
-    return `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`;
+    return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`);
 }
 function readVerification(context, input) {
     const file = path.resolve(input.file);