@deftai/directive-core 0.107.0 → 0.108.0

package/dist/session/git.js

@@ -1,5 +1,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
-import { resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { resolveCaptureFailureStderr, SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 function coerceGitBytes(value) {
     if (Buffer.isBuffer(value))
         return value;
@@ -21,6 +23,9 @@ export const defaultGitRunner = (projectRoot, args) => {
         const stdout = execFileSync("git", [...args], {
             cwd: projectRoot,
             stdio: ["ignore", "pipe", "pipe"],
+            // `git show <tip>:<path>` streams whole blobs; SPECIFICATION.md alone is
+            // past Node's 1 MB default (#3903).
+            maxBuffer: SUBPROCESS_MAX_BUFFER,
         });
         return { code: 0, stdout: gitStdoutString(coerceGitBytes(stdout), args), stderr: "" };
     }
@@ -32,10 +37,96 @@ export const defaultGitRunner = (projectRoot, args) => {
         return {
             code: typeof e.status === "number" ? e.status : 2,
             stdout: gitStdoutString(coerceGitBytes(e.stdout), args),
-            stderr: coerceGitBytes(e.stderr).toString("utf8").trimEnd(),
+            // A spawn-level failure (ENOBUFS on an oversized blob, timeout kill)
+            // throws with no status and empty stderr (#3903).
+            stderr: resolveCaptureFailureStderr({
+                captured: coerceGitBytes(e.stderr).toString("utf8").trimEnd(),
+                status: e.status,
+                message: e.message,
+            }),
         };
     }
 };
+/**
+ * One `git rev-parse` that answers the three ref reads the mutation gates
+ * otherwise make separately. Output is one line per requested value, in
+ * argument order: full HEAD, worktree root, branch name.
+ */
+const DISPATCH_GIT_CONTEXT_ARGS = [
+    "rev-parse",
+    "HEAD",
+    "--show-toplevel",
+    "--abbrev-ref",
+    "HEAD",
+];
+/** The individual reads `DISPATCH_GIT_CONTEXT_ARGS` can answer without a spawn. */
+const COALESCED_GIT_ARGS = [
+    ["rev-parse", "--verify", "HEAD"],
+    ["rev-parse", "--show-toplevel"],
+    ["symbolic-ref", "--short", "HEAD"],
+];
+/**
+ * Ref and identity reads whose answer cannot change inside one dispatch.
+ * Deliberately excludes content reads (no repeat callers, unbounded memory)
+ * and anything that touches the object store or a remote.
+ */
+const CACHEABLE_GIT_VERBS = new Set([
+    "rev-parse",
+    "symbolic-ref",
+    "merge-base",
+    "rev-list",
+]);
+function isCoalescedGitArgs(args) {
+    return COALESCED_GIT_ARGS.some((candidate) => candidate.length === args.length && candidate.every((arg, i) => arg === args[i]));
+}
+/**
+ * Serve a dispatch's repeated ref reads from one `git` child (#3736).
+ *
+ * The host mutation gate resolved HEAD, the worktree root, and the branch with
+ * a separate spawn each, twice over; on a loaded Windows box a spawn measured a
+ * 2.2s p50, so every concurrent agent's hook slowed every other agent's hook.
+ * The probe is lazy on purpose: it only fires for a read it can actually
+ * answer, so a caller that never asks for context never pays for it.
+ */
+export function memoizeGitRunner(runGit = defaultGitRunner) {
+    const cache = new Map();
+    const probed = new Set();
+    const keyFor = (root, args) => JSON.stringify([root, args]);
+    const probeContext = (projectRoot, root) => {
+        probed.add(root);
+        const context = runGit(projectRoot, DISPATCH_GIT_CONTEXT_ARGS);
+        if (context.code !== 0)
+            return;
+        const [head, worktree, branch, ...extra] = context.stdout.split(/\r?\n/);
+        if (!head || !worktree || !branch || extra.length > 0)
+            return;
+        const ok = (stdout) => ({ code: 0, stdout, stderr: "" });
+        cache.set(keyFor(root, ["rev-parse", "--verify", "HEAD"]), ok(head));
+        cache.set(keyFor(root, ["rev-parse", "--show-toplevel"]), ok(worktree));
+        // `--abbrev-ref` prints the literal "HEAD" on a detached head, where
+        // `symbolic-ref` exits non-zero — which is what callers branch on.
+        cache.set(keyFor(root, ["symbolic-ref", "--short", "HEAD"]), branch === "HEAD" ? { code: 1, stdout: "", stderr: "" } : ok(branch));
+    };
+    return (projectRoot, args) => {
+        const root = resolve(projectRoot);
+        const key = keyFor(root, args);
+        const cached = cache.get(key);
+        if (cached !== undefined)
+            return cached;
+        if (!probed.has(root) && isCoalescedGitArgs(args)) {
+            probeContext(projectRoot, root);
+            const coalesced = cache.get(key);
+            if (coalesced !== undefined)
+                return coalesced;
+        }
+        const result = runGit(projectRoot, args);
+        const verb = args[0];
+        if (verb !== undefined && CACHEABLE_GIT_VERBS.has(verb)) {
+            cache.set(key, result);
+        }
+        return result;
+    };
+}
 export function gitHead(projectRoot, runGit = defaultGitRunner) {
     const { code, stdout, stderr } = runGit(projectRoot, ["rev-parse", "--verify", "HEAD"]);
     if (code !== 0 || !stdout) {
@@ -50,6 +141,51 @@ export function worktreePath(projectRoot, runGit = defaultGitRunner) {
     }
     return resolve(projectRoot);
 }
+/**
+ * Walk from `targetPath` to the nearest existing directory. A write that
+ * creates a missing nested file is the common case; git cannot use a
+ * nonexistent cwd.
+ */
+export function existingAncestorDir(targetPath) {
+    let current = resolve(targetPath);
+    for (;;) {
+        if (existsSync(current)) {
+            try {
+                if (statSync(current).isDirectory())
+                    return current;
+            }
+            catch {
+                // Fall through to dirname when the path is not stat-able.
+            }
+            const parent = dirname(current);
+            return parent === current ? null : parent;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Failure-expressing sibling of {@link worktreePath}. Returns null instead of
+ * falling back to `startDir` so a missing git tree is distinguishable from
+ * success (#3794).
+ */
+export function worktreePathOrNull(startDir, runGit = defaultGitRunner) {
+    const { code, stdout } = runGit(startDir, ["rev-parse", "--show-toplevel"]);
+    const trimmed = stdout.trim();
+    if (code !== 0 || trimmed.length === 0)
+        return null;
+    return resolve(trimmed);
+}
+/** Absolute `--git-common-dir` for `projectRoot`, or null on failure. */
+export function gitCommonDir(projectRoot, runGit = defaultGitRunner) {
+    const { code, stdout } = runGit(projectRoot, ["rev-parse", "--git-common-dir"]);
+    const trimmed = stdout.trim();
+    if (code !== 0 || trimmed.length === 0)
+        return null;
+    return isAbsolute(trimmed) ? resolve(trimmed) : resolve(projectRoot, trimmed);
+}
 /** True when `ancestor` is reachable from `descendant` (same commit counts). */
 export function gitIsAncestor(projectRoot, ancestor, descendant, runGit = defaultGitRunner) {
     if (ancestor === descendant) {

package/dist/session/occupancy.d.ts

@@ -4,24 +4,121 @@
  * 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. Ordinary end is occupancy:release / session:end (#3604).
- * Join negotiation (`occupancy:request`) is out of scope.
+ *
+ * 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 { type LockDeps } from "../slice/lock.js";
+import { type SwarmWorkerRole } from "../swarm/routing.js";
 export declare const OCCUPANCY_SCHEMA_VERSION = 1;
 export declare const OCCUPANCY_RELPATH: readonly [".deft", "occupancy.json"];
 /** Crash recovery TTL: 20 minutes without heartbeat (15–30 window). */
 export declare const OCCUPANCY_TTL_MS: number;
+/**
+ * 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 declare const OCCUPANCY_REFRESH_AFTER_MS: number;
+/** Owner-allow staleness warning floor: three quarters of the TTL (#3599). */
+export declare const OCCUPANCY_STALE_WARN_MS: number;
+/**
+ * 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 declare const OCCUPANCY_MAX_LEASE_MS: number;
 export declare const OCCUPANCY_INTENTS: readonly ["mutation", "swarm", "review"];
 export type OccupancyIntent = (typeof OCCUPANCY_INTENTS)[number];
 export declare const OCCUPANCY_JOIN_PROTOCOLS: readonly ["none", "heartbeat-file", "parent-message"];
 export type OccupancyJoinProtocol = (typeof OCCUPANCY_JOIN_PROTOCOLS)[number];
+/**
+ * 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 declare const OCCUPANCY_GRANT_TTL_MS: number;
+/**
+ * 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 declare const OCCUPANCY_MAX_GRANTS = 32;
+/**
+ * A child admitted to the owner's lease (#3755). The five recorded fields are
+ * the point: possession of a session string proves nothing about who is behind
+ * it, so admission has to name the owner that issued it, the child it admits,
+ * the tree it covers, the role it was dispatched for, and when it stops being
+ * true. A grant admits writes; it never admits administration.
+ *
+ * `worktreePath` is recorded rather than assumed. Dispatched children land in
+ * their own worktree because the dispatch envelope puts them there, not because
+ * anything enforces it, so same-tree dispatch stays reachable and a lease may
+ * hold several grants over one path.
+ */
+export interface OccupancyGrant {
+    readonly ownerSessionId: string;
+    readonly childSessionId: string;
+    readonly worktreePath: string;
+    readonly role: SwarmWorkerRole;
+    readonly expiresAt: Date;
+    /** Per-actor host of the granted child, mirroring the occupant's own field. */
+    readonly host: string;
+    /** Per-actor address of the granted child, mirroring the occupant's own field. */
+    readonly address: string;
+    /** How this child reports back, from the parked join vocabulary. */
+    readonly joinProtocol: OccupancyJoinProtocol;
+}
+/**
+ * Who the presented id is to this lease (#3755). `member` is the only thing a
+ * grant buys, and it buys it for writes alone.
+ */
+export type OccupancyAdmission = "owner" | "member" | "stranger";
 export interface OccupancyRecord {
     readonly schemaVersion: number;
     readonly sessionId: string;
@@ -29,13 +126,24 @@ export interface OccupancyRecord {
     readonly intent: OccupancyIntent;
     readonly claimedAt: Date;
     readonly heartbeatAt: Date;
+    /**
+     * Last gated product write under this lease — by the owner or by a granted
+     * member (#3599 / #3755) — or null when none is recorded. Distinct from
+     * `heartbeatAt`, which any lease touch advances.
+     * Coarse to `OCCUPANCY_REFRESH_AFTER_MS`: a write inside that floor does not
+     * re-stamp, so the recorded time can trail the true last write by up to the
+     * refresh interval.
+     */
+    readonly lastWriteAt: Date | null;
     readonly host: string;
     readonly address: string;
     readonly retainCapable: boolean;
     readonly joinProtocol: OccupancyJoinProtocol;
+    /** Children the occupant admitted to this lease for writes (#3755). */
+    readonly grants: readonly OccupancyGrant[];
     readonly raw: Record<string, unknown>;
 }
-export type OccupancyAction = "claimed" | "heartbeat" | "stolen" | "denied" | "released";
+export type OccupancyAction = "claimed" | "heartbeat" | "stolen" | "denied" | "released" | "granted" | "revoked";
 export interface OccupancyDecision {
     readonly action: OccupancyAction;
     readonly sessionId: string;
@@ -57,18 +165,70 @@ export interface ApplyOccupancyInput {
     readonly address?: string;
     readonly retainCapable?: boolean;
     readonly joinProtocol?: OccupancyJoinProtocol;
-    /** When false, evaluate only (no write). Steal still writes. */
+    /** Record this touch as a product write, not only a heartbeat (#3599). */
+    readonly markWrite?: boolean;
+    /** When false, evaluate only (including confirmed steal) without writing. */
     readonly write?: boolean;
     /** Test seam for lock wait / timeout. */
     readonly lockDeps?: LockDeps;
 }
 export declare function occupancyPath(projectRoot: string): string;
 export declare function heartbeatAgeSeconds(record: OccupancyRecord, now?: Date): number;
-export declare function isOccupancyExpired(record: OccupancyRecord, now?: Date, ttlMs?: number): boolean;
+/** Age of the occupant's last recorded product write, or null when none (#3599). */
+export declare function lastWriteAgeSeconds(record: OccupancyRecord, now?: Date): number | null;
+/**
+ * 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 declare function formatLastWritePhrase(record: OccupancyRecord, now?: Date): string;
+/** Age of the lease itself, measured from the claim that opened it (#3599). */
+export declare function leaseAgeSeconds(record: OccupancyRecord, now?: Date): number;
+/**
+ * Why a lease is or is not live (#3599). The two dead states are not the same
+ * operator problem: `heartbeat-stale` says nobody has touched the lease, while
+ * `age-capped` says the holder may well be active but has held the tree past
+ * the bound that keeps crash recovery possible.
+ */
+export type OccupancyLiveness = "live" | "heartbeat-stale" | "age-capped";
+export declare function occupancyLiveness(record: OccupancyRecord, now?: Date, ttlMs?: number, maxLeaseMs?: number): OccupancyLiveness;
+export declare function isOccupancyExpired(record: OccupancyRecord, now?: Date, ttlMs?: number, maxLeaseMs?: number): boolean;
+/** Grants that still admit somebody (#3755). An expired grant admits nobody. */
+export declare function liveOccupancyGrants(record: OccupancyRecord, now?: Date): readonly OccupancyGrant[];
+/**
+ * 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 declare function occupancyGrantFor(record: OccupancyRecord, sessionId: string, now?: Date): OccupancyGrant | 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 declare function occupancyAdmission(record: OccupancyRecord, sessionId: string, now?: Date): OccupancyAdmission;
+/**
+ * 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 declare function formatOccupancyStaleWarning(record: OccupancyRecord, now?: Date, ttlMs?: number): string;
+/**
+ * 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 declare function formatOccupancyAgeCapRemediation(record: OccupancyRecord, now?: Date, maxLeaseMs?: number): string;
 export declare function formatOccupancyRemediation(record: OccupancyRecord, now?: Date): string;
+/**
+ * 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 declare function formatOccupancyMemberAdministrationRefusal(record: OccupancyRecord, grant: OccupancyGrant, verb: string): string;
 export declare function resolveOccupancySessionId(input?: ApplyOccupancyInput): string;
 export declare function readOccupancy(projectRoot: string): OccupancyRecord | null;
-export declare function liveOccupant(projectRoot: string, now?: Date, ttlMs?: number): OccupancyRecord | null;
+export declare function liveOccupant(projectRoot: string, now?: Date, ttlMs?: number, maxLeaseMs?: number): OccupancyRecord | null;
 export declare function applyWorktreeOccupancy(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
 export declare function stealOccupancy(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
 export declare function releaseOccupancy(projectRoot: string, input?: {
@@ -78,15 +238,81 @@ export declare function releaseOccupancy(projectRoot: string, input?: {
     readonly swarmCloseout?: boolean;
     readonly lockDeps?: LockDeps;
 }): OccupancyDecision;
-export declare function evaluateOccupancyWriteGate(projectRoot: string, input?: {
+export interface OccupancyMembershipInput {
+    /** The owner issuing or withdrawing the grant; never the child. */
+    readonly sessionId?: string;
+    readonly childSessionId?: string;
+    readonly role?: string;
+    readonly worktreePath?: string;
+    /** Explicit end of the grant; clamped to the owner's own lease cap. */
+    readonly expiresAt?: Date;
+    readonly ttlMs?: number;
+    readonly host?: string;
+    readonly address?: string;
+    readonly joinProtocol?: OccupancyJoinProtocol;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly now?: Date;
+    readonly lockDeps?: LockDeps;
+}
+/**
+ * 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 declare function grantOccupancyMembership(projectRoot: string, input?: OccupancyMembershipInput): OccupancyDecision;
+/**
+ * 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 declare function revokeOccupancyMembership(projectRoot: string, input?: OccupancyMembershipInput): OccupancyDecision;
+export interface OccupancyWriteGateResult {
+    readonly allow: boolean;
+    readonly message: string | null;
+    readonly occupant: OccupancyRecord | null;
+    /** True when this call re-stamped the owner's lease (#3599). */
+    readonly refreshed: boolean;
+    /** Set when the owner's own lease was inside the staleness window (#3599). */
+    readonly warning: string | null;
+    /** Why the write was admitted, or null on a refusal (#3755). */
+    readonly admitted: Exclude<OccupancyAdmission, "stranger"> | null;
+    /** The grant that admitted a member, or null (#3755). */
+    readonly grant: OccupancyGrant | null;
+}
+export interface OccupancyWriteGateInput {
     readonly sessionId?: string;
     readonly env?: NodeJS.ProcessEnv;
     readonly now?: Date;
-}): {
-    allow: boolean;
-    message: string | null;
-    occupant: OccupancyRecord | null;
-};
+    /**
+     * Re-stamp the owner's lease on the same-session allow (#3599). Off by
+     * default so the gate stays a pure read for callers that only probe; the
+     * dispatcher turns it on for the evaluation that immediately precedes an
+     * allowed write, so the stamp records a write that actually happened.
+     */
+    readonly refresh?: boolean;
+    readonly lockDeps?: 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 declare function evaluateOccupancyWriteGate(projectRoot: string, input?: OccupancyWriteGateInput): OccupancyWriteGateResult;
+/**
+ * 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 declare function heartbeatOccupancy(projectRoot: string, input?: ApplyOccupancyInput): OccupancyDecision;
 /** Close-out identity comes from the launch manifest or DEFT_SESSION_ID — never occupancy.json. */
 export declare function releaseSwarmOccupancy(projectRoot: string, input?: {
     readonly sessionId?: string;