@deksden-com/dd-flow-cli 0.9.0-beta.104 → 0.9.0-beta.105

package/dist/services/eval-snapshots.js

@@ -4,6 +4,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { registerStoreWriter } from "../storage/writer-contract.js";
+import { beginSnapshotImport, completeSnapshotImport } from "../storage/import-guard.js";
+import { foreignKeyTransaction } from "../storage/foreign-key-transaction.js";
 import { createContext } from "../runtime/context.js";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot, runtimeProtocolDir, runtimeRunDir } from "../storage/paths.js";
@@ -16,6 +18,7 @@ import { resourceHome } from "./managed-processes.js";
 import { codexHomeSharedEntries } from "./hooks.js";
 import { prepareOutputFile } from "../cli/input-preparation.js";
 import { localEnvironmentAllowed, projectServicePathFilter } from "./workspace-files.js";
+import { cleanupScopeWriters } from "./scope-writer-cleanup.js";
 /** Capture the only flow boundary which exists before `stage start --bootstrap` creates a RUN. */
 export function prepareEvalBootstrapSnapshot(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -387,9 +390,12 @@ function assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest
     if (context.db.get("SELECT 1 FROM projects LIMIT 1") || context.db.get("SELECT 1 FROM runs LIMIT 1"))
         throw new AppError("restore_home_not_empty", "Snapshot restore cannot replace an initialized runtime", 1);
 }
-export function restoreEvalRunSnapshot(context, input, prepared = prepareEvalRunRestore(context, input)) {
+export function restoreEvalRunSnapshot(context, input, prepared = prepareEvalRunRestore(context, input), prearmedImportId) {
     const { snapshot, manifest, recovery, projectRoot, sourceRuntime, sourceProject, routingInput, selectedProfile } = prepared;
     assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest);
+    const sourceManifestSha256 = fileHash(path.join(snapshot, "snapshot.json"));
+    const importId = prearmedImportId ?? beginSnapshotImport({ home: context.ddFlowHome, projectRoot,
+        workspaceRoot: restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome), sourceManifestSha256 });
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
@@ -399,7 +405,8 @@ export function restoreEvalRunSnapshot(context, input, prepared = prepareEvalRun
     const workspaceRoot = restoreWorkspace(snapshot, manifest, projectRoot, context.ddFlowHome);
     // The dispatch context was intentionally closed before replacing db.sqlite.
     // A fresh process owns all subsequent normal commands.
-    const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome });
+    const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome }, "initialize", importId);
+    let result, primary, failed = false;
     try {
         const runtimeLineage = recovery ? null : detachSnapshotRuntimeOwners(restored, snapshot, manifest);
         rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome, recovery);
@@ -433,7 +440,11 @@ export function restoreEvalRunSnapshot(context, input, prepared = prepareEvalRun
             fs.mkdirSync(path.dirname(relocationFile), { recursive: true });
             writeJson(relocationFile, relocation);
         }
