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

package/dist/services/lifecycle-invocations.js

@@ -0,0 +1,1122 @@
+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 { shortEntityReference } from "../shared/entity-references.js";
+import { resolveWorkReference } from "../storage/work-references.js";
+import { commandOption, continuationCommand, lifecycleCommandFromPayload, 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";
+import { normalizedPathAlias, resolveContextualPaths } from "./command-context.js";
+import { isRegisteredRepair } from "./repair-intents.js";
+import { stageAttempt } from "./stage-work-graph.js";
+import { contextualPathOptionsForLifecycle } from "../cli/command-inputs.js";
+import { canonicalPath } from "../storage/paths.js";
+/** Auxiliary commands have no invocation capability, but may not escape their
+ * native daemon's project/RUN. Context aliases never grant mutation authority. */
+export function assertAuxiliaryCommandScope(context, command, projectRoot) {
+    const auxiliary = continuationCommand(command);
+    const daemonId = context.env.DD_FLOW_DAEMON_ID;
+    if (!auxiliary || !daemonId)
+        return;
+    const event = observedLifecycleNativeEvent(context, command, daemonId);
+    if (!event)
+        throw new AppError("invocation_receipt_missing", "Auxiliary command has no exact native receipt", 1, { phase: "prepare", effect: "no_effect" });
+    const project = context.db.get("SELECT root FROM projects WHERE id = ?", [event.project_id]);
+    if (!project || !projectRoot || canonicalPath(projectRoot, false) !== project.root)
+        throw new AppError("invocation_scope_mismatch", "Auxiliary command differs from its native project scope", 1, { phase: "prepare", effect: "no_effect" });
+    for (const record of managedProcessStatus(context)) {
+        if (record.project_id !== event.project_id || !record.run_id || !record.kind.endsWith("-daemon"))
+            continue;
+        const metadata = JSON.parse(record.metadata_json);
+        if (typeof metadata.state_dir !== "string")
+            continue;
+        let state;
+        try {
+            state = readNativeDaemonState(metadata.state_dir);
+        }
+        catch {
+            continue;
+        }
+        if (state.daemon_id !== daemonId)
+            continue;
+        requireManagedDaemonBinding(context, { stateDir: metadata.state_dir, projectId: event.project_id, runId: record.run_id });
+        const reference = auxiliary.args.options.get("run")?.[0] ?? auxiliary.args.positional[2];
+        const run = context.db.get("SELECT id FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [event.project_id, reference, reference]);
+        if (run?.id !== record.run_id)
+            throw new AppError("invocation_scope_mismatch", "Auxiliary command differs from its native RUN scope", 1, { phase: "prepare", effect: "no_effect" });
+        assertRunMutationAllowed(context, event.project_id, record.run_id, metadata.run_generation);
+        return;
+    }
+    throw new AppError("invocation_scope_unavailable", "Auxiliary command has no live managed daemon binding", 1, { phase: "prepare", effect: "no_effect" });
+}
+// 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 (code.startsWith("native_hook_") || code === "invocation_receipt_timeout")
+        return false;
+    if (code === "fresh_session_required" || details.recoverable === false || details.handoff_required === true || details.effect === "unknown" || details.effect === "committed")
+        return false;
+    if (code === "validation" || code === "schema_validation")
+        return details.phase === "prepare" && details.effect === "no_effect" && details.recoverable === true;
+    if (["invocation_command_mismatch", "invocation_argument_mismatch"].includes(code))
+        return details.recoverable !== false;
+    return details.recoverable === true || ["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);
+}
+/** A correctable rejection either publishes an exact replacement command or
+ * proves that the controller must hand the existing Work to another Session.
+ * The latter is deliberately not retryable in the caller that just failed. */
+export function isCorrectableLifecycleRejection(code, details = {}) {
+    if (details.recoverable === false || details.effect === "unknown" || details.effect === "committed")
+        return false;
+    return isRetryableLifecycleRejection(code, details)
+        || (code === "fresh_session_required" && details.handoff_required === true
+            && details.recoverable === true);
+}
+function storage(context) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'")) {
+        throw new AppError("invocation_storage_unprepared", "Lifecycle invocation storage is not prepared; start dd-flow normally before issuing native work", 1);
+    }
+}
+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 projected = publicInvocationArgs(parsed);
+    const publicParsed = invocation(`${quote([parsed.executable])} ${quoteModelFacingArgs(projected)}`);
+    const options = [...publicParsed.args.options].filter(([key]) => !["invocation-id", "hook-event-id", "json", "progress-jsonl"].includes(key))
+        .map(([key, values]) => [key, key === "reason" ? ["<semantic-reason>"] : values.map(value => normalizedInvocationValue(key, value))])
+        .sort(([a], [b]) => a.localeCompare(b));
+    return crypto.createHash("sha256").update(JSON.stringify([parsed.operation, publicParsed.args.positional.map(value => normalizedInvocationValue("positional", value)), options])).digest("hex");
+}
+const runtimeOwnedOptions = {
+    stage_start: new Set(["project-root", "context-file", "context-sha256", "response-file", "require-session-binding"]),
+    stage_finish: new Set(["project-root", "result-file", "decision-file", "verification-file"]),
+    stage_pause: new Set(["project-root"]), stage_resume: new Set(["project-root", "answer-file"]),
+    work_start: new Set(["project-root", "recovery-id"]),
+    work_finish: new Set(["project-root"]), work_fail: new Set(["project-root"]),
+    merge_apply: new Set(["project-root"]), merge_repair: new Set(["project-root"]),
+    recovery_accept: new Set(["project-root"])
+};
+function publicInvocationArgs(parsed) {
+    const hidden = runtimeOwnedOptions[parsed.operation] ?? new Set();
+    const args = [];
+    for (let index = 0; index < parsed.argv.length; index += 1) {
+        const value = parsed.argv[index];
+        if (!value.startsWith("--")) {
+            args.push(value);
+            continue;
+        }
+        const key = value.slice(2).split("=", 1)[0];
+        const inline = value.includes("=");
+        const next = parsed.argv[index + 1];
+        if (hidden.has(key) || key === "invocation-id" || key === "hook-event-id") {
+            if (!inline && next && !next.startsWith("--"))
+                index += 1;
+            continue;
+        }
+        args.push(value);
+        if (!inline && next && !next.startsWith("--"))
+            args.push(parsed.argv[++index]);
+    }
+    // A managed coordinator Session is already bound to its RUN. Work IDs stay
+    // public because sibling Work assignments can coexist under one native root.
+    const operationOffset = parsed.operation === "recovery_accept" ? 3 : 2;
+    if (["stage_start", "stage_finish", "recovery_accept"].includes(parsed.operation)
+        && !parsed.args.options.has("bootstrap") && args[operationOffset] && !args[operationOffset].startsWith("--"))
+        args.splice(operationOffset, 1);
+    return args;
+}
+function normalizedInvocationValue(key, value) {
+    value = normalizedPathAlias(value);
+    if (key === "project-root" && (path.isAbsolute(value) || value === "@project"))
+        return "@project";
+    if (["result-file", "decision-file", "verification-file"].includes(key))
+        return "<validated-input-path>";
+    if (value.startsWith("@project") || value.startsWith("@workspace") || value.startsWith("@run"))
+        return value.replace(/\\/g, "/");
+    if (["result-file", "decision-file", "verification-file", "context-file"].includes(key) && path.isAbsolute(value)) {
+        const runRelative = value.replace(/\\/g, "/").match(/\/(?:runs\/)?RUN-[^/]+\/(.+)$/)?.[1];
+        if (runRelative)
+            return `@run/${runRelative}`;
+    }
+    if (["positional", "work", "run"].includes(key))
+        return shortEntityReference(value);
+    return key === "retry-check" ? /(?:^|\/)(RCP-\d{3,})$/.exec(value)?.[1] ?? value : value;
+}
+/** Shell/JSON builders sometimes preserve the shell escape before an alias.
+ * Accept it only for the small declared alias vocabulary. */
+function quoteModelFacingArgs(argv) {
+    return argv.map(value => /^@(project|workspace|run)(?:\/.*)?$/.test(value)
+        ? `'${value.replaceAll("'", `'\\''`)}'`
+        : quote([value])).join(" ");
+}
+function withoutInvocationId(command, aliases) {
+    const parsed = invocation(command);
+    const argv = publicInvocationArgs(parsed);
+    for (let index = 0; index < argv.length; index += 1) {
+        const option = argv[index - 1]?.replace(/^--/, "");
+        if (option === "project-root")
+            argv[index] = "@project";
+        else if (option === "work" || option === "run")
+            argv[index] = shortEntityReference(argv[index]);
+        else if (option && aliases && ["result-file", "decision-file", "verification-file", "context-file"].includes(option) && path.isAbsolute(argv[index])) {
+            for (const [name, root] of [["run", aliases.run], ["workspace", aliases.workspace], ["project", aliases.project]]) {
+                if (!root)
+                    continue;
+                const relative = path.relative(root, argv[index]);
+                if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+                    argv[index] = `@${name}${relative ? `/${relative.replaceAll(path.sep, "/")}` : ""}`;
+                    break;
+                }
+            }
+        }
+        else if (!argv[index - 1]?.startsWith("--") && !argv[index].startsWith("--"))
+            argv[index] = normalizedInvocationValue("positional", argv[index]);
+    }
+    const env = Object.fromEntries(Object.entries(parsed.env).filter(([key]) => !["DD_FLOW_INVOCATION_SCOPE", "DD_FLOW_HOME", "DD_FLOW_BIN"].includes(key)));
+    const executable = parsed.env.DD_FLOW_BIN || parsed.executable === "$DD_FLOW_BIN" ? '"$DD_FLOW_BIN"' : quote([parsed.executable]);
+    const prefix = Object.entries(env).map(([key, value]) => `${key}=${quote([value])}`).join(" ");
+    const suffix = command.slice(shellSuffixOffset(command)).trimStart();
+    return `${prefix ? `${prefix} ` : ""}${executable}${argv.length ? ` ${quoteModelFacingArgs(argv)}` : ""}${suffix ? ` ${suffix}` : ""}`.trim();
+}
+function publicInvocationCommand(context, row, command) {
+    if (!commandOption(invocation(command), "project-root"))
+        command = retainedCommandWithoutInvocationId(row);
+    const rendered = renderInvocationCommand(row, command);
+    const scope = JSON.parse(row.scope_json);
+    const run = scope.runId ? context.db.get("SELECT workspace_root, run_root FROM runs WHERE id = ?", [scope.runId]) : undefined;
+    return withoutInvocationId(rendered, { project: scope.projectRoot, ...(run?.workspace_root ? { workspace: run.workspace_root } : {}), ...(run?.run_root ? { run: run.run_root } : {}) });
+}
+function retainedCommandWithoutInvocationId(row) {
+    const marker = ` --invocation-id ${row.id}`;
+    const at = row.command.indexOf(marker);
+    if (at < 0 || row.command.indexOf(marker, at + marker.length) >= 0)
+        throw new AppError("invocation_command_invalid", "Retained issued command has an ambiguous invocation marker", 1);
+    return `${row.command.slice(0, at)}${row.command.slice(at + marker.length)}`;
+}
+/** Resolve the small, declared alias vocabulary used by model-facing lifecycle commands.
+ * Both native-hook admission and CLI execution call this function so they cannot
+ * disagree about the command that an alias denotes. */
+export function expandLifecycleInvocationArgs(context, args, scope, operation) {
+    const pathOptions = contextualPathOptionsForLifecycle(operation);
+    const run = scope.runId ? context.db.get("SELECT id, short_id, workspace_root, run_root FROM runs WHERE id = ?", [scope.runId]) : undefined;
+    const roots = { project: scope.projectRoot, workspace: run?.workspace_root, run: run?.run_root };
+    return resolveContextualPaths(args.map((value, index) => {
+        if (run && !args[index - 1]?.startsWith("--") && [run.short_id, normalizedInvocationValue("positional", run.id)].includes(value) && !operation.startsWith("work_"))
+            return run.id;
+        return value;
+    }), pathOptions, roots);
+}
+/** Validate alias spelling before native-receipt lookup, so a correctable
+ * command typo is never reported as missing infrastructure evidence. */
+export function validateLifecyclePathAliases(args, operation) {
+    const pathOptions = contextualPathOptionsForLifecycle(operation);
+    for (let index = 0; index < args.length; index += 1) {
+        const option = args[index - 1]?.replace(/^--/, "");
+        if (!option || !pathOptions.has(option))
+            continue;
+        const original = args[index];
+        const value = normalizedPathAlias(original);
+        if ((original.startsWith("\\") && original.replace(/^\\+/, "").startsWith("@") && value === original)
+            || (value.startsWith("@") && !/^@(project|workspace|run)(?:\/.*)?$/.test(value))) {
+            throw new AppError("usage", `Unknown path alias: ${original}`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+        }
+    }
+}
+function canonicalManagedCommand(context, command, scope) {
+    const parsed = invocation(command);
+    const argv = expandLifecycleInvocationArgs(context, parsed.argv, scope, parsed.operation);
+    const env = { ...parsed.env, DD_FLOW_INVOCATION_SCOPE: JSON.stringify(scope) };
+    const prefix = Object.entries(env).map(([key, value]) => `${key}=${quote([value])}`).join(" ");
+    const executable = parsed.executable === "$DD_FLOW_BIN" ? '"$DD_FLOW_BIN"' : quote([parsed.executable]);
+    const suffix = command.slice(shellSuffixOffset(command)).trimStart();
+    return `${prefix} ${executable}${argv.length ? ` ${quote(argv)}` : ""}${suffix ? ` ${suffix}` : ""}`.trim();
+}
+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 attempt for the requested operation; use a current runtime-issued command without adding an invocation ID", 1, { invocation_id: id, effect: "no_effect" });
+    }
+    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; use a current runtime-issued command without adding an invocation ID", 1, { invocation_id: id, effect: "no_effect" });
+    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" && !isRegisteredRepair(context, outcome.error?.details?.continuation, { projectId: project.id, runId: scope.runId }))
+                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" && !isCorrectableLifecycleRejection(error.code, error.details) && !isRegisteredRepair(context, error.details?.continuation, { projectId: project.id, runId: scope.runId }))
+            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, nativeEvent) {
+    const parsed = parseLifecycleCommand(command);
+    const auxiliary = continuationCommand(command);
+    if (parsed.kind !== "standalone" && !auxiliary)
+        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;
+        let correlation = {};
+        // 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;
+                const current = JSON.parse(owners[0].state_json);
+                correlation = { stage: current.stage, ...(current.stage ? { attempt: stageAttempt(context, projectId, runId, current.stage) } : {}), controller_turn: current.turns };
+            }
+        }
+        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.kind === "standalone" ? parsed.invocation.operation : auxiliary.operation, ...correlation, ...(auxiliary ? { auxiliary: true } : {}) };
+    };
+    if (nativeEvent)
+        context.observeLifecycleHook(nativeEvent.project_id, nativeEvent.id);
+    else
+        observeCommandHook(context, command);
+    const invocationId = parsed.kind === "standalone" ? commandOption(parsed.invocation, "invocation-id") : undefined;
+    if (!anchor && invocationId && !nativeEvent) {
+        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);
+        }
+        if (!anchor)
+            throw new AppError("invocation_receipt_missing", "Managed lifecycle command has no committed native receipt", 1, { invocation_id: invocationId, effect: "no_effect" });
+    }
+    return outcome => {
+        delete context.observeLifecycleHook;
+        if (!anchor)
+            return;
+        const error = outcome.error ? errorRecord(outcome.error) : undefined;
+        const correctable = error && isCorrectableLifecycleRejection(error.code, error.details);
+        const record = { ...anchor, ...(error ? { error } : outcome), effect: error ? error.details.effect ?? (correctable ? "no_effect" : "unknown") : "committed", disposition: error ? auxiliary ? "pending_continuation" : correctable ? "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 [...new Set(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 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 latest?.status === "issued" && (latest.deadline === null || latest.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" && input.harness !== "codex-desktop")
+        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 => typeof session === "string" ? session === input.sessionId : session.adapter_session_id === input.sessionId || session.provider_session_id === input.sessionId);
+    // Codex owns a single root Session per controller and persists that root as
+    // a string. Child agent_id values arrive later through the native hook and
+    // are checked against this root scope; they are not controller Sessions.
+    const rootSessionId = input.harness === "codex-desktop"
+        ? (typeof session === "string" ? session : session?.root_provider_session_id ?? session?.provider_session_id ?? null)
+        : (typeof session === "string" ? null : session?.root_provider_session_id ?? null);
+    if (!state.daemon_id || !rootSessionId)
+        throw new AppError("invocation_scope_unproven", "Managed native Session has no persisted native root binding", 1);
+    const scope = { projectRoot: project.root, daemonId: state.daemon_id, rootSessionId, 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. Execution
+ * can issue a retry; accepted HITL intent can replace an unobserved placeholder
+ * or issue the next pause's assignment after successful settlement. */
+export function managedLifecycleCommand(context, command, options = {}) {
+    const configured = context.env.DD_FLOW_INVOCATION_SCOPE;
+    if (!configured)
+        return command;
+    const scope = JSON.parse(configured);
+    command = canonicalManagedCommand(context, command, scope);
+    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 publicInvocationCommand(context, retained, 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 operation yet. End this Turn and await its next assignment; do not add or reuse an internal invocation ID.", 1);
+        return publicInvocationCommand(context, 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) {
+            const replacesAnswer = options.replaceUnobservedAnswer && parsed.operation === "stage_resume"
+                && (prior.status === "settled" || commandOption(invocation(prior.command), "answer-file") !== commandOption(parsed, "answer-file"));
+            if (!replacesAnswer)
+                return publicInvocationCommand(context, prior, command);
+            // The pause packet can prepare a placeholder before the controller has
+            // accepted an answer. Replace only an unobserved assignment; never change
+            // the authority of a native call already in flight.
+            const completed = prior.status === "settled" && prior.outcome_json && !JSON.parse(prior.outcome_json).error;
+            if (prior.status !== "issued" && !completed)
+                throw new AppError("invocation_answer_conflict", "Cannot replace an answer while its lifecycle assignment is in flight or failed", 1, { invocation_id: prior.id });
+            if (prior.status === "issued")
+                context.db.run("UPDATE lifecycle_invocations SET status = 'expired' WHERE id = ?", [prior.id]);
+        }
+        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 issued = issueLifecycleInvocation(context, command, scope);
+        return publicInvocationCommand(context, load(context, issued.id), 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. Shared by CLI argument
+ * validation and conclusive lifecycle/result rejection, never by hooks. */
+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 command = retainedCommandWithoutInvocationId(prior);
+    return managedLifecycleCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: prior.scope_json, DD_FLOW_CURRENT_INVOCATION: prior.id } }, command);
+}
+// 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: false };
+    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 });
+    }
+    return details;
+}
+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 = isRegisteredRepair(context, details.continuation)
+                ? "The repair is already registered. End this coordinator turn so the controller can launch its fresh child. Use retry_command only after that repair completes, with fresh semantic verification."
+                : "Correct only the evidenced defect, then use retry_command with the required result input. Reissuing the old command only reads its retained outcome.";
+        }
+        else if (isCorrectableLifecycleRejection(error.code, error.details)) {
+            details.effect = "no_effect";
+            details.recoverable = true;
+            details.handoff_required = true;
+            details.recovery_instruction = "Do not retry this command in the current Session. End the coordinator Turn; the controller will launch the already-registered Work in a fresh child Session.";
+        }
+        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] ?? "";
+        try {
+            workId = resolveWorkReference(context, target, { projectId: project.id, runId: scope.runId }).work_id;
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || !["not_found", "ambiguous_work_alias"].includes(error.code))
+                throw error;
+            throw new AppError("invocation_scope_mismatch", "Work does not belong unambiguously to the issued RUN scope", 1);
+        }
+    }
+    else if (parsed.operation.startsWith("merge_")) {
+        const request = context.db.get("SELECT project_id, run_id FROM merge_requests WHERE merge_request_id = ?", [parsed.args.positional[0] ?? ""]);
+        if (!request || request.project_id !== project.id || request.run_id !== scope.runId)
+            throw new AppError("invocation_scope_mismatch", "MERGE request does not belong to the issued RUN scope", 1);
+    }
+    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 prepareLifecycleIssuance(command, value) {
+    if (typeof command !== "string" || !command.trim() || !value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("invocation_scope_invalid", "Lifecycle issuance requires command and managed scope", 1);
+    }
+    const scope = value;
+    const parsed = invocation(command);
+    if (typeof scope.daemonId !== "string" || !scope.daemonId.trim() || typeof scope.rootSessionId !== "string" || !scope.rootSessionId.trim() || !Number.isSafeInteger(scope.generation) || scope.generation < 0
+        || (scope.runId !== null && (typeof scope.runId !== "string" || !scope.runId.trim()))
+        || typeof scope.projectRoot !== "string" || !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);
+    }
+    return { command, scope, parsed };
+}
+export function issueLifecycleInvocation(context, command, scope) {
+    const { parsed } = prepareLifecycleIssuance(command, scope);
+    storage(context);
+    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) {
+    storage(context);
+    const supplied = input.id ? context.db.get("SELECT * FROM lifecycle_invocations WHERE id = ?", [input.id]) : undefined;
+    const analysis = parseLifecycleCommand(input.command);
+    if (analysis.kind !== "standalone" || analysis.invocation.wrapped) {
+        const eventKey = input.recordReceipt();
+        if (analysis.kind !== "none") {
+            const retained = context.db.get("SELECT outcome_json FROM hook_events WHERE event_key = ?", [eventKey]);
+            let outcome = {};
+            try {
+                outcome = retained?.outcome_json ? JSON.parse(retained.outcome_json) : {};
+            }
+            catch {
+                outcome = {};
+            }
+            context.db.run("UPDATE hook_events SET outcome_json = ? WHERE event_key = ?", [JSON.stringify({
+                    ...outcome,
+                    lifecycle_observation: {
+                        code: "lifecycle_shell_syntax_invalid",
+                        reason: analysis.kind === "compound" ? analysis.reason : "wrapped_lifecycle_command",
+                        command_fingerprint: fingerprint(analysis.invocation),
+                        effect: "no_effect",
+                        recoverable: true
+                    }
+                }), eventKey]);
+        }
+        return { eventKey, duplicate: false, invocationId: null };
+    }
+    const candidates = context.db.all("SELECT * FROM lifecycle_invocations WHERE status IN ('issued','observed') ORDER BY rowid DESC")
+        .filter(row => {
+        const scope = JSON.parse(row.scope_json);
+        if (scope.daemonId !== input.identity.daemonId || scope.rootSessionId !== input.identity.rootSessionId)
+            return false;
+        try {
+            return fingerprint(invocation(canonicalManagedCommand(context, input.command, scope))) === row.fingerprint;
+        }
+        catch {
+            return false;
+        }
+    });
+    // A known explicit ID remains a compatibility path. A missing or mistyped
+    // public ID is corrected only by an exact operation/target match inside the
+    // trusted native root. Never fuzzy-match UUID text or select a global latest.
+    const initial = supplied ?? (candidates.length === 1 ? candidates[0] : undefined);
+    if (!initial) {
+        const eventKey = input.recordReceipt();
+        if (candidates.length > 1)
+            throw new AppError("invocation_ambiguous", "More than one issued lifecycle attempt matches this native command", 1, { effect: "no_effect", matches: candidates.map(row => row.id) });
+        return { eventKey, duplicate: false, invocationId: null };
+    }
+    const resolved = input.id === initial.id ? {} : { invocationId: initial.id };
+    // 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, ...resolved };
+    const scope = JSON.parse(initial.scope_json);
+    const project = requireProjectByRoot(context, scope.projectRoot);
+    const identity = input.identity;
+    checkNativeIdentity(scope, identity, initial.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 = ?", [initial.id]);
+        if (row.status === "settled") {
+            context.db.exec("COMMIT");
+            return { eventKey: row.event_key, duplicate: true, ...resolved };
+        }
+        // Observation records native facts only. CLI owns deadline, argument and
+        // RUN-state validation, including decisions about retrying an invocation.
+        if (row.status === "expired" || (row.deadline !== null && row.deadline <= Date.now() && !row.event_key)) {
+            context.db.exec("COMMIT");
+            return { eventKey: row.event_key, duplicate: true, ...resolved };
+        }
+        if (row.identity_json === identityJson) {
+            context.db.exec("COMMIT");
+            return { eventKey: row.event_key, duplicate: true, ...resolved };
+        }
+        const eventKey = input.recordReceipt({ projectRoot: scope.projectRoot, runId: scope.runId, command: initial.command });
+        // A native hook may execute from a provider worktree while the issued
+        // lifecycle scope is anchored to the stable project root. Project
+        // identity is the canonical boundary; comparing raw cwd would reject a
+        // valid receipt before the CLI can run (Codex does this in particular).
+        const receipt = eventKey && context.db.get("SELECT provider_session_id, daemon_id, status, harness FROM hook_events WHERE event_key = ? AND harness = ? AND project_id = ?", [eventKey, input.harness ?? "zcode-acp", project.id]);
+        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);
+        }
+        // The hook observes intent; it does not own execution. A native shell may
+        // reject a tool call before the CLI process exists (for example because
+        // its workdir is invalid), after which repeating the same issued command
+        // is safe. Keep the newest receipt until the CLI claims the attempt. The
+        // observed -> executing compare-and-swap remains the exactly-once boundary.
+        const updated = context.db.run("UPDATE lifecycle_invocations SET identity_json = ?, event_key = ?, status = 'observed', updated_at = ? WHERE id = ? AND status IN ('issued', 'observed')", [identityJson, eventKey, context.now(), initial.id]);
+        context.db.exec("COMMIT");
+        // Once execution has been claimed, later PreToolUse observations are
+        // retained as hook evidence but cannot replace the executor's receipt.
+        return { eventKey: updated.changes === 1 ? eventKey : row.event_key, duplicate: updated.changes !== 1, ...resolved };
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+}
+/** Correlate exact native argv for diagnostics, independently of assignment
+ * matching. A hook-added event key must name the same persisted native call. */
+export function observedLifecycleNativeEvent(context, command, daemonId) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE name = 'hook_events'"))
+        return null;
+    const signature = (value) => {
+        const parsed = parseLifecycleCommand(value);
+        const candidate = parsed.kind === "standalone" && !parsed.invocation.wrapped ? parsed.invocation : continuationCommand(value);
+        if (!candidate)
+            return null;
+        return JSON.stringify([candidate.operation, candidate.args.positional,
+            [...candidate.args.options].filter(([key]) => !["json", "progress-jsonl", "hook-event-id"].includes(key)).sort(([a], [b]) => a.localeCompare(b))]);
+    };
+    const expected = signature(command);
+    if (!expected)
+        return null;
+    const parsed = parseLifecycleCommand(command);
+    const eventKey = parsed.kind === "standalone" ? commandOption(parsed.invocation, "hook-event-id") : undefined;
+    const matches = context.db.all("SELECT project_id, id, event_key, sanitized_summary FROM hook_events WHERE daemon_id = ? AND status = 'observed' AND outcome_json IS NULL", [daemonId]).filter(row => {
+        if (eventKey && row.event_key !== eventKey)
+            return false;
+        try {
+            const observed = lifecycleCommandFromPayload(JSON.parse(row.sanitized_summary));
+            return typeof observed === "string" && signature(observed) === expected;
+        }
+        catch {
+            return false;
+        }
+    });
+    // Diagnostic correlation only: never use this as execution authority, and
+    // never choose the latest of several identical native calls.
+    return matches.length === 1 ? { project_id: matches[0].project_id, id: matches[0].id } : null;
+}
+/** Keep shell diagnostics distinct from genuinely absent native delivery. */
+export function observedLifecycleDiagnostic(context, command, daemonId) {
+    const analysis = parseLifecycleCommand(command);
+    if (analysis.kind !== "standalone")
+        return null;
+    const commandFingerprint = fingerprint(analysis.invocation);
+    const rows = context.db.all("SELECT event_key, outcome_json FROM hook_events WHERE daemon_id = ? AND status = 'observed' AND outcome_json IS NOT NULL ORDER BY id DESC LIMIT 20", [daemonId]).flatMap(row => {
+        try {
+            const outcome = JSON.parse(row.outcome_json);
+            return outcome.lifecycle_observation?.command_fingerprint === commandFingerprint ? [{ ...outcome.lifecycle_observation, event_key: row.event_key }] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    if (!rows.length)
+        return null;
+    const reasons = new Set(rows.map(row => `${String(row.code)}\0${String(row.reason)}`));
+    if (reasons.size !== 1)
+        return null;
+    return { ...rows[0], matching_events: rows.map(row => row.event_key) };
+}
+/** Resolve only a command that a native hook has already bound to an issued
+ * attempt. This is the CLI-side half of admission for model-facing commands
+ * that intentionally omit the internal UUID. */
+export function observedLifecycleInvocation(context, command, daemonId) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'"))
+        return null;
+    const analysis = parseLifecycleCommand(command);
+    if (analysis.kind !== "standalone" || analysis.invocation.wrapped)
+        return null;
+    const matches = context.db.all("SELECT * FROM lifecycle_invocations WHERE status IN ('observed','executing') ORDER BY rowid DESC")
+        .filter(row => {
+        try {
+            const scope = JSON.parse(row.scope_json);
+            if (daemonId && scope.daemonId !== daemonId)
+                return false;
+            return fingerprint(invocation(canonicalManagedCommand(context, command, scope))) === row.fingerprint;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!matches.length)
+        return null;
+    if (matches.length !== 1)
+        throw new AppError("invocation_ambiguous", "More than one observed lifecycle attempt matches this command", 1, { effect: "no_effect", matches: matches.map(row => row.id) });
+    return { id: matches[0].id, scope: JSON.parse(matches[0].scope_json) };
+}
+/** Replace presentation argv with the exact retained machine assignment.
+ * Public semantic arguments are already covered by the projected fingerprint;
+ * any explicitly repeated private value must agree instead of being ignored. */
+export function resolveObservedLifecycleArgs(context, id, actualArgs) {
+    const row = context.db.get("SELECT * FROM lifecycle_invocations WHERE id = ?", [id]);
+    if (!row)
+        throw new AppError("invocation_unknown", "Lifecycle invocation is not registered", 1, { invocation_id: id });
+    const retained = invocation(row.command), actual = invocation(`${quote([retained.executable])} ${quoteModelFacingArgs(actualArgs)}`);
+    if (fingerprint(actual) !== row.fingerprint)
+        throw new AppError("invocation_command_mismatch", "Lifecycle command does not match its issued assignment", 2, { phase: "prepare", effect: "no_effect", recoverable: true });
+    for (const key of runtimeOwnedOptions[retained.operation] ?? []) {
+        const supplied = commandOption(actual, key), expected = commandOption(retained, key);
+        if (supplied !== undefined && normalizedInvocationValue(key, supplied) !== normalizedInvocationValue(key, expected ?? "")) {
+            throw new AppError("invocation_argument_mismatch", `--${key} is owned by the managed assignment and does not match it`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: key });
+        }
+    }
+    return [...retained.argv];
+}
+export function settleLifecyclePreparationRejection(context, id, error) {
+    return context.db.writeTransaction(() => {
+        const row = load(context, id);
+        if (row.status === "settled") {
+            const details = row.outcome_json ? JSON.parse(row.outcome_json)?.error?.details : undefined;
+            return details?.effect === "no_effect" && details.retry_command ? details : { effect: "unknown", recoverable: false };
+        }
+        if (!["issued", "observed"].includes(row.status))
+            return { effect: "unknown", recoverable: false };
+        const scope = JSON.parse(row.scope_json);
+        if (scope.runId)
+            assertLifecycleInvocationCurrent(context, scope, row.command);
+        const signature = preparationRejectionSignature(error);
+        const repeated = context.db.all("SELECT outcome_json FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? AND id <> ? AND status = 'settled'", [row.scope_json, row.fingerprint, row.id])
+            .some(prior => { try {
+            return JSON.parse(prior.outcome_json ?? "null")?.error?.details?.rejection_signature === signature;
+        }
+        catch {
+            return false;
+        } });
+        const retryable = !repeated && isRetryableLifecycleRejection(error.code, error.details);
+        const details = { ...error.details, effect: "no_effect", recoverable: retryable, rejection_signature: signature,
+            ...(repeated ? { repeated_without_progress: true } : {}),
+            ...(retryable ? {
+                retry_command: successorLifecycleInvocationCommand(context, row),
+                retry_instruction: "Correct the reported input, then execute retry_command verbatim in this same Session. The rejected call changed no lifecycle state."
+            } : {}) };
+        context.db.run("UPDATE lifecycle_invocations SET status = 'settled', outcome_json = ?, updated_at = ? WHERE id = ?", [JSON.stringify({ error: { ...errorRecord(error), details } }), context.now(), row.id]);
+        return details;
+    });
+}
+function preparationRejectionSignature(error) {
+    const omitted = new Set(["retry_command", "retry_instruction", "invocation_id", "hook_event_id", "rejection_signature"]);
+    const normalize = (value) => {
+        if (Array.isArray(value))
+            return value.map(normalize);
+        if (!value || typeof value !== "object")
+            return value;
+        return Object.fromEntries(Object.entries(value).filter(([key]) => !omitted.has(key)).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, normalize(item)]));
+    };
+    return crypto.createHash("sha256").update(JSON.stringify([error.code, normalize(error.details)])).digest("hex");
+}
+export function currentLifecycleFailure(context, input) {
+    const attempts = context.db.all("SELECT * FROM lifecycle_invocations ORDER BY updated_at DESC, rowid DESC");
+    const scoped = attempts.filter(row => {
+        try {
+            const scope = JSON.parse(row.scope_json);
+            return scope.runId === input.runId && scope.generation === input.generation;
+        }
+        catch {
+            return false;
+        }
+    });
+    const fingerprints = [...new Set(scoped.map(row => row.fingerprint))];
+    for (const fingerprint of fingerprints) {
+        const rows = scoped.filter(row => row.fingerprint === fingerprint);
+        if (rows.some(row => ["issued", "observed", "executing"].includes(row.status)))
+            continue;
+        const row = rows.find(candidate => candidate.status === "settled");
+        if (!row)
+            continue;
+        let outcome;
+        try {
+            outcome = JSON.parse(row.outcome_json ?? "null") ?? {};
+        }
+        catch {
+            continue;
+        }
+        if (!outcome.error?.code || !outcome.error.message)
+            continue;
+        let parsed;
+        try {
+            parsed = invocation(row.command);
+        }
+        catch {
+            continue;
+        }
+        const stage = parsed.operation.startsWith("merge_") ? "merge" : commandOption(parsed, "stage");
+        if (stage !== input.stage)
+            continue;
+        return { code: outcome.error.code, message: outcome.error.message, details: outcome.error.details ?? {}, invocation_id: row.id };
+    }
+    return null;
+}
+/** 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);
+    try {
+        if (initial.status === "settled") {
+            checkCommand(initial, input.command);
+            return { outcome: JSON.parse(initial.outcome_json), replay: true };
+        }
+        input.validateArgs?.();
+        checkCommand(initial, input.command);
+        // A terminal command is immutable evidence.  Do not require a now-gone
+        // caller payload merely to replay its recorded result.
+        if (["issued", "observed"].includes(initial.status))
+            await input.prepare?.();
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || !(["usage", "invocation_command_mismatch", "invocation_command_invalid"].includes(error.code) || error.details.phase === "prepare"))
+            throw error;
+        Object.assign(error.details, settleLifecyclePreparationRejection(context, input.id, error));
+        throw error;
+    }
+    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 });
+    }
+}