@deftai/directive-core 0.108.0 → 0.109.1

package/dist/session/occupancy.js

@@ -19,6 +19,25 @@
  * composite hook write gate measures the tree's verified ritual owner against
  * the occupant that issued the grant, not against the writer.
  *
+ * Parent and child, answered per identity-source kind (#3954, and it does not
+ * have one answer). On a `host-env` host the parent and its dispatched children
+ * are different actors, because the host publishes a different id into each
+ * agent session. The answer there is identity, not automatic membership: each
+ * side resolves its own owner through the shared lookup chain below and claims
+ * its own worktree, which is where the dispatch envelope already puts it.
+ * Membership stays explicit and owner-issued for the deliberate same-tree case,
+ * and it stays affordable only that way -- 32 grants at a four-hour TTL against
+ * a twenty-minute lease means granting on every dispatch exhausts a busy
+ * parent's lease inside a day. The revocation trigger is therefore the owner's
+ * own `occupancy:grant --revoke`, or expiry; releasing a child's lease on its
+ * terminal event is dispatcher lifecycle in `child-occupancy.ts` (#3999).
+ * On a `payload` host parent and subagents share one id, so there is no foreign
+ * child lease to admit and nothing to grant -- and the live consequence is the
+ * inverse one: `owns` is true for both, so a parent's `occupancy:release`
+ * removes a working child's lease mid-flight with no denial. That is a property
+ * of shared host identity, not of this module; a bearer boundary cannot
+ * distinguish two processes presenting one string.
+ *
  * Concurrency model:
  * - Assumptions: local filesystem; cooperating processes on one machine.
  * - Guarantees: mutual exclusion under crash-free operation; detect-and-abort
@@ -40,6 +59,8 @@ import { containedRemove, containedWrite } from "../fs/contained-write.js";
 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, parseCanonicalHostSessionId, } from "./host-session-owner.js";
 import { stableJson } from "./json.js";
 import { parseTimestamp, timestampIso } from "./time.js";
 export const OCCUPANCY_SCHEMA_VERSION = 1;
@@ -166,6 +187,19 @@ export function occupancyAdmission(record, sessionId, now = new Date()) {
         return "owner";
     return occupancyGrantFor(record, presented, now) === null ? "stranger" : "member";
 }
