@deftai/directive-core 0.106.0 → 0.108.0

package/dist/session/occupancy.js

@@ -3,14 +3,35 @@
  *
  * Ritual-state is "this session completed ceremony." Occupancy is "who may
  * mutate this tree right now." Those lifetimes differ; do not overload
- * ritual-state.json. Join negotiation (`occupancy:request`) is out of scope.
+ * ritual-state.json. Ordinary end is occupancy:release / session:end (#3604).
+ *
+ * What this boundary is (#3755): a cooperative bearer-id boundary, not a
+ * lineage. The lease admits whoever presents an id the record itself names —
+ * the occupant's id, or a child id the occupant granted — so possession of a
+ * string is the whole credential. Nothing here observes parentage, so a
+ * dispatched child is admitted because a grant records it, never because it
+ * inherited the holder's rights. Membership is explicit, attributable and
+ * expiring (`grantOccupancyMembership`), and it admits writes only: release,
+ * steal, heartbeat and cohort close-out stay owner-only, so a grant cannot be
+ * spent on the lease itself. Child-initiated join queuing stays out of scope —
+ * the owner issues membership; the child does not request it. Ritual state is
+ * still single-owner, so a member writes under the occupant's ceremony: the
+ * composite hook write gate measures the tree's verified ritual owner against
+ * the occupant that issued the grant, not against the writer.
  *
  * Concurrency model:
  * - Assumptions: local filesystem; cooperating processes on one machine.
  * - Guarantees: mutual exclusion under crash-free operation; detect-and-abort
  *   if the sidecar lock is compromised (fence before rename/unlink).
  * - Non-goals: network filesystems; Byzantine processes; perfect off-Linux
- *   PID-reuse detection (hard age cap + fence instead).
+ *   PID-reuse detection (hard age cap — `OCCUPANCY_MAX_LEASE_MS` — plus fence
+ *   instead).
+ * - Residual: the write gate authorizes a write it does not itself perform, so
+ *   no verdict is atomic with the write. A takeover that publishes after the
+ *   allow — including one already holding the lock but not yet written — is
+ *   outside what this gate can see. Closing that would mean denying every
+ *   owner whose lease file is momentarily locked, which is the load-shedding
+ *   regression #3736 fixed. The bound is the TTL, not the gate.
  */
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync, renameSync, rmSync } from "node:fs";
@@ -18,28 +39,181 @@ import { dirname, join, resolve } from "node:path";
 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 { stableJson } from "./json.js";
 import { parseTimestamp, timestampIso } from "./time.js";
 export const OCCUPANCY_SCHEMA_VERSION = 1;
 export const OCCUPANCY_RELPATH = [".deft", "occupancy.json"];
 /** Crash recovery TTL: 20 minutes without heartbeat (15–30 window). */
 export const OCCUPANCY_TTL_MS = 20 * 60 * 1000;
+/**
+ * Owner-allow re-stamp floor (#3599). The write gate runs on every gated write,
+ * so refreshing unconditionally would rewrite the lease file per keystroke-scale
+ * event. A quarter of the TTL bounds that without shortening the safe window:
+ * a write at any age past this floor resets the clock, so an owner that writes
+ * at least once per TTL never expires.
+ */
+export const OCCUPANCY_REFRESH_AFTER_MS = OCCUPANCY_TTL_MS / 4;
+/** Owner-allow staleness warning floor: three quarters of the TTL (#3599). */
+export const OCCUPANCY_STALE_WARN_MS = (OCCUPANCY_TTL_MS * 3) / 4;
+/**
+ * Absolute lease age cap, keyed on `claimedAt` and independent of refresh
+ * (#3599). Occupancy admits whoever presents the occupant's session id, so
+ * "the owner is still writing" only proves that some process holds that
+ * string. Without a bound on claim age, refresh would turn the heartbeat TTL —
+ * the sole mechanism that reclaims a worktree from a dead session — into
+ * something a writer can extend forever.
+ *
+ * Thirty-six TTLs is twelve hours, sized by the stalled owner rather than the
+ * busy one. Refresh keys on writes, so an agent that finishes overnight and
+ * waits for its operator is alive, correct, and silent — it stops refreshing
+ * while staying entirely legitimate. Twelve hours spans a 23:00 dispatch to a
+ * 09:00 handoff and still bounds reclaim well inside a day. Reaching the cap
+ * costs the owner one re-claim, not its work.
+ *
+ * Known limitation: a pure time cap cannot tell a stalled-but-live owner from a
+ * dead one, because the only liveness signal on this path is a write. If that
+ * ambiguity starts to bite, the answer is a liveness signal that needs no write
+ * — an explicit parked state, or refresh on non-write activity — not a larger
+ * number here.
+ */
+export const OCCUPANCY_MAX_LEASE_MS = OCCUPANCY_TTL_MS * 36;
 export const OCCUPANCY_INTENTS = ["mutation", "swarm", "review"];
 export const OCCUPANCY_JOIN_PROTOCOLS = ["none", "heartbeat-file", "parent-message"];
+/**
+ * Default life of a grant (#3755), sized by one dispatched unit of work:
+ * implement, open the PR, run the review cycle. Four hours is a third of the
+ * absolute lease cap, so a grant that outlives its child still dies well inside
+ * the lease that issued it, and re-granting costs the owner one command.
+ */
+export const OCCUPANCY_GRANT_TTL_MS = 4 * 60 * 60 * 1000;
+/**
+ * Grants a single lease may carry (#3755). Bounded because the list is rewritten
+ * into the lease file on every touch and the topology it serves is a nuclear
+ * family (#3155), not a mesh — a lease needing more than this is a design
+ * problem, not a capacity one.
+ */
+export const OCCUPANCY_MAX_GRANTS = 32;
 export function occupancyPath(projectRoot) {
     return join(resolve(projectRoot), ...OCCUPANCY_RELPATH);
 }
 export function heartbeatAgeSeconds(record, now = new Date()) {
     return Math.max(0, Math.round((now.getTime() - record.heartbeatAt.getTime()) / 1000));
 }
-export function isOccupancyExpired(record, now = new Date(), ttlMs = OCCUPANCY_TTL_MS) {
-    return now.getTime() - record.heartbeatAt.getTime() > ttlMs;
+/** Age of the occupant's last recorded product write, or null when none (#3599). */
+export function lastWriteAgeSeconds(record, now = new Date()) {
+    if (record.lastWriteAt === null)
+        return null;
+    return Math.max(0, Math.round((now.getTime() - record.lastWriteAt.getTime()) / 1000));
+}
+/**
+ * Human phrase for how recently the occupant wrote (#3599). Heartbeat age alone
+ * cannot distinguish an occupant mid-edit from one that merely claimed and left.
+ */
+export function formatLastWritePhrase(record, now = new Date()) {
+    const age = lastWriteAgeSeconds(record, now);
+    return age === null ? "no recorded write" : `last write ${age}s ago`;
+}
+/** Age of the lease itself, measured from the claim that opened it (#3599). */
+export function leaseAgeSeconds(record, now = new Date()) {
+    return Math.max(0, Math.round((now.getTime() - record.claimedAt.getTime()) / 1000));
+}
+export function occupancyLiveness(record, now = new Date(), ttlMs = OCCUPANCY_TTL_MS, maxLeaseMs = OCCUPANCY_MAX_LEASE_MS) {
+    // The cap is checked first because it is the answer that survives (#3599).
+    // A lease can be both, and then the stale reading is actively misleading:
+    // it sends the holder to refresh, which a capped lease cannot accept. Order
+    // also decides the write gate — the capped-holder refusal below keys on this
+    // value, so reading a doubly-dead lease as merely stale would give the more
+    // dead lease the more permissive answer.
+    if (now.getTime() - record.claimedAt.getTime() > maxLeaseMs)
+        return "age-capped";
+    if (now.getTime() - record.heartbeatAt.getTime() > ttlMs)
+        return "heartbeat-stale";
+    return "live";
+}
+export function isOccupancyExpired(record, now = new Date(), ttlMs = OCCUPANCY_TTL_MS, maxLeaseMs = OCCUPANCY_MAX_LEASE_MS) {
+    return occupancyLiveness(record, now, ttlMs, maxLeaseMs) !== "live";
+}
+/** Grants that still admit somebody (#3755). An expired grant admits nobody. */
+export function liveOccupancyGrants(record, now = new Date()) {
+    return record.grants.filter((grant) => grant.expiresAt.getTime() > now.getTime());
+}
+/**
+ * The grant admitting `sessionId`, or null (#3755). Expiry is refused here, on
+ * read, rather than trusted to a sweep: nothing guarantees a lease is ever
+ * touched again after the grant is written, so a grant that outlived its clock
+ * must stop admitting the moment it is read, not the next time it is rewritten.
+ */
+export function occupancyGrantFor(record, sessionId, now = new Date()) {
+    const presented = sessionId.trim();
+    if (presented.length === 0)
+        return null;
+    // The owner holds the lease outright; a grant naming it would add nothing.
+    if (presented === record.sessionId)
+        return null;
+    return (liveOccupancyGrants(record, now).find((grant) => grant.childSessionId === presented) ?? null);
+}
+/**
+ * What the presented id is to this lease (#3755). Deliberately not a liveness
+ * question: it answers who, and callers pair it with `occupancyLiveness` to
+ * answer whether the lease is still worth anything.
+ */
+export function occupancyAdmission(record, sessionId, now = new Date()) {
+    const presented = sessionId.trim();
+    if (presented.length === 0)
+        return "stranger";
+    if (presented === record.sessionId)
+        return "owner";
+    return occupancyGrantFor(record, presented, now) === null ? "stranger" : "member";
+}
+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}`;
+}
+/**
+ * Warn the holder that its own lease is inside the staleness window (#3599).
+ * Without this the owner learns it went stale only when a peer steals the lease.
+ */
+export function formatOccupancyStaleWarning(record, now = new Date(), ttlMs = OCCUPANCY_TTL_MS) {
+    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}\`.`);
+}
+/**
+ * Tell the holder its lease aged out of the absolute cap (#3599). Distinct
+ * remediation from a stale heartbeat: beating harder cannot help, because the
+ * lease is gone rather than merely quiet, so the answer is to re-claim.
+ */
+export function formatOccupancyAgeCapRemediation(record, now = new Date(), maxLeaseMs = OCCUPANCY_MAX_LEASE_MS) {
+    const hours = Math.round(maxLeaseMs / (60 * 60 * 1000));
+    return (`Occupancy lease for session ${record.sessionId} passed its ${hours}h absolute age cap ` +
+        `(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.`);
 }
 export function formatOccupancyRemediation(record, now = new Date()) {
     const age = heartbeatAgeSeconds(record, now);
-    return (`Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago).\n` +
+    return (`Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago, ` +
+        `${formatLastWritePhrase(record, now)}, ${occupancyClockLine(record)}).\n` +
         "Stay read-only (`session:start --read-only`), use another worktree,\n" +
-        "queue a join (`occupancy:request`), or steal (`occupancy:steal --confirm`).");
+        "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>`).\n" +
+        "The occupant may release (`occupancy:release` / `session:end`).");
+}
+/**
+ * Refuse an administrative verb to a granted child (#3755). Named apart from
+ * the stranger refusal because the answer differs: this caller is admitted, and
+ * telling it to steal or wait would send it to take the very lease its grant
+ * derives from. A grant admits writes; the lease has one owner.
+ */
+export function formatOccupancyMemberAdministrationRefusal(record, grant, verb) {
+    return (`${verb} is owner-only. Session ${grant.childSessionId} holds a write grant on this lease ` +
+        `(role=${grant.role}, expires ${timestampIso(grant.expiresAt)}), not the lease itself, and a ` +
+        "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 = {}) {
     const explicit = input.sessionId?.trim();
@@ -68,9 +242,9 @@ export function readOccupancy(projectRoot) {
     }
     return parseOccupancy(payload, resolve(projectRoot));
 }
-export function liveOccupant(projectRoot, now = new Date(), ttlMs = OCCUPANCY_TTL_MS) {
+export function liveOccupant(projectRoot, now = new Date(), ttlMs = OCCUPANCY_TTL_MS, maxLeaseMs = OCCUPANCY_MAX_LEASE_MS) {
     const record = readOccupancy(projectRoot);
-    if (record === null || isOccupancyExpired(record, now, ttlMs))
+    if (record === null || isOccupancyExpired(record, now, ttlMs, maxLeaseMs))
         return null;
     return record;
 }
@@ -124,10 +298,15 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
             intent: input.intent ?? liveLocked?.intent ?? "mutation",
             claimedAt: liveLocked?.claimedAt ?? now,
             heartbeatAt: now,
+            lastWriteAt: input.markWrite === true ? now : (liveLocked?.lastWriteAt ?? null),
             host: input.host ?? liveLocked?.host ?? occupancyHost(input.env),
             address: input.address ?? liveLocked?.address ?? occupancyAddress(input.env),
             retainCapable: input.retainCapable ?? liveLocked?.retainCapable ?? false,
             joinProtocol: input.joinProtocol ?? liveLocked?.joinProtocol ?? "none",
+            // Grants belong to the lease that issued them (#3755): the same owner
+            // keeps its members across a heartbeat, and a fresh claim over expired
+            // residue starts with none.
+            grants: liveLocked === null ? [] : liveOccupancyGrants(liveLocked, now),
         }, fence);
         const action = liveLocked !== null ? "heartbeat" : "claimed";
         return {
@@ -145,13 +324,20 @@ export function applyWorktreeOccupancy(projectRoot, input = {}) {
 export function stealOccupancy(projectRoot, input = {}) {
     const now = input.now ?? new Date();
     const path = occupancyPath(projectRoot);
+    const incoming = resolveOccupancySessionId(input);
     if (input.confirm !== true) {
+        const current = readOccupancy(projectRoot);
+        // 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 occupantDetail = current !== null && !isOccupancyExpired(current, now)
+            ? `\n${formatOccupancyRemediation(current, now)}`
+            : "";
         return {
             action: "denied",
-            sessionId: resolveOccupancySessionId(input),
-            record: readOccupancy(projectRoot),
+            sessionId: incoming,
+            record: current,
             path,
-            message: "occupancy:steal requires --confirm after naming the occupant.",
+            message: `occupancy:steal requires --confirm after naming the occupant.${occupantDetail}`,
             code: 2,
         };
     }
@@ -159,7 +345,7 @@ export function stealOccupancy(projectRoot, input = {}) {
     if (named.length === 0) {
         return {
             action: "denied",
-            sessionId: resolveOccupancySessionId(input),
+            sessionId: incoming,
             record: readOccupancy(projectRoot),
             path,
             message: "occupancy:steal requires --occupant <session-id> to name the current occupant.",
@@ -168,10 +354,26 @@ export function stealOccupancy(projectRoot, input = {}) {
     }
     const existing = readOccupancy(projectRoot);
     const live = existing !== null && !isOccupancyExpired(existing, now) ? existing : null;
+    // A grant admits writes, never the lease itself (#3755). Letting a child steal
+    // from the owner that admitted it would turn delegated write access into a
+    // path to replace the delegator — the escalation explicit membership exists to
+    // remove. Cooperative, like the rest of this file: a caller can present some
+    // other id, and then it is a stranger doing a confirmed steal, on the record.
+    const stealerGrant = live === null ? null : occupancyGrantFor(live, incoming, now);
+    if (live !== null && stealerGrant !== null) {
+        return {
+            action: "denied",
+            sessionId: incoming,
+            record: live,
+            path,
+            message: formatOccupancyMemberAdministrationRefusal(live, stealerGrant, "occupancy:steal"),
+            code: 1,
+        };
+    }
     if (live !== null && live.sessionId !== named) {
         return {
             action: "denied",
-            sessionId: resolveOccupancySessionId(input),
+            sessionId: incoming,
             record: live,
             path,
             message: `occupancy:steal named occupant ${named} does not match live occupant ${live.sessionId}.\n` +
@@ -179,13 +381,36 @@ export function stealOccupancy(projectRoot, input = {}) {
             code: 1,
         };
     }
+    if (input.write === false) {
+        return {
+            action: "stolen",
+            sessionId: incoming,
+            record: live,
+            path,
+            message: live === null
+                ? `occupancy steal preview: writer would be session ${incoming}`
+                : `occupancy steal preview: ${live.sessionId} would be replaced by session ${incoming}`,
+            code: 0,
+        };
+    }
     return withOccupancyLock(projectRoot, (fence) => {
         const existingLocked = readOccupancy(projectRoot);
         const liveLocked = existingLocked !== null && !isOccupancyExpired(existingLocked, now) ? existingLocked : null;
+        const lockedStealerGrant = liveLocked === null ? null : occupancyGrantFor(liveLocked, incoming, now);
+        if (liveLocked !== null && lockedStealerGrant !== null) {
+            return {
+                action: "denied",
+                sessionId: incoming,
+                record: liveLocked,
+                path,
+                message: formatOccupancyMemberAdministrationRefusal(liveLocked, lockedStealerGrant, "occupancy:steal"),
+                code: 1,
+            };
+        }
         if (liveLocked !== null && liveLocked.sessionId !== named) {
             return {
                 action: "denied",
-                sessionId: resolveOccupancySessionId(input),
+                sessionId: incoming,
                 record: liveLocked,
                 path,
                 message: `occupancy:steal named occupant ${named} does not match live occupant ${liveLocked.sessionId}.\n` +
@@ -193,24 +418,35 @@ export function stealOccupancy(projectRoot, input = {}) {
                 code: 1,
             };
         }
-        const incoming = resolveOccupancySessionId(input);
+        const priorClock = existingLocked !== null
+            ? ` (${formatLastWritePhrase(existingLocked, now)}, ${occupancyClockLine(existingLocked)})`
+            : "";
         const record = writeOccupancyRecord(projectRoot, {
             sessionId: incoming,
             worktreePath: resolve(projectRoot),
             intent: input.intent ?? "mutation",
             claimedAt: now,
             heartbeatAt: now,
+            lastWriteAt: null,
             host: input.host ?? occupancyHost(input.env),
             address: input.address ?? occupancyAddress(input.env),
             retainCapable: input.retainCapable ?? false,
             joinProtocol: input.joinProtocol ?? "none",
+            // A steal replaces the owner, and grants are that owner's word about
+            // who may write. The new owner never said it, so it does not inherit
+            // the members either (#3755).
+            grants: [],
         }, fence);
         return {
             action: "stolen",
             sessionId: record.sessionId,
             record,
             path,
-            message: `occupancy stolen from ${named}; writer is now session ${record.sessionId}`,
+            message: `occupancy stolen from ${named}${priorClock}; writer is now session ${record.sessionId}. ` +
+                "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.",
             code: 0,
         };
     }, input.lockDeps);
@@ -239,7 +475,7 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: existing,
                 path,
-                message: formatOccupancyRemediation(existing, now),
+                message: membershipOwnerDenial(existing, caller, now, "occupancy:release"),
                 code: 1,
             };
         }
@@ -264,7 +500,7 @@ export function releaseOccupancy(projectRoot, input = {}) {
                 sessionId: caller,
                 record: still,
                 path,
-                message: formatOccupancyRemediation(still, now),
+                message: membershipOwnerDenial(still, caller, now, "occupancy:release"),
                 code: 1,
             };
         }
@@ -279,19 +515,503 @@ export function releaseOccupancy(projectRoot, input = {}) {
         };
     }, input.lockDeps);
 }
+function membershipOwnerDenial(live, caller, now, verb) {
+    const grant = occupancyGrantFor(live, caller, now);
+    return grant === null
+        ? formatOccupancyRemediation(live, now)
+        : formatOccupancyMemberAdministrationRefusal(live, grant, verb);
+}
+/**
+ * Admit a dispatched child to this lease for writes (#3755).
+ *
+ * Owner-only, and the record is the point: a child that writes here is named
+ * on the lease it writes under, so an unexpected edit resolves to a session, a
+ * role and a tree instead of to "somebody who had the string". The grant cannot
+ * outlive the lease that issued it — expiry is clamped to the absolute lease
+ * cap — and it buys writes alone.
+ */
+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 child = input.childSessionId?.trim() ?? "";
+    const role = input.role?.trim() ?? "";
+    if (owner.length === 0) {
+        return {
+            action: "denied",
+            sessionId: "",
+            record: readOccupancy(projectRoot),
+            path,
+            message: "occupancy:grant needs the owner id: pass --session-id <your-session-id> or set " +
+                "DEFT_SESSION_ID. Only the occupant may admit a child to its lease.",
+            code: 2,
+        };
+    }
+    if (child.length === 0) {
+        return {
+            action: "denied",
+            sessionId: owner,
+            record: readOccupancy(projectRoot),
+            path,
+            message: "occupancy:grant needs --child-session-id <session-id>: the id the dispatched child " +
+                "will present on its own writes.",
+            code: 2,
+        };
+    }
+    if (child === owner) {
+        return {
+            action: "denied",
+            sessionId: owner,
+            record: readOccupancy(projectRoot),
+            path,
+            message: "occupancy:grant refuses a self-grant: the lease already admits its owner, so a grant " +
+                "naming the same id records nothing and would only blur who wrote what.",
+            code: 2,
+        };
+    }
+    if (!SWARM_WORKER_ROLES.includes(role)) {
+        return {
+            action: "denied",
+            sessionId: owner,
+            record: readOccupancy(projectRoot),
+            path,
+            message: `occupancy:grant needs --role from ${SWARM_WORKER_ROLES.join(", ")}. The role is what the ` +
+                "grant is for; an unnamed role makes the record unreadable after the fact.",
+            code: 2,
+        };
+    }
+    const ttlMs = input.ttlMs ?? OCCUPANCY_GRANT_TTL_MS;
+    return withOccupancyLock(projectRoot, (fence) => {
+        const current = readOccupancy(projectRoot);
+        const live = current !== null && !isOccupancyExpired(current, now) ? current : null;
+        if (live === null) {
+            const capped = current !== null &&
+                current.sessionId === owner &&
+                occupancyLiveness(current, now) === "age-capped";
+            return {
+                action: "denied",
+                sessionId: owner,
+                record: capped ? current : null,
+                path,
+                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}\`.`,
+                code: 1,
+            };
+        }
+        if (live.sessionId !== owner) {
+            return {
+                action: "denied",
+                sessionId: owner,
+                record: live,
+                path,
+                message: membershipOwnerDenial(live, owner, now, "occupancy:grant"),
+                code: 1,
+            };
+        }
+        const requested = input.expiresAt ?? new Date(now.getTime() + ttlMs);
+        if (requested.getTime() <= now.getTime()) {
+            return {
+                action: "denied",
+                sessionId: owner,
+                record: live,
+                path,
+                message: "occupancy:grant refuses an expiry that is already past: a grant that admits nobody " +
+                    "is indistinguishable from no grant, and recording one would only mislead.",
+                code: 2,
+            };
+        }
+        // A grant is derived authority, so it dies with the lease it derives from
+        // (#3755). Without this clamp a chain of grants would outlast the absolute
+        // cap that keeps a worktree reclaimable.
+        const leaseEnds = live.claimedAt.getTime() + OCCUPANCY_MAX_LEASE_MS;
+        const expiresAt = requested.getTime() > leaseEnds ? new Date(leaseEnds) : requested;
+        const clamped = expiresAt.getTime() !== requested.getTime();
+        const kept = liveOccupancyGrants(live, now).filter((existing) => existing.childSessionId !== child);
+        if (kept.length >= OCCUPANCY_MAX_GRANTS) {
+            return {
+                action: "denied",
+                sessionId: owner,
+                record: live,
+                path,
+                message: `occupancy:grant refuses a ${OCCUPANCY_MAX_GRANTS + 1}th live grant on one lease. ` +
+                    "Revoke a finished child (`occupancy:grant --revoke --child-session-id=<id>`) or let " +
+                    "its grant expire.",
+                code: 1,
+            };
+        }
+        const grant = {
+            ownerSessionId: owner,
+            childSessionId: child,
+            worktreePath: input.worktreePath?.trim() || live.worktreePath,
+            role: role,
+            expiresAt,
+            host: input.host?.trim() || "none",
+            address: input.address?.trim() || "none",
+            joinProtocol: input.joinProtocol ?? "parent-message",
+        };
+        const record = writeOccupancyRecord(projectRoot, {
+            sessionId: live.sessionId,
+            worktreePath: live.worktreePath,
+            intent: live.intent,
+            claimedAt: live.claimedAt,
+            // Issuing a grant is the owner touching its own lease, which is what
+            // heartbeat_at records; claimed_at is untouched, so the cap holds.
+            heartbeatAt: now,
+            lastWriteAt: live.lastWriteAt,
+            host: live.host,
+            address: live.address,
+            retainCapable: live.retainCapable,
+            joinProtocol: live.joinProtocol,
+            grants: [...kept, grant],
+        }, fence);
+        return {
+            action: "granted",
+            sessionId: owner,
+            record,
+            path,
+            message: `occupancy grant issued to session ${child} (role=${grant.role}, ` +
+                `worktree=${grant.worktreePath}, expires ${timestampIso(expiresAt)}` +
+                `${clamped ? ", clamped to this lease's absolute age cap" : ""}). ` +
+                "It admits writes only; release, steal, heartbeat and cohort close-out stay yours.",
+            code: 0,
+        };
+    }, input.lockDeps);
+}
+/**
+ * Withdraw a child's grant early (#3755). Expiry already bounds every grant, so
+ * this exists for the case expiry cannot serve: the child finished, or should
+ * never have been admitted, and the owner wants that true now.
+ */
+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 child = input.childSessionId?.trim() ?? "";
+    if (owner.length === 0 || child.length === 0) {
+        return {
+            action: "denied",
+            sessionId: owner,
+            record: readOccupancy(projectRoot),
+            path,
+            message: "occupancy:grant --revoke needs both the owner id (--session-id or DEFT_SESSION_ID) and " +
+                "--child-session-id <session-id>.",
+            code: 2,
+        };
+    }
+    return withOccupancyLock(projectRoot, (fence) => {
+        const current = readOccupancy(projectRoot);
+        const live = current !== null && !isOccupancyExpired(current, now) ? current : null;
+        if (live === null) {
+            return {
+                action: "revoked",
+                sessionId: owner,
+                record: null,
+                path,
+                message: "occupancy:grant --revoke found no live lease, so no grant survives it either: " +
+                    "grants die with the lease that issued them.",
+                code: 0,
+            };
+        }
+        if (live.sessionId !== owner) {
+            return {
+                action: "denied",
+                sessionId: owner,
+                record: live,
+                path,
+                message: membershipOwnerDenial(live, owner, now, "occupancy:grant --revoke"),
+                code: 1,
+            };
+        }
+        const before = liveOccupancyGrants(live, now);
+        const remaining = before.filter((existing) => existing.childSessionId !== child);
+        if (remaining.length === before.length) {
+            return {
+                action: "revoked",
+                sessionId: owner,
+                record: live,
+                path,
+                message: `occupancy has no live grant for session ${child}; nothing to revoke.`,
+                code: 0,
+            };
+        }
+        const record = writeOccupancyRecord(projectRoot, {
+            sessionId: live.sessionId,
+            worktreePath: live.worktreePath,
+            intent: live.intent,
+            claimedAt: live.claimedAt,
+            heartbeatAt: now,
+            lastWriteAt: live.lastWriteAt,
+            host: live.host,
+            address: live.address,
+            retainCapable: live.retainCapable,
+            joinProtocol: live.joinProtocol,
+            grants: remaining,
+        }, fence);
+        return {
+            action: "revoked",
+            sessionId: owner,
+            record,
+            path,
+            message: `occupancy grant revoked for session ${child}; its writes are refused from now on.`,
+            code: 0,
+        };
+    }, input.lockDeps);
+}
+/**
+ * Decide whether the presented session may write, and — on the owner-allow
+ * path — keep the owner's lease alive (#3599).
+ *
+ * Before this, the gate was read-only on owner-allow, so the one event that
+ * proves the owner is alive did not extend its lease: the live window was
+ * twenty minutes from claim, once, regardless of how long the session worked.
+ */
 export function evaluateOccupancyWriteGate(projectRoot, input = {}) {
     const now = input.now ?? new Date();
-    const live = liveOccupant(projectRoot, now);
-    if (live === null)
-        return { allow: true, message: null, occupant: null };
     const incoming = input.sessionId?.trim() || (input.env ?? process.env).DEFT_SESSION_ID?.trim() || "";
-    if (incoming.length > 0 && incoming === live.sessionId) {
-        return { allow: true, message: null, occupant: live };
+    const record = readOccupancy(projectRoot);
+    const liveness = record === null ? null : occupancyLiveness(record, now);
+    const admission = record === null ? "stranger" : occupancyAdmission(record, incoming, now);
+    if (record !== null && liveness === "age-capped" && admission !== "stranger") {
+        // Refuse the capped holder rather than warn it (#3599). Its tree is now
+        // unheld, so allowing the write would let the very bearer the cap exists to
+        // bound keep mutating a worktree a peer may claim between this allow and
+        // the write itself. On gated writes the identity comes from the host
+        // payload, so the holder cannot present a stranger's id to dodge this.
+        //
+        // A granted child is refused on the same footing (#3755). Its grant is
+        // derived from this lease, so once the lease is gone the grant authorizes
+        // writes to a tree nobody holds — the exact bypass the cap exists to close,
+        // one hop removed.
+        return {
+            allow: false,
+            message: formatOccupancyAgeCapRemediation(record, now),
+            occupant: null,
+            refreshed: false,
+            warning: null,
+            admitted: null,
+            grant: null,
+        };
+    }
+    if (record === null || liveness !== "live") {
+        return {
+            allow: true,
+            message: null,
+            occupant: null,
+            refreshed: false,
+            warning: null,
+            admitted: null,
+            grant: null,
+        };
+    }
+    const live = record;
+    if (admission === "stranger") {
+        return {
+            allow: false,
+            message: formatOccupancyRemediation(live, now),
+            occupant: live,
+            refreshed: false,
+            warning: null,
+            admitted: null,
+            grant: null,
+        };
+    }
+    if (admission === "member") {
+        // A member's write keeps the lease alive (#3755). The lease answers "who may
+        // mutate this tree right now", and a tree a granted child is actively
+        // writing is in use — letting it lapse would hand the worktree to a peer
+        // mid-edit, which is the loss the TTL exists to prevent, not the abandonment
+        // it exists to detect. Two bounds still hold: `claimedAt` is untouched, so
+        // the absolute age cap is unmoved, and the grant expires on its own clock.
+        const memberAgeMs = now.getTime() - live.heartbeatAt.getTime();
+        const memberWarning = memberAgeMs >= OCCUPANCY_STALE_WARN_MS ? formatOccupancyStaleWarning(live, now) : null;
+        if (input.refresh !== true || memberAgeMs < OCCUPANCY_REFRESH_AFTER_MS) {
+            return {
+                allow: true,
+                message: null,
+                occupant: live,
+                refreshed: false,
+                warning: memberWarning,
+                admitted: "member",
+                grant: occupancyGrantFor(live, incoming, now),
+            };
+        }
+        const memberOutcome = restampOccupancyHeartbeat(projectRoot, live.sessionId, now, true, input.lockDeps, incoming);
+        if (memberOutcome.status !== "refreshed") {
+            // Same re-decide as the owner path: contention says nothing about who
+            // holds the lease now, so ask the file rather than the pre-lock snapshot.
+            return evaluateOccupancyWriteGate(projectRoot, { ...input, now, refresh: false });
+        }
+        return {
+            allow: true,
+            message: null,
+            occupant: memberOutcome.record,
+            refreshed: true,
+            warning: null,
+            admitted: "member",
+            grant: occupancyGrantFor(memberOutcome.record, incoming, now),
+        };
+    }
+    const ageMs = now.getTime() - live.heartbeatAt.getTime();
+    const warning = ageMs >= OCCUPANCY_STALE_WARN_MS ? formatOccupancyStaleWarning(live, now) : null;
+    if (input.refresh !== true || ageMs < OCCUPANCY_REFRESH_AFTER_MS) {
+        return {
+            allow: true,
+            message: null,
+            occupant: live,
+            refreshed: false,
+            warning,
+            admitted: "owner",
+            grant: null,
+        };
+    }
+    const outcome = restampOccupancyHeartbeat(projectRoot, live.sessionId, now, true, input.lockDeps);
+    if (outcome.status !== "refreshed") {
+        // Neither failure leaves the pre-lock record usable. `lost` says the lease
+        // changed hands outright. `unavailable` says only that the lock could not
+        // be taken — but a peer takeover is one of the things that holds it, so a
+        // re-stamp that blocks until timeout hides the same handover. Decide
+        // against what is on disk now instead of the snapshot read at 598: a lease
+        // still ours under contention re-allows exactly as before (#3736), while a
+        // replacement owner wins (#3599). Re-entry cannot recurse — refresh is off.
+        return evaluateOccupancyWriteGate(projectRoot, { ...input, now, refresh: false });
+    }
+    return {
+        allow: true,
+        message: null,
+        occupant: outcome.record,
+        refreshed: true,
+        // `warning` was measured against the pre-refresh heartbeat. Returning it
+        // beside a successful re-stamp would tell the owner its lease is going
+        // stale on the very write that renewed it.
+        warning: null,
+        admitted: "owner",
+        grant: null,
+    };
+}
+/**
+ * Re-stamp an existing live lease held by `sessionId`. Reports `lost` when the
+ * lease is gone, expired, or now held by someone else — refresh must never
+ * claim or resurrect a lease, only extend one the caller already holds.
+ *
+ * Lock contention and IO errors report `unavailable` rather than `lost`: they
+ * observed no owner at all, so they are not evidence of replacement. `heartbeat`
+ * says so and leaves the lease alone; the write gate re-reads the file rather
+ * than trusting either its own stale snapshot or a denial the lock never earned.
+ */
+function restampOccupancyHeartbeat(projectRoot, sessionId, now, markWrite, lockDeps, 
+/** Refresh on behalf of this granted member rather than the owner (#3755). */
+memberSessionId) {
+    try {
+        return withOccupancyLock(projectRoot, (fence) => {
+            const current = readOccupancy(projectRoot);
+            if (current === null || current.sessionId !== sessionId)
+                return { status: "lost" };
+            if (isOccupancyExpired(current, now))
+                return { status: "lost" };
+            // Re-check membership under the lock: the grant read before the wait may
+            // have been revoked or expired while it ran (#3755).
+            if (memberSessionId !== undefined &&
+                occupancyGrantFor(current, memberSessionId, now) === null) {
+                return { status: "lost" };
+            }
+            const record = writeOccupancyRecord(projectRoot, {
+                sessionId: current.sessionId,
+                worktreePath: current.worktreePath,
+                intent: current.intent,
+                claimedAt: current.claimedAt,
+                heartbeatAt: now,
+                lastWriteAt: markWrite ? now : current.lastWriteAt,
+                host: current.host,
+                address: current.address,
+                retainCapable: current.retainCapable,
+                joinProtocol: current.joinProtocol,
+                // Refresh extends the lease, so it also prunes the grants that died
+                // while it ran; expiry is already refused on read (#3755).
+                grants: liveOccupancyGrants(current, now),
+            }, fence);
+            return { status: "refreshed", record };
+        }, lockDeps);
+    }
+    catch {
+        return { status: "unavailable" };
+    }
+}
+/**
+ * Refresh the caller's own live lease (#3599). Discoverable counterpart to the
+ * automatic write-gate refresh, for sessions whose work is long and quiet:
+ * reading, building, or waiting produces no gated write to ride on.
+ *
+ * Never claims and never mints an owner — an unheld or foreign lease is denied.
+ */
+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() || "";
+    if (caller.length === 0) {
+        return {
+            action: "denied",
+            sessionId: "",
+            record: readOccupancy(projectRoot),
+            path,
+            message: "occupancy:heartbeat needs the owner id: pass --session-id <your-session-id> or set " +
+                "DEFT_SESSION_ID. Refresh extends an existing lease and never mints an owner.",
+            code: 2,
+        };
+    }
+    const existing = readOccupancy(projectRoot);
+    const live = existing !== null && !isOccupancyExpired(existing, now) ? existing : null;
+    if (live === null) {
+        const capped = existing !== null &&
+            existing.sessionId === caller &&
+            occupancyLiveness(existing, now) === "age-capped";
+        return {
+            action: "denied",
+            sessionId: caller,
+            record: capped ? existing : null,
+            path,
+            message: capped && existing !== null
+                ? formatOccupancyAgeCapRemediation(existing, now)
+                : "occupancy:heartbeat found no live lease to refresh. Claim one with " +
+                    `\`deft session:start --session-id=${caller}\`.`,
+            code: 1,
+        };
+    }
+    if (live.sessionId !== caller) {
+        return {
+            action: "denied",
+            sessionId: caller,
+            record: live,
+            path,
+            message: membershipOwnerDenial(live, caller, now, "occupancy:heartbeat"),
+            code: 1,
+        };
+    }
+    const outcome = restampOccupancyHeartbeat(projectRoot, caller, now, false, input.lockDeps);
+    if (outcome.status !== "refreshed") {
+        return {
+            action: "denied",
+            sessionId: caller,
+            record: readOccupancy(projectRoot),
+            path,
+            message: outcome.status === "lost"
+                ? "occupancy:heartbeat could not refresh the lease: it expired or changed owner " +
+                    "while the refresh was running."
+                : "occupancy:heartbeat could not take the occupancy lock, so the lease is " +
+                    "unchanged and still yours. Retry in a moment.",
+            code: 1,
+        };
     }
+    const record = outcome.record;
     return {
-        allow: false,
-        message: formatOccupancyRemediation(live, now),
-        occupant: live,
+        action: "heartbeat",
+        sessionId: record.sessionId,
+        record,
+        path,
+        message: `occupancy heartbeat session ${record.sessionId} (intent=${record.intent}, ` +
+            `${occupancyClockLine(record)})`,
+        code: 0,
     };
 }
 /** Close-out identity comes from the launch manifest or DEFT_SESSION_ID — never occupancy.json. */
