@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.74

package/dist/services/lifecycle-invocations.js

@@ -0,0 +1,637 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import fs from "node:fs";
+import { quote } from "shell-quote";
+import { setTimeout as delay } from "node:timers/promises";
+import { AppError, errorRecord } 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 { readNativeDaemonState, requireManagedDaemonBinding } from "./managed-daemon-binding.js";
+import { managedProcessStatus } from "./managed-processes.js";
+import { appendEvent } from "./run-controller-state.js";
+import { recoverCommittedWorkStart } from "./work-registry.js";
+import { observeCommandHook } from "./hooks.js";
+import { runtimeHarness } from "./execution-policy.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 = {}) {
+    if (details.recoverable === false || details.effect === "unknown" || details.effect === "committed")
+        return false;
+    return details.recoverable === true || ["validation", "schema_validation", "work_checks_failed", "code_gate_failed", "code_review_gate_failed", "merge_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);
+}
+/** Read-only controller observation of a retained lifecycle outcome. */
+export function lifecycleInvocationOutcome(context, id) {
+    const row = load(context, id);
+    return { status: row.status, outcome: row.outcome_json ? JSON.parse(row.outcome_json) : null };
+}
+/** Current failures are read from runtime authority, never from model text. */
+export function assertLifecycleOutcomes(context, scope) {
+    const project = requireProjectByRoot(context, scope.projectRoot);
+    const diagnostics = lifecycleDiagnostics(context, project.id, scope.runId, scope.generation);
+    if (fs.existsSync(diagnostics)) {
+        for (const name of fs.readdirSync(diagnostics).filter(name => name.endsWith(".json"))) {
+            const record = JSON.parse(fs.readFileSync(path.join(diagnostics, name), "utf8"));
+            if (record.project_id !== project.id || record.run_id !== scope.runId || record.generation !== scope.generation)
+                throw new AppError("lifecycle_outcome_conflict", "Lifecycle diagnostic scope differs", 1);
+            throw new AppError(record.error?.code ?? "lifecycle_outcome_unknown", record.error?.message ?? "Lifecycle settlement could not be persisted", 1, { ...record.error?.details, lifecycle_outcome: record, diagnostic_artifact: path.join(diagnostics, name) });
+        }
+    }
+    const columns = context.db.all("PRAGMA table_info(hook_events)");
+    if (columns.some(column => column.name === "outcome_json")) {
+        for (const row of context.db.all("SELECT outcome_json FROM hook_events WHERE project_id = ? AND json_extract(outcome_json, '$.run_id') = ? AND json_extract(outcome_json, '$.generation') = ? ORDER BY id", [project.id, scope.runId, scope.generation])) {
+            const outcome = JSON.parse(row.outcome_json);
+            if (outcome.disposition === "retrying" && outcome.deadline <= Date.now())
+                throw new AppError("lifecycle_outcome_unknown", "Storage retry has no terminal receipt; reconcile its committed evidence", 1, { lifecycle_outcome: outcome, effect: "unknown" });
+            if (outcome.disposition === "fatal")
+                throw new AppError(outcome.error?.code ?? "lifecycle_outcome_unknown", outcome.error?.message || "Mandatory lifecycle failed (historical receipt has no message)", 1, { ...outcome.error?.details, lifecycle_outcome: outcome });
+        }
+    }
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'"))
+        return;
+    const rows = context.db.all(`SELECT a.* FROM lifecycle_invocations a
+    WHERE json_extract(a.scope_json, '$.projectRoot') = ? AND json_extract(a.scope_json, '$.runId') = ?
+      AND json_extract(a.scope_json, '$.generation') = ? AND a.status = 'settled'
+      AND NOT EXISTS (SELECT 1 FROM lifecycle_invocations newer WHERE newer.scope_json = a.scope_json AND newer.fingerprint = a.fingerprint AND newer.rowid > a.rowid)
+    ORDER BY a.rowid`, [scope.projectRoot, scope.runId, scope.generation]);
+    for (const row of rows) {
+        const error = (row.outcome_json ? JSON.parse(row.outcome_json) : null)?.error;
+        if (typeof error?.code === "string" && !isRetryableLifecycleRejection(error.code, error.details))
+            throw new AppError(error.code, typeof error.message === "string" ? error.message : "Mandatory lifecycle failed", 1, { ...(error.details ?? {}), invocation_id: row.id });
+    }
+}
+/** Hooks already own native identity. Retain command outcomes there, with an
+ * atomic controller notification; missing notifications reconcile from the row. */
+export function observeLifecycleCommand(context, command) {
+    const parsed = parseLifecycleCommand(command);
+    if (parsed.kind !== "standalone")
+        return () => { };
+    let anchor;
+    context.observeLifecycleHook = (projectId, eventId) => {
+        if (anchor)
+            return;
+        const event = context.db.get("SELECT session_id, provider_session_id, parent_session_id, daemon_id, harness FROM hook_events WHERE id = ? AND project_id = ?", [eventId, projectId]);
+        if (!event)
+            return;
+        let runId = context.db.get("SELECT run_id FROM sessions WHERE project_id = ? AND harness = ? AND (session_id = ? OR session_id = ? OR provider_session_id = ?) AND run_id IS NOT NULL ORDER BY session_id = ? DESC LIMIT 1", [projectId, event.harness, event.session_id, event.parent_session_id, event.parent_session_id, event.session_id])?.run_id;
+        let generation;
+        // A first Stage command precedes logical Session binding. Its native root
+        // is already owned by the controller's retained create receipt.
+        if (context.db.get("SELECT 1 FROM sqlite_master WHERE name = 'run_controllers'")) {
+            const owners = context.db.all("SELECT run_id, generation, state_json FROM run_controllers WHERE project_id = ? AND status NOT IN ('completed','cancelled','superseded')", [projectId]).filter(owner => {
+                const state = JSON.parse(owner.state_json);
+                return state.sessions?.some(session => [event.provider_session_id ?? event.session_id, event.parent_session_id].includes(session.id) && runtimeHarness(session.profile) === event.harness);
+            });
+            if (owners.length > 1)
+                return;
+            if (owners.length === 1) {
+                if (runId && runId !== owners[0].run_id)
+                    return;
+                runId = owners[0].run_id;
+                generation = owners[0].generation;
+            }
+        }
+        if (event.daemon_id) {
+            for (const record of managedProcessStatus(context)) {
+                if (record.project_id !== projectId || !record.run_id || !record.kind.endsWith("-daemon"))
+                    continue;
+                const metadata = JSON.parse(record.metadata_json);
+                if (typeof metadata.state_dir !== "string")
+                    continue;
+                let daemonId;
+                try {
+                    daemonId = readNativeDaemonState(metadata.state_dir).daemon_id;
+                }
+                catch {
+                    continue;
+                } // Discovery of unrelated historical daemons is not authority.
+                if (daemonId !== event.daemon_id)
+                    continue;
+                const binding = requireManagedDaemonBinding(context, { stateDir: metadata.state_dir, projectId, runId: record.run_id });
+                if (binding.state.daemon_id !== event.daemon_id)
+                    continue;
+                runId = record.run_id;
+                generation = metadata.run_generation;
+                break;
+            }
+        }
+        if (!runId)
+            return;
+        anchor = { project_id: projectId, run_id: runId, generation: generation ?? recoveryGuard(context, projectId, runId)?.generation ?? 0, hook_event_id: eventId, session_id: event.session_id, harness: event.harness, operation: parsed.invocation.operation };
+    };
+    observeCommandHook(context, command);
+    const invocationId = commandOption(parsed.invocation, "invocation-id");
+    if (!anchor && invocationId) {
+        const attempt = load(context, invocationId);
+        checkCommand(attempt, command);
+        if (attempt.event_key && ["observed", "executing"].includes(attempt.status)) {
+            const scope = JSON.parse(attempt.scope_json);
+            const project = requireProjectByRoot(context, scope.projectRoot);
+            const event = context.db.get("SELECT id FROM hook_events WHERE project_id = ? AND event_key = ?", [project.id, attempt.event_key]);
+            if (event)
+                context.observeLifecycleHook(project.id, event.id);
+        }
+    }
+    return outcome => {
+        delete context.observeLifecycleHook;
+        if (!anchor)
+            return;
+        const error = outcome.error ? errorRecord(outcome.error) : undefined;
+        const retryable = error && isRetryableLifecycleRejection(error.code, error.details);
+        const record = { ...anchor, ...(error ? { error } : outcome), effect: error ? error.details.effect ?? (retryable ? "no_effect" : "unknown") : "committed", disposition: error ? retryable ? "correctable" : "fatal" : "completed" };
+        try {
+            context.db.writeTransaction(() => {
+                const retained = context.db.get("SELECT outcome_json FROM hook_events WHERE id = ?", [anchor.hook_event_id]);
+                const previous = retained?.outcome_json ? JSON.parse(retained.outcome_json) : null;
+                if (previous?.storage_retry === 1)
+                    Object.assign(record, { storage_retry: 1, work_id: previous.work_id });
+                const encoded = JSON.stringify(record);
+                if (retained?.outcome_json && previous?.disposition !== "retrying") {
+                    if (retained.outcome_json !== encoded)
+                        throw new AppError("lifecycle_outcome_conflict", "Hook outcome cannot change", 1, { hook_event_id: anchor.hook_event_id });
+                    return;
+                }
+                context.db.run("UPDATE hook_events SET outcome_json = ? WHERE id = ?", [encoded, anchor.hook_event_id]);
+                if (context.db.get("SELECT 1 FROM sqlite_master WHERE name = 'run_controllers'"))
+                    for (const controller of context.db.all("SELECT controller_id FROM run_controllers WHERE project_id = ? AND run_id = ? AND generation = ?", [anchor.project_id, anchor.run_id, anchor.generation]))
+                        appendEvent(context, controller.controller_id, "lifecycle_outcome", record);
+            });
+        }
+        catch (persistence) {
+            if (persistence instanceof AppError && persistence.code === "lifecycle_outcome_conflict")
+                throw persistence;
+            // Diagnostic evidence is not replay authority. If SQL is unavailable,
+            // the controller still sees this failure and fences instead of waiting
+            // for a model to report it or invent a new invocation.
+            const directory = lifecycleDiagnostics(context, anchor.project_id, anchor.run_id, anchor.generation);
+            try {
+                fs.mkdirSync(directory, { recursive: true });
+                fs.writeFileSync(path.join(directory, `${anchor.hook_event_id}.json`), JSON.stringify({ ...record, disposition: "fatal", persistence_error: String(persistence) }), { flag: "wx", mode: 0o600, flush: true });
+            }
+            catch (diagnostic) {
+                if (diagnostic.code !== "EEXIST")
+                    process.stderr.write(`${JSON.stringify({ primary: record.error ?? { effect: "committed" }, persistence: String(persistence), diagnostic: String(diagnostic) })}\n`);
+            }
+            throw persistence;
+        }
+    };
+}
+function lifecycleDiagnostics(context, projectId, runId, generation) {
+    return path.join(context.ddFlowHome, "diagnostics", "lifecycle", encodeURIComponent(projectId), encodeURIComponent(runId), String(generation));
+}
+/** 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" && (successor.deadline === null || successor.deadline > Date.now()) ? [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);
+    const suppliedId = commandOption(parsed, "invocation-id");
+    // An invocation id is authority, never decorative text.  In particular,
+    // callers that add arguments after rendering must not be able to reuse an
+    // issued id for a different command.
+    if (suppliedId) {
+        const retained = load(context, suppliedId);
+        if (retained.scope_json !== JSON.stringify(scope)) {
+            throw new AppError("invocation_scope_mismatch", "Lifecycle attempt belongs to another managed scope", 1, { invocation_id: suppliedId });
+        }
+        checkCommand(retained, command);
+        assertRenderableInvocation(retained);
+        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", "The controller has not issued this lifecycle command yet. End this Turn and await its next assignment with the exact command; do not generate or reuse an invocation ID.", 1);
+        return renderInvocationCommand(retained, command);
+    }
+    storage(context);
+    return context.db.writeTransaction(() => {
+        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) {
+            return renderInvocationCommand(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);
+        return issueLifecycleInvocation(context, command, scope).command;
+    });
+}
+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);
+    return successorLifecycleInvocationCommand(context, prior);
+}
+/** A predecessor may publish exactly one successor only while the caller has
+ * proved that no lifecycle effect was admitted.  This is shared by ordinary
+ * command validation and the native pre-execution rejection path. */
+function successorLifecycleInvocationCommand(context, prior) {
+    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 issued command lost its invocation marker", 1);
+    // The parser proves the marker belongs to argv. Remove that one rendered
+    // token from the retained text so response-file/stdin/heredoc presentation
+    // remains byte-for-byte stable across a retry.
+    const marker = ` --invocation-id ${prior.id}`;
+    const markerAt = prior.command.indexOf(marker);
+    if (markerAt < 0 || prior.command.indexOf(marker, markerAt + marker.length) >= 0)
+        throw new AppError("invocation_command_invalid", "Retained issued command has an ambiguous invocation marker", 1);
+    const command = `${prior.command.slice(0, markerAt)}${prior.command.slice(markerAt + marker.length)}`;
+    return managedLifecycleCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: prior.scope_json, DD_FLOW_CURRENT_INVOCATION: prior.id } }, command);
+}
+/** A native observer can reject a malformed tool call before the CLI claims
+ * execution.  Persist that fact and its sole replacement atomically: waiting
+ * callers must never time out merely because the observer rejected syntax. */
+export function settleLifecycleNoEffectRejection(context, id, command, error, identity) {
+    storage(context);
+    context.db.beginWriteTransaction();
+    try {
+        const prior = load(context, id);
+        checkCommand(prior, command);
+        const scope = JSON.parse(prior.scope_json);
+        checkNativeIdentity(scope, identity, id);
+        if (prior.status === "settled") {
+            context.db.exec("COMMIT");
+            return;
+        }
+        if (scope.runId)
+            assertLifecycleInvocationCurrent(context, scope, command);
+        if (prior.status !== "issued")
+            throw new AppError("invocation_rejection_conflict", "A lifecycle rejection arrived after execution admission", 1, { invocation_id: id });
+        settleUnadmittedInvocation(context, prior, error);
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
+// Caller holds the write transaction and has checked authority. Issued (or
+// legacy expired) attempts have never admitted an effect; observed/executing
+// attempts must never receive an automatic replacement.
+function settleUnadmittedInvocation(context, prior, error) {
+    if (!["issued", "expired"].includes(prior.status))
+        throw new AppError("invocation_rejection_conflict", "Attempt already admitted native execution", 1);
+    const details = { ...error.details, effect: "no_effect", recoverable: true, retry_command: successorLifecycleInvocationCommand(context, prior),
+        retry_instruction: "Use retry_command as one standalone lifecycle command. The rejected command did not change lifecycle state." };
+    if (context.db.run("UPDATE lifecycle_invocations SET status = 'settled', outcome_json = ?, updated_at = ? WHERE id = ? AND status = ?", [JSON.stringify({ error: { ...error, details } }), context.now(), prior.id, prior.status]).changes !== 1) {
+        throw new AppError("invocation_settlement_conflict", "Lifecycle rejection could not be committed", 1, { invocation_id: prior.id });
+    }
+}
+const receiptTimeout = (id) => ({ code: "invocation_receipt_timeout", message: "No native confirmation before the receipt deadline; lifecycle state was not changed", exitCode: 1, details: { invocation_id: id } });
+/** 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.beginWriteTransaction();
+    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 });
+        const storageRetry = error.code === "storage_write_failed" && error.details.effect === "no_effect"
+            && !context.db.get("SELECT 1 FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? AND json_extract(outcome_json, '$.error.details.storage_retry') = 1 LIMIT 1", [prior.scope_json, prior.fingerprint]);
+        if (isRetryableLifecycleRejection(error.code, error.details) || storageRetry) {
+            const retry = retryLifecycleInvocationCommand(context, id);
+            details.retry_command = retry;
+            details.recoverable = true;
+            if (storageRetry)
+                details.storage_retry = 1;
+            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 assertRenderableInvocation(row) {
+    const outcome = row.outcome_json ? JSON.parse(row.outcome_json) : null;
+    if (row.status === "settled" && outcome?.error)
+        throw new AppError("invocation_command_blocked", "Failed lifecycle authority cannot be advertised as an executable command", 1, { invocation_id: row.id, outcome });
+    if (row.status === "expired" || row.status === "issued" && row.deadline !== null && row.deadline <= Date.now()) {
+        throw new AppError("invocation_expired", "Retained lifecycle attempt has expired; inspection cannot grant a new attempt", 1, { invocation_id: row.id, status: row.status, outcome: row.outcome_json ? JSON.parse(row.outcome_json) : null });
+    }
+}
+function renderInvocationCommand(row, command) {
+    assertRenderableInvocation(row);
+    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. */
+function checkNativeIdentity(scope, identity, id) {
+    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: id });
+    }
+}
+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;
+    checkNativeIdentity(scope, identity, input.id);
+    const identityJson = JSON.stringify([identity.daemonId, identity.rootSessionId, identity.sessionId, identity.parentSessionId, identity.toolCallId]);
+    context.db.beginWriteTransaction();
+    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)) {
+            if (scope.runId)
+                assertLifecycleInvocationCurrent(context, scope, input.command);
+            settleUnadmittedInvocation(context, row, receiptTimeout(input.id));
+            context.db.exec("COMMIT");
+            return { eventKey: row.event_key, duplicate: true };
+        }
+        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") {
+            const scope = JSON.parse(row.scope_json);
+            if (invocation(row.command).operation === "work_start" && row.event_key) {
+                input.assertCurrent(scope);
+                const result = recoverCommittedWorkStart(context, row.id, row.event_key, scope.generation);
+                if (result) {
+                    const outcome = { result, effect: "committed" };
+                    settleLifecycleInvocation(context, row.id, outcome);
+                    return { outcome, replay: true };
+                }
+            }
+            throw new AppError("invocation_outcome_pending", "This attempt already started; inspect its retained operation outcome before retrying", 1, { invocation_id: input.id, effect: "unknown" });
+        }
+        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())) {
+            context.db.beginWriteTransaction();
+            try {
+                const current = load(context, input.id);
+                if (["issued", "expired"].includes(current.status)) {
+                    input.assertCurrent(JSON.parse(current.scope_json));
+                    settleUnadmittedInvocation(context, current, receiptTimeout(input.id));
+                }
+                context.db.exec("COMMIT");
+            }
+            catch (error) {
+                context.db.exec("ROLLBACK");
+                throw error;
+            }
+            continue;
+        }
+        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 });
+    }
+}