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

package/dist/services/hooks.js

@@ -2,17 +2,18 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { parse, stringify } from "smol-toml";
+import { parse, stringify, TomlError } from "smol-toml";
 import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
-import { ensureDir, resolveProjectRoot } from "../storage/paths.js";
+import { canonicalPath, ensureDir, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
+import { prepareTextFile, prepareJsonText, prepareError } from "../cli/input-preparation.js";
 import { nativeSessionIdentity, storageSessionId } from "./session-identity.js";
 import { assertRecoveryHookCurrent } from "./run-recovery.js";
-import { observeLifecycleInvocation, settleLifecycleNoEffectRejection } from "./lifecycle-invocations.js";
-import { commandHasOption, commandOption, commandPosition, shellSuffixOffset, parseLifecycleCommand, unwrapShellCommand } from "./lifecycle-command.js";
+import { observeLifecycleInvocation } from "./lifecycle-invocations.js";
+import { commandHasOption, commandOption, commandPosition, shellSuffixOffset, parseLifecycleCommand, lifecycleCommandFromPayload } from "./lifecycle-command.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
-import { activeFlowSessionsForProject, bindObservedFlowSession, flowSessionPayloadFromRegisterCommand, recordFlowSessionObservation } from "./sessions.js";
+import { activeFlowSessionsForProject, recordFlowSessionObservation } from "./sessions.js";
 const defaultProfileName = "default";
 const maxSanitizedSummaryLength = 1600;
 export const codexHomeSharedEntries = [
@@ -57,17 +58,23 @@ export function planCodexHome(context, input) {
         codex_env: { CODEX_HOME: paths.targetHome }
     };
 }
-export function initCodexHome(context, input) {
+export function prepareCodexHome(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const profile = resolveProfileName(input.profile);
     const paths = resolveHomePaths(context, project, profile, input);
+    if (canonicalPath(paths.sourceHome, false) === canonicalPath(paths.targetHome, false))
+        throw new AppError("validation", "Managed Codex home must differ from its source home", 2);
+    const config = readTomlIfExists(path.join(paths.sourceHome, "config.toml"));
+    return { project, profile, paths, config };
+}
+export function initCodexHome(context, input, prepared = prepareCodexHome(context, input)) {
+    const { project, profile, paths, config } = prepared;
     const now = context.now();
     ensureDir(paths.targetHome);
     ensureDir(path.join(paths.targetHome, "log"));
     ensureDir(path.join(paths.targetHome, ".tmp"));
     ensureDir(path.join(paths.targetHome, "tmp"));
     const linked = createSharedLinks(paths.sourceHome, paths.targetHome);
-    const config = readTomlIfExists(path.join(paths.sourceHome, "config.toml"));
     fs.writeFileSync(paths.configPath, stringify(withManagedConfig(config, paths.sourceHome, paths.targetHome)));
     writeJsonFile(paths.hooksPath, expectedHooksConfig(project.root));
     writeJsonFile(path.join(paths.targetHome, ".dd-flow-home.json"), {
@@ -138,7 +145,7 @@ export function printCodexHomeEnv(context, input) {
         command_prefix: `CODEX_HOME=${JSON.stringify(record.target_home)}`
     };
 }
-export function removeCodexHome(context, input) {
+export function prepareCodexHomeRemoval(context, input) {
     if (!["keep-shared", "remove-owned"].includes(input.mode)) {
         throw new AppError("validation", "--mode must be keep-shared or remove-owned", 2);
     }
@@ -146,9 +153,30 @@ export function removeCodexHome(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const profile = resolveProfileName(input.profile);
     const record = homeProfile(context, project.id, profile);
+    if (record && record.status !== "removed" && fs.existsSync(record.target_home)) {
+        let marker;
+        try {
+            const value = JSON.parse(fs.readFileSync(path.join(record.target_home, ".dd-flow-home.json"), "utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error("Invalid marker");
+            marker = value;
+        }
+        catch {
+            throw new AppError("runtime_artifact_invalid", "Managed Codex home ownership marker is missing or invalid; refusing removal", 1, { target_home: record.target_home });
+        }
+        if (marker.managed_by !== "dd-flow-cli" || marker.project_id !== project.id || marker.profile !== profile || marker.target_home !== record.target_home || marker.source_home !== record.source_home || canonicalPath(record.target_home, false) === canonicalPath(record.source_home, false)) {
+            throw new AppError("runtime_artifact_invalid", "Managed Codex home ownership does not match its registration; refusing removal", 1, { target_home: record.target_home });
+        }
+    }
+    return { project, profile, record, mode };
+}
+export function removeCodexHome(context, input) {
+    const { project, profile, record, mode } = prepareCodexHomeRemoval(context, input);
     if (!record) {
         return { ok: true, removed: false, profile, status: "not_initialized" };
     }
+    if (record.status === "removed")
+        return { ok: true, removed: false, profile, status: "already_removed" };
     const removedEntries = [];
     for (const relative of ["config.toml", "hooks.json", ".dd-flow-home.json", "log", ".tmp", "tmp"]) {
         const target = path.join(record.target_home, relative);
@@ -209,7 +237,7 @@ export function getCodexHooksStatus(context, input) {
         recorded
     };
 }
-export function installCodexHooks(context, input) {
+export function prepareCodexHooks(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const target = resolveHookTarget(input.target);
     const location = requireHookLocation(context, project, target, resolveProfileName(input.profile));
@@ -219,9 +247,16 @@ export function installCodexHooks(context, input) {
             hooks_path: location.hooksPath
         });
     }
-    const existing = readJsonIfExists(location.hooksPath) ?? {};
-    const backup = target === "default" && fs.existsSync(location.hooksPath) ? backupFile(location.hooksPath, context.now()) : null;
+    const text = fs.existsSync(location.hooksPath) ? prepareTextFile(location.hooksPath, "hooks configuration").text : null;
+    const existing = text === null ? {} : prepareJsonText(text, { file: location.hooksPath }).value;
+    if (!existing || typeof existing !== "object" || Array.isArray(existing) || (existing.hooks !== undefined && (!existing.hooks || typeof existing.hooks !== "object" || Array.isArray(existing.hooks) || Object.values(existing.hooks).some(entries => !Array.isArray(entries)))))
+        return prepareError(new AppError("validation", "Hooks configuration requires an object with event arrays", 2), { file: location.hooksPath });
+    return { project, target, location, existing, text };
+}
+export function installCodexHooks(context, input, prepared = prepareCodexHooks(context, input)) {
+    const { project, target, location, existing, text } = prepared;
     const nextConfig = mergeHooksConfig(existing, project.root);
+    const backup = target === "default" && text !== null ? backupFile(location.hooksPath, context.now(), text) : null;
     ensureDir(path.dirname(location.hooksPath));
     writeJsonFile(location.hooksPath, nextConfig);
     recordHookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath), location.hooksPath, true, "none");
@@ -240,20 +275,11 @@ export function installCodexHooks(context, input) {
         expected_hash: hashObject(expectedHooksConfig(project.root))
     };
 }
-export function removeCodexHooks(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const target = resolveHookTarget(input.target);
-    const location = requireHookLocation(context, project, target, resolveProfileName(input.profile));
-    if (target === "default" && !input.yes) {
-        throw new AppError("confirmation_required", "Direct default Codex home mutation requires --yes", 1, {
-            target,
-            hooks_path: location.hooksPath
-        });
-    }
-    const existing = readJsonIfExists(location.hooksPath) ?? {};
+export function removeCodexHooks(context, input, prepared = prepareCodexHooks(context, input)) {
+    const { project, target, location, existing, text } = prepared;
     const hadManaged = hasManagedHooks(existing, project.root);
-    const backup = target === "default" && fs.existsSync(location.hooksPath) ? backupFile(location.hooksPath, context.now()) : null;
     const nextConfig = removeManagedHooks(existing, project.root);
+    const backup = target === "default" && text !== null ? backupFile(location.hooksPath, context.now(), text) : null;
     ensureDir(path.dirname(location.hooksPath));
     writeJsonFile(location.hooksPath, nextConfig);
     recordHookInstallation(context, project.id, installationScope(target, location.profile, location.hooksPath), location.hooksPath, false, "not_installed");
@@ -276,7 +302,6 @@ export function handleCodexHook(context, input) {
     // therefore the only valid identity for a fresh Work.
     const rawChildProviderSessionId = stringValue(payload.agent_id) ?? null;
     const providerSessionId = rawChildProviderSessionId ?? rootProviderSessionId;
-    const parentProviderSessionId = rawChildProviderSessionId ? codexNativeParentId(payload, rawChildProviderSessionId) : null;
     const turnId = stringValue(payload.turn_id);
     const toolName = stringValue(payload.tool_name) ?? toolNameFromPayload(payload);
     const command = lifecycleCommandFromPayload(payload);
@@ -285,108 +310,131 @@ export function handleCodexHook(context, input) {
     const lifecycle = lifecycleFacts(command);
     if (!lifecycle)
         return { ok: true, observed: false, reason: "event_not_participating", event: eventName };
+    const parentProviderSessionId = rawChildProviderSessionId ? codexNativeParentId(payload, rawChildProviderSessionId) : null;
     // 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") {
-        return {
-            ok: false,
-            observed: false,
-            reason: "compound_lifecycle_command",
-            message: "Run the dd-flow lifecycle invocation as the first technical action and as one standalone Bash command in this same Session.",
-            standalone_command: lifecycle.invocation.command,
-            hookSpecificOutput: {
-                hookEventName: "PreToolUse",
-                permissionDecision: "deny",
-                permissionDecisionReason: `dd-flow lifecycle commands must be standalone. Retry in this same Session: ${lifecycle.invocation.command}`
-            }
-        };
+    const { bootstrapStageStart } = lifecycle;
+    const invocationId = commandOption(lifecycle.invocation, "invocation-id");
+    if (invocationId || context.env.DD_FLOW_DAEMON_ID) {
+        const proof = context.codexHookProof;
+        if (!proof || proof.daemonId !== context.env.DD_FLOW_DAEMON_ID || proof.rootSessionId !== rootProviderSessionId
+            || proof.sessionId !== providerSessionId || proof.parentSessionId !== parentProviderSessionId
+            || proof.toolCallId !== payload.tool_use_id || proof.command !== command) {
+            throw new AppError("native_hook_unproven", "Managed Codex admission requires its active native hook delivery, not a manual handler call", 1, { ...(invocationId ? { invocation_id: invocationId } : {}), effect: "no_effect" });
+        }
     }
-    const { flowPayload, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, bootstrapStageStart, commandProjectRoot } = lifecycle;
-    const matchKey = commandProjectRoot ? lifecycleMatchKey(lifecycle, commandProjectRoot) : null;
+    const nativeProjectRoot = context.codexHookProof?.projectRoot ?? input.projectRoot;
     // A bootstrap stage is the first stateful command for a new materialized project.
     // Its PreToolUse event arrives before stage start can register that project.
-    if (bootstrapStageStart && commandProjectRoot) {
-        registerProject(context, { root: commandProjectRoot });
-    }
-    let project;
-    try {
-        project = projectForHook(context, input.projectRoot ?? commandProjectRoot, stringValue(payload.cwd));
-    }
-    catch (error) {
-        // A terminal command outside a registered flow gets no trusted receipt;
-        // the CLI will fail closed if it is actually executed. This keeps hooks
-        // inert for unrelated shell-parser probes and stale project directories.
-        if (stageFinish || stagePause || workFinish || workFail)
-            return { ok: true, observed: false, reason: "project_not_registered" };
-        throw error;
-    }
-    if (!project)
+    const bootstrapRoot = nativeProjectRoot ?? stringValue(payload.cwd);
+    if (bootstrapStageStart && bootstrapRoot) {
+        registerProject(context, { root: bootstrapRoot });
+    }
+    const project = projectForHook(context, nativeProjectRoot, stringValue(payload.cwd));
+    if (!project) {
+        if (invocationId)
+            throw new AppError("project_not_registered", "Managed lifecycle invocation has no registered project", 1, { project_root: nativeProjectRoot ?? null });
         return { ok: true, observed: false, reason: "unrelated_cwd" };
+    }
+    let matchKey = lifecycleMatchKey(lifecycle, project.root);
     // Codex retains the root session_id for a thread-spawned child, while the
     // payload transcript belongs to the current agent_id. Keep lineage separate
     // from ownership: otherwise a child overwrites the root transcript binding.
     const eventKey = hookEventKey(payload, eventName, toolName, command);
     const storageId = providerSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", providerSessionId)) : null;
     const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("codex-desktop", parentProviderSessionId)) : null;
-    assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "codex-desktop", providerSessionId: providerSessionId ?? null, parentSessionId, daemonId: stringValue(context.env.DD_FLOW_DAEMON_ID) ?? null, sessionId: storageId, turnId: turnId ?? null, eventName, toolName: toolName ?? null, matchKey, cwd: stringValue(payload.cwd) ?? null });
+    const eventCwd = stringValue(payload.cwd) ?? project.root;
+    assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "codex-desktop", providerSessionId: providerSessionId ?? null, parentSessionId, daemonId: stringValue(context.env.DD_FLOW_DAEMON_ID) ?? null, sessionId: storageId, turnId: turnId ?? null, eventName, toolName: toolName ?? null, matchKey, cwd: eventCwd });
     const bindingOwnerId = providerSessionId ?? rootProviderSessionId;
-    const binding = bindingOwnerId ? upsertSessionBindingFromPayload(context, project, bindingOwnerId, payload) : undefined;
-    const observedSession = flowPayload
-        ? bindObservedFlowSession(context, project, {
-            ...flowPayload,
-            harness: "codex-desktop",
-            provider_session_id: providerSessionId ?? flowPayload.provider_session_id ?? null,
-            parent_session_id: parentSessionId
-        }, storageId ?? undefined)
-        : undefined;
-    const effectiveSessionId = observedSession?.session_id ?? storageId;
-    const protocolId = observedSession?.protocol_id ?? binding?.protocol_id ?? null;
-    const inserted = recordHookEvent(context, {
-        projectId: project.id,
-        protocolId,
-        harness: "codex-desktop",
-        providerSessionId: providerSessionId ?? null,
-        parentSessionId,
-        // Pinned by the owning app-server process, never derived from current RUN
-        // state or an agent-supplied shell command/payload.
-        daemonId: stringValue(context.env.DD_FLOW_DAEMON_ID) ?? null,
-        sessionId: effectiveSessionId,
-        agentId: rawChildProviderSessionId ?? null,
-        turnId: turnId ?? null,
-        eventName,
-        toolName: toolName ?? null,
-        status: "observed",
-        payload,
-        eventKey,
-        matchKey,
-        transcriptPath: binding?.transcript_path ?? null,
-        cwd: stringValue(payload.cwd) ?? null
-    });
-    if (effectiveSessionId) {
-        recordFlowSessionObservation(context, {
+    // Resolve legacy transcript discovery before acquiring the receipt write lock.
+    const transcriptPath = stringValue(payload.transcript_path)
+        ?? (bindingOwnerId ? sessionBinding(context, project.id, bindingOwnerId)?.transcript_path ?? locateCodexTranscript(bindingOwnerId, context.env.CODEX_HOME) : null);
+    const persist = (scope) => {
+        if (scope)
+            matchKey = lifecycleMatchKey(lifecycle, project.root, scope);
+        const binding = bindingOwnerId ? upsertSessionBindingFromPayload(context, project, bindingOwnerId, payload, transcriptPath) : undefined;
+        const effectiveSessionId = storageId;
+        const protocolId = binding?.protocol_id ?? null;
+        const inserted = recordHookEvent(context, {
             projectId: project.id,
-            sessionId: effectiveSessionId,
-            runId: observedSession?.run_id ?? null,
             protocolId,
-            cwd: stringValue(payload.cwd) ?? null,
+            harness: "codex-desktop",
+            providerSessionId: providerSessionId ?? null,
+            parentSessionId,
+            // Pinned by the owning app-server process, never derived from current RUN
+            // state or an agent-supplied shell command/payload.
+            daemonId: stringValue(context.env.DD_FLOW_DAEMON_ID) ?? null,
+            sessionId: effectiveSessionId,
+            agentId: rawChildProviderSessionId ?? null,
+            turnId: turnId ?? null,
+            eventName,
             toolName: toolName ?? null,
-            eventKey
+            status: "observed",
+            payload,
+            eventKey,
+            matchKey,
+            transcriptPath: binding?.transcript_path ?? null,
+            cwd: stringValue(payload.cwd) ?? project.root
         });
-    }
-    return {
+        if (effectiveSessionId) {
+            recordFlowSessionObservation(context, {
+                projectId: project.id,
+                sessionId: effectiveSessionId,
+                protocolId,
+                cwd: eventCwd,
+                toolName: toolName ?? null,
+                eventKey
+            });
+        }
+        return { inserted, protocolId };
+    };
+    const common = {
         ok: true,
-        observed: inserted,
-        duplicate: !inserted,
         event_key: eventKey,
         session: providerSessionId ? nativeSessionIdentity("codex-desktop", providerSessionId) : null,
         ...(parentProviderSessionId ? { parent_session: nativeSessionIdentity("codex-desktop", parentProviderSessionId) } : {}),
-        protocol_id: protocolId,
-        ...(providerSessionId && (flowPayload || stageStart || stageFinish || stagePause || stageResume || workStart || workFinish || workFail || lifecycle.invocation.operation === "recovery_accept")
+        protocol_id: null
+    };
+    if (invocationId || context.env.DD_FLOW_DAEMON_ID) {
+        const daemonId = stringValue(context.env.DD_FLOW_DAEMON_ID);
+        const toolCallId = stringValue(payload.tool_use_id) ?? stringValue(payload.event_id) ?? stringValue(payload.delivery_id) ?? stringValue(payload.id);
+        if (!daemonId || !rootProviderSessionId || !providerSessionId || !toolCallId)
+            throw new AppError("codex_identity_missing", "Managed Codex lifecycle hook has no complete native invocation identity", 1, { invocation_id: invocationId });
+        const receipt = observeLifecycleInvocation(context, {
+            ...(invocationId ? { id: invocationId } : {}),
+            command,
+            harness: "codex-desktop",
+            identity: { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId, toolCallId },
+            recordReceipt: scope => { persist(scope); return eventKey; }
+        });
+        const stored = context.db.get("SELECT protocol_id FROM hook_events WHERE project_id = ? AND event_key = ?", [project.id, receipt.eventKey]);
+        const admittedInvocationId = receipt.invocationId ?? invocationId;
+        if (admittedInvocationId)
+            return { ...common, protocol_id: stored?.protocol_id ?? null, observed: !receipt.duplicate, duplicate: receipt.duplicate, event_key: receipt.eventKey, invocation_id: admittedInvocationId };
+        return {
+            ...common,
+            protocol_id: stored?.protocol_id ?? null,
+            observed: !receipt.duplicate,
+            duplicate: receipt.duplicate,
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+                updatedInput: { ...objectRecord(payload.tool_input), command: commandWithHookEvent(command, eventKey) }
+            }
+        };
+    }
+    const persisted = persist();
+    return {
+        ...common,
+        protocol_id: persisted.protocolId,
+        observed: persisted.inserted,
+        duplicate: !persisted.inserted,
+        ...(providerSessionId
             ? {
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",
                     permissionDecision: "allow",
-                    updatedInput: { command: commandWithHookEvent(command, eventKey) }
+                    updatedInput: { ...objectRecord(payload.tool_input), command: commandWithHookEvent(command, eventKey) }
                 }
             }
             : {})
@@ -398,7 +446,24 @@ function codexNativeParentId(payload, childId) {
     if (!transcript || !path.isAbsolute(transcript))
         return null;
     try {
-        const firstLine = fs.readFileSync(transcript, "utf8").split("\n", 1)[0];
+        const descriptor = fs.openSync(transcript, "r");
+        const chunks = [];
+        try {
+            for (;;) {
+                const buffer = Buffer.alloc(4096);
+                const length = fs.readSync(descriptor, buffer, 0, buffer.length, null);
+                if (!length)
+                    break;
+                const newline = buffer.subarray(0, length).indexOf(10);
+                chunks.push(buffer.subarray(0, newline < 0 ? length : newline));
+                if (newline >= 0)
+                    break;
+            }
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        const firstLine = Buffer.concat(chunks).toString("utf8");
         if (!firstLine)
             return null;
         const record = JSON.parse(firstLine);
@@ -456,9 +521,6 @@ function recordZcodeLifecycle(context, input, invocationId) {
     if (!invocationId && commandOption(lifecycle.invocation, "invocation-id"))
         return { ok: true, observed: false, reason: "cli_invocation_owns_admission" };
     const expectedRoot = resolveProjectRoot(input.projectRoot);
-    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 meta = objectRecord(hook._meta);
     const ddZcode = objectRecord(meta.ddZcode);
     const providerSessionId = stringValue(hook.session_id) ?? stringValue(hook.sessionId);
@@ -474,56 +536,46 @@ function recordZcodeLifecycle(context, input, invocationId) {
     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);
-    if (lifecycle.analysis.kind === "compound") {
-        if (lifecycle.analysis.reason !== "shell_composition")
-            throw new AppError("compound_lifecycle_command", "Ambiguous shell cannot authorize a lifecycle replacement", 1, { reason: lifecycle.analysis.reason });
-        if (invocationId) {
-            const error = { code: "compound_lifecycle_command", message: "dd-flow lifecycle commands must be a standalone ZCode Bash tool call", exitCode: 1,
-                details: { standalone_command: lifecycle.invocation.command } };
-            settleLifecycleNoEffectRejection(context, invocationId, lifecycle.invocation.command, error, { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId ?? null, toolCallId: toolUseId });
-            return { ok: true, observed: false, invocation_id: invocationId, no_effect: true, error };
-        }
-        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 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 sessionId = storageSessionId(nativeSessionIdentity("zcode-acp", providerSessionId));
     const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", parentProviderSessionId)) : null;
     const observedProfile = objectRecord(ddZcode.observedProfile);
-    const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
+    let matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
     const eventNameForReceipt = invocationId ? "ToolCallObserved" : "PreToolUse";
-    const persist = () => {
+    const persist = (scope) => {
+        if (scope)
+            matchKey = lifecycleMatchKey(lifecycle, expectedRoot, scope);
         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,
+            projectId: project.id, protocolId: 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 });
+        recordFlowSessionObservation(context, { projectId: project.id, sessionId, 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 } } };
     };
-    if (!invocationId)
-        return persist();
+    let persistedResult;
     const receipt = observeLifecycleInvocation(context, {
-        id: invocationId, command, identity: { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId ?? null, toolCallId: toolUseId },
-        recordReceipt: () => { persist(); return eventKey; }
+        ...(invocationId ? { id: invocationId } : {}), command,
+        harness: "zcode-acp",
+        identity: { daemonId, rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId: parentProviderSessionId ?? null, toolCallId: toolUseId },
+        recordReceipt: scope => { persistedResult = persist(scope); return eventKey; }
     });
-    return { ok: true, observed: !receipt.duplicate, duplicate: receipt.duplicate, event_key: receipt.eventKey, invocation_id: invocationId };
+    const admittedInvocationId = receipt.invocationId ?? invocationId;
+    if (admittedInvocationId)
+        return { ok: true, observed: !receipt.duplicate, duplicate: receipt.duplicate, event_key: receipt.eventKey, invocation_id: admittedInvocationId };
+    // Without an issued managed attempt this is still ordinary hook evidence.
+    // Preserve persist()'s replay result instead of overwriting it with the
+    // admission layer's non-authoritative duplicate flag.
+    return persistedResult ?? persist();
 }
 /** Convert a Grok Build PreToolUse hook into a trusted lifecycle receipt. */
 export function handleGrokEvent(context, input) {
@@ -541,18 +593,8 @@ 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") {
-        throw new AppError("compound_lifecycle_command", "dd-flow lifecycle commands must be a standalone Grok Build tool call", 1, {
-            standalone_command: lifecycle.invocation.command
-        });
-    }
-    const { flowPayload, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, bootstrapStageStart, commandProjectRoot } = lifecycle;
+    const { bootstrapStageStart } = lifecycle;
     const expectedRoot = resolveProjectRoot(input.projectRoot);
-    if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
-        throw new AppError("project_mismatch", "Grok Build lifecycle command project root does not match the controlled workspace", 1, {
-            expected: expectedRoot, actual: commandProjectRoot
-        });
-    }
     const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
@@ -573,27 +615,22 @@ export function handleGrokEvent(context, input) {
         harness: "grok-acp", providerSessionId, command, turn: hook.turn_id ?? hook.turnId ?? null
     })).digest("hex");
     assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "grok-acp", providerSessionId, parentSessionId, daemonId: daemonId ?? null, sessionId, turnId: stringValue(hook.turn_id) ?? stringValue(hook.turnId) ?? null, eventName: "PreToolUse", toolName: toolName ?? "Bash", matchKey, cwd: expectedRoot });
-    const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
-        ...flowPayload, harness: "grok-acp", provider_session_id: providerSessionId, agent_id: agentId ?? null, parent_session_id: parentSessionId
-    }, sessionId) : undefined;
     const payload = {
         ...hook, 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(hook.subagent_type) ?? stringValue(hook.subagentType)
     };
     const inserted = recordHookEvent(context, {
-        projectId: project.id, protocolId: observedSession?.protocol_id ?? null, harness: "grok-acp", providerSessionId, parentSessionId,
+        projectId: project.id, protocolId: null, harness: "grok-acp", providerSessionId, parentSessionId,
         daemonId: daemonId ?? null, sessionId, agentId: agentId ?? null, turnId: stringValue(hook.turn_id) ?? stringValue(hook.turnId) ?? null,
         eventName: "PreToolUse", toolName: toolName ?? "Bash", status: "observed", payload, eventKey, matchKey, transcriptPath: null, cwd: expectedRoot
     });
     recordFlowSessionObservation(context, {
-        projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null,
+        projectId: project.id, sessionId,
         cwd: expectedRoot, toolName: toolName ?? "Bash", eventKey
     });
     const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: eventKey, session: nativeSessionIdentity("grok-acp", providerSessionId),
         ...(isChild ? { parent_session: nativeSessionIdentity("grok-acp", stringValue(ddGrok.parentProviderSessionId) ?? rootProviderSessionId) } : {}), daemon_id: daemonId ?? null };
-    return (flowPayload || stageStart || stageFinish || stagePause || stageResume || workStart || workFinish || workFail || lifecycle.invocation.operation === "recovery_accept")
-        ? { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...(rawInput ?? {}), command: commandWithHookEvent(command, eventKey) } } }
-        : result;
+    return { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, eventKey) } } };
 }
 /** Convert a controlled OpenCode tool hook into the shared lifecycle receipt. */
 export function handleOpenCodeEvent(context, input) {
@@ -656,13 +693,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") {
-        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;
-    if (commandProjectRoot && resolveProjectRoot(commandProjectRoot) !== expectedRoot) {
-        throw new AppError("project_mismatch", `${label} lifecycle command project root does not match the controlled workspace`, 1, { expected: expectedRoot, actual: commandProjectRoot });
-    }
+    const { bootstrapStageStart } = lifecycle;
     const matchKey = lifecycleMatchKey(lifecycle, expectedRoot);
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
@@ -675,23 +706,17 @@ function handleControlledToolEvent(context, input, event, harness) {
     }
     const agentId = stringValue(session.agent_id);
     assertHookEventReplay(context, { projectId: project.id, eventKey: baseKey, harness, providerSessionId, parentSessionId, daemonId, sessionId, turnId: stringValue(event.message_id) ?? null, eventName: "PreToolUse", toolName, matchKey, cwd: expectedRoot });
-    const observedSession = flowPayload ? bindObservedFlowSession(context, project, {
-        ...flowPayload, harness, provider_session_id: providerSessionId, agent_id: agentId ?? null,
-        parent_session_id: parentSessionId, provider: stringValue(profile.provider) ?? null, model: stringValue(profile.model) ?? null,
-        reasoning: stringValue(droid ? profile.reasoning : profile.variant) ?? null, mode: stringValue(droid ? profile.mode : profile.agent) ?? null, agent_type: stringValue(droid ? profile.agent_type : profile.agent) ?? null,
-        metadata: droid ? { droid_version: stringValue(event.runtime_version) ?? null } : { opencode_version: stringValue(event.server_version) ?? null, api_fingerprint: stringValue(event.api_fingerprint) ?? null, plugin_sha256: stringValue(event.plugin_sha256) ?? null, native_project_id: stringValue(session.project_id) ?? null }
-    }, sessionId) : undefined;
     const payload = {
         session_id: providerSessionId, agent_id: agentId, cwd: expectedRoot, tool_name: toolName, tool_input: rawInput, command,
         provider: stringValue(profile.provider), model: stringValue(profile.model), reasoning: stringValue(droid ? profile.reasoning : profile.variant),
         mode: stringValue(droid ? profile.mode : profile.agent), agent_type: stringValue(droid ? profile.agent_type : profile.agent)
     };
     const inserted = recordHookEvent(context, {
-        projectId: project.id, protocolId: observedSession?.protocol_id ?? null, harness, providerSessionId, parentSessionId,
+        projectId: project.id, protocolId: null, harness, providerSessionId, parentSessionId,
         daemonId, sessionId, agentId: agentId ?? null, turnId: stringValue(event.message_id) ?? null, eventName: "PreToolUse", toolName,
         status: "observed", payload, eventKey: baseKey, matchKey, transcriptPath: droid ? stringValue(event.transcript_path) ?? null : null, cwd: expectedRoot
     });
-    recordFlowSessionObservation(context, { projectId: project.id, sessionId, runId: observedSession?.run_id ?? null, protocolId: observedSession?.protocol_id ?? null, cwd: expectedRoot, toolName, eventKey: baseKey });
+    recordFlowSessionObservation(context, { projectId: project.id, sessionId, cwd: expectedRoot, toolName, eventKey: baseKey });
     const result = { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}), daemon_id: daemonId };
     return agy ? result : { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, baseKey) } } };
 }