+// Session ids reach remediation text from operator flags, host environments and
+// whatever a peer wrote into the lease, so a value can carry whitespace or shell
+// metacharacters. Only a value a shell would take as one bare token is inlined
+// into a printed command; anything else keeps its placeholder, because the right
+// quoting differs per shell and a mis-parsed copyable command is worse than one
+// the reader has to fill in. The id itself is still named in the prose above.
+// A leading dash is excluded as well: every CLI parser here reads such a value
+// as another option, so `--occupant --weird-id` fails argument parsing even
+// though the shell itself would have passed the token through intact.
+const SHELL_SAFE_SESSION_ID = /^(?!-)[A-Za-z0-9_.:+=,/-]+$/;
+function commandSessionId(sessionId, placeholder) {
+    return SHELL_SAFE_SESSION_ID.test(sessionId) ? sessionId : placeholder;
+}
 function occupancyClockLine(record) {
     const lastWrite = record.lastWriteAt === null ? "" : ` last_write_at=${timestampIso(record.lastWriteAt)}`;
     return `claimed_at=${timestampIso(record.claimedAt)} heartbeat_at=${timestampIso(record.heartbeatAt)}${lastWrite}`;
@@ -178,7 +212,7 @@ export function formatOccupancyStaleWarning(record, now = new Date(), ttlMs = OC
     const age = heartbeatAgeSeconds(record, now);
     return (`Occupancy lease for session ${record.sessionId} has not beaten for ${age}s of its ` +
         `${Math.round(ttlMs / 1000)}s window; another session may read it as abandoned. ` +
-        `Refresh it with \`deft occupancy:heartbeat --session-id=${record.sessionId}\`.`);
+        `Refresh it with \`deft occupancy:heartbeat --session-id=${commandSessionId(record.sessionId, "<your-session-id>")}\`.`);
 }
 /**
  * Tell the holder its lease aged out of the absolute cap (#3599). Distinct
@@ -191,17 +225,45 @@ export function formatOccupancyAgeCapRemediation(record, now = new Date(), maxLe
         `(claimed ${leaseAgeSeconds(record, now)}s ago, ${occupancyClockLine(record)}), so this ` +
         "worktree is no longer held and a peer may claim it at any moment. Heartbeats cannot " +
         "extend a capped lease — re-claim the worktree with " +
-        `\`deft session:start --session-id=${record.sessionId}\` before writing again.`);
+        `\`deft session:start --session-id=${commandSessionId(record.sessionId, "<your-session-id>")}\` before writing again.`);
 }
-export function formatOccupancyRemediation(record, now = new Date()) {
+/**
+ * Tell a refused caller who holds the lease and what it can actually run.
+ *
+ * `presented` is the id the refused caller offered (#3873). Without it the
+ * message can only print `<your-session-id>` placeholders, which is fine for a
+ * CLI caller that passed its own `--session-id` and useless to a hook process,
+ * which does not know what identity it presented. Passing it also keeps the
+ * message honest when there is none: a grant cannot name an empty child --
+ * `occupancy:grant --child-session-id=` is refused at parse and at membership --
+ * so that remediation is not printed to a caller who could never run it.
+ */
+export function formatOccupancyRemediation(record, now = new Date(), presented) {
     const age = heartbeatAgeSeconds(record, now);
-    return (`Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago, ` +
-        `${formatLastWritePhrase(record, now)}, ${occupancyClockLine(record)}).\n` +
+    const header = `Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago, ` +
+        `${formatLastWritePhrase(record, now)}, ${occupancyClockLine(record)}).\n`;
+    const tail = "\nThe occupant may release (`occupancy:release` / `session:end`).";
+    if (presented === undefined) {
+        return (`${header}Stay read-only (\`session:start --read-only\`), use another worktree,\n` +
+            "ask the occupant for a write grant (`occupancy:grant --child-session-id=<your-session-id> " +
+            "--role <worker-role>`, run by the occupant), or run a confirmed owner transition " +
+            `(\`session:start --steal --confirm --occupant <reported-session-id> --session-id=<your-session-id>\`).${tail}`);
+    }
+    const actor = presented.trim();
+    const occupantArg = commandSessionId(record.sessionId, "<reported-session-id>");
+    if (actor.length === 0) {
+        return (`${header}This process presented no session identity, so a write grant cannot name it ` +
+            "and an owner transition would not be recognised on its next write.\n" +
+            "Stay read-only (`session:start --read-only`), use another worktree, or ask the occupant " +
+            `to release the lease (\`occupancy:release --session-id=${occupantArg}\` / \`session:end\`).${tail}`);
+    }
+    const actorArg = commandSessionId(actor, "<your-session-id>");
+    return (`${header}This process presented session ${actor}, which neither holds that lease nor has a ` +
+        "write grant on it.\n" +
         "Stay read-only (`session:start --read-only`), use another worktree,\n" +
-        "ask the occupant for a write grant (`occupancy:grant --child-session-id=<your-session-id> " +
+        `ask the occupant for a write grant (\`occupancy:grant --child-session-id=${actorArg} ` +
         "--role <worker-role>`, run by the occupant), or run a confirmed owner transition " +
-        "(`session:start --steal --confirm --occupant <reported-session-id> --session-id=<your-session-id>`).\n" +
-        "The occupant may release (`occupancy:release` / `session:end`).");
+        `(\`session:start --steal --confirm --occupant ${occupantArg} --session-id=${actorArg}\`).${tail}`);
 }
 /**
  * Refuse an administrative verb to a granted child (#3755). Named apart from
@@ -215,13 +277,74 @@ export function formatOccupancyMemberAdministrationRefusal(record, grant, verb)
         "grant never escalates into administration.\n" +
         `Ask the occupant (session ${record.sessionId}) to run it, or wait for the grant to expire.`);
 }
-export function resolveOccupancySessionId(input = {}) {
+/**
+ * The one lookup order every occupancy surface shares (#3954): an explicit
+ * `--session-id`, then `DEFT_SESSION_ID`, then the owner the running host
+ * published.
+ *
+ * The terminal is the caller's, not this function's. Claim mints, because
+ * claiming establishes an identity where none exists. Release, heartbeat and
+ * grant/revoke are proving one, so they take the empty string and keep the
+ * diagnosis written for it -- a shared mint would replace "you presented
+ * nothing" with a plausible id no later hook will ever present, on every host
+ * that publishes no owner of its own.
+ *
+ * Disagreement is reported, not resolved. The order stands, so an explicit id
+ * beats the environment and the environment beats the host; what changes is
+ * that a refused caller is told the host names someone else, which is the state
+ * a stale inherited `DEFT_SESSION_ID` produces and the one an operator cannot
+ * otherwise see.
+ */
+export function resolvePresentedIdentity(input = {}) {
+    const env = input.env ?? process.env;
+    const hostOwner = ambientHostSessionOwner(env);
+    const disagreement = (chosen) => hostOwner !== null && hostOwner !== chosen ? hostOwner : null;
     const explicit = input.sessionId?.trim();
-    if (explicit)
-        return explicit;
-    const envId = (input.env ?? process.env).DEFT_SESSION_ID?.trim();
-    if (envId)
-        return envId;
+    if (explicit) {
+        return {
+            sessionId: explicit,
+            source: "explicit",
+            disagreeingHostOwner: disagreement(explicit),
+        };
+    }
+    const envId = env.DEFT_SESSION_ID?.trim();
+    if (envId) {
+        return { sessionId: envId, source: "environment", disagreeingHostOwner: disagreement(envId) };
+    }
+    if (hostOwner !== null) {
+        return { sessionId: hostOwner, source: "host", disagreeingHostOwner: null };
+    }
+    return { sessionId: "", source: "none", disagreeingHostOwner: null };
+}
+/**
+ * Name a claimer-versus-presenter split on a refusal, or return "" (#3954).
+ *
+ * Appended only to denials: while the caller is admitted the split costs it
+ * nothing, and on a refusal it is the one fact that explains why an id the
+ * operator believes is theirs is being treated as a stranger's.
+ */
+export function formatPresentedIdentityDisagreement(identity) {
+    const other = identity.disagreeingHostOwner;
+    if (other === null)
+        return "";
+    const named = identity.source === "explicit" ? "The id passed on the command line" : "DEFT_SESSION_ID";
+    return (`\n${named} names session ${identity.sessionId}, but this host published ` +
+        `${other}. Those are different sessions: re-run with ` +
+        `\`--session-id=${commandSessionId(other, "<host-published-id>")}\` to act as the host owner.`);
+}
+/**
+ * The owner a claim is made under: the shared lookup chain, then a mint.
+ *
+ * The host step is what makes an identified host's claim reachable (#3873).
+ * Minting instead binds the lease to an id no later hook process can present,
+ * so the session that claimed the worktree is refused by its own lease. The
+ * mint stays as the last resort for hosts that publish nothing, and it is the
+ * one terminal the prove-surfaces deliberately do not share (#3954).
+ */
+export function resolveOccupancySessionId(input = {}) {
+    const presented = resolvePresentedIdentity(input).sessionId;
+    if (presented.length > 0)
+        return presented;
     return (input.newSessionId ?? randomUUID)();
 }
 export function readOccupancy(projectRoot) {
@@ -263,7 +386,10 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
             sessionId: incoming,
             record: live,
             path,
-            message: formatOccupancyRemediation(live, now),
+            // 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"),
             code: 1,
         };
     }
