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

package/dist/services/cli-operation-classifier.js

@@ -104,6 +104,8 @@ function isRouterNative(args) {
     if (first === "storage" && args[1] === "migrate-writer")
         return true;
     return (first === "codex" && args[1] === "hook" && args[2] === "handle")
+        || (first === "zcode" && args[1] === "hook" && args[2] === "handle")
+        || (first === "zcode" && args[1] === "invocation" && args[2] === "prepare")
         || (first === "zcode" && args[1] === "event" && args[2] === "handle")
         || (first === "zcode" && args[1] === "usage" && args[2] === "ingest")
         || (first === "grok" && args[1] === "event" && args[2] === "handle")
@@ -129,7 +131,11 @@ function isReadOnlyDiagnostic(family, command, action) {
     if (family === "plan")
         return command === "status";
     if (family === "run")
-        return command === "status" || command === "list" || (["drive", "control"].includes(command ?? "") && action === "status");
+        return command === "status" || command === "list" || (command === "recovery" && action === "inspect") || (["drive", "control"].includes(command ?? "") && action === "status");
+    if (family === "work")
+        return ["status", "ls", "show"].includes(command ?? "");
+    if (family === "stage")
+        return command === "fanout" && action === "status";
     if (family === "lane") {
         return (command === "status" ||
             command === "waiters" ||

package/dist/services/eval-snapshots.js

@@ -391,7 +391,7 @@ function detachSnapshotRuntimeOwners(context, snapshot, manifest) {
         throw new AppError("snapshot_control_requires_recovery", "A fenced RUN requires explicit recovery, not a stage-entry fork", 1);
     if (context.db.get("SELECT 1 FROM merge_requests WHERE status IN ('dispatching','active','waiting_user','action_required','recovery_required') LIMIT 1"))
         throw new AppError("snapshot_execution_active", "A stage-entry fork cannot discard an unresolved MERGE execution", 1);
-    const detachedTables = ["run_control_admissions", "run_control_stage_admissions", "run_control_operations", "run_control_workers", "run_controls", "run_controller_events", "run_controller_operations", "run_controllers", "run_recovery_bindings", "work_recovery_segments", "run_recovery_guards", "work_launches", "merge_servers", "merge_sessions", "lane_locks", "lane_waiters"].filter(hasTable);
+    const detachedTables = ["lifecycle_invocations", "run_control_admissions", "run_control_stage_admissions", "run_control_operations", "run_control_workers", "run_controls", "run_controller_events", "run_controller_operations", "run_controllers", "run_recovery_bindings", "work_recovery_segments", "run_recovery_guards", "work_launches", "merge_servers", "merge_sessions", "lane_locks", "lane_waiters"].filter(hasTable);
     const runTables = Object.fromEntries([...detachedTables, "runs", "merge_requests", "sessions", "work_sessions"].map(table => [table, context.db.all(`SELECT * FROM ${table}`)]));
     const resourceFile = path.join(context.ddFlowHome, "runtime.sqlite");
     const resources = fs.existsSync(resourceFile) ? new DatabaseSync(resourceFile) : null;

package/dist/services/external-work-launch.js

@@ -10,6 +10,7 @@ import { resolveExecutionPolicy, runtimeHarness, validateExecutionOverride } fro
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { assertWorkLaunchReady, workStartCommand } from "./work-registry.js";
 import { initCodexHome } from "./hooks.js";
+import { managedInvocationContext } from "./lifecycle-invocations.js";
 /**
  * Creates an external provider root for one already-created Work.  The launch
  * is not a Work claim: only the worker's trusted `work start` hook binds it.
@@ -48,7 +49,7 @@ export async function launchExternalWork(context, input) {
     fs.mkdirSync(root, { recursive: true });
     const now = context.now();
     const flowExecutable = prepareHarnessFlowExecutable(context, root);
-    const env = { ...context.env, DD_FLOW_BIN: flowExecutable };
+    const env = { ...context.env, DD_FLOW_BIN: flowExecutable, DD_FLOW_INVOCATION_SCOPE: undefined, DD_FLOW_CURRENT_INVOCATION: undefined };
     // An external Codex root is a fresh thread, so it does not inherit the
     // coordinator's managed PreToolUse hook.  Its first `work start` must emit
     // that hook event to bind the Work to the physical session.
@@ -57,7 +58,7 @@ export async function launchExternalWork(context, input) {
         initCodexHome(context, { projectRoot: run.project_root, profile: `external-${operationId}`, targetHome: codexHome, ...(context.env.CODEX_HOME ? { sourceHome: context.env.CODEX_HOME } : {}) });
         env.CODEX_HOME = codexHome;
     }
-    const runtimeContext = { ...context, env };
+    let runtimeContext = { ...context, env };
     const runtimeOwner = { schema_id: "dd-flow/runtime-owner@1", owner_id: `run:${work.run_id}:work:${work.work_id}`, role: "worker", project_id: work.project_id, run_id: work.run_id, work_id: work.work_id, operation_id: operationId, state_dir: root, dd_flow_home: context.ddFlowHome, dd_flow_bin: flowExecutable, resource_home: context.env.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome, budget: runtimeBudgetForRun(context, work.project_id, work.run_id) };
     const executable = resolveHarnessCommand(context.ddFlowHome, runtimeHarness(resolved.worker), "adapter");
     context.db.run("INSERT INTO work_launches (operation_id, work_id, profile_json, profile_hash, status, state_dir, journal_path, provider_session_id, adapter_receipt_json, created_at, updated_at) VALUES (?, ?, ?, ?, 'launching', ?, ?, NULL, NULL, ?, ?)", [operationId, work.work_id, JSON.stringify({ ...resolved, runtime_adapter: { executable, owner: runtimeOwner } }), resolved.profile_hash, root, journal, now, now]);
@@ -73,6 +74,8 @@ export async function launchExternalWork(context, input) {
             throw new AppError("harness_adapter_invalid", "Harness adapter did not return a typed Session id", 1, { work_id: work.work_id, harness: runtimeHarness(resolved.worker) });
         // Retain the physical root before any subsequent guard or prompt can fail.
         context.db.run("UPDATE work_launches SET provider_session_id = ?, adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [sessionId, JSON.stringify({ create: created }), context.now(), operationId]);
+        runtimeContext = managedInvocationContext(runtimeContext, { harness: runtimeHarness(resolved.worker), stateDir: root, sessionId,
+            projectRoot: run.project_root, runId: work.run_id, generation });
         assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
         assertWorkLaunchReady(context, work.work_id);
         const promptFile = path.join(root, "launch.md");

package/dist/services/hooks.js

@@ -9,7 +9,8 @@ import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { nativeSessionIdentity, storageSessionId } from "./session-identity.js";
 import { assertRecoveryHookCurrent } from "./run-recovery.js";
-import { commandHasOption, commandOption, commandPosition, parseLifecycleCommand, unwrapShellCommand } from "./lifecycle-command.js";
+import { observeLifecycleInvocation } from "./lifecycle-invocations.js";
+import { commandHasOption, commandOption, commandPosition, shellSuffixOffset, parseLifecycleCommand, unwrapShellCommand } from "./lifecycle-command.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { activeFlowSessionsForProject, bindObservedFlowSession, flowSessionPayloadFromRegisterCommand, recordFlowSessionObservation } from "./sessions.js";
 const defaultProfileName = "default";
@@ -286,7 +287,7 @@ export function handleCodexHook(context, input) {
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
     // Resume legitimately receives an answer through stdin. It is matched by
     // immutable lifecycle arguments below; never reject or rewrite that pipe.
-    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
+    if (lifecycle.analysis.kind === "compound") {
         return {
             ok: false,
             observed: false,
@@ -409,118 +410,112 @@ function codexNativeParentId(payload, childId) {
         return null;
     }
 }
-/** Convert a zcode-acp Bash tool notification into the same trusted lifecycle receipt used by Codex hooks. */
+/** ACP is asynchronous evidence. Only an explicitly issued invocation may use
+ * it as the receipt that its CLI waits for; this is not a PreToolUse hook. */
 export function handleZcodeEvent(context, input) {
     const notification = parseJsonObject(input.stdin || "{}", "zcode ACP notification");
-    if (notification.method !== "session/update")
+    const params = objectRecord(notification.params), update = objectRecord(params.update);
+    if (notification.method !== "session/update" || update.sessionUpdate !== "tool_call")
         return { ok: true, observed: false, reason: "event_not_participating" };
-    const params = objectRecord(notification.params);
-    const update = objectRecord(params.update);
-    if (update.sessionUpdate !== "tool_call")
-        return { ok: true, observed: false, reason: "event_not_participating" };
-    const updateMeta = objectRecord(update._meta);
-    const claudeCode = objectRecord(updateMeta.claudeCode);
-    const runtime = objectRecord(updateMeta.zcodeRuntime);
-    const toolName = stringValue(claudeCode.toolName) ?? stringValue(update.kind);
-    const rawInput = objectRecord(update.rawInput);
+    const rawInput = objectRecord(update.rawInput), meta = objectRecord(update._meta), native = objectRecord(meta.zcodeRuntime);
+    const toolName = stringValue(objectRecord(meta.claudeCode).toolName);
+    if (toolName !== "Bash" && toolName !== "bash" && toolName !== "execute")
+        return { ok: true, observed: false, reason: "non_bash_tool" };
     const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd);
-    if (!command || (toolName && toolName !== "Bash" && toolName !== "bash" && update.kind !== "execute")) {
+    const parsed = command ? parseLifecycleCommand(command) : { kind: "none" };
+    if (parsed.kind === "none" || !commandOption(parsed.invocation, "invocation-id"))
+        return { ok: true, observed: false, reason: "acp_evidence_only" };
+    const controlled = objectRecord(objectRecord(notification._meta).ddZcode);
+    const providerSessionId = stringValue(native.childSessionId) ?? stringValue(controlled.rootProviderSessionId);
+    return recordZcodeLifecycle(context, { projectRoot: input.projectRoot, stdin: JSON.stringify({
+            session_id: providerSessionId, tool_use_id: update.toolCallId, tool_name: toolName, tool_input: rawInput,
+            agent_id: native.agentId, _meta: { ddZcode: controlled }
+        }) }, commandOption(parsed.invocation, "invocation-id"));
+}
+/**
+ * Accept the synchronous native ZCode PreToolUse callback.  ACP notifications
+ * are retained as evidence, but cannot be an admission signal: they arrive
+ * after the tool call and may be serialized behind unrelated work.
+ */
+export function handleZcodeHook(context, input) {
+    return recordZcodeLifecycle(context, input);
+}
+function recordZcodeLifecycle(context, input, invocationId) {
+    const hook = parseJsonObject(input.stdin || "{}", "ZCode hook event");
+    const eventName = stringValue(hook.hook_event_name) ?? stringValue(hook.hookEventName);
+    if (eventName && eventName !== "PreToolUse" && eventName !== "pre_tool_use")
+        return { ok: true, observed: false, reason: "event_not_participating" };
+    const toolName = stringValue(hook.tool_name) ?? stringValue(hook.toolName);
+    const rawInput = objectRecord(hook.tool_input ?? hook.toolInput);
+    const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd) ?? stringValue(hook.command);
+    if (!command || (toolName && toolName !== "Bash" && toolName !== "bash" && toolName !== "execute"))
         return { ok: true, observed: false, reason: "non_bash_tool" };
-    }
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
-        throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", 1, {
-            standalone_command: lifecycle.invocation.command
-        });
+    if (!invocationId && commandOption(lifecycle.invocation, "invocation-id"))
+        return { ok: true, observed: false, reason: "cli_invocation_owns_admission" };
+    if (lifecycle.analysis.kind === "compound") {
+        throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", 1, { standalone_command: lifecycle.invocation.command });
     }
-    const { flowPayload, bootstrapStageStart, commandProjectRoot } = lifecycle;
     const expectedRoot = resolveProjectRoot(input.projectRoot);
-    if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
-        throw new AppError("project_mismatch", "ZCode lifecycle command project root does not match the controlled workspace", 1, {
-            expected: expectedRoot,
-            actual: commandProjectRoot
-        });
+    if (lifecycle.commandProjectRoot && resolveProjectRoot(lifecycle.commandProjectRoot) !== expectedRoot) {
+        throw new AppError("project_mismatch", "ZCode lifecycle command project root does not match the controlled workspace", 1, { expected: expectedRoot, actual: lifecycle.commandProjectRoot });
     }
-    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
-    if (bootstrapStageStart)
+    const meta = objectRecord(hook._meta);
+    const ddZcode = objectRecord(meta.ddZcode);
+    const providerSessionId = stringValue(hook.session_id) ?? stringValue(hook.sessionId);
+    const rootProviderSessionId = stringValue(ddZcode.rootProviderSessionId);
+    const parentProviderSessionId = stringValue(ddZcode.parentProviderSessionId);
+    const daemonId = stringValue(ddZcode.daemonId);
+    if (!providerSessionId || !rootProviderSessionId || !daemonId) {
+        throw new AppError("zcode_identity_missing", "ZCode native hook has no controlled Session identity", 1);
+    }
+    if (providerSessionId === rootProviderSessionId ? parentProviderSessionId : !parentProviderSessionId) {
+        throw new AppError("zcode_identity_missing", "ZCode native hook has inconsistent Session ancestry", 1);
+    }
+    const toolUseId = stringValue(hook.tool_use_id) ?? stringValue(hook.toolUseId) ?? stringValue(hook.event_id) ?? stringValue(hook.eventId);
+    if (!toolUseId)
+        throw new AppError("zcode_hook_event_missing", "ZCode native hook has no tool-use ID", 1);
+    const eventKey = crypto.createHash("sha256").update(JSON.stringify(["zcode-acp", daemonId, providerSessionId, toolUseId])).digest("hex");
+    const rewritten = invocationId ? command : commandWithHookEvent(command, eventKey);
+    if (!invocationId && rewritten === command && commandOption(lifecycle.invocation, "hook-event-id") !== eventKey)
+        throw new AppError("zcode_hook_rewrite_unsupported", "ZCode requires a direct lifecycle command whose exact receipt can be delivered", 1);
+    if (lifecycle.bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
-    const envelopeMeta = objectRecord(notification._meta);
-    const ddZcode = objectRecord(envelopeMeta.ddZcode);
-    const observedProfile = objectRecord(ddZcode.observedProfile);
-    const rootProviderSessionId = stringValue(ddZcode.rootProviderSessionId) ?? stringValue(params.sessionId);
-    const daemonId = stringValue(ddZcode.daemonId);
-    if (!rootProviderSessionId)
-        throw new AppError("zcode_identity_missing", "ZCode ACP event has no root provider Session ID", 1);
-    const childProviderSessionId = stringValue(runtime.childSessionId);
-    const providerSessionId = childProviderSessionId ?? rootProviderSessionId;
     const sessionId = storageSessionId(nativeSessionIdentity("zcode-acp", providerSessionId));
-    const parentSessionId = childProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", rootProviderSessionId)) : null;
-    const agentId = stringValue(runtime.agentId);
-    const eventKey = stringValue(update.toolCallId) ?? crypto.createHash("sha256").update(JSON.stringify({
-        harness: "zcode-acp", providerSessionId, command
-    })).digest("hex");
-    assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "zcode-acp", providerSessionId, parentSessionId, daemonId: daemonId ?? null, sessionId, turnId: null, eventName: "PreToolUse", toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
-    const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
-        ...flowPayload,
-        harness: "zcode-acp",
-        provider_session_id: providerSessionId,
-        agent_id: agentId ?? null,
-        parent_session_id: parentSessionId
-    }, sessionId) : undefined;
-    const payload = {
-        session_id: providerSessionId,
-        agent_id: agentId,
-        cwd: expectedRoot,
-        tool_name: toolName ?? "Bash",
-        tool_input: rawInput,
-        command,
-        provider: stringValue(observedProfile.provider),
-        model: stringValue(observedProfile.model),
-        reasoning: stringValue(observedProfile.reasoning),
-        mode: stringValue(observedProfile.mode),
-        agent_type: stringValue(runtime.source)
+    const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", parentProviderSessionId)) : null;
+    const observedProfile = objectRecord(ddZcode.observedProfile);
+    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
+    const eventNameForReceipt = invocationId ? "ToolCallObserved" : "PreToolUse";
+    const persist = () => {
+        assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "zcode-acp", providerSessionId, parentSessionId, daemonId, sessionId, turnId: null, eventName: eventNameForReceipt, toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
+        const observedSession = lifecycle.flowPayload ? bindObservedFlowSession(context, project, {
+            ...lifecycle.flowPayload, harness: "zcode-acp", provider_session_id: providerSessionId,
+            parent_session_id: parentSessionId, provider: stringValue(observedProfile.provider) ?? null,
+            model: stringValue(observedProfile.model) ?? null, reasoning: stringValue(observedProfile.reasoning) ?? null,
+            mode: stringValue(observedProfile.mode) ?? null, agent_id: stringValue(hook.agent_id) ?? stringValue(hook.agentId) ?? null
+        }, sessionId) : undefined;
+        const payload = { ...hook, session_id: providerSessionId, cwd: expectedRoot, tool_name: toolName ?? "Bash", tool_input: rawInput,
+            command, provider: stringValue(observedProfile.provider), model: stringValue(observedProfile.model), reasoning: stringValue(observedProfile.reasoning), mode: stringValue(observedProfile.mode) };
+        const inserted = recordHookEvent(context, {
+            projectId: project.id, protocolId: observedSession?.protocol_id ?? null, harness: "zcode-acp", providerSessionId, parentSessionId,
+            daemonId, sessionId, agentId: stringValue(hook.agent_id) ?? stringValue(hook.agentId) ?? null, turnId: null,
+            eventName: eventNameForReceipt, toolName: toolName ?? "Bash", status: "observed", payload, eventKey, matchKey,
+            transcriptPath: stringValue(hook.transcript_path) ?? null, cwd: expectedRoot
+        });
+        recordFlowSessionObservation(context, { projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null, cwd: expectedRoot, toolName: toolName ?? "Bash", eventKey });
+        const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, harness: "zcode-acp", session: nativeSessionIdentity("zcode-acp", providerSessionId), ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("zcode-acp", parentProviderSessionId) } : {}), daemon_id: daemonId };
+        return { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: rewritten } } };
     };