@@ -740,10 +765,6 @@ export function isolatedDdFlowHomeFromHookStdin(stdin) {
  * hook contract intentionally narrow: unwrap only that whole-command form,
  * then apply the same lifecycle parser to its actual shell payload.
  */
-function lifecycleCommandFromPayload(payload) {
-    const command = commandFromPayload(payload);
-    return command ? unwrapShellCommand(command) : undefined;
-}
 /**
  * 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
@@ -754,8 +775,6 @@ export function commandWithHookEvent(command, eventKey) {
     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;
     }
     const option = `--hook-event-id '${eventKey.replaceAll("'", "'\\''")}'`;
@@ -825,7 +844,6 @@ function lifecycleFacts(command) {
     return {
         analysis,
         invocation,
-        flowPayload: flowSessionPayloadFromRegisterCommand(invocation),
         stageStart,
         stageFinish,
         stagePause,
@@ -850,11 +868,17 @@ function allowsStdinLifecycleCompound(facts) {
             || (operation === "stage_pause" && commandHasOption(facts.invocation, "question-stdin"))
             || (operation === "stage_resume" && commandHasOption(facts.invocation, "answer-stdin")));
 }
-function lifecycleMatchKey(facts, projectRoot) {
+function lifecycleMatchKey(facts, projectRoot, scope) {
+    // Observe the actual argument without validating it. A mistyped project
+    // must not leave a receipt matching a later, corrected non-rewriting call.
+    if (!scope && facts.commandProjectRoot && canonicalPath(facts.commandProjectRoot, false) !== canonicalPath(projectRoot, false))
+        return null;
     const { invocation, bootstrapStageStart, stageStart, stageFinish, stagePause, stageResume, workStart, workFinish, workFail, stageName, runId, workId, contextSha256 } = facts;
+    const effectiveRoot = scope?.projectRoot ?? projectRoot;
+    const effectiveRunId = scope?.runId ?? runId;
     if (invocation.operation === "recovery_accept") {
         const run = commandPosition(invocation, 0), recovery = commandOption(invocation, "recovery-id");
-        return run && recovery ? recoveryAcceptMatchKey(run, recovery, projectRoot) : null;
+        return (scope?.runId ?? run) && recovery ? recoveryAcceptMatchKey((scope?.runId ?? run), recovery, effectiveRoot) : null;
     }
     if (bootstrapStageStart)
         return bootstrapMatchKey({
@@ -863,20 +887,20 @@ function lifecycleMatchKey(facts, projectRoot) {
             intakeMode: contextSha256 ? "context" : commandHasOption(invocation, "intake-stdin") ? "stdin" : "file",
             ...(contextSha256 ? { contextSha256 } : {})
         });
-    if (stageStart && runId && stageName)
-        return stageStartMatchKey(runId, stageName, projectRoot, contextSha256);
-    if (stageFinish && runId && stageName)
-        return stageLifecycleMatchKey("stage_finish", runId, stageName, projectRoot);
-    if (stagePause && runId && stageName && workId)
-        return stageLifecycleMatchKey("stage_pause", runId, stageName, projectRoot, workId);
-    if (stageResume && runId && stageName && workId)
-        return stageResumeMatchKey(runId, stageName, workId, projectRoot);
+    if (stageStart && effectiveRunId && stageName)
+        return stageStartMatchKey(effectiveRunId, stageName, effectiveRoot, contextSha256);
+    if (stageFinish && effectiveRunId && stageName)
+        return stageLifecycleMatchKey("stage_finish", effectiveRunId, stageName, effectiveRoot);
+    if (stagePause && effectiveRunId && stageName && workId)
+        return stageLifecycleMatchKey("stage_pause", effectiveRunId, stageName, effectiveRoot, workId);
+    if (stageResume && effectiveRunId && stageName && workId)
+        return stageResumeMatchKey(effectiveRunId, stageName, workId, effectiveRoot);
     if (workStart && workId)
-        return workStartMatchKey(workId, projectRoot, commandOption(invocation, "recovery-id"));
+        return workStartMatchKey(workId, effectiveRoot, commandOption(invocation, "recovery-id"));
     if (workFinish && workId)
-        return workLifecycleMatchKey("work_finish", workId, projectRoot);
+        return workLifecycleMatchKey("work_finish", workId, effectiveRoot);
     if (workFail && workId)
-        return workLifecycleMatchKey("work_fail", workId, projectRoot);
+        return workLifecycleMatchKey("work_fail", workId, effectiveRoot);
     return null;
 }
 /** Observe exact immutable command attribution before reading model-supplied
@@ -892,6 +916,8 @@ export function observeCommandHook(context, command) {
     if (!matchKey)
         return;
     let key = commandOption(facts.invocation, "hook-event-id");
+    if (!key && commandOption(facts.invocation, "invocation-id"))
+        return;
     if (!key) {
         try {
             key = findRecentMatchingHookEvent(context, { projectId: project.id, matchKey, errorCode: "trusted_session_binding_required", operation: facts.invocation.operation }).eventKey;
@@ -1011,7 +1037,7 @@ export function findRecentMatchingHookEvent(context, input) {
         events = find();
     }
     if (events.length === 0 || !events[0]?.event_key) {
-        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);
+        throw new AppError(input.errorCode, `${input.operation} requires a trusted lifecycle receipt. Check native hook delivery; managed commands are admitted from committed native identity, not from model-supplied invocation IDs or updatedInput.`, 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) });
@@ -1147,6 +1173,8 @@ export function codexHookEventsForProject(context, projectId) {
      FROM hook_events WHERE project_id = ? ORDER BY created_at DESC, id DESC LIMIT 20`, [projectId]);
 }
 function resolveProfileName(profile) {
+    if (profile !== undefined && (typeof profile !== "string" || !profile.trim()))
+        throw new AppError("validation", "--profile must be nonempty text", 2);
     return sanitizeProfile(profile ?? defaultProfileName);
 }
 function sanitizeProfile(value) {
@@ -1174,11 +1202,12 @@ function readTomlIfExists(file) {
     if (!fs.existsSync(file)) {
         return {};
     }
+    const { text } = prepareTextFile(file, "Codex config");
     try {
-        return parse(fs.readFileSync(file, "utf8"));
+        return parse(text);
     }
     catch (error) {
-        throw new AppError("validation", `Invalid TOML in ${file}: ${String(error)}`, 2);
+        throw new AppError("validation", `Invalid TOML in ${file}`, 2, { file, ...(error instanceof TomlError ? { line: error.line, column: error.column } : {}) });
     }
 }
 function withManagedConfig(config, sourceHome, targetHome) {
@@ -1254,7 +1283,10 @@ function hookEntry(matcher, command, statusMessage) {
     return { matcher, hooks: [commandHook(command, statusMessage)] };
 }
 function commandHook(command, statusMessage) {
-    return { type: "command", command, timeout: 5, statusMessage };
+    // Hook admission is synchronous (the CLI must see a committed receipt), but
+    // the old 5s budget was shorter than a cold CLI/store open under fan-out.
+    // Startup owns migrations; this budget only covers the bounded hot path.
+    return { type: "command", command, timeout: 30, statusMessage };
 }
 function hookCommand(event) {
     const args = `codex hook handle --event ${event} --json`;
@@ -1434,11 +1466,10 @@ function recordHookInstallation(context, projectId, scope, configPath, installed
 function installationScope(target, profile, hooksPath) {
     return target === "isolated" ? `isolated:${profile}` : `default:${path.dirname(hooksPath)}`;
 }
-function upsertSessionBindingFromPayload(context, project, sessionId, payload) {
+function upsertSessionBindingFromPayload(context, project, sessionId, payload, transcriptPath) {
     const existing = sessionBinding(context, project.id, sessionId);
     const now = context.now();
     const cwd = stringValue(payload.cwd) ?? existing?.cwd ?? null;
-    const transcriptPath = stringValue(payload.transcript_path) ?? existing?.transcript_path ?? locateCodexTranscript(sessionId, context.env.CODEX_HOME);
     context.db.run(`INSERT INTO codex_session_bindings
       (session_id, project_id, protocol_id, handshake_id, cwd, transcript_path, status, created_at, updated_at)
      VALUES (?, ?, NULL, NULL, ?, ?, 'active', ?, ?)
@@ -1566,14 +1597,6 @@ function hookEventKey(payload, eventName, toolName, command) {
         command
     })).digest("hex");
 }
-function commandFromPayload(payload) {
-    const direct = stringValue(payload.command);
-    if (direct) {
-        return direct;
-    }
-    const toolInput = objectRecord(payload.tool_input);
-    return stringValue(toolInput.command) ?? stringValue(toolInput.cmd);
-}
 function toolNameFromPayload(payload) {
     const toolInput = objectRecord(payload.tool_input);
     return stringValue(toolInput.name);
@@ -1616,10 +1639,10 @@ function writeJsonFile(file, value) {
     ensureDir(path.dirname(file));
     fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
-function backupFile(file, now) {
+function backupFile(file, now, text) {
     const suffix = now.replace(/[:.]/g, "-");
     const backup = `${file}.${suffix}.bak`;
-    fs.copyFileSync(file, backup);
+    fs.writeFileSync(backup, text, { mode: 0o600 });
     return backup;
 }
 function hashObject(value) {