@@ -288,7 +414,7 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
                 sessionId: incoming,
                 record: liveLocked,
                 path,
-                message: formatOccupancyRemediation(liveLocked, now),
+                message: membershipOwnerDenial(liveLocked, incoming, now, "session:start"),
                 code: 1,
             };
         }
@@ -309,6 +435,9 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
             grants: liveLocked === null ? [] : liveOccupancyGrants(liveLocked, now),
         }, fence);
         const action = liveLocked !== null ? "heartbeat" : "claimed";
+        if (action === "claimed") {
+            maybeRecordChildOccupancyOnClaim(projectRoot, incoming, input.env);
+        }
         return {
             action,
             sessionId: record.sessionId,
@@ -321,6 +450,32 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
         };
     }, input.lockDeps);
 }
+/**
+ * Stamp the dispatch-recorded child occupancy store at claim time (#3999).
+ * Pre-dispatch / worktree mkdir cannot know a host-env child's occupancy
+ * owner; the claiming process does. Heartbeat `agent_id` on this host is the
+ * raw GROK_SESSION_ID, so that is the store key the terminal monitor looks up.
+ */
+function maybeRecordChildOccupancyOnClaim(projectRoot, occupancyOwner, env) {
+    const resolved = env ?? process.env;
+    const grokRaw = resolved.GROK_SESSION_ID?.trim() ?? "";
+    const agentId = grokRaw.length > 0 ? grokRaw : occupancyHost(env);
+    if (agentId.length === 0 || agentId === "none")
+        return;
+    const parentId = occupancyAddress(env);
+    try {
+        recordChildOccupancyLease(projectRoot, {
+            agentId,
+            parentId,
+            occupancyOwner,
+            worktreePath: resolve(projectRoot),
+            identitySourceKind: grokRaw.length > 0 ? "host-env" : "payload",
+        });
+    }
+    catch {
+        // Claim already succeeded; a missing dispatch record is a no-op on terminal.
+    }
+}
 export function stealOccupancy(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
@@ -451,10 +606,26 @@ export function stealOccupancy(projectRoot, input = {}) {
         };
     }, input.lockDeps);
 }
