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

package/dist/services/lifecycle-invocations.js

@@ -13,25 +13,38 @@ 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 { assertPathWithin } from "../storage/paths.js";
+import { contextualPathOptionsForLifecycle } from "../cli/command-inputs.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")
+    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;
-    return details.recoverable === true || ["validation", "schema_validation", "work_checks_failed", "code_gate_failed", "code_review_gate_failed", "merge_gate_failed",
+    if (code === "validation" || code === "schema_validation")
+        return details.phase === "prepare" && details.effect === "no_effect" && details.recoverable === true;
+    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) {
-    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
-  )`);
+    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);
@@ -44,17 +57,101 @@ function invocation(command) {
 // 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])
+        .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, parsed.args.positional, options])).digest("hex");
+    return crypto.createHash("sha256").update(JSON.stringify([parsed.operation, parsed.args.positional.map(value => normalizedInvocationValue("positional", value)), options])).digest("hex");
+}
+function normalizedInvocationValue(key, 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}`;
+    }
+    const entity = /^(PRJ|RUN|WRK)-\d{3,}(?:-|$)/.exec(value)?.[0]?.replace(/-$/, "");
+    if (entity)
+        return entity;
+    return /(?:^|\/)(RCP-\d{3,})$/.exec(value)?.[1] ?? value;
+}
+function withoutInvocationId(command, aliases) {
+    const parsed = invocation(command);
+    const argv = [...parsed.argv];
+    const at = argv.indexOf("--invocation-id");
+    if (at >= 0)
+        argv.splice(at, 2);
+    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 && 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 ? ` ${quote(argv)}` : ""}${suffix ? ` ${suffix}` : ""}`.trim();
+}
+function publicInvocationCommand(context, row, command) {
+    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 } : {}) });
+}
+/** 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 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;
+        const option = args[index - 1]?.replace(/^--/, "");
+        if (!option || !pathOptions.has(option) || !value.startsWith("@"))
+            return value;
+        const match = /^@(project|workspace|run)(?:\/(.*))?$/.exec(value);
+        if (!match)
+            throw new AppError("usage", `Unknown path alias: ${value}`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+        const root = roots[match[1]];
+        if (!root)
+            throw new AppError("usage", `Path alias @${match[1]} is unavailable without a bound RUN`, 2, { phase: "prepare", effect: "no_effect", recoverable: true, parameter: option });
+        return assertPathWithin(root, path.join(root, match[2] ?? ""), `${match[1]}_alias`);
+    });
+}
+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 attempts", 1, { invocation_id: id });
+        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", 1, { invocation_id: id });
+        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) {
@@ -96,7 +193,7 @@ export function assertLifecycleOutcomes(context, scope) {
     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))
+        if (typeof error?.code === "string" && !isCorrectableLifecycleRejection(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 });
     }
 }
@@ -171,14 +268,16 @@ export function observeLifecycleCommand(context, command) {
             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 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" };
+        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 ? 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]);
@@ -226,35 +325,40 @@ 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 [...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 [];
-            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")
+    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 => 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 };
+    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 };
 }
@@ -265,6 +369,7 @@ export function managedLifecycleCommand(context, command) {
     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,
@@ -277,24 +382,25 @@ export function managedLifecycleCommand(context, command) {
         }
         checkCommand(retained, command);
         assertRenderableInvocation(retained);
-        return command;
+        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 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);
+            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) {
-            return renderInvocationCommand(prior, command);
+            return publicInvocationCommand(context, 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;
+        const issued = issueLifecycleInvocation(context, command, scope);
+        return publicInvocationCommand(context, load(context, issued.id), command);
     });
 }
 export function retryLifecycleInvocationCommand(context, id) {
@@ -304,8 +410,8 @@ export function retryLifecycleInvocationCommand(context, id) {
     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. */
+ * 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];
@@ -322,44 +428,17 @@ function successorLifecycleInvocationCommand(context, prior) {
     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." };
+    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.
@@ -383,6 +462,12 @@ export function settleLifecycleRejection(context, id, error) {
                 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.";
         }
+        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);
@@ -477,14 +562,23 @@ function checkCommand(row, command) {
 }
 /** 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);
+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 (!scope.daemonId || !scope.rootSessionId || !Number.isInteger(scope.generation) || scope.generation < 0
-        || !path.isAbsolute(scope.projectRoot) || commandOption(parsed, "project-root") !== scope.projectRoot
+    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.
@@ -527,56 +621,153 @@ function checkNativeIdentity(scope, identity, id) {
     }
 }
 export function observeLifecycleInvocation(context, input) {
-    const initial = load(context, input.id);
-    checkCommand(initial, input.command);
+    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)
+        return { eventKey: input.recordReceipt(), 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 };
+        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, input.id);
+    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 = ?", [input.id]);
+        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 };
+            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)) {
-            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 };
+            return { eventKey: row.event_key, duplicate: true, ...resolved };
         }
-        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 });
+        if (row.identity_json === identityJson) {
             context.db.exec("COMMIT");
-            return { eventKey: row.event_key, duplicate: true };
+            return { eventKey: row.event_key, duplicate: true, ...resolved };
         }
-        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]);
+        const eventKey = input.recordReceipt(scope);
+        // 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);
         }
-        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]);
+        // 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");
-        return { eventKey, duplicate: false };
+        // 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;
     }
 }
+/** 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) {
+    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);
+            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) };
+}
 /** 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);
+    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;
+        const rejectionDetails = context.db.writeTransaction(() => {
+            const row = load(context, input.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);
+            // No executor has claimed this attempt. Atomically retain the rejected
+            // call and issue one corrected command; old IDs only replay the outcome.
+            const details = { ...error.details, effect: "no_effect", recoverable: true,
+                retry_command: successorLifecycleInvocationCommand(context, row),
+                retry_instruction: "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;
+        });
+        Object.assign(error.details, rejectionDetails);
+        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);