@deftai/directive-runtime 0.126.0-beta.1 → 0.126.0-beta.3

package/vendor/directive-core/dist/session/occupancy.js

@@ -75,13 +75,30 @@ import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { assertAppendLockOwned, withAppendLock } from "../slice/lock.js";
 import { SWARM_WORKER_ROLES } from "../swarm/routing.js";
 import { recordChildOccupancyLease } from "./child-occupancy.js";
-import { ambientHostSessionOwner, claimsHostSessionIdShape, detectDeclaredIdentityHosts, isUsableHostSessionId, parseCanonicalHostSessionId, printCompanionHostOwner, } from "./host-session-owner.js";
+import { worktreePathOrNull } from "./git.js";
+import { ambientHostSessionOwner, canonicalHostSessionId, claimsHostSessionIdShape, detectDeclaredIdentityHosts, HOST_IDENTITY_PROVIDERS, isUsableHostSessionId, parseCanonicalHostSessionId, printCompanionHostOwner, } from "./host-session-owner.js";
 import { stableJson } from "./json.js";
 import { isLinkedWorktreePath, isMainWorktreePath, listLinkedWorktreeCheckouts, mainWorktreeRoot, } from "./main-worktree.js";
 import { readRitualState } from "./ritual-sentinel.js";
 import { parseTimestamp, timestampIso } from "./time.js";
 export const OCCUPANCY_SCHEMA_VERSION = 1;
 export const OCCUPANCY_RELPATH = [".deft", "occupancy.json"];