@@ -306,7 +1026,9 @@ export function releaseSwarmOccupancy(projectRoot, input = {}) {
             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. Steal with occupancy:steal --confirm --occupant <id>.",
+                "and DEFT_SESSION_ID is unset. Re-establish an aligned owner with " +
+                "session:start --steal --confirm --occupant <reported-session-id> " +
+                "--session-id=<your-session-id>.",
             code: 1,
         };
     }
@@ -343,6 +1065,9 @@ function parseOccupancy(payload, fallbackWorktree) {
     const heartbeatAt = parseTimestamp(obj.heartbeat_at) ?? claimedAt;
     if (claimedAt === null || heartbeatAt === null)
         return null;
+    // Additive and optional (#3599): records written before the field exists,
+    // and by older CLIs, stay readable — absence means "no recorded write".
+    const lastWriteAt = parseTimestamp(obj.last_write_at);
     const joinRaw = typeof obj.join_protocol === "string" ? obj.join_protocol : "none";
     const joinProtocol = OCCUPANCY_JOIN_PROTOCOLS.includes(joinRaw)
         ? joinRaw
@@ -357,13 +1082,63 @@ function parseOccupancy(payload, fallbackWorktree) {
         intent,
         claimedAt,
         heartbeatAt,
+        lastWriteAt,
         host: typeof obj.host === "string" && obj.host.length > 0 ? obj.host : "none",
         address: typeof obj.address === "string" && obj.address.length > 0 ? obj.address : "none",
         retainCapable: obj.retain_capable === true,
         joinProtocol,
+        grants: parseOccupancyGrants(obj.grants, sessionId, worktreePath),
         raw: { ...obj },
     };
 }