-    const inserted = recordHookEvent(context, {
-        projectId: project.id,
-        protocolId: observedSession?.protocol_id ?? null,
-        harness: "zcode-acp",
-        providerSessionId,
-        parentSessionId,
-        daemonId: daemonId ?? null,
-        sessionId,
-        agentId: agentId ?? null,
-        turnId: null,
-        eventName: "PreToolUse",
-        toolName: toolName ?? "Bash",
-        status: "observed",
-        payload,
-        eventKey,
-        matchKey,
-        transcriptPath: null,
-        cwd: expectedRoot
+    if (!invocationId)
+        return persist();
+    const receipt = observeLifecycleInvocation(context, {
+        id: invocationId, command, identity: { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId ?? null, toolCallId: toolUseId },
+        recordReceipt: () => { persist(); return eventKey; }
     });
-    recordFlowSessionObservation(context, {
-        projectId: project.id,
-        sessionId,
-        runId: observedSession?.run_id ?? null,
-        protocolId: observedSession?.protocol_id ?? null,
-        cwd: expectedRoot,
-        toolName: toolName ?? "Bash",
-        eventKey
-    });
-    return {
-        ok: true,
-        observed: inserted,
-        duplicate: !inserted,
-        event_key: eventKey,
-        harness: "zcode-acp",
-        session: nativeSessionIdentity("zcode-acp", providerSessionId),
-        ...(childProviderSessionId ? { parent_session: nativeSessionIdentity("zcode-acp", rootProviderSessionId) } : {}),
-        daemon_id: daemonId ?? null
-    };
+    return { ok: true, observed: !receipt.duplicate, duplicate: receipt.duplicate, event_key: receipt.eventKey, invocation_id: invocationId };
 }
 /** Convert a Grok Build PreToolUse hook into a trusted lifecycle receipt. */
 export function handleGrokEvent(context, input) {
@@ -538,7 +533,7 @@ export function handleGrokEvent(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
+    if (lifecycle.analysis.kind === "compound") {
         throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone Grok Build tool call", 1, {
             standalone_command: lifecycle.invocation.command
         });
@@ -653,7 +648,7 @@ function handleControlledToolEvent(context, input, event, harness) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating" };
-    if (lifecycle.analysis.kind === "compound" && !allowsStdinLifecycleCompound(lifecycle)) {
+    if (lifecycle.analysis.kind === "compound") {
         throw new AppError("compound_lifecycle_command", `dd-flow lifecycle commands must be a standalone ${label} shell tool call`, 1, { standalone_command: lifecycle.invocation.command });
     }
     const { flowPayload, bootstrapStageStart, commandProjectRoot } = lifecycle;
@@ -741,11 +736,58 @@ function lifecycleCommandFromPayload(payload) {
     const command = commandFromPayload(payload);
     return command ? unwrapShellCommand(command) : undefined;
 }
-function commandWithHookEvent(command, eventKey) {
+/**
+ * Adds the receipt to the command that the shell will execute.  Heredoc input
+ * belongs to that command too, but an option appended after its delimiter is a
+ * second shell command rather than an argument, so insert it before `<<`.
+ */
+export function commandWithHookEvent(command, eventKey) {
     const analysis = parseLifecycleCommand(command);
-    if (analysis.kind !== "standalone" || !analysis.invocation.rewriteSafe || commandHasOption(analysis.invocation, "hook-event-id"))
+    if (analysis.kind !== "standalone")
+        return command;
+    if (commandHasOption(analysis.invocation, "hook-event-id")) {
+        if (commandOption(analysis.invocation, "hook-event-id") !== eventKey)
+            throw new AppError("hook_event_mismatch", "The command specifies a receipt from another tool invocation", 1);
         return command;
-    return `${command.trim()} --hook-event-id ${JSON.stringify(eventKey)}`;
+    }
+    const option = `--hook-event-id '${eventKey.replaceAll("'", "'\\''")}'`;
+    if (analysis.invocation.rewriteSafe) {
+        const index = shellSuffixOffset(command);
+        return `${command.slice(0, index).trimEnd()} ${option} ${command.slice(index)}`.trimEnd();
+    }
+    if (!analysis.invocation.wrapped && analysis.invocation.heredoc && allowsStdinLifecycleCompound(lifecycleFacts(command))) {
+        const index = firstHeredoc(command);
+        if (index >= 0)
+            return `${command.slice(0, index).trimEnd()} ${option} ${command.slice(index)}`;
+    }
+    return command;
+}
+function firstHeredoc(command) {
+    let quoteState = null;
+    let escaped = false;
+    for (let index = 0; index < command.length - 1; index += 1) {
+        const char = command[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quoteState !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quoteState) {
+            if (char === quoteState)
+                quoteState = null;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quoteState = char;
+            continue;
+        }
+        if (char === "<" && command[index + 1] === "<" && command[index + 2] !== "<")
+            return index;
+    }
+    return -1;
 }
 /**
  * Recognise the small shell surface used by generated dd-flow lifecycle
@@ -794,8 +836,11 @@ function lifecycleFacts(command) {
 // not a second authority. Everything else remains standalone-only.
 function allowsStdinLifecycleCompound(facts) {
     const operation = facts.invocation.operation;
-    return (operation === "work_finish" && commandHasOption(facts.invocation, "result-stdin"))
-        || ((operation === "stage_pause" || operation === "stage_resume") && facts.invocation.heredoc);
+    return facts.analysis.kind === "standalone" && facts.invocation.heredoc && !facts.invocation.wrapped
+        && ((operation === "work_finish" && commandHasOption(facts.invocation, "result-stdin"))
+            || (operation === "stage_start" && commandHasOption(facts.invocation, "intake-stdin"))
+            || (operation === "stage_pause" && commandHasOption(facts.invocation, "question-stdin"))
+            || (operation === "stage_resume" && commandHasOption(facts.invocation, "answer-stdin")));
 }
 function lifecycleMatchKey(facts, projectRoot) {
     const { invocation, bootstrapStageStart, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, stageName, runId, workId, contextSha256 } = facts;
@@ -920,17 +965,19 @@ export function findRecentMatchingHookEvent(context, input) {
     const freshAfter = new Date(Date.parse(context.now()) - 60_000).toISOString();
     const find = () => context.db.all(`SELECT id, event_key FROM hook_events
      WHERE project_id = ? AND match_key = ? AND status = 'observed' AND created_at >= ?
-     ORDER BY id DESC LIMIT 2`, [input.projectId, input.matchKey, freshAfter]);
+       AND harness IN ('codex-desktop', 'antigravity-cli')
+       AND (? IS NULL OR session_id = ?)
+     ORDER BY id DESC LIMIT 2`, [input.projectId, input.matchKey, freshAfter, input.sessionId ?? null, input.sessionId ?? null]);
     let events = find();
-    // Some harnesses publish nested-agent tool events concurrently with command
-    // execution. Give the trusted event a short bounded window to reach SQLite.
+    // Only the qualified non-rewriting transports may correlate the original
+    // command: Codex Desktop and Antigravity. New harnesses fail closed by default.
     const deadline = Date.now() + 250;
     while (events.length === 0 && Date.now() < deadline) {
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
         events = find();
     }
     if (events.length === 0 || !events[0]?.event_key) {
-        throw new AppError(input.errorCode, `${input.operation} requires one matching harness lifecycle event. Stay in this Session and retry the exact standalone lifecycle command; do not create a new Session.`, 1);
+        throw new AppError(input.errorCode, `${input.operation} requires a trusted lifecycle receipt. Check native hook delivery and updatedInput; managed ZCode requires its issued --invocation-id.`, 1);
     }
     if (events.length > 1) {
         throw new AppError("ambiguous_lifecycle_receipt", `${input.operation} has more than one fresh matching lifecycle event; provide its exact hook event ID`, 1, { match_key: input.matchKey, event_keys: events.map((event) => event.event_key) });
@@ -1009,10 +1056,8 @@ export function stageResumeMatchKey(runId, stage, workId, projectRoot) {
 /** Claims the resume command observed in the Session that received the user answer. */
 export function claimStageResumeHookEvent(context, input) {
     const matchKey = stageResumeMatchKey(input.runId, input.stage, input.workId, input.projectRoot);
-    const freshAfter = new Date(Date.parse(context.now()) - 60_000).toISOString();
-    const event = input.eventKey
-        ? context.db.get("SELECT id, event_key, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey])
-        : context.db.get("SELECT id, event_key, session_id, match_key, status FROM hook_events WHERE project_id = ? AND session_id = ? AND match_key = ? AND status = 'observed' AND created_at >= ? ORDER BY id DESC LIMIT 1", [input.projectId, input.sessionId ?? "", matchKey, freshAfter]);
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, { projectId: input.projectId, matchKey, sessionId: input.sessionId ?? "", errorCode: "trusted_stage_resume_required", operation: "stage resume" }).eventKey;
+    const event = context.db.get("SELECT id, event_key, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
     if (!event?.event_key || !event.session_id || event.match_key !== matchKey || event.status !== "observed") {
         throw new AppError("trusted_stage_resume_required", "stage resume requires one fresh matching PreToolUse event", 1, { run_id: input.runId, stage: input.stage, work_id: input.workId });
     }

package/dist/services/lifecycle-command.js

@@ -32,7 +32,7 @@ function parseLifecycleCommandInner(command, wrapped) {
     const heredoc = stripHeredocBodies(command);
     let entries;
     try {
-        entries = parse(heredoc.command, (name) => `$${name}`);
+        entries = parse(withoutFileDescriptors(heredoc.command), (name) => `$${name}`);
     }
     catch {
         // A command that cannot be tokenized cannot create a trusted claim. The
@@ -56,11 +56,11 @@ function parseLifecycleCommandInner(command, wrapped) {
     if (!found.length)
         return { kind: "none" };
     const first = found[0];
-    if (found.length !== 1 || composed || first.nestedCompound) {
+    if (found.length !== 1 || composed || first.nestedCompound || (heredoc.present && !heredoc.safe)) {
         return {
             kind: "compound",
             invocation: { ...first.invocation, rewriteSafe: false },
-            reason: found.length !== 1 ? "multiple_lifecycle_invocations" : first.nestedCompound ? "nested_compound_invocation" : "shell_composition"
+            reason: found.length !== 1 ? "multiple_lifecycle_invocations" : first.nestedCompound ? "nested_compound_invocation" : heredoc.present && !heredoc.safe ? "unsafe_heredoc" : "shell_composition"
         };
     }
     return { kind: "standalone", invocation: first.invocation };
@@ -170,6 +170,9 @@ function wrappedInvocationFromSegment(segment) {
     return parseLifecycleCommandInner(payload, true);
 }
 function lifecycleOperation(argv) {
+    // The CLI handles help before dispatch, wherever the flag occurs.
+    if (argv.some(arg => arg === "--help" || arg === "-h"))
+        return null;
     if (argv[0] === "run" && argv[1] === "recovery" && argv[2] === "accept")
         return "recovery_accept";
     const key = `${argv[0] ?? ""} ${argv[1] ?? ""}`;
@@ -223,6 +226,58 @@ export function commandPosition(invocation, index) {
 function assignment(word) {
     return /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
 }
+/** Source offsets matter: shell-quote loses the difference between `2>&1`
+ * and the literal argument `2 >&1`. Only inspect unquoted shell syntax. */
+function shellSyntaxOffsets(command) {
+    const offsets = [];
+    let quoted = null, escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quoted !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quoted) {
+            if (char === quoted)
+                quoted = null;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quoted = char;
+            continue;
+        }
+        if (char === "#" && (i === 0 || /\s/.test(command[i - 1]))) {
+            offsets.push(i);
+            break;
+        }
+        if (char === "<" || char === ">")
+            offsets.push(i);
+    }
+    return offsets;
+}
+function descriptorStart(command, index) {
+    let start = index;
+    while (start > 0 && /[0-9]/.test(command[start - 1]))
+        start--;
+    return start === 0 || /[\s;&|]/.test(command[start - 1]) ? start : index;
+}
+export function shellSuffixOffset(command) {
+    const offset = shellSyntaxOffsets(command)[0];
+    return offset === undefined ? command.length : descriptorStart(command, offset);
+}
+function withoutFileDescriptors(command) {
+    for (const index of shellSyntaxOffsets(command).reverse()) {
+        if (command[index] === "#")
+            continue;
+        const start = descriptorStart(command, index);
+        command = command.slice(0, start) + command.slice(index);
+    }
+    return command;
+}
 function addAssignment(env, word) {
     const separator = word.indexOf("=");
     env[word.slice(0, separator)] = word.slice(separator + 1);
@@ -233,6 +288,7 @@ function stripHeredocBodies(command) {
     const pending = [];
     let active;
     let present = false;
+    let count = 0, quoted = true;
     for (const line of lines) {
         if (active) {
             const candidate = active.stripTabs ? line.replace(/^\t+/, "") : line;
@@ -243,13 +299,15 @@ function stripHeredocBodies(command) {
         if (line.trim())
             output.push(line);
         const found = heredocDelimiters(line);
+        count += found.length;
+        quoted &&= found.every(item => item.quoted);
         if (found.length) {
             present = true;
             active = found[0];
             pending.push(...found.slice(1));
         }
     }
-    return { command: output.join(" ; "), present };
+    return { command: output.join(" ; "), present, safe: count === 1 && quoted && !active && pending.length === 0 };
 }
 function heredocDelimiters(line) {
     const result = [];
@@ -292,7 +350,7 @@ function heredocDelimiters(line) {
                 index += 1;
         const delimiter = line.slice(start, index);
         if (delimiter)
-            result.push({ delimiter, stripTabs });
+            result.push({ delimiter, stripTabs, quoted: delimiterQuote !== null });
     }
     return result;
 }