+/**
+ * Release the caller's own lease.
+ *
+ * Owner-only, deliberately (#3954 item 4, answering the open question the
+ * design-critique arc left for the builder). Letting an unidentified caller
+ * release the occupant the lease file itself records would make possession of
+ * that file path into authority to delete a live lease, which is exactly what
+ * the `!expired && !owns` refusal exists to prevent -- and the cooperative
+ * bearer model (#3755) has no second check behind it. The unreachable printed
+ * recovery is fixed by the shared lookup chain instead: on a host that
+ * publishes an owner, the occupant now resolves itself and a bare
+ * `occupancy:release` is the occupant, so the message the deny prints is one
+ * the party it addresses can actually run.
+ */
 export function releaseOccupancy(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
-    const caller = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    const identity = resolvePresentedIdentity(input);
+    const caller = identity.sessionId;
+    const split = formatPresentedIdentityDisagreement(identity);
     return withOccupancyLock(projectRoot, (fence) => {
         const existing = readOccupancy(projectRoot);
         if (existing === null) {
@@ -475,7 +646,7 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: existing,
                 path,
-                message: membershipOwnerDenial(existing, caller, now, "occupancy:release"),
+                message: membershipOwnerDenial(existing, caller, now, "occupancy:release") + split,
                 code: 1,
             };
         }
@@ -500,7 +671,7 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: still,
                 path,
-                message: membershipOwnerDenial(still, caller, now, "occupancy:release"),
+                message: membershipOwnerDenial(still, caller, now, "occupancy:release") + split,
                 code: 1,
             };
         }
@@ -515,10 +686,18 @@ export function releaseOccupancy(projectRoot, input = {}) {
         };
     }, input.lockDeps);
 }