-        return {
+        const expectedWorkspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome);
+        if (physicalPath(workspaceRoot) !== physicalPath(expectedWorkspaceRoot))
+            throw new AppError("snapshot_workspace_restore_failed", "Restored workspace differs from the import target", 1, { workspace_root: workspaceRoot, expected_workspace_root: expectedWorkspaceRoot });
+        completeSnapshotImport(context.ddFlowHome, importId, { projectRoot, workspaceRoot: expectedWorkspaceRoot, sourceManifestSha256 });
+        result = {
             ok: true,
             schema_id: "dd-flow/eval-run-restore@1",
             snapshot,
@@ -448,9 +459,19 @@ export function restoreEvalRunSnapshot(context, input, prepared = prepareEvalRun
             next_command: recovery ? `dd-flow run recovery inspect ${status.run.id} --project-root ${JSON.stringify(projectRoot)} --json` : `dd-flow stage start ${status.run.id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
         };
     }
-    finally {
-        restored.db.close?.();
+    catch (error) {
+        primary = error;
+        failed = true;
     }
+    const cleanup = cleanupScopeWriters([{ name: restored.ddFlowHome, db: restored.db, rollback: false, close: "always" }]);
+    if (failed) {
+        if (primary instanceof AppError && cleanup.length)
+            primary.details.import_cleanup_errors = cleanup;
+        throw primary;
+    }
+    if (cleanup.length)
+        throw new AppError("snapshot_import_cleanup_failed", "Snapshot imported but its connection could not be closed", 1, { effect: "committed", import_complete: true, import_cleanup_errors: cleanup });
+    return result;
 }
 export function prepareVnextSpecifyRun(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -498,10 +519,11 @@ function assertSnapshotRuntimeDetachAllowed(get) {
 function detachSnapshotRuntimeOwners(context, snapshot, manifest) {
     const hasTable = (table) => Boolean(context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?", [table]));
     assertSnapshotRuntimeDetachAllowed(sql => context.db.get(sql));
-    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 detachedTables = ["lifecycle_packet_assignments", "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;
+    let resourceHeld = false, resourceCommitted = false, result, primary, failed = false;
     try {
         if (resources)
             registerStoreWriter(resources);
@@ -512,42 +534,56 @@ function detachSnapshotRuntimeOwners(context, snapshot, manifest) {
         fs.writeFileSync(file, `${JSON.stringify({ schema_id: "dd-flow/snapshot-runtime-lineage@1", source_snapshot: snapshot, source_manifest_sha256: fileHash(path.join(snapshot, "snapshot.json")), source_runtime: manifest.dd_flow_home, restored_runtime: context.ddFlowHome, run_id: manifest.run_id, run_tables: runTables, resource_tables: resourceTables }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
         syncPath(file);
         syncPath(directory);
-        context.db.beginWriteTransaction();
-        try {
-            context.db.run("UPDATE sessions SET metadata_json = json_set(metadata_json, '$.snapshot_import', json(?))", [JSON.stringify({ lineage_file: file, lineage_sha256: fileHash(file) })]);
-            for (const table of detachedTables)
-                context.db.exec(`DELETE FROM ${table}`);
+        const lineage = JSON.stringify({ lineage_file: file, lineage_sha256: fileHash(file) });
+        context.db.writeTransaction(() => {
+            assertSnapshotRuntimeDetachAllowed(sql => context.db.get(sql));
+            for (const [table, rows] of Object.entries(runTables))
+                if (JSON.stringify(context.db.all(`SELECT * FROM ${table}`)) !== JSON.stringify(rows))
+                    throw new AppError("snapshot_runtime_changed", "Imported runtime changed during lineage preparation", 1, { table });
+            context.db.run("UPDATE sessions SET metadata_json = json_set(metadata_json, '$.snapshot_import', json(?))", [lineage]);
+            for (const table of detachedTables) {
+                try {
+                    context.db.exec(`DELETE FROM ${table}`);
+                }
+                catch (error) {
+                    throw new AppError("snapshot_runtime_detach_failed", `Could not detach imported ${table} authority`, 1, { table, cause: String(error) });
+                }
+            }
             context.db.run("UPDATE merge_requests SET dispatch_owner = NULL, dispatch_lease_token = NULL, dispatch_lease_expires_at = NULL, lock_acquired_at = NULL, adapter_receipt_json = NULL");
             // Only the copied dedicated registry is touched. Source/external homes
             // are historical references in the archive and are never opened here.
             if (resources) {
                 resources.exec("BEGIN IMMEDIATE");
-                try {
-                    for (const table of Object.keys(resourceTables))
-                        resources.exec(`DELETE FROM ${table}`);
-                    resources.exec("COMMIT");
-                }
-                catch (error) {
-                    resources.exec("ROLLBACK");
-                    throw error;
+                resourceHeld = true;
+                for (const [table, rows] of Object.entries(resourceTables)) {
+                    if (JSON.stringify(resources.prepare(`SELECT * FROM ${table}`).all()) !== JSON.stringify(rows))
+                        throw new AppError("snapshot_runtime_changed", "Imported resource evidence changed during lineage preparation", 1, { table });
+                    resources.exec(`DELETE FROM ${table}`);
                 }
+                resources.exec("COMMIT");
+                resourceHeld = false;
+                resourceCommitted = true;
             }
-            context.db.exec("COMMIT");
-        }
-        catch (error) {
-            context.db.exec("ROLLBACK");
-            throw error;
-        }
-        return file;
+        });
+        result = file;
     }
-    finally {
-        resources?.close();
+    catch (error) {
+        primary = error;
+        failed = true;
     }
+    const cleanup = resources ? cleanupScopeWriters([{ name: resourceFile, db: resources, rollback: resourceHeld, close: "always" }]) : [];
+    if (failed || cleanup.length) {
+        const details = { effect: resourceCommitted ? "partial" : "unknown", ...(cleanup.length ? { import_cleanup_errors: cleanup } : {}) };
+        if (primary instanceof AppError) {
+            Object.assign(primary.details, details);
+            throw primary;
+        }
+        throw new AppError("snapshot_runtime_detach_failed", primary instanceof Error ? primary.message : "Imported runtime authority could not be detached", 1, { ...details, ...(failed ? { cause: String(primary) } : {}) });
+    }
+    return result;
 }
 function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome, recovery = false) {
-    context.db.exec("PRAGMA foreign_keys = OFF");
-    context.db.beginWriteTransaction();
-    try {
+    foreignKeyTransaction(context.db, () => {
         context.db.run("UPDATE projects SET root = ?", [newRoot]);
         context.db.run("UPDATE runs SET project_root = ?, workspace_root = ?", [newRoot, newWorkspace]);
         for (const column of ["runtime_path", "run_dir", "run_index_path", "run_home_path", "run_root", "index_json"])
@@ -575,15 +611,7 @@ function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, ol
         if (!recovery)
             context.db.run("UPDATE work_sessions SET status = CASE WHEN status = 'running' THEN 'completed' ELSE status END, completed_at = COALESCE(completed_at, ?), updated_at = ?", [context.now(), context.now()]);
         context.db.run("DELETE FROM codex_session_bindings");
-        context.db.run("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
-    finally {
-        context.db.exec("PRAGMA foreign_keys = ON");
-    }
+    });
     // Only operational database paths move. Imported packets, results and
     // journals retain their historical bytes, including interrupted JSONL tails.
     // The frozen workspace route is an operational receipt consumed by later
@@ -660,7 +688,7 @@ function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     restoreIndex(snapshot, "workspace", manifest.workspace, workspaceRoot);
     return fs.realpathSync(workspaceRoot);
 }
-function restoredWorkspaceRoot(manifest, projectRoot, ddFlowHome) {
+export function restoredWorkspaceRoot(manifest, projectRoot, ddFlowHome) {
     if (manifest.workspace.kind === "project")
         return projectRoot;
     const managedRoot = physicalPath(manifest.dd_flow_home), sourceRoot = physicalPath(manifest.workspace.source_root);

package/dist/services/execution-policy.js

@@ -132,16 +132,27 @@ export function assertSameSessionMerge(input) {
             throw new AppError("merge_profile_session_conflict", "Same-session MERGE cannot switch execution profiles; select a compatible profile or server MERGE", 2, { previous_stage: stage, previous_profile_id: previous.id, merge_profile_id: merge.id });
     }
 }
+/** The RUN identity root and a native Session's fixed launch directory are distinct. */
+export function stageExecutionCwd(input) {
+    return path.resolve(input.stage === "specify" || input.stage === "protocolize" ? input.projectRoot
+        : input.stage === "merge" ? input.mergeTargetWorkspace ?? input.projectRoot
+            : input.workspaceRoot);
+}
 export function resolveStageTransition(input) {
     const target = resolveExecutionPolicy(input);
     const previous = input.fromStage ? resolveExecutionPolicy({ ...input, stage: input.fromStage }).coordinator : null;
     const compatible = !previous || sameSessionProfile(previous, target.coordinator);
+    const previousCwd = input.fromStage ? stageExecutionCwd({ ...input, stage: input.fromStage }) : null;
+    const targetCwd = stageExecutionCwd(input);
+    const sameWorkspace = previousCwd === null || previousCwd === targetCwd;
     if (input.stage === "merge" && input.mergeMode === "same_session") {
         if (!compatible)
             throw new AppError("merge_profile_session_conflict", "Same-session MERGE cannot replace its current coordinator", 2);
+        if (!sameWorkspace)
+            throw new AppError("merge_session_workspace_conflict", "Same-session MERGE cannot change the native coordinator workspace", 2, { source_workspace: previousCwd, target_workspace: targetCwd });
         return { ...target, session_mode: "same_session" };
     }
-    return { ...target, session_mode: !compatible || (input.stage === "merge" && input.mergeMode === "server") ? "new_session" : input.stageSessionMode };
+    return { ...target, session_mode: !compatible || !sameWorkspace || (input.stage === "merge" && input.mergeMode === "server") ? "new_session" : input.stageSessionMode };
 }
 function validateDelegation(value) {
     if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !["mode", "agent_profile_id", "max_parallel"].includes(key)))

package/dist/services/hooks.js

@@ -7,6 +7,7 @@ import { AppError } from "../shared/errors.js";
 import { entityReferenceVariants } from "../shared/entity-references.js";
 import { parseJsonObject } from "../shared/json.js";
 import { canonicalPath, ensureDir, resolveProjectRoot } from "../storage/paths.js";
+import { resolveWorkReference } from "../storage/work-references.js";
 import { appendAudit } from "./audit.js";
 import { prepareTextFile, prepareJsonText, prepareError } from "../cli/input-preparation.js";
 import { nativeSessionIdentity, storageSessionId } from "./session-identity.js";
@@ -549,21 +550,22 @@ function recordZcodeLifecycle(context, input, invocationId) {
     const sessionId = storageSessionId(nativeSessionIdentity("zcode-acp", providerSessionId));
     const parentSessionId = parentProviderSessionId ? storageSessionId(nativeSessionIdentity("zcode-acp", parentProviderSessionId)) : null;
     const observedProfile = objectRecord(ddZcode.observedProfile);
+    const observedCwd = stringValue(hook.cwd) && path.isAbsolute(String(hook.cwd)) ? resolveProjectRoot(String(hook.cwd)) : null;
     let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     const eventNameForReceipt = invocationId ? "ToolCallObserved" : "PreToolUse";
     const persist = (scope) => {
         if (scope)
             matchKey = lifecycleMatchKey(lifecycleFacts(scope.command), 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 payload = { ...hook, session_id: providerSessionId, cwd: expectedRoot, tool_name: toolName ?? "Bash", tool_input: rawInput,
+        assertHookEventReplay(context, { projectId: project.id, eventKey, harness: "zcode-acp", providerSessionId, parentSessionId, daemonId, sessionId, turnId: null, eventName: eventNameForReceipt, toolName: toolName ?? "Bash", matchKey, cwd: observedCwd });
+        const payload = { ...hook, session_id: providerSessionId, cwd: observedCwd, 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: 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
+            transcriptPath: stringValue(hook.transcript_path) ?? null, cwd: observedCwd
         });
-        recordFlowSessionObservation(context, { projectId: project.id, sessionId, cwd: expectedRoot, toolName: toolName ?? "Bash", eventKey });
+        recordFlowSessionObservation(context, { projectId: project.id, sessionId, cwd: observedCwd, 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 } } };
     };
@@ -602,13 +604,14 @@ export function handleGrokEvent(context, input) {
         return { ok: true, observed: false, reason: "event_not_participating" };
     const bootstrapStageStart = lifecycle?.bootstrapStageStart;
     const expectedRoot = resolveProjectRoot(input.projectRoot);
-    const matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
+    let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
     const meta = objectRecord(hook._meta);
     const ddGrok = objectRecord(meta.ddGrok);
     const observedProfile = objectRecord(ddGrok.observedProfile);
+    const observedCwd = stringValue(hook.cwd) && path.isAbsolute(String(hook.cwd)) ? resolveProjectRoot(String(hook.cwd)) : null;
     const rootProviderSessionId = stringValue(ddGrok.rootProviderSessionId);
     const providerSessionId = stringValue(hook.session_id) ?? stringValue(hook.sessionId);
     if (!rootProviderSessionId || !providerSessionId)
@@ -622,23 +625,35 @@ export function handleGrokEvent(context, input) {
         harness: "grok-acp", providerSessionId, toolUseId: hook.tool_use_id ?? hook.toolUseId ?? null,
         promptId: hook.prompt_id ?? hook.promptId ?? null, 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 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 persist = (scope) => {
+        if (scope)
+            matchKey = lifecycleMatchKey(lifecycleFacts(scope.command), expectedRoot, scope);
+        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: observedCwd });
+        const payload = {
+            ...hook, session_id: providerSessionId, agent_id: agentId, cwd: observedCwd, 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: 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: observedCwd
+        });
+        recordFlowSessionObservation(context, { projectId: project.id, sessionId, cwd: observedCwd, toolName: toolName ?? "Bash", eventKey });
+        return inserted;
     };
-    const inserted = recordHookEvent(context, {
-        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,
-        cwd: expectedRoot, toolName: toolName ?? "Bash", eventKey
+    const result = (inserted) => ({ 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 });
+    if (!lifecycle)
+        return { ...result(context.db.writeTransaction(() => persist())), hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, eventKey) } } };
+    let inserted = false;
+    const receipt = observeLifecycleInvocation(context, {
+        command, harness: "grok-acp", projectId: project.id,
+        identity: { daemonId: daemonId ?? "", rootSessionId: rootProviderSessionId, sessionId: providerSessionId, parentSessionId, toolCallId: eventKey },
+        recordReceipt: scope => { inserted = persist(scope); return 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 { ...result, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, eventKey) } } };
+    if (receipt.invocationId)
+        return { ...result(inserted), invocation_id: receipt.invocationId, hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, eventKey) } } };
+    return { ...result(inserted), 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) {
@@ -654,6 +669,65 @@ export function handleDroidEvent(context, input) {
         throw new AppError("unsupported_droid_event_schema", "Unsupported Droid event schema", 1);
     return handleControlledToolEvent(context, input, event, "droid-cli");
 }
+/** Stable project identity is not the native Session's execution workspace. */
+function controlledLifecycleCwd(context, projectRoot, facts, providerSessionId, auxiliary) {
+    if (facts?.bootstrapStageStart)
+        return projectRoot;
+    const project = context.db.get("SELECT id FROM projects WHERE root = ?", [projectRoot]);
+    if (!project)
+        return projectRoot;
+    let work;
+    if (facts?.workId) {
+        try {
+            work = resolveWorkReference(context, facts.workId, { projectId: project.id });
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || !["not_found", "ambiguous_work_alias"].includes(error.code))
+                throw error;
+        }
+    }
+    const reference = work?.run_id ?? facts?.runId ?? auxiliary?.args.options.get("run")?.[0] ?? auxiliary?.args.positional[2];
+    if (!reference)
+        return projectRoot;
+    const run = context.db.get("SELECT id, run_root, workspace_root FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [project.id, reference, reference]);
+    if (!run)
+        return projectRoot; // Hook ingress does not validate a mistyped CLI target.
+    if (work) {
+        // PROTOCOLIZE provisions the feature checkout after its coordinator
+        // Session has launched in the stable project root. Its transition Work
+        // must keep that physical route until the Stage is complete.
+        if (context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'stage_work_memberships'")
+            && context.db.get("SELECT 1 FROM stage_work_memberships WHERE project_id = ? AND run_id = ? AND work_id = ? AND stage IN ('specify','protocolize') LIMIT 1", [project.id, run.id, work.work_id]))
+            return projectRoot;
+        const merge = context.db.get("SELECT target_workspace FROM merge_requests WHERE executor_work_id = ? AND run_id = ?", [work.work_id, run.id]);
+        if (merge)
+            return resolveProjectRoot(merge.target_workspace);
+        if (context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'work_launches'")) {
+            const launch = context.db.get("SELECT provider_session_id, profile_json FROM work_launches WHERE work_id = ? AND status IN ('launching', 'start_requested')", [work.work_id]);
+            if (launch?.provider_session_id === providerSessionId && run.run_root) {
+                const copy = JSON.parse(launch.profile_json).review_copy?.root;
+                if (copy) {
+                    const target = path.resolve(run.run_root, copy);
+                    const relative = path.relative(run.run_root, target);
+                    if (relative === ".." || relative.startsWith(`..${path.sep}`))
+                        throw new AppError("read_only_workspace_unbound", "Review copy escapes its owning RUN", 1);
+                    return resolveProjectRoot(target);
+                }
+            }
+        }
+    }
+    if (facts?.stageName === "specify" || facts?.stageName === "protocolize")
+        return projectRoot;
+    if (facts?.stageName === "merge") {
+        const pending = context.db.all("SELECT target_workspace FROM merge_requests WHERE project_id = ? AND run_id = ? AND status IN ('dispatching','active','action_required') ORDER BY updated_at DESC", [project.id, run.id]);
+        const targets = [...new Set(pending.map(item => resolveProjectRoot(item.target_workspace)))];
+        if (targets.length > 1)
+            throw new AppError("merge_workspace_ambiguous", "Current MERGE requests disagree on the native execution workspace", 1, { run_id: run.id, target_workspaces: targets });
+        if (targets.length === 1)
+            return targets[0];
+    }
+    return resolveProjectRoot(run.workspace_root);
+}
 function handleControlledToolEvent(context, input, event, harness) {
     const agy = harness === "antigravity-cli";
     const droid = harness === "droid-cli";
@@ -676,9 +750,7 @@ function handleControlledToolEvent(context, input, event, harness) {
         throw new AppError(`${errorPrefix}_session_identity_invalid`, `${label} event is missing trusted physical identity`, 1);
     }
     const expectedRoot = resolveProjectRoot(input.projectRoot);
-    if (resolveProjectRoot(directory) !== expectedRoot) {
-        throw new AppError(`${errorPrefix}_directory_mismatch`, `${label} Session directory does not match the controlled workspace`, 1, { expected: expectedRoot, actual: directory });
-    }
+    const observedCwd = resolveProjectRoot(directory);
     if (droid && nativeParentId === providerSessionId)
         throw new AppError("droid_session_identity_invalid", "A Droid Session cannot parent itself", 1);
     const sessionId = storageSessionId(nativeSessionIdentity(harness, providerSessionId));
@@ -690,8 +762,8 @@ function handleControlledToolEvent(context, input, event, harness) {
         const inserted = recordHookEvent(context, {
             projectId: project.id, protocolId: null, harness, providerSessionId, parentSessionId,
             daemonId, sessionId, agentId: stringValue(session.agent_id) ?? null, turnId: stringValue(event.message_id) ?? null,
-            eventName: "PostToolUse", toolName, status: "observed", payload: { session_id: providerSessionId, cwd: expectedRoot, tool_name: toolName, status: objectRecord(event.outcome).status },
-            eventKey: baseKey, matchKey: null, transcriptPath: droid ? stringValue(event.transcript_path) ?? null : null, cwd: expectedRoot
+            eventName: "PostToolUse", toolName, status: "observed", payload: { session_id: providerSessionId, cwd: observedCwd, tool_name: toolName, status: objectRecord(event.outcome).status },
+            eventKey: baseKey, matchKey: null, transcriptPath: droid ? stringValue(event.transcript_path) ?? null : null, cwd: observedCwd
         });
         return { ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}) };
     }
@@ -699,10 +771,15 @@ function handleControlledToolEvent(context, input, event, harness) {
         return { ok: true, observed: false, reason: command ? "non_bash_tool" : "event_not_participating" };
     }
     const lifecycle = lifecycleFacts(command);
-    if (!lifecycle && !continuationCommand(command))
+    const auxiliary = continuationCommand(command);
+    if (!lifecycle && !auxiliary)
         return { ok: true, observed: false, reason: "event_not_participating" };
+    const expectedCwd = controlledLifecycleCwd(context, expectedRoot, lifecycle, providerSessionId, auxiliary);
+    if (observedCwd !== expectedCwd) {
+        throw new AppError(`${errorPrefix}_directory_mismatch`, `${label} ${agy ? "launch route" : "Session directory"} does not match the assigned execution workspace`, 1, { expected: expectedCwd, actual: observedCwd, ...(agy ? { actual_provenance: stringValue(event.cwd_provenance) ?? "unknown" } : {}) });
+    }
     const bootstrapStageStart = lifecycle?.bootstrapStageStart;
-    const matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
+    let matchKey = lifecycle ? lifecycleMatchKey(lifecycle, expectedRoot) : null;
     if (bootstrapStageStart)
         registerProject(context, { root: expectedRoot });
     const project = requireProjectByRoot(context, expectedRoot);
@@ -713,28 +790,55 @@ 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 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 persist = (scope) => {
+        if (scope)
+            matchKey = lifecycleMatchKey(lifecycleFacts(scope.command), expectedRoot, scope);
+        assertHookEventReplay(context, { projectId: project.id, eventKey: baseKey, harness, providerSessionId, parentSessionId, daemonId, sessionId, turnId: stringValue(event.message_id) ?? null, eventName: "PreToolUse", toolName, matchKey, cwd: observedCwd });
+        const payload = {
+            session_id: providerSessionId, agent_id: agentId, cwd: observedCwd, tool_name: toolName, tool_input: rawInput, command,
+            ...(agy ? { cwd_provenance: stringValue(event.cwd_provenance) ?? "unknown" } : {}),
+            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: 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: observedCwd
+        });
+        recordFlowSessionObservation(context, { projectId: project.id, sessionId, cwd: observedCwd, toolName, eventKey: baseKey });
+        return inserted;
     };