+/**
+ * Harbor / cell bootstrap signal (#5544 Prefer-A): a declared agent host will
+ * attach to this tree. Claimer surface is Harbor ritual applying
+ * `applyWorktreeOccupancy`. When set, last-resort UUID mint is refused so the
+ * later host can self-claim.
+ */
+export const DEFT_EXPECTED_DECLARED_HOST_ATTACH = "DEFT_EXPECTED_DECLARED_HOST_ATTACH";
+/** Worktree applying-host record for multi-host PreToolUse deposits (#5676). */
+export const APPLYING_HOST_RELPATH = [".deft", "applying-host.json"];
+export const APPLYING_HOST_SCHEMA = "deft.applying-host.v1";
+/**
+ * Applying-host staleness floor (#5676). Mirrors tip ritual staleness (8h) so a
+ * reconnect SessionStart / read-only session:start republish stays in the same
+ * recovery window as ceremony re-arm; UUID residual stays under #5544.
+ */
+export const APPLYING_HOST_STALE_MS = Number("8") * 60 * 60 * 1000;
 /** Crash recovery TTL: 20 minutes without heartbeat (15–30 window). */
 export const OCCUPANCY_TTL_MS = 20 * 60 * 1000;
 /**
@@ -227,6 +244,381 @@ export const OCCUPANCY_MAX_GRANTS = 32;
 export function occupancyPath(projectRoot) {
     return join(resolve(projectRoot), ...OCCUPANCY_RELPATH);
 }
+export function applyingHostPath(projectRoot) {
+    return join(resolve(projectRoot), ...APPLYING_HOST_RELPATH);
+}
+function isHookHostIdentityProvider(value) {
+    return HOST_IDENTITY_PROVIDERS.includes(value);
+}
+function parseApplyingHostPayload(payload) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const row = payload;
+    if (row.schema !== APPLYING_HOST_SCHEMA)
+        return null;
+    if (typeof row.provider !== "string" || !isHookHostIdentityProvider(row.provider))
+        return null;
+    if (typeof row.rawSessionId !== "string" || !isUsableHostSessionId(row.rawSessionId))
+        return null;
+    if (typeof row.applyingHostSessionId !== "string")
+        return null;
+    if (typeof row.claimed_at !== "string" || parseTimestamp(row.claimed_at) === null)
+        return null;
+    const transport = row.transport === "grok-hook-event" ? "grok-hook-event" : "native";
+    const expected = canonicalHostSessionId(row.provider, row.rawSessionId);
+    if (row.applyingHostSessionId !== expected)
+        return null;
+    return {
+        schema: APPLYING_HOST_SCHEMA,
+        provider: row.provider,
+        rawSessionId: row.rawSessionId,
+        applyingHostSessionId: expected,
+        claimed_at: row.claimed_at,
+        transport,
+    };
+}
+/** Read the worktree applying-host record (#5676). */
+export function readApplyingHost(projectRoot, now = new Date()) {
+    const path = applyingHostPath(projectRoot);
+    try {
+        if (!existsSync(path))
+            return { status: "missing", record: null };
+    }
+    catch {
+        return { status: "missing", record: null };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+    }
+    catch {
+        return {
+            status: "invalid",
+            record: null,
+            message: "applying-host record is unreadable; republish via SessionStart or read-only session:start",
+        };
+    }
+    const record = parseApplyingHostPayload(payload);
+    if (record === null) {
+        return {
+            status: "invalid",
+            record: null,
+            message: "applying-host record is malformed; republish via SessionStart or read-only session:start",
+        };
+    }
+    const claimedAt = parseTimestamp(record.claimed_at);
+    if (claimedAt === null) {
+        return {
+            status: "invalid",
+            record: null,
+            message: "applying-host record has invalid claimed_at; republish via SessionStart or read-only session:start",
+        };
+    }
+    if (now.getTime() - claimedAt.getTime() > APPLYING_HOST_STALE_MS) {
+        return {
+            status: "stale",
+            record,
+            message: formatApplyingHostRepairDiagnostic("stale"),
+        };
+    }
+    return { status: "ok", record };
+}
+/**
+ * Supported repair when the applying-host record is missing, stale, or
+ * conflicting (#5676 Prefer-A Recut-5). Mutation session:start is reinforcement
+ * only — first publication is SessionStart or read-only session:start.
+ */
+export function formatApplyingHostRepairDiagnostic(reason = "missing") {
+    const subject = reason === "missing"
+        ? "Applying-host record is missing"
+        : reason === "stale"
+            ? "Applying-host record is stale"
+            : reason === "conflicting"
+                ? "Applying-host record conflicts with this host session"
+                : "Applying-host record is invalid";
+    return (`${subject}. Republish via host SessionStart reconnect and/or ` +
+        "`deft session:start --read-only --session-id=<applyingHostSessionId>` " +
+        "before retrying mutation lifecycle. UUID / Harbor residuals stay under #5544.");
+}
+/** Write/replace the worktree applying-host record (#5676). */
+export function publishApplyingHost(projectRoot, input) {
+    if (!isUsableHostSessionId(input.rawSessionId)) {
+        throw new Error("publishApplyingHost: rawSessionId is not a usable host session id");
+    }
+    const root = resolve(projectRoot);
+    const claimedAt = input.claimedAt ?? new Date();
+    const record = {
+        schema: APPLYING_HOST_SCHEMA,
+        provider: input.provider,
+        rawSessionId: input.rawSessionId,
+        applyingHostSessionId: canonicalHostSessionId(input.provider, input.rawSessionId),
+        claimed_at: timestampIso(claimedAt),
+        transport: input.transport ?? "native",
+    };
+    const target = applyingHostPath(root);
+    assertWriteTargetSafe(root, target);
+    const dir = dirname(target);
+    const tmpName = join(dir, `.applying-host.${process.pid}.json.tmp`);
+    const text = `${stableJson(record, 2)}\n`;
+    try {
+        containedWrite({ root, target: tmpName, data: text, mode: "create" });
+        renameSync(tmpName, target);
+    }
+    finally {
+        try {
+            rmSync(tmpName, { force: true });
+        }
+        catch {
+            /* best-effort cleanup of tmp only */
+        }
+    }
+    return record;
+}
+/**
+ * Publish from a canonical `host:<provider>:v1:<base64url>` owner (#5676).
+ * Returns null when the id is not canonical (opaque UUID leftovers stay #5544).
+ */
+export function publishApplyingHostFromCanonicalSessionId(projectRoot, sessionId, opts = {}) {
+    const parsed = parseCanonicalHostSessionId(sessionId.trim());
+    if (parsed === null)
+        return null;
+    return publishApplyingHost(projectRoot, {
+        provider: parsed.provider,
+        rawSessionId: parsed.rawSessionId,
+        claimedAt: opts.claimedAt,
+        transport: opts.transport,
+    });
+}
+/**
+ * Lifecycle admission against the applying-host record (#5676).
+ *
+ * Matching deposits enforce `applyingHostSessionId`. Non-matching deposits
+ * soft-pass only when the command already names that id. Missing/stale/
+ * conflicting records name SessionStart / read-only repair. Absent record with
+ * no flip-flop shape returns `absent` so single-host flows keep prior behavior.
+ */
+export function evaluateApplyingHostLifecycleAdmission(input) {
+    const read = readApplyingHost(input.projectRoot, input.now ?? new Date());
+    if (read.status === "invalid") {
+        return {
+            kind: "repair",
+            record: null,
+            message: read.message,
+        };
+    }
+    if (read.status === "stale") {
+        // Live occupancy owner cleanup when applying-host TTL elapsed but the lease
+        // is still heartbeat-fresh (#5676 Greptile P1). Soft-pass only when argv
+        // already names that live owner so bare commands keep the rewrite path.
+        const staleLive = liveOccupant(input.projectRoot, input.now ?? new Date());
+        const staleLiveId = staleLive?.sessionId ?? null;
+        const staleNamed = input.namedSessionId?.trim() || null;
+        if (staleLiveId !== null &&
+            read.record.applyingHostSessionId === staleLiveId &&
+            staleNamed === staleLiveId) {
+            return {
+                kind: "soft-pass",
+                record: read.record,
+                reason: "live-lease-owner-cleanup",
+            };
+        }
+        return { kind: "repair", record: read.record, message: read.message };
+    }
+    if (read.status === "missing" || read.record === null) {
+        const named = input.namedSessionId?.trim() || null;
+        const deposit = input.depositSessionId?.trim() || null;
+        if (named !== null && deposit !== null && named !== deposit) {
+            const namedParts = parseCanonicalHostSessionId(named);
+            const depositParts = parseCanonicalHostSessionId(deposit);
+            if (namedParts !== null &&
+                depositParts !== null &&
+                namedParts.rawSessionId === depositParts.rawSessionId &&
+                namedParts.provider !== depositParts.provider) {
+                return {
+                    kind: "repair",
+                    record: null,
+                    message: formatApplyingHostRepairDiagnostic("missing"),
+                };
+            }
+        }
+        return { kind: "absent", record: null };
+    }
+    const record = read.record;
+    // Live occupancy owner cleanup when a later SessionStart replaced applying-host
+    // (#5676 Greptile P1). Only soft-pass when argv already names that live owner so
+    // bare commands still take the rewrite path (do not skip --session-id injection).
+    const live = liveOccupant(input.projectRoot, input.now ?? new Date());
+    const liveId = live?.sessionId ?? null;
+    const named = input.namedSessionId?.trim() || null;
+    if (liveId !== null && record.applyingHostSessionId !== liveId && named === liveId) {
+        return {
+            kind: "soft-pass",
+            record,
+            reason: "live-lease-owner-cleanup",
+        };
+    }
+    if (isHookHostIdentityProvider(input.depositHost) &&
+        input.depositHost === record.provider &&
+        input.depositSessionId !== null &&
+        input.depositSessionId !== record.applyingHostSessionId) {
+        const depositParts = parseCanonicalHostSessionId(input.depositSessionId);
+        if (depositParts === null || depositParts.rawSessionId !== record.rawSessionId) {
+            return {
+                kind: "repair",
+                record,
+                message: formatApplyingHostRepairDiagnostic("conflicting"),
+            };
+        }
+    }
+    const matchingDeposit = input.depositHost === record.provider;
+    if (!matchingDeposit) {
+        // Soft-pass only when argv already names applyingHostSessionId (#5676).
+        // Bare commands must not skip the owner rewrite / explicit-owner gate.
+        if (named === record.applyingHostSessionId) {
+            return {
+                kind: "soft-pass",
+                record,
+                reason: "non-matching-deposit-names-applying-host",
+            };
+        }
+        return {
+            kind: "foreign-owner",
+            record,
+            namedSessionId: named,
+            message: named === null
+                ? `Directive refused bare lifecycle command; applying-host is ` +
+                    `${record.applyingHostSessionId}. Re-run with ` +
+                    `--session-id=${record.applyingHostSessionId}.`
+                : `Directive refused foreign owner ${named}; applying-host is ` +
+                    `${record.applyingHostSessionId}. Re-run with ` +
+                    `--session-id=${record.applyingHostSessionId}.`,
+        };
+    }
+    if (named !== null && named !== record.applyingHostSessionId) {
+        return {
+            kind: "foreign-owner",
+            record,
+            namedSessionId: named,
+            message: `Directive refused foreign owner ${named}; applying-host is ` +
+                `${record.applyingHostSessionId}. Re-run with ` +
+                `--session-id=${record.applyingHostSessionId}.`,
+        };
+    }
+    return {
+        kind: "enforce",
+        record,
+        matchingDeposit: true,
+    };
+}
+/**
+ * Resolve the lease root CLI and hooks share for the same worktree (#5544 P2).
+ *
+ * Uses the Git worktree toplevel when available (same tree hooks select when
+ * payload alone gates, or when writes stay inside that worktree). Linked
+ * worktrees keep their own toplevel — never collapsed into the main checkout.
+ */
+const occupancyLeaseRootCache = new Map();
+/**
+ * Process-local cache so Write-hook double probes (preview + refresh) and
+ * nested readOccupancy calls do not re-shell `git rev-parse` for the same path.
+ */
+export function resolveOccupancyLeaseRoot(projectRoot) {
+    const absolute = resolve(projectRoot);
+    const cached = occupancyLeaseRootCache.get(absolute);
+    if (cached !== undefined)
+        return cached;
+    const toplevel = worktreePathOrNull(absolute);
+    const root = toplevel ?? absolute;
+    occupancyLeaseRootCache.set(absolute, root);
+    occupancyLeaseRootCache.set(root, root);
+    return root;
+}
+/** Print the occupancy file (and optional Write-gate effectiveRoot) (#5544 P2). */
+export function formatOccupancyLeaseViewNote(occupancyFilePath, options = {}) {
+    const parts = [`occupancyFile=${occupancyFilePath}`];
+    if (options.effectiveRoot !== undefined && options.effectiveRoot.length > 0) {
+        parts.push(`effectiveRoot=${options.effectiveRoot}`);
+    }
+    return parts.join(" ");
+}
+export function formatOccupancyAlreadyFree(occupancyFilePath, options = {}) {
+    return `occupancy already free (${formatOccupancyLeaseViewNote(occupancyFilePath, options)})`;
+}
+export function expectedDeclaredHostAttachSignaled(input = {}) {
+    if (input.expectedDeclaredHostAttach === true)
+        return true;
+    const raw = (input.env ?? process.env)[DEFT_EXPECTED_DECLARED_HOST_ATTACH]?.trim() ?? "";
+    if (raw.length === 0)
+        return false;
+    return raw === "1" || raw.toLowerCase() === "true" || raw.toLowerCase() === "yes";
+}
+export function formatOccupancyExpectedHostMintRefusal() {
+    return ("occupancy refuses last-resort mint: Harbor/bootstrap signaled a declared agent host will attach " +
+        `(${DEFT_EXPECTED_DECLARED_HOST_ATTACH}=1 or expectedDeclaredHostAttach). ` +
+        "Claimer surface: Harbor ritual applying applyWorktreeOccupancy. " +
+        "Default is host-self-claim after attach. Stay read-only (`session:start --read-only`) or skip mutation session:start. " +
+        "If a pre-attach mutation lease is required, bind the exact later host session id " +
+        "(`session:start --session-id=<host:provider:v1:...>`) and release successfully before agent launch — " +
+        "failed cleanup blocks launch (assertOccupancyFreeForHostLaunch).");
+}
+/**
+ * Harbor launch gate (#5544 Prefer-A): failed pre-attach occupancy cleanup
+ * blocks agent launch. Exit 0 only when this lease root is free.
+ */
+export function assertOccupancyFreeForHostLaunch(projectRoot, input = {}) {
+    const root = resolveOccupancyLeaseRoot(projectRoot);
+    const path = occupancyPath(root);
+    const live = liveOccupant(root, input.now ?? new Date());
+    if (live === null) {
+        return {
+            action: "released",
+            sessionId: "",
+            record: null,
+            path,
+            message: formatOccupancyAlreadyFree(path),
+            code: 0,
+        };
+    }
+    const occupantArg = commandSessionId(live.sessionId, "<reported-session-id>");
+    return {
+        action: "denied",
+        sessionId: "",
+        record: live,
+        path,
+        message: `Harbor launch blocked: live occupancy lease still holds (${formatOccupancyLeaseViewNote(path)}). ` +
+            `session=${live.sessionId}. Failed pre-attach cleanup blocks launch. ` +
+            `Release with \`occupancy:release --session-id=${occupantArg} --project-root=${root}\` before attaching the agent host.`,
+        code: 1,
+    };
+}
+/**
+ * Narrow #5544 Prefer-A P3 gate: live minted lease + canonical host-shaped
+ * presenter may steal under confirm. Does not broaden steal defaults.
+ */
+export function occupancyMintedDeclaredHostStealAdmitted(record, presented) {
+    if (record.identityProvenance !== "minted")
+        return false;
+    const actor = presented?.trim() ?? "";
+    if (actor.length === 0)
+        return false;
+    return parseCanonicalHostSessionId(actor) !== null;
+}
+export function formatOccupancyMintedDeclaredHostStealRemediation(record, presented, projectRoot) {
+    const root = projectRoot !== undefined ? resolveOccupancyLeaseRoot(projectRoot) : undefined;
+    const path = root !== undefined ? occupancyPath(root) : undefined;
+    const occupantArg = commandSessionId(record.sessionId, "<reported-session-id>");
+    const hostArg = commandSessionId(presented, "<host-published-id>");
+    const rootFlag = root !== undefined ? ` --project-root=${JSON.stringify(root)}` : "";
+    const view = path !== undefined ? ` Lease view: ${formatOccupancyLeaseViewNote(path)}.` : "";
+    const rootNote = root !== undefined ? ` Target root: ${root}.` : "";
+    return (`Closed recovery for a minted lease while host-shaped presenter ${presented} is already on this tree:${view}${rootNote} ` +
+        `Run \`occupancy:steal --occupant=${occupantArg} --session-id=${hostArg} --confirm${rootFlag}\`` +
+        `. That is the permitted lease operation under the minted+declared-host gate (not a broad steal default). ` +
+        "Steal changes the lease only; then restore ceremony as the same presenter: " +
+        `\`session:start --rearm --session-id=${hostArg}${rootFlag}\` when re-arm is eligible, otherwise ` +
+        `\`session:start --session-id=${hostArg}${rootFlag}\` for a cold ceremony. ` +
+        "Owner-only UUID release then host re-claim remains available but is not the primary agent path.");
+}
 /**
  * Whether a stored lease names this worktree (#3926).
  *
@@ -430,7 +822,7 @@ function isOwnInheritedPresentation(occupantId, presented) {
 }
 /** Advisory coordination preface for occupancy denials (#3729 Prefer-A AC4). */
 export const OCCUPANCY_ADVISORY_COORDINATION_PREFACE = "Occupancy is advisory coordination for accidental same-machine collision, not same-user authorization.";