+/**
+ * Read the grant list (#3755). A malformed entry is dropped rather than failing
+ * the whole record: the lease still has an owner, and losing one grant denies a
+ * child a write it can ask for again, while losing the record would strand the
+ * tree. Expiry is parsed but not judged here — `occupancyGrantFor` decides that
+ * against a clock, so an expired grant stays visible to the owner reading its
+ * own lease and is still refused on admission.
+ */
+function parseOccupancyGrants(payload, ownerSessionId, fallbackWorktree) {
+    if (!Array.isArray(payload))
+        return [];
+    const grants = [];
+    for (const entry of payload.slice(0, OCCUPANCY_MAX_GRANTS)) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const obj = entry;
+        const childSessionId = typeof obj.child_session_id === "string" ? obj.child_session_id.trim() : "";
+        if (childSessionId.length === 0)
+            continue;
+        const owner = typeof obj.owner_session_id === "string" ? obj.owner_session_id.trim() : "";
+        // A grant naming a different owner is residue from a lease that has since
+        // changed hands; the current occupant never issued it, so it admits nobody.
+        if (owner.length === 0 || owner !== ownerSessionId)
+            continue;
+        const expiresAt = parseTimestamp(obj.expires_at);
+        if (expiresAt === null)
+            continue;
+        const roleRaw = typeof obj.role === "string" ? obj.role : "";
+        if (!SWARM_WORKER_ROLES.includes(roleRaw))
+            continue;
+        const joinRaw = typeof obj.join_protocol === "string" ? obj.join_protocol : "none";
+        grants.push({
+            ownerSessionId: owner,
+            childSessionId,
+            worktreePath: typeof obj.worktree_path === "string" && obj.worktree_path.trim().length > 0
+                ? obj.worktree_path
+                : fallbackWorktree,
+            role: roleRaw,
+            expiresAt,
+            host: typeof obj.host === "string" && obj.host.length > 0 ? obj.host : "none",
+            address: typeof obj.address === "string" && obj.address.length > 0 ? obj.address : "none",
+            joinProtocol: OCCUPANCY_JOIN_PROTOCOLS.includes(joinRaw)
+                ? joinRaw
+                : "none",
+        });
+    }
+    return grants;
+}
 function occupancyPayload(record) {
     return {
         schemaVersion: OCCUPANCY_SCHEMA_VERSION,
@@ -372,10 +1147,28 @@ function occupancyPayload(record) {
         intent: record.intent,
         claimed_at: timestampIso(record.claimedAt),
         heartbeat_at: timestampIso(record.heartbeatAt),
+        ...(record.lastWriteAt === null ? {} : { last_write_at: timestampIso(record.lastWriteAt) }),
         host: record.host,
         address: record.address,
         retain_capable: record.retainCapable,
         join_protocol: record.joinProtocol,
+        // Additive (#3755): absent on records written before membership existed,
+        // and omitted again when empty so an ungranted lease keeps its old shape.
+        ...(record.grants.length === 0
+            ? {}
+            : { grants: record.grants.map((grant) => occupancyGrantPayload(grant)) }),
+    };
+}
+function occupancyGrantPayload(grant) {
+    return {
+        owner_session_id: grant.ownerSessionId,
+        child_session_id: grant.childSessionId,
+        worktree_path: grant.worktreePath,
+        role: grant.role,
+        expires_at: timestampIso(grant.expiresAt),
+        host: grant.host,
+        address: grant.address,
+        join_protocol: grant.joinProtocol,
     };
 }
 function writeOccupancyRecord(projectRoot, record, fence) {