-    const inserted = recordHookEvent(context, {
-        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, 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) } } };
+    const result = (inserted) => ({ ok: true, observed: inserted, duplicate: !inserted, event_key: baseKey, phase, harness, session: nativeSessionIdentity(harness, providerSessionId), ...(nativeParentId ? { parent_session: nativeSessionIdentity(harness, nativeParentId) } : {}), daemon_id: daemonId });
+    if (agy && lifecycle) {
+        let inserted = false;
+        const receipt = observeLifecycleInvocation(context, {
+            command, harness, projectId: project.id, identity: { daemonId, rootSessionId: nativeParentId ?? providerSessionId, sessionId: providerSessionId, parentSessionId: nativeParentId ?? null, toolCallId: toolCallId },
+            recordReceipt: scope => { inserted = persist(scope); return baseKey; }
+        });
+        return { ...result(inserted), ...(receipt.invocationId ? { invocation_id: receipt.invocationId } : {}) };
+    }
+    const inserted = context.db.writeTransaction(() => persist());
+    return agy ? result(inserted) : { ...result(inserted), hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: { ...rawInput, command: commandWithHookEvent(command, baseKey) } } };
 }
 /** Convert an Antigravity CLI tool hook into the shared lifecycle receipt. */
 export function handleAgyEvent(context, input) {
     const event = parseJsonObject(input.stdin || "{}", "Antigravity tool event");
     if (event.schema_id !== "dd-flow/agy-tool-event@1")
         throw new AppError("unsupported_agy_event_schema", "Unsupported Antigravity event schema", 1);
-    const workspacePaths = Array.isArray(event.workspace_paths) ? event.workspace_paths : [];
-    const directory = workspacePaths.find((value) => typeof value === "string" && path.isAbsolute(value));
+    // workspacePaths lists available workspaces; its first element is not a
+    // native selected-cwd observation. The daemon's spawn cwd is a separate,
+    // launch-bound route, and the list only corroborates its membership.
+    const workspacePaths = Array.isArray(event.workspace_paths)
+        ? event.workspace_paths.filter((value) => typeof value === "string" && path.isAbsolute(value)) : [];
+    const launchCwd = stringValue(event.launch_cwd);
+    const qualifiedLaunchCwd = launchCwd && path.isAbsolute(launchCwd) ? launchCwd : undefined;
+    const directory = qualifiedLaunchCwd ?? (workspacePaths.length === 1 ? workspacePaths[0] : undefined);
+    if (!directory && workspacePaths.length > 1)
+        throw new AppError("agy_workspace_route_unproven", "Antigravity did not identify the active route among multiple workspaces", 1, { workspace_paths: workspacePaths });
+    if (directory && qualifiedLaunchCwd && workspacePaths.length
+        && !workspacePaths.some(value => resolveProjectRoot(value) === resolveProjectRoot(directory))) {
+        throw new AppError("agy_workspace_route_unproven", "Antigravity launch cwd is absent from the native workspace list", 1, { launch_cwd: directory, workspace_paths: workspacePaths });
+    }
     const providerSessionId = stringValue(event.conversation_id);
     const daemonId = stringValue(event.daemon_id);
     const eventId = stringValue(event.event_id);
@@ -743,6 +847,9 @@ export function handleAgyEvent(context, input) {
         throw new AppError("agy_session_identity_invalid", "Antigravity event is missing trusted physical identity", 1);
     const rawInput = objectRecord(event.input);
     const command = stringValue(rawInput.command) ?? stringValue(rawInput.cmd) ?? stringValue(rawInput.CommandLine);
+    if (command && (lifecycleFacts(command) || continuationCommand(command)) && !qualifiedLaunchCwd) {
+        throw new AppError("agy_workspace_route_unproven", "Managed Antigravity call has no launch-bound execution cwd", 1, { phase: "prepare", effect: "no_effect", recoverable: false, workspace_paths: workspacePaths });
+    }
     const invalidStep = !Number.isSafeInteger(event.step_index) || Number(event.step_index) < 0;
     const invalidExecution = event.execution_num !== undefined && (!Number.isSafeInteger(event.execution_num) || Number(event.execution_num) < 0);
     if (event.phase === "before" && command && (lifecycleFacts(command) || continuationCommand(command)) && (invalidStep || invalidExecution)) {
@@ -753,6 +860,7 @@ export function handleAgyEvent(context, input) {
         daemon_id: daemonId, tool_call_id: eventId, tool: toolName, input: event.input,
         message_id: event.step_index === undefined ? null : String(event.step_index),
         session: { provider_session_id: providerSessionId, parent_provider_session_id: event.parent_conversation_id, directory },
+        cwd_provenance: qualifiedLaunchCwd ? "launch_bound" : "workspace_paths_singleton",
         profile: { provider: objectRecord(event.profile).provider, model: objectRecord(event.profile).model, variant: objectRecord(event.profile).reasoning, agent: objectRecord(event.profile).mode },
         outcome: { status: stringValue(event.error) ? "error" : "completed" }
     };