@deftai/directive-core 0.106.0 → 0.108.0

package/dist/hooks/dispatcher.js

@@ -1,6 +1,7 @@
 import { lstatSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { appendAuthzAudit, classifyHookAuthzOps, evaluateAuthzMutation, evidenceSatisfiesImplementationApproval, listActiveHumanGrants, loadAuthzStateResult, markGrantUsed, shouldConsumeSingleUseGrant, utcIso, } from "../authz/index.js";
+import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
@@ -9,13 +10,14 @@ import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRE
 import { classifyMcpTool, DEFAULT_RUNTIME_AUTHORITY_POLICY, evaluateRuntimeAuthorityDirectWrite, evaluateRuntimeAuthorityShellOp, listShellOps, loadRuntimeAuthorityFromProject, } from "../policy/runtime-authority.js";
 import { loadStoryWriteFenceFromPath, resolveWriteFence } from "../policy/write-fence.js";
 import { appendSoftAgentsRebindToMessage, decisionCarriesSoftAgentsRebind, formatSoftAgentsRebindChecklist, } from "../session/compact-ritual.js";
-import { detectBranch } from "../session/git.js";
+import { defaultGitRunner, detectBranch, existingAncestorDir, gitCommonDir, memoizeGitRunner, worktreePathOrNull, } from "../session/git.js";
 import { evaluateOccupancyWriteGate } from "../session/occupancy.js";
 import { emitSessionRitualBlockedProcessCost } from "../session/process-cost.js";
 import { markRitualStaleAfterCompact } from "../session/ritual-sentinel.js";
 import { runSessionStartHookWrite } from "../session/session-start-hook.js";
-import { formatRitualRecoveryInstruction, verifySessionRitual, } from "../session/verify-session-ritual.js";
-import { hookMcpArgsText, hookShellCommand, hookToolName, hookWriteTargetPath, missingToolNameMessage, record, } from "./classify/index.js";
+import { formatRitualRecoveryInstruction, inspectSessionRitual, verifySessionRitual, WRITE_GATED_REQUIRED_STEPS, writeGateRitualOptions, } from "../session/verify-session-ritual.js";
+import { hookMcpArgsText, hookMutationTargetPaths, hookShellCommand, hookToolName, hookWriteTargetPath, inspectExactLifecycleCommand, missingToolNameMessage, record, resolveHookHostIdentity, rewriteExactLifecycleCommand, toolInputRecord, } from "./classify/index.js";
+import { classifyProductDestForms, payloadWithInjectedWriteTarget } from "./dest-form.js";
 import { isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
 import { inspectActiveScope } from "./scope.js";
 import { isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool } from "./tools.js";
@@ -192,8 +194,8 @@ export function isAssistScratchWrite(projectRoot, targetPath, payload, environ =
         return true;
     return false;
 }
-function isWindowsDriveOnlyRoot(value) {
-    return /^[A-Za-z]:[/\\]?$/.test(value.trim());
+function isWindowsDriveOnlyRoot(value, platform = process.platform) {
+    return platform === "win32" && /^[A-Za-z]:[/\\]?$/.test(value.trim());
 }
 function hookPayloadRootCandidates(input) {
     const candidates = [];
@@ -249,12 +251,114 @@ export function projectRootFromHookPayload(payload, fallback) {
     }
     return fallbackResolved;
 }
+/** Interpolate both roots so a deny names the tree that was judged (#3794). */
+export function formatHookRootNote(payloadRoot, effectiveRoot) {
+    return `payloadRoot=${payloadRoot} effectiveRoot=${effectiveRoot}`;
+}
+function admitPayload(payload, candidate) {
+    return { root: payload, foreign: false, candidate, refusal: null };
+}
+/**
+ * Admit the Git toplevel of the write target only when it shares
+ * `--git-common-dir` with `payloadRoot`.
+ *
+ * Identity resolves to one of three outcomes, not two. A `payloadRoot` that is
+ * not a Git repository never posed a containment question, so it keeps today's
+ * payloadRoot gating. A `payloadRoot` that *is* a repository, paired with a
+ * target that resolved to some other toplevel whose identity cannot be read, is
+ * a question asked and left unanswered — that fails closed rather than
+ * inheriting payloadRoot's occupancy and ritual state (#3794).
+ */
+export function admitEffectiveHookRoot(payloadRoot, writeTarget, runGit) {
+    const payload = normalizeHookProjectRoot(payloadRoot);
+    if (writeTarget === null)
+        return admitPayload(payload, null);
+    const ancestor = existingAncestorDir(writeTarget);
+    if (ancestor === null)
+        return admitPayload(payload, null);
+    const candidateRaw = worktreePathOrNull(ancestor, runGit);
+    if (candidateRaw === null)
+        return admitPayload(payload, null);
+    const candidate = normalizeHookProjectRoot(candidateRaw);
+    if (candidate === payload)
+        return admitPayload(payload, candidate);
+    const payloadCommon = gitCommonDir(payload, runGit);
+    if (payloadCommon === null) {
+        // No containment question exists: payloadRoot is not a repository, so there
+        // is no boundary for the target to be inside or outside of. Denying here
+        // would invent a class this defect never had.
+        return admitPayload(payload, candidate);
+    }
+    const candidateCommon = gitCommonDir(candidate, runGit);
+    if (candidateCommon === null) {
+        return { root: payload, foreign: true, candidate, refusal: "unproven-identity" };
+    }
+    if (normalizeHookProjectRoot(payloadCommon) === normalizeHookProjectRoot(candidateCommon)) {
+        return { root: candidate, foreign: false, candidate, refusal: null };
+    }
+    return { root: payload, foreign: true, candidate, refusal: "foreign-repository" };
+}
+/**
+ * Admit every mutation target and require one effectiveRoot. A refused member
+ * short-circuits; a span of two admitted worktrees is also refused so
+ * occupancy/ritual cannot follow only the declared ApplyPatch path (#3794).
+ */
+export function admitMutationTargetSet(payloadRoot, targets, runGit) {
+    const payload = normalizeHookProjectRoot(payloadRoot);
+    if (targets.length === 0)
+        return admitPayload(payload, null);
+    const admitted = [];
+    for (const target of targets) {
+        const next = admitEffectiveHookRoot(payload, target, runGit);
+        if (next.foreign)
+            return next;
+        admitted.push(next);
+    }
+    const roots = [...new Set(admitted.map((item) => item.root))];
+    if (roots.length > 1) {
+        return {
+            root: payload,
+            foreign: true,
+            candidate: roots.join(" | "),
+            refusal: "worktree-span",
+        };
+    }
+    return admitted[0] ?? admitPayload(payload, null);
+}
 export function isHookHost(value) {
     return HOOK_HOSTS.includes(value);
 }
 export function isHookEvent(value) {
     return HOOK_EVENTS.includes(value);
 }
+/**
+ * Coverage sentence appended to a scope-not-ready deny.
+ *
+ * #3828: this used to claim Shell dest-form coverage unconditionally. Coverage
+ * is opt-in (`plan.policy.runtimeAuthority.shellDestForms: "enforce"`) and the
+ * default is `off`, so on a default-policy repository the sentence advertised a
+ * fence that was not there and, by naming `python -c` as the exception, implied
+ * the gap was a sliver rather than the whole Shell surface. State the coverage
+ * actually in force.
+ */
+function scopeNotReadyCoverageHint(toolName, shellDestFormsEnforced) {
+    if (isSpawnTool(toolName))
+        return "";
+    if (isShellTool(toolName)) {
+        return (" This deny is the active-scope write gate on a recognized Shell dest-form " +
+            "(git checkout --, git restore, rm/rmdir of in-repo paths).");
+    }
+    if (shellDestFormsEnforced) {
+        return (" This gate covers direct-write tools (Edit/Write), implementation spawn, and " +
+            "recognized Shell dest-forms (git checkout --, git restore, rm/rmdir), because " +
+            "plan.policy.runtimeAuthority.shellDestForms is enforce. Shell whose target " +
+            "cannot be resolved to a product path stays outside this deny.");
+    }
+    return (" This gate covers direct-write tools (Edit/Write) and implementation spawn. " +
+        "plan.policy.runtimeAuthority.shellDestForms is off (the default), so no Shell " +
+        "command is covered by this deny -- reaching for one to get around it defeats " +
+        "the gate rather than satisfying it.");
+}
 function deny(input, code, toolName, message, scopePath = null) {
     return {
         verdict: "deny",
@@ -267,8 +371,55 @@ function deny(input, code, toolName, message, scopePath = null) {
         scopePath,
     };
 }
-function runtimeAuthorityForDirectWrite(input, toolName, seams, scopePath) {
+/**
+ * Resolve the cooperative actor presented to the occupancy gate.
+ * Supported payload hosts are payload-authoritative; ambient identity may only
+ * corroborate. Grok retains the pre-#3611 environment path until its payload
+ * contract is verified.
+ */
+function resolveMutationActor(input, environ) {
+    const hostIdentity = resolveHookHostIdentity(input.host, input.payload);
+    const environmentId = environ.DEFT_SESSION_ID?.trim() || undefined;
+    if (hostIdentity.status === "unsupported") {
+        return {
+            sessionId: environmentId,
+            issue: null,
+            message: null,
+            payloadAuthoritative: false,
+        };
+    }
+    if (hostIdentity.status === "ok" && hostIdentity.sessionId !== null) {
+        if (environmentId !== undefined && environmentId !== hostIdentity.sessionId) {
+            return {
+                sessionId: hostIdentity.sessionId,
+                issue: "conflict",
+                message: `Host payload owner ${hostIdentity.sessionId} conflicts with ` +
+                    `DEFT_SESSION_ID ${environmentId}.`,
+                payloadAuthoritative: true,
+            };
+        }
+        return {
+            sessionId: hostIdentity.sessionId,
+            issue: null,
+            message: null,
+            payloadAuthoritative: true,
+        };
+    }
+    return {
+        sessionId: undefined,
+        issue: hostIdentity.status === "conflict" ? "conflict" : "unavailable",
+        message: hostIdentity.message,
+        payloadAuthoritative: true,
+    };
+}
+function runtimeAuthorityForDirectWrite(input, toolName, seams, scopePath, effectiveRoot) {
+    // #3794 commit 2: the project runtimeAuthority layer is project-level
+    // authorization config and stays on payloadRoot, alongside authz. Only the
+    // story fence and the path it is matched against follow the tree the write
+    // lands in, so a story `file_scope` of `packages/**` still matches a write
+    // inside a linked worktree rather than `.deft-scratch/worktrees/<x>/packages/`.
     const projectRoot = resolve(input.projectRoot);
+    const fenceRoot = resolve(effectiveRoot);
     // Project policy load failure: treat as disabled project layer, still apply
     // independent story file_scope when present (#516 / #2443 Greptile P1).
     let basePolicy = DEFAULT_RUNTIME_AUTHORITY_POLICY;
@@ -284,7 +435,7 @@ function runtimeAuthorityForDirectWrite(input, toolName, seams, scopePath) {
     let storyFence;
     try {
         storyFence = seams.loadStoryWriteFence
-            ? seams.loadStoryWriteFence(projectRoot, scopePath)
+            ? seams.loadStoryWriteFence(fenceRoot, scopePath)
             : loadStoryWriteFenceFromPath(scopePath);
     }
     catch {
@@ -298,14 +449,19 @@ function runtimeAuthorityForDirectWrite(input, toolName, seams, scopePath) {
     if (!fence.fenceActive)
         return null;
     const writeTarget = hookWriteTargetPath(input.payload);
-    const relPath = writeTarget !== null ? toProjectRelativePosix(projectRoot, writeTarget) : null;
+    const relPath = writeTarget !== null ? toProjectRelativePosix(fenceRoot, writeTarget) : null;
     const verdict = evaluateRuntimeAuthorityDirectWrite({
         policy: fence.policy,
         relPathPosix: relPath,
     });
     if (verdict.allowed)
         return null;
-    return deny(input, verdict.code ?? "runtime-policy-deny-path", toolName, verdict.reason ?? "Directive denied this direct write under write fence policy.", scopePath);
+    // #3794: relPath is now measured from the tree the write lands in. When that
+    // differs from the payload root, a bare "outside file_scope" reason does not
+    // say which tree the fence was relativised against.
+    const fenceRootNote = fenceRoot === projectRoot ? "" : ` ${formatHookRootNote(projectRoot, fenceRoot)}`;
+    return deny(input, verdict.code ?? "runtime-policy-deny-path", toolName, (verdict.reason ?? "Directive denied this direct write under write fence policy.") +
+        fenceRootNote, scopePath);
 }
 function loadAuthzContext(projectRoot, seams) {
     if (seams.loadAuthzState !== undefined) {
@@ -368,6 +524,8 @@ function recordAuthzAudit(projectRoot, decision, state, seams) {
  * Composes before runtimeAuthority path/scope checks for direct writes and shell/MCP.
  */
 function authzForMutation(input, toolName, seams, options) {
+    // #3794: grant scoping and the authz audit trail stay on payloadRoot.
+    // Re-pointing would break exact-string UAT grants and shard the audit file.
     const projectRoot = resolve(input.projectRoot);
     let state;
     let grants;
@@ -401,7 +559,7 @@ function authzForMutation(input, toolName, seams, options) {
     // Structural context for bound grants (branch from git; repo optional env).
     let branch = null;
     try {
-        branch = detectBranch(projectRoot);
+        branch = detectBranch(projectRoot, options.runGit);
     }
     catch {
         branch = null;
@@ -540,23 +698,50 @@ function decideShellOrMcpRuntimeAuthority(input, toolName, seams) {
     };
 }
 function inspectMutationGates(input, toolName, seams, options) {
-    const projectRoot = resolve(input.projectRoot);
+    // payloadRoot stays authoritative for authz grant scoping, the authz audit
+    // trail, the kill-switch, the #2885 outside-root carve-out, and
+    // deny().projectRoot. effectiveRoot governs occupancy and ritual (commit 1),
+    // and active scope, the story write fence and assist-scratch (commit 2).
+    const payloadRoot = resolve(input.projectRoot);
+    const projectRoot = payloadRoot;
     const environ = input.environ ?? process.env;
+    const dispatchGit = memoizeGitRunner(seams.ritualRunGit ?? defaultGitRunner);
+    const mutationTargets = isSpawnTool(toolName) ? [] : hookMutationTargetPaths(input.payload);
+    const admission = isSpawnTool(toolName)
+        ? { root: payloadRoot, foreign: false, candidate: null, refusal: null }
+        : admitMutationTargetSet(payloadRoot, mutationTargets, dispatchGit);
+    const effectiveRoot = admission.root;
+    const rootsNote = ` ${formatHookRootNote(payloadRoot, effectiveRoot)}`;
+    if (admission.foreign) {
+        const candidate = admission.candidate ?? "<none>";
+        const reason = admission.refusal === "worktree-span"
+            ? `write targets span more than one Git worktree (candidate=${candidate}).`
+            : admission.refusal === "unproven-identity"
+                ? `write target resolved to a separate Git working tree whose repository ` +
+                    `identity could not be read, so containment is unproven (candidate=${candidate}).`
+                : `write target is in a different Git repository ` +
+                    `than the hook payload root (candidate=${candidate}).`;
+        return deny(input, "foreign-repository-deny", toolName, `Directive denied ${toolName}: ${reason}${rootsNote}`);
+    }
     // Assist/scratch low-ceremony writes (#1802): allowlisted gitignored roots under
     // assist/ephemeral classification skip ritual + active-scope (no fake scope:activate).
     // Tracked product paths never match the path fence. Read-only still denied upstream.
     if (!isSpawnTool(toolName)) {
         const scratchTarget = hookWriteTargetPath(input.payload);
-        if (isAssistScratchWrite(projectRoot, scratchTarget, input.payload, environ)) {
+        // #3794 commit 2: classify against effectiveRoot. Relative to payloadRoot every
+        // file in a `.deft-scratch/worktrees/<x>/` worktree read as assist scratch, so
+        // assist/ephemeral worktree writes skipped ritual, occupancy and scope entirely.
+        if (isAssistScratchWrite(effectiveRoot, scratchTarget, input.payload, environ)) {
             const relPath = scratchTarget !== null ? toProjectRelativePosix(projectRoot, scratchTarget) : null;
             const authzDeny = authzForMutation(input, toolName, seams, {
                 isDirectWrite: true,
                 relPath,
                 scopePath: null,
+                runGit: dispatchGit,
             });
             if (authzDeny !== null)
                 return authzDeny;
-            const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, null);
+            const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, null, effectiveRoot);
             if (runtimeDeny !== null)
                 return runtimeDeny;
             return {
@@ -574,19 +759,88 @@ function inspectMutationGates(input, toolName, seams, options) {
             };
         }
     }
+    const actor = isSpawnTool(toolName) ? null : resolveMutationActor(input, environ);
+    const occupancyGate = isSpawnTool(toolName)
+        ? {
+            allow: true,
+            message: null,
+            occupant: null,
+            admitted: null,
+        }
+        : evaluateOccupancyWriteGate(effectiveRoot, {
+            sessionId: actor?.sessionId,
+            // Payload-supported hosts must not fall back to a stale ambient owner.
+            env: actor?.payloadAuthoritative === true ? {} : environ,
+        });
+    // #3769: occupancy decides before any ritual persist. The gated verifier
+    // executes agent_hooks and rebinds a forward HEAD, and both rewrite
+    // .deft/ritual-state.json — so verifying first let a session this gate was
+    // about to deny rewrite the occupant's record. The deny paths below read the
+    // ritual through the no-write inspect, which runs no step and never rebinds;
+    // only a session occupancy would admit reaches the verifier.
+    //
+    // Ritual detail on an occupancy deny is telemetry and message decoration, so
+    // an inspect failure must not convert an occupancy verdict into a ritual one.
+    const ritualDetailForOccupancyDeny = () => {
+        try {
+            return (seams.inspectRitual ??
+                seams.verifyRitual ??
+                ((root) => inspectSessionRitual(root, {
+                    tier: "gated",
+                    posture: "mutation",
+                    runGit: dispatchGit,
+                    requiredGatedSteps: WRITE_GATED_REQUIRED_STEPS,
+                })))(effectiveRoot);
+        }
+        catch {
+            return null;
+        }
+    };
+    if (occupancyGate.occupant !== null && actor?.issue !== null && actor !== null) {
+        const inspected = ritualDetailForOccupancyDeny();
+        const code = actor.issue === "conflict" ? "occupancy-identity-conflict" : "occupancy-identity-unavailable";
+        const detail = actor.message ??
+            "The host did not supply a usable cooperative session/conversation identity.";
+        emitSessionRitualBlockedProcessCost({
+            toolName,
+            code,
+            recoveryTier: inspected?.recoveryTier === "rearm" ? "rearm" : "cold",
+            detail,
+        }, { projectRoot });
+        return deny(input, code, toolName, `Directive denied ${toolName}: ${detail} A live occupancy lease exists for ` +
+            `session ${occupancyGate.occupant.sessionId}; use an exact host-mediated lifecycle ` +
+            "command or pass the matching --session-id explicitly." +
+            rootsNote);
+    }
+    if (!occupancyGate.allow && occupancyGate.message !== null) {
+        const inspected = ritualDetailForOccupancyDeny();
+        const ritualNote = inspected !== null && inspected.code !== 0
+            ? ` Also ritual-not-ready: ${inspected.message}`
+            : "";
+        emitSessionRitualBlockedProcessCost({
+            toolName,
+            code: "occupancy-occupied",
+            recoveryTier: inspected?.recoveryTier === "rearm" ? "rearm" : "cold",
+            detail: occupancyGate.message,
+        }, { projectRoot });
+        return deny(input, "occupancy-occupied", toolName, `Directive denied ${toolName}: ${occupancyGate.message}${ritualNote}${rootsNote}`);
+    }
     let ritual;
     try {
         // Mutation dispatch is a live gated boundary: active verification reruns
         // non-cacheable agent-hook readiness instead of trusting persisted success.
+        // Write-surface authority executes agent_hooks only (#3738). cache_fresh
+        // is not required and is never executed. doctor is read from the record.
         // Its allow fixture is non-write and its deny fixture is read-only, so the
         // installed-shim probe cannot recurse into this mutation path.
         ritual = (seams.verifyRitual ??
             seams.inspectRitual ??
-            ((root) => verifySessionRitual(root, {
-                tier: "gated",
-                posture: "mutation",
+            ((root) => verifySessionRitual(root, writeGateRitualOptions({
                 bypass: false,
-            })))(projectRoot);
+                runner: seams.ritualRunner,
+                detectWorkSelection: seams.detectWorkSelection,
+                runGit: dispatchGit,
+            }))))(effectiveRoot);
     }
     catch (cause) {
         // #2994: best-effort local process-cost; never changes deny verdict.
@@ -597,20 +851,36 @@ function inspectMutationGates(input, toolName, seams, options) {
             detail: `inspect threw: ${String(cause)}`,
         }, { projectRoot });
         return deny(input, "ritual-not-ready", toolName, `Directive could not inspect the gated session ritual: ${String(cause)}. ` +
-            formatRitualRecoveryInstruction("cold"));
+            formatRitualRecoveryInstruction("cold") +
+            rootsNote);
     }
-    const occupancyGate = isSpawnTool(toolName)
-        ? { allow: true, message: null, occupant: null }
-        : evaluateOccupancyWriteGate(projectRoot, { env: environ });
-    if (!occupancyGate.allow && occupancyGate.message !== null) {
-        const ritualNote = ritual.code !== 0 ? ` Also ritual-not-ready: ${ritual.message}` : "";
-        emitSessionRitualBlockedProcessCost({
-            toolName,
-            code: "occupancy-occupied",
-            recoveryTier: ritual.recoveryTier === "rearm" ? "rearm" : "cold",
-            detail: occupancyGate.message,
-        }, { projectRoot });
-        return deny(input, "occupancy-occupied", toolName, `Directive denied ${toolName}: ${occupancyGate.message}${ritualNote}`);
+    if (occupancyGate.occupant !== null && actor !== null) {
+        // A granted member writes under the owner's ceremony (#3755). Ritual state
+        // is single-owner and a child cannot bind its own while the owner's lease is
+        // live, so requiring the writer's own binding would make every admitted
+        // member's write unreachable — the grant would authorize nothing. What is
+        // checked instead is the identity that issued the grant: the tree's exact
+        // verified ritual owner must be the occupant whose lease admits this member.
+        const expectedOwner = occupancyGate.admitted === "member" ? occupancyGate.occupant.sessionId : actor.sessionId;
+        const verifiedOwner = ritual.boundSessionId;
+        const ritualOwnerMismatch = expectedOwner !== undefined &&
+            (verifiedOwner !== undefined ? verifiedOwner !== expectedOwner : ritual.code === 0);
+        if (ritualOwnerMismatch) {
+            const detail = verifiedOwner === undefined
+                ? "gated ritual verification returned ready without an exact bound owner"
+                : `exact verified ritual owner ${verifiedOwner} differs from host/lease owner ${expectedOwner}`;
+            emitSessionRitualBlockedProcessCost({
+                toolName,
+                code: "occupancy-ritual-mismatch",
+                recoveryTier: ritual.recoveryTier === "rearm" ? "rearm" : "cold",
+                detail,
+            }, { projectRoot });
+            return deny(input, "occupancy-ritual-mismatch", toolName, `Directive denied ${toolName}: ${detail}. ` +
+                "Run `deft session:start --rearm --session-id=<same-session-id>` when re-arm is eligible; " +
+                "otherwise run `deft session:start --session-id=<same-session-id>` for a cold ceremony. " +
+                "Intermediate lease/ritual mismatches fail closed." +
+                rootsNote);
+        }
     }
     if (ritual.code !== 0) {
         // #2992: prefer re-arm recovery when age/compact stale; cold when bind invalid.
@@ -622,23 +892,73 @@ function inspectMutationGates(input, toolName, seams, options) {
             recoveryTier,
             detail: ritual.message,
         }, { projectRoot });
-        return deny(input, "ritual-not-ready", toolName, `Directive denied ${toolName}: ${ritual.message} ${formatRitualRecoveryInstruction(recoveryTier)}`);
+        return deny(input, "ritual-not-ready", toolName, `Directive denied ${toolName}: ${ritual.message} ${formatRitualRecoveryInstruction(recoveryTier)}` +
+            rootsNote);
     }
+    // Narrow the cooperative file-gate race: authorization/scope checks can
+    // take long enough for another session to transition the lease. Re-read
+    // only occupancy immediately before each direct-write allow, while retaining
+    // the exact ritual owner above (never adopt a later ritual file here).
+    // #3599: the owner's lease is only kept alive here, on the last evaluation
+    // before an allowed write, so the stamp records a write that really happened.
+    let occupancyWarning = null;
+    const recheckOccupancyBeforeWriteAllow = () => {
+        if (actor === null)
+            return null;
+        const finalOccupancy = evaluateOccupancyWriteGate(effectiveRoot, {
+            sessionId: actor.sessionId,
+            env: actor.payloadAuthoritative ? {} : environ,
+            refresh: true,
+        });
+        occupancyWarning = finalOccupancy.warning;
+        if (finalOccupancy.occupant !== null && actor.issue !== null) {
+            return deny(input, actor.issue === "conflict"
+                ? "occupancy-identity-conflict"
+                : "occupancy-identity-unavailable", toolName, `Directive denied ${toolName}: the live occupancy owner changed while mutation ` +
+                "gates were running, and this hook has no unambiguous matching actor identity." +
+                rootsNote);
+        }
+        if (!finalOccupancy.allow && finalOccupancy.message !== null) {
+            return deny(input, "occupancy-occupied", toolName, `Directive denied ${toolName}: occupancy changed while mutation gates were running. ` +
+                finalOccupancy.message +
+                rootsNote);
+        }
+        // Same member rule as the pre-gate check above (#3755): an admitted member
+        // is measured against the occupant that granted it, not against itself.
+        const finalExpectedOwner = finalOccupancy.admitted === "member" && finalOccupancy.occupant !== null
+            ? finalOccupancy.occupant.sessionId
+            : actor.sessionId;
+        if (finalOccupancy.occupant !== null &&
+            finalExpectedOwner !== undefined &&
+            ritual.boundSessionId !== finalExpectedOwner) {
+            return deny(input, "occupancy-ritual-mismatch", toolName, `Directive denied ${toolName}: final lease owner ${finalExpectedOwner} does not match ` +
+                `the exact verified ritual owner ${ritual.boundSessionId ?? "<unbound>"}. ` +
+                "Run `deft session:start --rearm --session-id=<same-session-id>` when re-arm is eligible; " +
+                "otherwise run `deft session:start --session-id=<same-session-id>` for a cold ceremony." +
+                rootsNote);
+        }
+        return null;
+    };
+    const withOccupancyWarning = (message) => occupancyWarning === null ? message : `${message} ${occupancyWarning}`;
     if (options.proposedLifecycleExempt) {
         const writeTarget = hookWriteTargetPath(input.payload);
-        if (isProposedLifecycleWrite(projectRoot, writeTarget)) {
+        if (isProposedLifecycleWrite(effectiveRoot, writeTarget)) {
             const relPath = writeTarget !== null ? toProjectRelativePosix(projectRoot, writeTarget) : null;
             // UAT still allows xbrief/proposed/** as evidence/defect capture (#2944).
             const authzDeny = authzForMutation(input, toolName, seams, {
                 isDirectWrite: true,
                 relPath,
                 scopePath: null,
+                runGit: dispatchGit,
             });
             if (authzDeny !== null)
                 return authzDeny;
-            const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, null);
+            const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, null, effectiveRoot);
             if (runtimeDeny !== null)
                 return runtimeDeny;
+            const occupancyDeny = recheckOccupancyBeforeWriteAllow();
+            if (occupancyDeny !== null)
+                return occupancyDeny;
             return {
                 verdict: "allow",
                 code: "write-propose-ready",
@@ -646,26 +966,33 @@ function inspectMutationGates(input, toolName, seams, options) {
                 host: input.host,
                 toolName,
                 projectRoot,
-                message: `Directive write gate allowed ${toolName} for a proposed lifecycle xBRIEF ` +
-                    "(planning write; active scope not required).",
+                message: withOccupancyWarning(`Directive write gate allowed ${toolName} for a proposed lifecycle xBRIEF ` +
+                    "(planning write; active scope not required)."),
                 scopePath: null,
             };
         }
     }
     let scope;
     try {
-        scope = (seams.inspectScope ?? inspectActiveScope)(projectRoot);
+        // #3794 commit 2: a write is governed by the active scope of the worktree it
+        // lands in, not the primary checkout's. Admission has already proved
+        // effectiveRoot shares --git-common-dir with payloadRoot.
+        scope = (seams.inspectScope ?? inspectActiveScope)(effectiveRoot);
     }
     catch (cause) {
         scope = { ready: false, path: null, message: String(cause) };
     }
     if (!scope.ready) {
         const writeTarget = hookWriteTargetPath(input.payload);
-        const relTarget = writeTarget !== null ? toProjectRelativePosix(projectRoot, writeTarget) : null;
+        const relTarget = writeTarget !== null ? toProjectRelativePosix(effectiveRoot, writeTarget) : null;
         // Active-scope governs in-repo lifecycle work only. Outside-root Write/Edit
         // (agent memory, $TMPDIR, user config) skips the deny; null/unparseable
         // targets stay fail-closed. Spawn has no write target → still requires scope (#2885).
         // Lexical ../ + realpath re-entry guard (not bare startsWith(".."); not symlink aliases).
+        // #3794: the #2885 carve-out is measured from payloadRoot, so a linked
+        // worktree that lives outside the payload root keeps today's skip. Worktrees
+        // under the payload root -- `.deft-scratch/worktrees/`, the swarm layout --
+        // are inside it and are now gated on their own active scope.
         const outsideRoot = writeTarget !== null && isOutsideProjectRootWrite(projectRoot, writeTarget);
         if (!outsideRoot || isSpawnTool(toolName)) {
             let proposedPathHint;
@@ -705,7 +1032,17 @@ function inspectMutationGates(input, toolName, seams, options) {
                                 "assist posture (commands.md #1802) — do not fake `scope:activate` for notes.");
             }
             const denyCode = isSpawnTool(toolName) ? "spawn-not-ready" : "scope-not-ready";
-            return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
+            // #3794: the recovery has to run in the tree whose active scope was read.
+            // Once the two roots differ, "the project root" names no single directory
+            // the agent can act on, and activating in the payload root does not clear
+            // a deny measured against the worktree.
+            const recoveryRootNote = resolve(effectiveRoot) === payloadRoot
+                ? ""
+                : ` Active scope was read from ${effectiveRoot}, so run that recovery there rather than in ${payloadRoot}.`;
+            return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}` +
+                scopeNotReadyCoverageHint(toolName, loadRuntimeAuthorityPolicySafe(input, seams)?.shellDestForms === "enforce") +
+                recoveryRootNote +
+                rootsNote);
         }
     }
     const allowCode = isSpawnTool(toolName) ? "spawn-ready" : "write-ready";
@@ -724,12 +1061,16 @@ function inspectMutationGates(input, toolName, seams, options) {
             isDirectWrite: true,
             relPath,
             scopePath: scope.path,
+            runGit: dispatchGit,
         });
         if (authzDeny !== null)
             return authzDeny;
-        const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, scope.path);
+        const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, scope.path, effectiveRoot);
         if (runtimeDeny !== null)
             return runtimeDeny;
+        const occupancyDeny = recheckOccupancyBeforeWriteAllow();
+        if (occupancyDeny !== null)
+            return occupancyDeny;
     }
     return {
         verdict: "allow",
@@ -738,10 +1079,203 @@ function inspectMutationGates(input, toolName, seams, options) {
         host: input.host,
         toolName,
         projectRoot,
-        message: `Directive ${isSpawnTool(toolName) ? "spawn" : "write"} gate passed for ${toolName}.`,
+        message: withOccupancyWarning(`Directive ${isSpawnTool(toolName) ? "spawn" : "write"} gate passed for ${toolName}.`),
         scopePath: scope.path,
     };
 }
+/**
+ * Route recognized Shell dest-forms through inspectMutationGates, then push/merge.
+ * Dest-form allow is kept when runtime authority has nothing classifiable.
+ */
+function decideShellDestFormsThenRuntimeAuthority(input, toolName, seams) {
+    const command = hookShellCommand(input.payload);
+    let destAllow = null;
+    let expansionDeny = null;
+    // #3438 / #3594: opt-in. `off` (the default) leaves Shell exactly as it was
+    // before this gate existed — unrecognized and fail-open — so landing the
+    // classifier cannot deny anything a consumer runs today. `enforce` turns on
+    // BOTH halves together: resolved dests through inspectMutationGates and
+    // fail-closed for targets that cannot be proved. ⊗ Do not split those two:
+    // enforcing only resolved dests would allow `cd x && rm y` while denying
+    // `rm x/y`, and enforcing only fail-closed would deny the compound while
+    // letting the in-scope simple form through unchecked.
+    // An unreadable policy resolves to `off`, which is the no-new-denials
+    // direction and matches the opt-in default rather than failing closed.
+    const destFormsEnforced = loadRuntimeAuthorityPolicySafe(input, seams)?.shellDestForms === "enforce";
+    if (command !== null && destFormsEnforced) {
+        for (const dest of classifyProductDestForms(command)) {
+            if (dest.expansion === true) {
+                expansionDeny = deny(input, "scope-not-ready", toolName, `Directive denied ${toolName}: Shell dest-form target is not reconstructable ` +
+                    "(compound command, glob/variable, leading ~, or a git context option). Name a " +
+                    "concrete path in ONE simple command — split `cd x && rm y` into a single " +
+                    "`rm x/y`, or one tool call per command — or use Edit/Write. Only a single simple " +
+                    "command with an absolute dest is checked soundly; a relative dest assumes the " +
+                    "shell is at the project root. Everything else stays fail-closed (#3438).");
+                continue;
+            }
+            const destInput = {
+                ...input,
+                payload: payloadWithInjectedWriteTarget(input.payload, dest.path),
+            };
+            const destDecision = inspectMutationGates(destInput, toolName, seams, {
+                proposedLifecycleExempt: true,
+            });
+            if (destDecision.verdict === "deny")
+                return destDecision;
+            destAllow = destDecision;
+        }
+    }
+    const runtime = decideShellOrMcpRuntimeAuthority(input, toolName, seams);
+    if (runtime.verdict === "deny")
+        return runtime;
+    if (expansionDeny !== null)
+        return expansionDeny;
+    if (destAllow !== null && runtime.code === "shell-op-unclassifiable") {
+        return destAllow;
+    }
+    return runtime;
+}
+const LIFECYCLE_EXECUTION_DIRECTORY_FIELDS = [
+    "cwd",
+    "workdir",
+    "working_directory",
+    "workingDirectory",
+];
+function sameExecutionDirectory(left, right) {
+    if (process.platform === "win32")
+        return left.toLowerCase() === right.toLowerCase();
+    return left === right;
+}
+function lifecycleExecutionRootCheck(payload, projectRoot, realpath, platform) {
+    const input = record(payload);
+    if (input === null) {
+        return { aligned: false, message: "the hook payload has no inspectable execution root" };
+    }
+    const expected = normalizeHookProjectRoot(projectRoot);
+    const toolInput = toolInputRecord(input);
+    const records = toolInput === null || toolInput === input ? [input] : [input, toolInput];
+    for (const source of records) {
+        for (const field of LIFECYCLE_EXECUTION_DIRECTORY_FIELDS) {
+            if (!(field in source))
+                continue;
+            const raw = source[field];
+            if (typeof raw !== "string" || raw.trim().length === 0) {
+                return {
+                    aligned: false,
+                    message: `execution-directory field ${field} is missing or invalid`,
+                };
+            }
+            const trimmed = raw.trim();
+            // Cursor can report a drive-only cwd (for example `C:`) while the
+            // explicit/workspace-derived project root remains usable (#2787). Keep
+            // this fence aligned with projectRootFromHookPayload: a drive-only value
+            // is not a concrete execution directory and must not override that root.
+            if (isWindowsDriveOnlyRoot(trimmed, platform))
+                continue;
+            if (trimmed.replace(/\\/g, "/").split("/").includes("..")) {
+                return {
+                    aligned: false,
+                    message: `execution-directory field ${field} contains parent traversal`,
+                };
+            }
+            const candidate = isAbsolute(trimmed) ? trimmed : `${expected}${sep}${trimmed}`;
+            let actual;
+            let expectedReal;
+            try {
+                // Keep relative `..` segments intact until realpath resolution. Lexical
+                // path.resolve would collapse `link/..` before observing that `link`
+                // can be a symlink to a foreign tree.
+                expectedReal = normalizeHookProjectRoot(realpath(expected));
+                actual = normalizeHookProjectRoot(realpath(candidate));
+            }
+            catch (cause) {
+                return {
+                    aligned: false,
+                    message: `execution-directory field ${field} could not be realpath-bound: ${String(cause)}`,
+                };
+            }
+            if (!sameExecutionDirectory(actual, expectedReal)) {
+                return {
+                    aligned: false,
+                    message: `execution-directory field ${field} resolves to ${actual}, not the hook project ` +
+                        `root ${expectedReal}`,
+                };
+            }
+        }
+    }
+    return { aligned: true, message: "execution directory is project-root aligned" };
+}
+/**
+ * Add the claim-time owner only after the existing shell decision allowed the
+ * command. The host wire format must emit `allow` with updated input, so this
+ * path is intentionally restricted by rewriteExactLifecycleCommand.
+ */
+function attachLifecycleIdentityRewrite(input, toolName, decision, seams) {
+    if (decision.verdict !== "allow")
+        return decision;
+    const lifecycle = inspectExactLifecycleCommand(input.payload);
+    if (lifecycle === null)
+        return decision;
+    if (!lifecycle.requiresOwner)
+        return decision;
+    if (lifecycle.sessionIdStatus === "invalid") {
+        return deny(input, "occupancy-identity-conflict", toolName, `Directive denied exact lifecycle command ${lifecycle.verb}: ` +
+            "--session-id is empty, duplicated, or otherwise ambiguous.");
+    }
+    const identity = resolveHookHostIdentity(input.host, input.payload);
+    if (identity.status === "unsupported")
+        return decision;
+    if (identity.status !== "ok" || identity.sessionId === null) {
+        const code = identity.status === "conflict"
+            ? "occupancy-identity-conflict"
+            : "occupancy-identity-unavailable";
+        return deny(input, code, toolName, `Directive denied exact lifecycle command ${lifecycle.verb}: ` +
+            `${identity.message ?? "host payload identity is unavailable"}. ` +
+            "Directive cannot bind the occupancy claim without a stable host owner; " +
+            "manual callers must pass --session-id explicitly outside the host rewrite path.");
+    }
+    const environmentId = (input.environ ?? process.env).DEFT_SESSION_ID?.trim();
+    if (environmentId !== undefined &&
+        environmentId.length > 0 &&
+        environmentId !== identity.sessionId) {
+        return deny(input, "occupancy-identity-conflict", toolName, `Directive denied ${toolName}: host payload owner ${identity.sessionId} conflicts with ` +
+            `DEFT_SESSION_ID ${environmentId}; refusing an auto-approved lifecycle rewrite.`);
+    }
+    if (lifecycle.sessionIdStatus === "present" && lifecycle.sessionId !== identity.sessionId) {
+        return deny(input, "occupancy-identity-conflict", toolName, `Directive denied ${toolName}: lifecycle command ${lifecycle.verb} names ` +
+            `${lifecycle.sessionId ?? "<missing>"}, but the host payload owner is ` +
+            `${identity.sessionId}.`);
+    }
+    const sourceTask = !lifecycle.task ||
+        (seams.runningInsideDeftRepo ?? runningInsideDeftRepo)(resolve(input.projectRoot));
+    const executionRoot = lifecycleExecutionRootCheck(input.payload, input.projectRoot, seams.realpathLifecycleExecutionRoot ?? realpathSync, seams.lifecycleExecutionPlatform ?? process.platform);
+    if (!executionRoot.aligned) {
+        return deny(input, "occupancy-identity-conflict", toolName, `Directive denied exact lifecycle command ${lifecycle.verb}: ${executionRoot.message}. ` +
+            `Run the lifecycle command from ${normalizeHookProjectRoot(resolve(input.projectRoot))} ` +
+            "so policy, lease, and ritual state target the same worktree.");
+    }
+    const rewriteAllowed = lifecycle.rewriteSafe && sourceTask;
+    if (lifecycle.sessionIdStatus === "absent" && !rewriteAllowed) {
+        let reason;
+        if (lifecycle.task && !sourceTask) {
+            reason = "Task lifecycle rewrites are only trusted in the Directive source repository";
+        }
+        else {
+            reason = "this argument shape is outside the narrowly auto-approved rewrite surface";
+        }
+        return deny(input, "occupancy-identity-unavailable", toolName, `Directive denied exact lifecycle command ${lifecycle.verb}: ${reason}. ` +
+            `Re-run the command with --session-id=${identity.sessionId}; Directive will verify ` +
+            "that explicit owner without auto-approving or replacing the command.");
+    }
+    const rewrite = rewriteExactLifecycleCommand(input.payload, identity.sessionId);
+    if (rewrite === null)
+        return decision;
+    if (rewrite.kind === "conflict") {
+        return deny(input, "occupancy-identity-conflict", toolName, `Directive denied ${toolName}: ${rewrite.message} Host payload owner is ` +
+            `${identity.sessionId}, but the command names ${rewrite.existingSessionId}.`);
+    }
+    return { ...decision, updatedInput: rewrite.updatedInput };
+}
 /** Decide a normalized event using only the P0 direct-write policy. */
 export function decideHook(input, seams = {}) {
     const projectRoot = resolve(input.projectRoot);
@@ -749,6 +1283,8 @@ export function decideHook(input, seams = {}) {
     // short-circuit (SessionStart / compact / PreToolUse). Deposit may remain.
     // Tracked/committed flags do NOT bypass gates (repo-controlled content must
     // not disable enforcement for clones) — doctor warns instead.
+    // #3794: the kill-switch is pinned to payloadRoot. The flag is untracked, so
+    // linked worktrees do not carry it; re-pointing would silently re-arm.
     {
         const detectKill = seams.detectDeftDirectiveDisable ?? detectDeftDirectiveDisable;
         const kill = detectKill(projectRoot);
@@ -775,6 +1311,12 @@ export function decideHook(input, seams = {}) {
         }
     }
     if (input.event === "session.compact") {
+        // #3769 Path 2: compact stays always-allow and never routes through
+        // inspectMutationGates — entering the mutation gates would re-run the
+        // ritual persist Path 1 closes, or occupancy-deny an owner's own compact.
+        // The stale-mark is fail-open: it writes even when no acting identity can
+        // be bound, because compact has no issue context and no surface a human
+        // reads. The accepted cost is an unidentified compact re-arming the owner.
         try {
             const result = (seams.markCompactStale ?? markRitualStaleAfterCompact)(projectRoot);
             if (!result.changed) {
@@ -930,13 +1472,17 @@ export function decideHook(input, seams = {}) {
         }
         return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: false });
     }
-    // Shell/Bash and classifiable MCP: enforce scopes.push / scopes.merge (#2711).
+    // Shell dest-forms (#3438): recognized product mutations share inspectMutationGates
+    // with Edit/Write (assist/scratch, proposed lifecycle, file_scope). Push/merge stay
+    // on runtimeAuthority (#2711). Non-dest unclassifiable shell (git status) fail-open.
+    if (isShellTool(toolName)) {
+        const decision = decideShellDestFormsThenRuntimeAuthority(input, toolName, seams);
+        return attachLifecycleIdentityRewrite(input, toolName, decision, seams);
+    }
+    // Classifiable MCP: enforce scopes.push / scopes.merge (#2711).
     // Route bare push/merge MCP names (merge_pull_request, git_push, …) even when
     // isMcpTool is false — classifyMcpTool is the gate (dispatcher-side, no tools↔policy cycle).
-    // Does not require active-scope ritual — only runtimeAuthority when enabled.
-    if (isShellTool(toolName) ||
-        isMcpTool(toolName) ||
-        classifyMcpTool(toolName, hookMcpArgsText(input.payload)) !== null) {
+    if (isMcpTool(toolName) || classifyMcpTool(toolName, hookMcpArgsText(input.payload)) !== null) {
         return decideShellOrMcpRuntimeAuthority(input, toolName, seams);
     }
     if (!isDirectWriteTool(toolName)) {
@@ -986,6 +1532,24 @@ function softAgentsRebindWireText(decision) {
  */
 export function renderHostDecision(host, decision) {
     if (decision.verdict === "allow") {
+        if (decision.event === "tool.before" && decision.updatedInput !== undefined) {
+            if (host === "cursor") {
+                return JSON.stringify({
+                    permission: "allow",
+                    code: decision.code,
+                    updated_input: decision.updatedInput,
+                });
+            }
+            if (host === "claude" || host === "codex") {
+                return JSON.stringify({
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "allow",
+                        updatedInput: decision.updatedInput,
+                    },
+                });
+            }
+        }
         const soft = softAgentsRebindWireText(decision);
         if (host === "cursor") {
             if (decision.event === "session.start" && soft !== null) {