-export function formatOccupancyRemediation(record, now = new Date(), presented, env) {
+export function formatOccupancyRemediation(record, now = new Date(), presented, env, projectRoot) {
     const age = heartbeatAgeSeconds(record, now);
     const header = `${OCCUPANCY_ADVISORY_COORDINATION_PREFACE}\n` +
         `Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago, ` +
@@ -439,6 +831,13 @@ export function formatOccupancyRemediation(record, now = new Date(), presented,
     const worktreeFirst = "Use another worktree.";
     const occupantArg = commandSessionId(record.sessionId, "<reported-session-id>");
     if (record.identityProvenance === "minted") {
+        // #5544 Prefer-A P3: when a canonical host-shaped id is already presenting,
+        // replace "Do not steal" with the closed steal-then-ceremony path.
+        const hostPresenter = presented?.trim() ?? "";
+        if (occupancyMintedDeclaredHostStealAdmitted(record, hostPresenter)) {
+            return (`${header}This lease was claimed under a minted owner. No later hook process can present that id.\n` +
+                `${formatOccupancyMintedDeclaredHostStealRemediation(record, hostPresenter, projectRoot)}`);
+        }
         const hosts = detectDeclaredIdentityHosts(env ?? process.env);
         const suggested = uniquePrintCompanion(hosts, env ?? process.env);
         const named = suggested === null
@@ -446,7 +845,8 @@ export function formatOccupancyRemediation(record, now = new Date(), presented,
             : commandSessionId(suggested, "<host-published-id>");
         return (`${header}This lease was claimed under a minted owner. No later hook process can present that id.\n` +
             `${formatOccupancySkipMutationClaimWhenMinted()}\n` +
-            `${worktreeFirst} Do not steal this lease. Stay read-only (\`session:start --read-only\`), or ` +
+            `${worktreeFirst} Do not steal this lease unless a declared host-shaped id is already presenting ` +
+            `(then use the minted+declared-host \`occupancy:steal\` gate). Stay read-only (\`session:start --read-only\`), or ` +
             `release it (\`occupancy:release --session-id=${occupantArg}\` / \`session:end\`) and re-claim ` +
             `with the host-published owner (\`session:start --session-id=${named}\`).${tail}`);
     }
@@ -624,6 +1024,35 @@ export function formatPresentedIdentityDisagreement(identity) {
  */
 export function resolveOccupancySessionClaim(input = {}) {
     const identity = resolvePresentedIdentity(input);
+    // #5544 Prefer-A: when Harbor signals expected declared-host attach, the only
+    // pre-attach mutation exception is an explicit argv --session-id that is
+    // already host-shaped. Inherited DEFT_SESSION_ID (even host-shaped) and
+    // opaque ids are refused so the later host is not locked out.
+    if (expectedDeclaredHostAttachSignaled(input)) {
+        const explicitHostBind = identity.source === "explicit" &&
+            identity.sessionId.length > 0 &&
+            parseCanonicalHostSessionId(identity.sessionId) !== null;
+        if (explicitHostBind) {
+            return {
+                status: "ok",
+                sessionId: identity.sessionId,
+                provenance: "explicit",
+                source: "explicit",
+            };
+        }
+        if (identity.sessionId.length > 0 || identity.disagreeingHostOwner !== null) {
+            return {
+                status: "refuse-mint",
+                sessionId: "",
+                provenance: null,
+                source: "mint",
+                hosts: [],
+                suggestedSessionId: null,
+                message: formatOccupancyExpectedHostMintRefusal(),
+            };
+        }
+        // No presented identity yet — fall through to declared-host / empty-mint refuse.
+    }
     // #4066: host-authoritative claim. Inherited DEFT_SESSION_ID must not beat the
     // host-published owner -- that split is the measured steal-from-self loop.
     if (identity.source === "environment" && identity.disagreeingHostOwner !== null) {
@@ -658,6 +1087,20 @@ export function resolveOccupancySessionClaim(input = {}) {
             message,
         };
     }
+    // #5544 Prefer-A P1: Harbor pre-attach empty-hosts mint window. Signal closes
+    // last-resort mint before the declared host attaches; exact --session-id bind
+    // is the only pre-attach mutation exception (already returned above when set).
+    if (expectedDeclaredHostAttachSignaled(input)) {
+        return {
+            status: "refuse-mint",
+            sessionId: "",
+            provenance: null,
+            source: "mint",
+            hosts: [],
+            suggestedSessionId: null,
+            message: formatOccupancyExpectedHostMintRefusal(),
+        };
+    }
     return {
         status: "ok",
         sessionId: (input.newSessionId ?? randomUUID)(),
@@ -696,6 +1139,8 @@ function occupancyMintRefusalDecision(projectRoot, claim) {
     };
 }
 export function readOccupancy(projectRoot) {
+    // #5544: reads share the claim/release lease-root view.
+    projectRoot = resolveOccupancyLeaseRoot(projectRoot);
     const path = occupancyPath(projectRoot);
     try {
         if (!existsSync(path))
@@ -796,6 +1241,8 @@ export const OCCUPANCY_CEREMONY_CASES = [
  * session:ready. Matches persist, including the sibling-lease primary fence.
  */
 export function evaluateOccupancyCeremonyEligibility(projectRoot, input = {}) {
+    // #5544: same lease-root view as claim / release / Write-gate.
+    projectRoot = resolveOccupancyLeaseRoot(projectRoot);
     const now = input.now ?? new Date();
     const claim = resolveOccupancySessionClaim(input);
     if (claim.status === "refuse-mint") {
@@ -822,7 +1269,7 @@ export function evaluateOccupancyCeremonyEligibility(projectRoot, input = {}) {
             sessionId: incoming,
             occupantId: live.sessionId,
             restrictedPrimary,
-            denialMessage: formatOccupancyRemediation(live, now, incoming, input.env),
+            denialMessage: formatOccupancyRemediation(live, now, incoming, input.env, projectRoot),
         };
     }
     if (live !== null) {
@@ -830,7 +1277,7 @@ export function evaluateOccupancyCeremonyEligibility(projectRoot, input = {}) {
         if (admission === "member") {
             const grant = occupancyGrantFor(live, incoming, now);
             const memberText = grant === null
-                ? formatOccupancyRemediation(live, now, incoming, input.env)
+                ? formatOccupancyRemediation(live, now, incoming, input.env, projectRoot)
                 : formatOccupancyMemberAdministrationRefusal(live, grant, "session:start");
             return {
                 admitCeremony: false,
@@ -848,7 +1295,7 @@ export function evaluateOccupancyCeremonyEligibility(projectRoot, input = {}) {
                 sessionId: incoming,
                 occupantId: live.sessionId,
                 restrictedPrimary,
-                denialMessage: formatOccupancyRemediation(live, now, incoming, input.env),
+                denialMessage: formatOccupancyRemediation(live, now, incoming, input.env, projectRoot),
             };
         }
         return {
@@ -903,6 +1350,8 @@ export function evaluateOccupancyCeremonyEligibility(projectRoot, input = {}) {
     };
 }
 export function applyWorktreeOccupancy(projectRoot, input = {}) {
+    // #5544: claim/read/release share one lease-root view (git worktree toplevel).
+    projectRoot = resolveOccupancyLeaseRoot(projectRoot);
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
     const claim = resolveOccupancySessionClaim(input);
@@ -942,7 +1391,7 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
             // A granted child reads the member refusal rather than an offer of the
             // write grant it already holds (#3954 item 5): membership admits writes,
             // and claiming the lease stays owner-only.
-            message: membershipOwnerDenial(live, incoming, now, "session:start"),
+            message: membershipOwnerDenial(live, incoming, now, "session:start", projectRoot),
             code: 1,
         };
     }
@@ -976,7 +1425,7 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
                 sessionId: incoming,
                 record: liveLocked,
                 path,
-                message: membershipOwnerDenial(liveLocked, incoming, now, "session:start"),
+                message: membershipOwnerDenial(liveLocked, incoming, now, "session:start", projectRoot),
                 code: 1,
             };
         }
@@ -1068,6 +1517,8 @@ function occupancyStealUsesMintedWriter(input, claim) {
     return claim.status === "ok" && (claim.provenance === "minted" || claim.source === "mint");
 }
 export function stealOccupancy(projectRoot, input = {}) {
+    // #5544: steal uses the same lease-root view as claim/release.
+    projectRoot = resolveOccupancyLeaseRoot(projectRoot);
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
     const claim = resolveOccupancySessionClaim(input);
@@ -1099,7 +1550,9 @@ export function stealOccupancy(projectRoot, input = {}) {
         // Show the occupant's write recency before the steal, not only after it
         // (#3599): heartbeat age alone hides an occupant that is mid-edit.
         const liveCurrent = liveOccupancyOnTree(projectRoot, current, now);
-        const occupantDetail = liveCurrent !== null ? `\n${formatOccupancyRemediation(liveCurrent, now)}` : "";
+        const occupantDetail = liveCurrent !== null
+            ? `\n${formatOccupancyRemediation(liveCurrent, now, undefined, undefined, projectRoot)}`
+            : "";
         return {
             action: "denied",
             sessionId: incoming,
@@ -1145,7 +1598,7 @@ export function stealOccupancy(projectRoot, input = {}) {
             record: live,
             path,
             message: `occupancy:steal named occupant ${named} does not match live occupant ${live.sessionId}.\n` +
-                formatOccupancyRemediation(live, now),
+                formatOccupancyRemediation(live, now, undefined, undefined, projectRoot),
             code: 1,
         };
     }
@@ -1189,7 +1642,7 @@ export function stealOccupancy(projectRoot, input = {}) {
                 record: liveLocked,
                 path,
                 message: `occupancy:steal named occupant ${named} does not match live occupant ${liveLocked.sessionId}.\n` +
-                    formatOccupancyRemediation(liveLocked, now),
+                    formatOccupancyRemediation(liveLocked, now, undefined, undefined, projectRoot),
                 code: 1,
             };
         }
@@ -1224,16 +1677,19 @@ export function stealOccupancy(projectRoot, input = {}) {
             };
         }
         const record = written.record;
+        const root = resolve(projectRoot);
         return {
             action: "stolen",
             sessionId: record.sessionId,
             record,
             path,
             message: `occupancy stolen from ${named}${priorClock}; writer is now session ${record.sessionId}. ` +
+                `Lease view: ${formatOccupancyLeaseViewNote(path)}. Target root: ${root}. ` +
+                `Presenter/writer: ${record.sessionId}. Permitted lease operation completed: occupancy:steal. ` +
                 "This command changes the lease only; direct writes remain denied unless ritual state already names the same owner. " +
-                "If the owners differ, 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, using the writer ID above.",
+                "Required ceremony: 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, using the writer ID above.",
             code: 0,
         };
     }, input.lockDeps);
@@ -1254,23 +1710,26 @@ export function stealOccupancy(projectRoot, input = {}) {
  */
 export function releaseOccupancy(projectRoot, input = {}) {
     const now = input.now ?? new Date();
-    const path = occupancyPath(projectRoot);
+    // #5544 P2: share the lease-root view CLI and Write hooks use for this tree.
+    const root = resolveOccupancyLeaseRoot(projectRoot);
+    const path = occupancyPath(root);
     const identity = resolvePresentedIdentity(input);
     const caller = identity.sessionId;
     const split = formatPresentedIdentityDisagreement(identity);
-    return withOccupancyLock(projectRoot, (fence) => {
-        const existing = readOccupancy(projectRoot);
+    const leaseNote = ` ${formatOccupancyLeaseViewNote(path)}`;
+    return withOccupancyLock(root, (fence) => {
+        const existing = readOccupancy(root);
         if (existing === null) {
             return {
                 action: "released",
                 sessionId: caller,
                 record: null,
                 path,
-                message: "occupancy already free",
+                message: formatOccupancyAlreadyFree(path),
                 code: 0,
             };
         }
-        const expired = liveOccupancyOnTree(projectRoot, existing, now) === null;
+        const expired = liveOccupancyOnTree(root, existing, now) === null;
         const owns = caller.length > 0 && caller === existing.sessionId;
         if (!expired && !owns) {
             return {
@@ -1278,7 +1737,9 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: existing,
                 path,
-                message: membershipOwnerDenial(existing, caller, now, "occupancy:release") + split,
+                message: membershipOwnerDenial(existing, caller, now, "occupancy:release", root) +
+                    split +
+                    leaseNote,
                 code: 1,
             };
         }
@@ -1286,6 +1747,8 @@ export function releaseOccupancy(projectRoot, input = {}) {
         // never stamp Prefer-A marker / rewrite AGENTS.md for a denied caller (#4544 P1).
         // Session exit with this-session untracked product evidence must still reach
         // enforce when markWrite persist never ran (Shell-bypass / hookless).
+        // Prefer-A #5544 residual / babysit P1: header check uses the supplied project
+        // root (consumer AGENTS.md), not the git lease root (which may be a parent repo).
         const evidenceGate = enforceConsumerHeaderPlaceholderWhenProductEvidence(projectRoot);
         if (!evidenceGate.ok) {
             return {
@@ -1293,19 +1756,19 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: existing,
                 path,
-                message: evidenceGate.message,
+                message: evidenceGate.message + leaseNote,
                 code: 1,
             };
         }
         fence();
-        const still = readOccupancy(projectRoot);
+        const still = readOccupancy(root);
         if (still === null) {
             return {
                 action: "released",
                 sessionId: caller,
                 record: null,
                 path,
-                message: "occupancy already free",
+                message: formatOccupancyAlreadyFree(path),
                 code: 0,
             };
         }
@@ -1318,17 +1781,19 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: still,
                 path,
-                message: membershipOwnerDenial(still, caller, now, "occupancy:release") + split,
+                message: membershipOwnerDenial(still, caller, now, "occupancy:release", root) +
+                    split +
+                    leaseNote,
                 code: 1,
             };
         }
-        removeOccupancyFile(projectRoot, fence);
+        removeOccupancyFile(root, fence);
         return {
             action: "released",
             sessionId: still.sessionId,
             record: null,
             path,
-            message: `occupancy released session ${still.sessionId}`,
+            message: `occupancy released session ${still.sessionId} (${formatOccupancyLeaseViewNote(path)})`,
             code: 0,
         };
     }, input.lockDeps);
@@ -1374,6 +1839,8 @@ function ritualAlignedAfterAcquisition(projectRoot, acquired) {
  * this persist.
  */
 export function rollbackAcquiredOccupancy(projectRoot, acquired, input = {}) {
+    // #5544: rollback must target the same lease root claim wrote.
+    projectRoot = resolveOccupancyLeaseRoot(projectRoot);
     const path = occupancyPath(projectRoot);
     if (!isPersistTimeAcquisition(acquired.action)) {
         return {
@@ -1393,7 +1860,7 @@ export function rollbackAcquiredOccupancy(projectRoot, acquired, input = {}) {
                 sessionId: acquired.sessionId,
                 record: null,
                 path,
-                message: "occupancy already free",
+                message: formatOccupancyAlreadyFree(path),
                 code: 0,
             };
         }
@@ -1425,7 +1892,7 @@ export function rollbackAcquiredOccupancy(projectRoot, acquired, input = {}) {
                 sessionId: acquired.sessionId,
                 record: null,
                 path,
-                message: "occupancy already free",
+                message: formatOccupancyAlreadyFree(path),
                 code: 0,
             };
         }
@@ -1470,10 +1937,10 @@ export function rollbackAcquiredOccupancy(projectRoot, acquired, input = {}) {
  * have chosen explicitly, so a refusal that does not name what was presented
  * leaves it guessing which identity it was refused under.
  */
-function membershipOwnerDenial(live, caller, now, verb) {
+function membershipOwnerDenial(live, caller, now, verb, projectRoot) {
     const grant = occupancyGrantFor(live, caller, now);
     return grant === null
-        ? formatOccupancyRemediation(live, now, caller)
+        ? formatOccupancyRemediation(live, now, caller, undefined, projectRoot)
         : formatOccupancyMemberAdministrationRefusal(live, grant, verb);
 }
 /**
@@ -1486,6 +1953,8 @@ function membershipOwnerDenial(live, caller, now, verb) {
  * cap — and it buys writes alone.
  */
 export function grantOccupancyMembership(projectRoot, input = {}) {
+    // #5544: membership verbs share claim/release lease-root view.
+    projectRoot = resolveOccupancyLeaseRoot(projectRoot);
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
     const identity = resolvePresentedIdentity(input);
@@ -1604,7 +2073,7 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
                 sessionId: owner,
                 record: live,
                 path,
-                message: membershipOwnerDenial(live, owner, now, "occupancy:grant") + split,
+                message: membershipOwnerDenial(live, owner, now, "occupancy:grant", projectRoot) + split,
                 code: 1,
             };
         }
@@ -1695,6 +2164,8 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
  * never have been admitted, and the owner wants that true now.
  */
 export function revokeOccupancyMembership(projectRoot, input = {}) {
+    // #5544: membership verbs share claim/release lease-root view.
+    projectRoot = resolveOccupancyLeaseRoot(projectRoot);
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
     const identity = resolvePresentedIdentity(input);
@@ -1734,7 +2205,8 @@ export function revokeOccupancyMembership(projectRoot, input = {}) {
                 sessionId: owner,
                 record: live,
                 path,
-                message: membershipOwnerDenial(live, owner, now, "occupancy:grant --revoke") + split,
+                message: membershipOwnerDenial(live, owner, now, "occupancy:grant --revoke", projectRoot) +
+                    split,
                 code: 1,
             };
         }
@@ -1795,6 +2267,10 @@ export function revokeOccupancyMembership(projectRoot, input = {}) {
  */
 export function evaluateOccupancyWriteGate(projectRoot, input = {}) {
     const now = input.now ?? new Date();
+    // #5544: lease identity is always the git worktree toplevel. leaseRoot is only
+    // a preferred base path (hook effectiveRoot may be a subdirectory when writes
+    // leave the git tree); never skip resolve, or read/match disagree (#5544 P1).
+    projectRoot = resolveOccupancyLeaseRoot(input.leaseRoot ?? projectRoot);
     const incoming = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
     const stored = readOccupancy(projectRoot);
     const record = stored !== null && occupancyWorktreeMatches(stored.worktreePath, projectRoot) ? stored : null;
@@ -1848,12 +2324,16 @@ export function evaluateOccupancyWriteGate(projectRoot, input = {}) {
         // Two-axis unknown-identity axis (#3729 Prefer-A): live lease + stranger →
         // fail closed (OCCUPANCY_UNKNOWN_IDENTITY_POLICY). Advisory coordination,
         // not authorization — prefer another worktree / grant over steal-as-primary.
+        // #5544 P2: name the occupancy file (and effectiveRoot when the Write gate
+        // supplies this projectRoot) so CLI/hook split-brain is diagnosable.
+        const path = occupancyPath(projectRoot);
         return {
             allow: false,
             // The refused caller is told what identity it actually presented (#3873).
             // A hook process cannot otherwise know, and the grant this message offers
             // is only runnable when the occupant can name a non-empty child.
-            message: formatOccupancyRemediation(live, now, incoming, input.env),
+            message: `${formatOccupancyRemediation(live, now, incoming, input.env, projectRoot)} ` +
+                formatOccupancyLeaseViewNote(path, { effectiveRoot: projectRoot }),
             occupant: live,
             refreshed: false,
             warning: null,
@@ -2031,6 +2511,8 @@ persistProductMutationMarker = false) {
  * heartbeat into long verbs cannot close that deadlock: this verb is owner-only.
  */
 export function heartbeatOccupancy(projectRoot, input = {}) {
+    // #5544: heartbeat shares claim/release lease-root view.
+    projectRoot = resolveOccupancyLeaseRoot(projectRoot);
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
     const identity = resolvePresentedIdentity(input);
@@ -2072,7 +2554,7 @@ export function heartbeatOccupancy(projectRoot, input = {}) {
             sessionId: caller,
             record: live,
             path,
-            message: membershipOwnerDenial(live, caller, now, "occupancy:heartbeat") + split,
+            message: membershipOwnerDenial(live, caller, now, "occupancy:heartbeat", projectRoot) + split,
             code: 1,
         };
     }