+/**
+ * Refuse an owner-only verb, saying which of the three the caller is.
+ *
+ * The caller is passed to `formatOccupancyRemediation` as the presented id
+ * (#3954): every one of these surfaces now resolves an actor the caller may not
+ * 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) {
     const grant = occupancyGrantFor(live, caller, now);
     return grant === null
-        ? formatOccupancyRemediation(live, now)
+        ? formatOccupancyRemediation(live, now, caller)
         : formatOccupancyMemberAdministrationRefusal(live, grant, verb);
 }
 /**
@@ -533,7 +712,9 @@ function membershipOwnerDenial(live, caller, now, verb) {
 export function grantOccupancyMembership(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
-    const owner = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    const identity = resolvePresentedIdentity(input);
+    const owner = identity.sessionId;
+    const split = formatPresentedIdentityDisagreement(identity);
     const child = input.childSessionId?.trim() ?? "";
     const role = input.role?.trim() ?? "";
     if (owner.length === 0) {
@@ -569,6 +750,46 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
             code: 2,
         };
     }
+    // #3954 item 3. A child id under the reserved `host:` prefix must be a
+    // well-formed canonical owner: measured, `host:nosuchhost:v9:zzzz` and
+    // `host:grok:v1:!!!not-base64url!!!` were granted and then admitted as
+    // `member` by the write gate, so the lease read as membership while admitting
+    // nobody. An id outside that prefix is still accepted, because a child on a
+    // host with no identity contract presents whatever `DEFT_SESSION_ID` holds
+    // and refusing that would deny a grant nothing has measured wrong.
+    if (claimsHostSessionIdShape(child) && parseCanonicalHostSessionId(child) === null) {
+        return {
+            action: "denied",
+            sessionId: owner,
+            record: readOccupancy(projectRoot),
+            path,
+            message: `occupancy:grant refuses the child id ${child}: the \`host:\` prefix is reserved for ` +
+                "host-published identity, and this is not a well-formed owner " +
+                "(`host:<provider>:v1:<base64url>`), so no session could ever present it. Pass the id " +
+                "the child's own host publishes, or an opaque id the child sets as DEFT_SESSION_ID.",
+            code: 2,
+        };
+    }
+    // Same defect one step subtler: re-prefixing the owner's own payload under a
+    // second provider passes the shape check and is a self-grant in disguise --
+    // no session on that other host would present it, and the owner already holds
+    // the lease outright.
+    const childParts = parseCanonicalHostSessionId(child);
+    const ownerParts = parseCanonicalHostSessionId(owner);
+    if (childParts !== null &&
+        ownerParts !== null &&
+        childParts.rawSessionId === ownerParts.rawSessionId) {
+        return {
+            action: "denied",
+            sessionId: owner,
+            record: readOccupancy(projectRoot),
+            path,
+            message: `occupancy:grant refuses the child id ${child}: it carries this lease owner's own host ` +
+                `session (${ownerParts.rawSessionId}) under provider ${childParts.provider}. That is a ` +
+                "self-grant across a provider prefix, and the child it names cannot exist.",
+            code: 2,
+        };
+    }
     if (!SWARM_WORKER_ROLES.includes(role)) {
         return {
             action: "denied",
@@ -596,7 +817,7 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
                 message: capped && current !== null
                     ? formatOccupancyAgeCapRemediation(current, now)
                     : "occupancy:grant found no live lease to grant on. A grant is derived authority, " +
-                        `so claim the worktree first with \`deft session:start --session-id=${owner}\`.`,
+                        `so claim the worktree first with \`deft session:start --session-id=${commandSessionId(owner, "<your-session-id>")}\`.`,
                 code: 1,
             };
         }
@@ -606,7 +827,7 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
                 sessionId: owner,
                 record: live,
                 path,
-                message: membershipOwnerDenial(live, owner, now, "occupancy:grant"),
+                message: membershipOwnerDenial(live, owner, now, "occupancy:grant") + split,
                 code: 1,
             };
         }
@@ -687,7 +908,11 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
 export function revokeOccupancyMembership(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
-    const owner = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    const identity = resolvePresentedIdentity(input);
+    const owner = identity.sessionId;
+    const split = formatPresentedIdentityDisagreement(identity);
+    // Revoke deliberately skips the grant-time child-id checks: a malformed grant
+    // written before those checks existed must stay withdrawable (#3954 item 3).
     const child = input.childSessionId?.trim() ?? "";
     if (owner.length === 0 || child.length === 0) {
         return {
@@ -720,7 +945,7 @@ export function revokeOccupancyMembership(projectRoot, input = {}) {
                 sessionId: owner,
                 record: live,
                 path,
-                message: membershipOwnerDenial(live, owner, now, "occupancy:grant --revoke"),
+                message: membershipOwnerDenial(live, owner, now, "occupancy:grant --revoke") + split,
                 code: 1,
             };
         }
@@ -809,7 +1034,10 @@ export function evaluateOccupancyWriteGate(projectRoot, input = {}) {
     if (admission === "stranger") {
         return {
             allow: false,
-            message: formatOccupancyRemediation(live, now),
+            // 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),
             occupant: live,
             refreshed: false,
             warning: null,
@@ -948,7 +1176,9 @@ memberSessionId) {
 export function heartbeatOccupancy(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
-    const caller = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
+    const identity = resolvePresentedIdentity(input);
+    const caller = identity.sessionId;
+    const split = formatPresentedIdentityDisagreement(identity);
     if (caller.length === 0) {
         return {
             action: "denied",
@@ -974,7 +1204,7 @@ export function heartbeatOccupancy(projectRoot, input = {}) {
             message: capped && existing !== null
                 ? formatOccupancyAgeCapRemediation(existing, now)
                 : "occupancy:heartbeat found no live lease to refresh. Claim one with " +
-                    `\`deft session:start --session-id=${caller}\`.`,
+                    `\`deft session:start --session-id=${commandSessionId(caller, "<your-session-id>")}\`.`,
             code: 1,
         };
     }
@@ -984,7 +1214,7 @@ export function heartbeatOccupancy(projectRoot, input = {}) {
             sessionId: caller,
             record: live,
             path,
-            message: membershipOwnerDenial(live, caller, now, "occupancy:heartbeat"),
+            message: membershipOwnerDenial(live, caller, now, "occupancy:heartbeat") + split,
             code: 1,
         };
     }
@@ -1014,10 +1244,18 @@ export function heartbeatOccupancy(projectRoot, input = {}) {
         code: 0,
     };
 }
-/** Close-out identity comes from the launch manifest or DEFT_SESSION_ID — never occupancy.json. */
+/**
+ * Close-out identity comes from the launch manifest, `DEFT_SESSION_ID`, or the
+ * owner the running host published — never occupancy.json (#3954).
+ *
+ * Reading the lease for identity would be the anonymous recorded-occupant
+ * release refused in `releaseOccupancy`; the host step is the same shared
+ * lookup chain every other occupancy surface uses, so a cohort launched on a
+ * host that publishes an owner can close out without an explicit id.
+ */
 export function releaseSwarmOccupancy(projectRoot, input = {}) {
     const env = input.env ?? process.env;
-    const sessionId = input.sessionId?.trim() || env.DEFT_SESSION_ID?.trim() || "";
+    const sessionId = resolvePresentedIdentity({ sessionId: input.sessionId, env }).sessionId;
     if (sessionId.length === 0) {
         const occupant = readOccupancy(projectRoot);
         return {
@@ -1025,9 +1263,9 @@ export function releaseSwarmOccupancy(projectRoot, input = {}) {
             sessionId: "",
             record: occupant,
             path: occupancyPath(projectRoot),
-            message: "swarm close-out has no occupancy_session_id (manifest missing or predates the field) " +
-                "and DEFT_SESSION_ID is unset. Re-establish an aligned owner with " +
-                "session:start --steal --confirm --occupant <reported-session-id> " +
+            message: "swarm close-out has no occupancy_session_id (manifest missing or predates the field), " +
+                "DEFT_SESSION_ID is unset, and this host published no owner. Re-establish an aligned " +
+                "owner with session:start --steal --confirm --occupant <reported-session-id> " +
                 "--session-id=<your-session-id>.",
             code: 1,
         };

package/dist/session/verify-ac-session-cache.d.ts

@@ -4,8 +4,8 @@
  * Disk-backed so check composition (spawned verify:ac) can serve from_cache
  * after a green run in the same session when plan + product hash still match.
  */
-export declare const VERIFY_AC_SESSION_CACHE_DIR = ".deft/verify-ac-session-cache";
-export declare const AC_SERVED_FROM: readonly ["bank", "cache", "executed"];
+export declare const VERIFY_AC_SESSION_CACHE_DIR = ".deft/cache/verify-ac-session-cache";
+export declare const AC_SERVED_FROM: readonly ["bank", "cache", "executed", "refused"];
 export type AcServedFrom = (typeof AC_SERVED_FROM)[number];
 export interface CachedVerifyAcSnapshot {
     readonly ok: boolean;

package/dist/session/verify-ac-session-cache.js

@@ -8,8 +8,8 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
 import { sanitizeScopeIdForFilename } from "./ac-pass-banking.js";
-export const VERIFY_AC_SESSION_CACHE_DIR = ".deft/verify-ac-session-cache";
-export const AC_SERVED_FROM = ["bank", "cache", "executed"];
+export const VERIFY_AC_SESSION_CACHE_DIR = ".deft/cache/verify-ac-session-cache";
+export const AC_SERVED_FROM = ["bank", "cache", "executed", "refused"];
 function asRecord(value) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         return value;

package/dist/swarm/complete-cohort.js

@@ -496,6 +496,8 @@ export function completeCohort(args) {
             }
         }
         if (result.ok && sessionId.length > 0) {
+            // Launcher occupancy only. Child owner leases release on the
+            // orchestration terminal transition (#3999), not here.
             const released = releaseSwarmOccupancy(projectRoot, {
                 env,
                 sessionId,

package/dist/swarm/pre-dispatch.js

@@ -177,6 +177,8 @@ function runBegin(input) {
     // heuristic, so accept an on-disk worktree as the second arming signal.
     const armTarget = resolve(input.projectRoot, input.targetId.trim());
     if (looksLikeFilesystemTarget(input.targetId) || looksLikeWorktreeDir(armTarget)) {
+        // Heartbeat dir only. Child occupancy owner is recorded at claim time
+        // (#3999): this parent process does not know a host-env child's id.
         ensureSubagentStatusDir(armTarget);
     }
     // Exclusive lock → reload → evaluate → begin+save (same decision under lock;

package/dist/swarm/subagent-status-dir.d.ts

@@ -6,6 +6,7 @@
  * worktree create and at pre-dispatch begin so a later missing record is
  * exit 1. Does not write heartbeat records or liveness onto the C2 manifest.
  */
+import { type ChildOccupancyDispatchInput } from "../session/child-occupancy.js";
 /**
  * True when a resolved path is an on-disk git worktree, i.e. it carries a `.git`
  * entry (a file for `git worktree add` trees, a directory for the main clone).
@@ -23,5 +24,5 @@ export declare function looksLikeWorktreeDir(resolvedPath: string): boolean;
  * Returns the directory path, or null when the worktree is not on disk yet
  * (do not mkdir a stray tree for a branch-name target).
  */
-export declare function ensureSubagentStatusDir(worktreeRoot: string): string | null;
+export declare function ensureSubagentStatusDir(worktreeRoot: string, childLease?: Omit<ChildOccupancyDispatchInput, "worktreePath">): string | null;
 //# sourceMappingURL=subagent-status-dir.d.ts.map

package/dist/swarm/subagent-status-dir.js

@@ -7,8 +7,9 @@
  * exit 1. Does not write heartbeat records or liveness onto the C2 manifest.
  */
 import { existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { defaultScratchDir } from "../orchestration/subagent-monitor.js";
+import { recordChildOccupancyLease, } from "../session/child-occupancy.js";
 /**
  * True when a resolved path is an on-disk git worktree, i.e. it carries a `.git`
  * entry (a file for `git worktree add` trees, a directory for the main clone).
@@ -31,12 +32,20 @@ export function looksLikeWorktreeDir(resolvedPath) {
  * Returns the directory path, or null when the worktree is not on disk yet
  * (do not mkdir a stray tree for a branch-name target).
  */
-export function ensureSubagentStatusDir(worktreeRoot) {
+export function ensureSubagentStatusDir(worktreeRoot, childLease) {
     const trimmed = worktreeRoot.trim();
     if (trimmed.length === 0 || !existsSync(trimmed))
         return null;
     const dir = defaultScratchDir(trimmed);
     mkdirSync(dir, { recursive: true });
+    // Optional: parent already knows the child's occupancy owner (spawn return).
+    // Host-env production claims also record via applyWorktreeOccupancy (#3999).
+    if (childLease !== undefined) {
+        recordChildOccupancyLease(trimmed, {
+            ...childLease,
+            worktreePath: resolve(trimmed),
+        });
+    }
     return dir;
 }
 //# sourceMappingURL=subagent-status-dir.js.map

package/dist/swarm/worktrees.js

@@ -198,6 +198,7 @@ export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, op
                     `but requested base '${trimmedBase}' resolves to ${requestedOid}; ` +
                     `this is a snapshot check at resolution time, not a pin on the worker's start revision`);
             }
+            // Heartbeat dir only. Child occupancy owner is recorded at claim (#3999).
             ensureSubagentStatusDir(entry._abs);
             continue;
         }
@@ -205,6 +206,7 @@ export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, op
             throw new MissingWorktreeError(`story '${entry.story_id}' maps to '${entry.worktree_path}' which is not a registered git worktree and create_missing is disabled`);
         }
         createWorktree(root, entry._abs, trimmedBase, git);
+        // Heartbeat dir only. Child occupancy owner is recorded at claim (#3999).
         ensureSubagentStatusDir(entry._abs);
     }
     return resolved.map(({ story_id, worktree_path, base_branch }) => ({