@deftai/directive-core 0.109.0 → 0.109.1

package/dist/design-critique/completed-arc-record.d.ts

@@ -15,7 +15,14 @@ export type ThreadComment = {
     readonly id: number;
     readonly body: string;
 };
-export type CompletedArcBlockReason = "missing-record" | "lone-shape" | "cite-not-lean" | "missing-table-cite" | "ambiguous-table-cite";
+/**
+ * Closed reason set, published in `content/contracts/design-critique.md`
+ * `### One parser, set membership, observed diagnostics`. The union is derived
+ * from this array so a member added here without a contract row fails the
+ * content-contract suite (#3942).
+ */
+export declare const COMPLETED_ARC_BLOCK_REASONS: readonly ["missing-record", "lone-shape", "cite-not-lean", "missing-table-cite", "unshaped-table-cite", "ambiguous-table-cite"];
+export type CompletedArcBlockReason = (typeof COMPLETED_ARC_BLOCK_REASONS)[number];
 export type CompletedArcVerdict = {
     readonly status: "not-in-arc";
 } | {

package/dist/design-critique/completed-arc-record.js

@@ -13,6 +13,20 @@
  */
 import { ACCEPTED_CITATION_FORMS, scanCitations, } from "./citation-grammar.js";
 import { DESIGN_CRITIQUE_CATALOG_CHIPS } from "./exclusive-chip.js";
+/**
+ * Closed reason set, published in `content/contracts/design-critique.md`
+ * `### One parser, set membership, observed diagnostics`. The union is derived
+ * from this array so a member added here without a contract row fails the
+ * content-contract suite (#3942).
+ */
+export const COMPLETED_ARC_BLOCK_REASONS = [
+    "missing-record",
+    "lone-shape",
+    "cite-not-lean",
+    "missing-table-cite",
+    "unshaped-table-cite",
+    "ambiguous-table-cite",
+];
 const SYNTHESIS_SHAPE_RE = /(?:^|\n)\s*design-critique:\s*synthesis accepted,\s*because\b/i;
 const LEAN_HEADING_RE = /(?:^|\n)\s*\*{0,2}Lean:\*{0,2}/;
 const TABLE_HEADING_RE = /(?:^|\n)\s*##\s+Verified-claims table\b/;
@@ -148,6 +162,14 @@ function resolveCitedLean(citations, byCommentId, latestLean) {
  * `comment` citations scan as kind `comment`, and that is the published form
  * these records use. Narrowing the citation contract so a table must be named
  * by keyword is a separate decision needing its own migration criteria.
+ *
+ * Refusal partition (#3942). A typed claim fails in two states, and only one of
+ * them is fixed by adding the heading: the id is not a comment on this thread,
+ * or it is a comment whose body fails `isVerifiedClaimsTableBody`. One reason
+ * and one detail for both asserted the first in either case, so an author whose
+ * table is on the thread read a true citation being called false and had no
+ * path to the missing heading. Absent ids rank first because a body that is not
+ * there cannot be given a heading.
  */
 function resolveCitedTable(citations, byCommentId) {
     const claimed = citations.filter((row) => row.kind === "table");
@@ -160,13 +182,30 @@ function resolveCitedTable(citations, byCommentId) {
         };
     }
     const resolved = claimed.map((row) => ({ id: row.id, cited: byCommentId.get(row.id) }));
-    const unresolved = resolved.filter((row) => row.cited === undefined || !isVerifiedClaimsTableBody(row.cited.body));
-    if (unresolved.length > 0) {
+    const absent = resolved.filter((row) => row.cited === undefined).map((row) => row.id);
+    const unshaped = resolved
+        .filter((row) => row.cited !== undefined && !isVerifiedClaimsTableBody(row.cited.body))
+        .map((row) => row.id);
+    if (absent.length > 0) {
         return {
             ok: false,
             reason: "missing-table-cite",
-            detail: "synthesis cites a verified-claims table id that is not a table on this thread: " +
-                renderIds(unresolved.map((row) => row.id)),
+            detail: "synthesis cites a verified-claims table id that is not a comment on this thread: " +
+                renderIds(absent) +
+                (unshaped.length > 0
+                    ? "; also cited, on this thread and carrying no verified-claims-table heading: " +
+                        renderIds(unshaped)
+                    : ""),
+        };
+    }
+    if (unshaped.length > 0) {
+        return {
+            ok: false,
+            reason: "unshaped-table-cite",
+            detail: "synthesis cites a verified-claims table id that is a comment on this thread but " +
+                "opens no line with the `## Verified-claims table` heading: " +
+                renderIds(unshaped) +
+                "; add that heading to the cited comment",
         };
     }
     const distinct = [...new Set(claimed.map((row) => row.id))];

package/dist/hooks/classify/host-session-identity.d.ts

@@ -44,7 +44,7 @@ export declare function resolveHookHostIdentity(host: string, payload: unknown,
  * still denies. A present-but-malformed variable is `invalid` and fails closed.
  */
 export declare function hostIdentityFallsBackToExplicitOwner(host: string, resolution: HookHostIdentityResolution): boolean;
-export declare const EXACT_LIFECYCLE_VERBS: readonly ["session:start", "session:ready", "session:end", "occupancy:steal", "occupancy:release", "occupancy:heartbeat", "swarm:launch"];
+export declare const EXACT_LIFECYCLE_VERBS: readonly ["session:start", "session:ready", "session:end", "occupancy:steal", "occupancy:release", "occupancy:heartbeat", "occupancy:grant", "swarm:launch"];
 export type ExactLifecycleVerb = (typeof EXACT_LIFECYCLE_VERBS)[number];
 export interface ExactLifecycleCommandRewrite {
     readonly kind: "rewrite";

package/dist/hooks/classify/host-session-identity.js

@@ -7,7 +7,7 @@
  * `session/host-session-owner.ts` because the CLI claim path resolves the same
  * owner from the same host (#3873).
  */
-import { ambientHostSessionOwner, canonicalHostSessionId, HOST_IDENTITY_PROVIDERS, hookHostIdentitySource, isUsableHostSessionId, MAX_HOOK_HOST_IDENTITY_UTF8_BYTES, readHostEnvIdentity, } from "../../session/host-session-owner.js";
+import { ambientHostSessionOwner, CANONICAL_OWNER_PATTERN, canonicalHostSessionId, HOST_IDENTITY_PROVIDERS, hookHostIdentitySource, isUsableHostSessionId, MAX_HOOK_HOST_IDENTITY_UTF8_BYTES, readHostEnvIdentity, } from "../../session/host-session-owner.js";
 import { isShellTool } from "../tools.js";
 import { record, toolInputRecord } from "./payload.js";
 import { hookToolName } from "./tool-name.js";
@@ -100,6 +100,10 @@ export const EXACT_LIFECYCLE_VERBS = [
     "occupancy:steal",
     "occupancy:release",
     "occupancy:heartbeat",
+    // #3954 item 2: `occupancy:grant` (and its `--revoke` arm) was the only
+    // occupancy lifecycle verb absent from this table, so the one verb that must
+    // be run by the occupant had no way to be told who the occupant is.
+    "occupancy:grant",
     "swarm:launch",
 ];
 const DIRECT_LIFECYCLE_VERBS = {
@@ -109,12 +113,9 @@ const DIRECT_LIFECYCLE_VERBS = {
     "occupancy:steal": "occupancy:steal",
     "occupancy:release": "occupancy:release",
     "occupancy:heartbeat": "occupancy:heartbeat",
+    "occupancy:grant": "occupancy:grant",
     "swarm-launch": "swarm:launch",
 };
-// Derived from the provider list so the rewrite surface cannot drift from the
-// identity surface: a provider added to one is added to both (#3873). Provider
-// ids are lowercase ASCII words, so the alternation needs no escaping.
-const CANONICAL_OWNER_PATTERN = new RegExp(`^host:(?:${HOST_IDENTITY_PROVIDERS.join("|")}):v1:[A-Za-z0-9_-]+$`);
 // Shell expansion markers are deliberately absent: `$`/backticks for POSIX,
 // `@` splatting for PowerShell, and `%NAME%` expansion for command shells.
 // Backslashes are inspectable so Windows path-bearing lifecycle commands fail
@@ -176,6 +177,23 @@ const LIFECYCLE_ARGUMENT_POLICIES = {
         valueFlags: new Set(["--session-id", "--project-root"]),
         rewriteUnsafeFlags: new Set(["--project-root"]),
     },
+    "occupancy:grant": {
+        booleanFlags: new Set(["--revoke"]),
+        valueFlags: new Set([
+            "--session-id",
+            "--child-session-id",
+            "--role",
+            "--worktree",
+            "--ttl-minutes",
+            "--host",
+            "--address",
+            "--join-protocol",
+            "--project-root",
+        ]),
+        // `--worktree` rebinds the tree the grant covers, so it joins the
+        // path/destination flags kept outside the auto-approved rewrite surface.
+        rewriteUnsafeFlags: new Set(["--project-root", "--worktree"]),
+    },
     "swarm:launch": {
         booleanFlags: new Set([
             "--autonomous",

package/dist/hooks/dispatcher.d.ts

@@ -5,9 +5,10 @@ import { type RuntimeAuthorityPolicy } from "../policy/runtime-authority.js";
 import { type GitRunner } from "../session/git.js";
 import { type DetectWorkSelection, type RitualRunner, type VerifyResult } from "../session/verify-session-ritual.js";
 import { type HookPayloadContext } from "./classify/index.js";
+import { type OwnerLivenessInput, type OwnerLivenessOutcome } from "./owner-liveness.js";
 import { type ActiveScopeInspection } from "./scope.js";
 export { ASSIST_SESSION_POSTURE_ENV, hookReadOnlyFromPayload, isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
-export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, GROK_MUTATION_TOOL_CATALOG, GROK_NON_MUTATION_TOOLS, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, matcherHasLiteralToken, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, GROK_MUTATION_TOOL_CATALOG, GROK_NON_MUTATION_TOOLS, HOST_TOOL_SURFACE_AUDIT, type HostMutationToolCatalog, type HostToolSurfaceAudit, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, matcherHasLiteralToken, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
 export declare const HOOK_HOSTS: readonly ["claude", "grok", "cursor", "codex"];
 export type HookHost = (typeof HOOK_HOSTS)[number];
 export declare const HOOK_EVENTS: readonly ["session.start", "session.compact", "tool.before"];
@@ -126,6 +127,8 @@ export interface HookPolicySeams {
     readonly realpathLifecycleExecutionRoot?: (path: string) => string;
     /** Test seam for Windows drive-only execution-root payloads (#2787). */
     readonly lifecycleExecutionPlatform?: NodeJS.Platform;
+    /** Test seam for the #3987 post-decision owner-liveness re-stamp. */
+    readonly restampOwnerLiveness?: (input: OwnerLivenessInput) => OwnerLivenessOutcome;
 }
 /** POSIX-ish project-relative path for lifecycle matching. */
 export declare function toProjectRelativePosix(projectRoot: string, targetPath: string): string;
@@ -200,6 +203,19 @@ export interface EffectiveHookRootAdmission {
  * target that resolved to some other toplevel whose identity cannot be read, is
  * a question asked and left unanswered — that fails closed rather than
  * inheriting payloadRoot's occupancy and ritual state (#3794).
+ *
+ * The `candidateRaw === null` fallback below — a target whose nearest existing
+ * ancestor has no Git toplevel at all (OS temp, a home file, anything outside
+ * every checkout) — is the third case and is deliberate, not a gap (#4013).
+ * `effectiveRoot` selects occupancy, ritual, active scope, the write fence and
+ * assist-scratch, so returning no root would drop all of them for an
+ * out-of-tree write, not just the lease; occupancy and ritual are cross-checked
+ * and the allow path re-stamps the lease, so exempting the lease alone is not a
+ * complete state transition; and `admitMutationTargetSet` demands one unique
+ * root, so a member contributing none has no defined combining rule and an
+ * untrusted patch path would become an authority-selection input. Gate-by-gate
+ * disposition, the three-surface matrix and the relative-target
+ * canonicalization limitation (#4023): content/docs/hook-root-admission.md.
  */
 export declare function admitEffectiveHookRoot(payloadRoot: string, writeTarget: string | null, runGit: GitRunner): EffectiveHookRootAdmission;
 /**

package/dist/hooks/dispatcher.js

@@ -19,6 +19,7 @@ import { formatRitualRecoveryInstruction, inspectSessionRitual, verifySessionRit
 import { hookApplyPatchBodyPaths, hookApplyPatchBodyText, hookMcpArgsText, hookMutationTargetPaths, hookShellCommand, hookToolName, hookWriteTargetPath, hostIdentityFallsBackToExplicitOwner, inspectExactLifecycleCommand, missingToolNameMessage, record, resolveHookHostIdentity, rewriteExactLifecycleCommand, toolInputRecord, } from "./classify/index.js";
 import { classifyGitDestructive, classifyProductDestForms, payloadWithInjectedWriteTarget, } from "./dest-form.js";
 import { appendGitDestructiveRecord, GIT_DESTRUCTIVE_LOG_ENV } from "./git-destructive-log.js";
+import { restampOwnerLivenessOnHookEvent, } from "./owner-liveness.js";
 import { isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
 import { inspectActiveScope } from "./scope.js";
 import { classifyShellWriteTargets, isInRepoShellWritePath } from "./shell-write-targets.js";
@@ -26,7 +27,7 @@ import { isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool } from "./tools.
 // Pure parse/classify helpers are defined in ./classify/ and re-exported from
 // ./index.ts (#2950). Dispatcher is orchestration: classify → policy → decision.
 export { ASSIST_SESSION_POSTURE_ENV, hookReadOnlyFromPayload, isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
-export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, GROK_MUTATION_TOOL_CATALOG, GROK_NON_MUTATION_TOOLS, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, matcherHasLiteralToken, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, GROK_MUTATION_TOOL_CATALOG, GROK_NON_MUTATION_TOOLS, HOST_TOOL_SURFACE_AUDIT, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, matcherHasLiteralToken, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
 export const HOOK_HOSTS = ["claude", "grok", "cursor", "codex"];
 export const HOOK_EVENTS = ["session.start", "session.compact", "tool.before"];
 /** Hosts that receive compact/resume hook deposits via init/update (#2113). */
@@ -330,6 +331,19 @@ function admitPayload(payload, candidate) {
  * target that resolved to some other toplevel whose identity cannot be read, is
  * a question asked and left unanswered — that fails closed rather than
  * inheriting payloadRoot's occupancy and ritual state (#3794).
+ *
+ * The `candidateRaw === null` fallback below — a target whose nearest existing
+ * ancestor has no Git toplevel at all (OS temp, a home file, anything outside
+ * every checkout) — is the third case and is deliberate, not a gap (#4013).
+ * `effectiveRoot` selects occupancy, ritual, active scope, the write fence and
+ * assist-scratch, so returning no root would drop all of them for an
+ * out-of-tree write, not just the lease; occupancy and ritual are cross-checked
+ * and the allow path re-stamps the lease, so exempting the lease alone is not a
+ * complete state transition; and `admitMutationTargetSet` demands one unique
+ * root, so a member contributing none has no defined combining rule and an
+ * untrusted patch path would become an authority-selection input. Gate-by-gate
+ * disposition, the three-surface matrix and the relative-target
+ * canonicalization limitation (#4023): content/docs/hook-root-admission.md.
  */
 export function admitEffectiveHookRoot(payloadRoot, writeTarget, runGit) {
     const payload = normalizeHookProjectRoot(payloadRoot);
@@ -787,6 +801,13 @@ function inspectMutationGates(input, toolName, seams, options) {
         ? { root: payloadRoot, foreign: false, candidate: null, refusal: null }
         : admitMutationTargetSet(payloadRoot, mutationTargets, dispatchGit);
     const effectiveRoot = admission.root;
+    if (options.observation !== undefined) {
+        if (!options.observation.effectiveRoots.includes(effectiveRoot)) {
+            options.observation.effectiveRoots.push(effectiveRoot);
+        }
+        if (admission.foreign)
+            options.observation.foreignTarget = true;
+    }
     const rootsNote = ` ${formatHookRootNote(payloadRoot, effectiveRoot)}`;
     if (admission.foreign) {
         const candidate = admission.candidate ?? "<none>";
@@ -1224,7 +1245,7 @@ function decideGitDestructive(input, toolName) {
  * Authorize recognized in-repo Shell file-write dests through inspectMutationGates (#3983 / #3987).
  * Deny is returned; allow falls through so dest-forms and push/merge still run.
  */
-function decideShellWriteReissue(input, toolName, seams) {
+function decideShellWriteReissue(input, toolName, seams, observation) {
     const command = hookShellCommand(input.payload);
     if (command === null)
         return null;
@@ -1245,6 +1266,7 @@ function decideShellWriteReissue(input, toolName, seams) {
         };
         const destDecision = inspectMutationGates(destInput, toolName, seams, {
             proposedLifecycleExempt: true,
+            observation,
         });
         if (destDecision.verdict === "deny")
             return destDecision;
@@ -1255,7 +1277,7 @@ function decideShellWriteReissue(input, toolName, seams) {
  * Route recognized Shell dest-forms through inspectMutationGates, then push/merge.
  * Dest-form allow is kept when runtime authority has nothing classifiable.
  */
-function decideShellDestFormsThenRuntimeAuthority(input, toolName, seams) {
+function decideShellDestFormsThenRuntimeAuthority(input, toolName, seams, observation) {
     const command = hookShellCommand(input.payload);
     let destAllow = null;
     let expansionDeny = null;
@@ -1287,6 +1309,7 @@ function decideShellDestFormsThenRuntimeAuthority(input, toolName, seams) {
             };
             const destDecision = inspectMutationGates(destInput, toolName, seams, {
                 proposedLifecycleExempt: true,
+                observation,
             });
             if (destDecision.verdict === "deny")
                 return destDecision;
@@ -1463,8 +1486,55 @@ function attachLifecycleIdentityRewrite(input, toolName, decision, seams) {
     }
     return { ...decision, updatedInput: rewrite.updatedInput };
 }
+/**
+ * Renew the owner's occupancy lease from a hook event that already proved the
+ * owner is present (#3987).
+ *
+ * Deliberately runs AFTER the decision and never feeds it. Two reasons: a
+ * liveness re-stamp must not be able to change a verdict, and re-stamping first
+ * would reset the shared age floor and so suppress the mutation gate's own
+ * `markWrite = true` refresh — leaving an actively-writing owner recorded as
+ * having no recorded write. Failure is swallowed: liveness is bookkeeping, and
+ * a lease that cannot be renewed simply ages out as it did before.
+ */
+function restampOwnerLiveness(input, seams, observation) {
+    if (input.event !== "tool.before")
+        return;
+    // A refused admission proves no tree at all, so there is nothing to renew.
+    if (observation.foreignTarget)
+        return;
+    try {
+        const actor = resolveMutationActor(input, input.environ ?? process.env);
+        const restamp = seams.restampOwnerLiveness ?? restampOwnerLivenessOnHookEvent;
+        // The trees occupancy was authorized against, not the payload root. Each
+        // was admitted on its own, so each is renewed on its own.
+        const roots = observation.effectiveRoots.length > 0
+            ? observation.effectiveRoots
+            : [resolve(input.projectRoot)];
+        for (const projectRoot of roots) {
+            restamp({
+                projectRoot,
+                ownerSessionId: actor.sessionId,
+                hostAuthoritative: actor.hostAuthoritative && actor.issue === null,
+            });
+        }
+    }
+    catch {
+        /* liveness is best-effort bookkeeping; never let it affect a verdict */
+    }
+}
 /** Decide a normalized event using only the P0 direct-write policy. */
 export function decideHook(input, seams = {}) {
+    const observation = { effectiveRoots: [], foreignTarget: false };
+    const decision = routeHookDecision(input, seams, observation);
+    // Skipped for the #3039 kill-switch and #2926 opt-out, which short-circuit
+    // before any Directive enforcement runs — including this bookkeeping.
+    if (decision.code !== "directive-disabled" && decision.code !== "session-start-disabled") {
+        restampOwnerLiveness(input, seams, observation);
+    }
+    return decision;
+}
+function routeHookDecision(input, seams, observation) {
     const projectRoot = resolve(input.projectRoot);
     // #3039: local (untracked) `.deft-directive-disable` wins for enforcement
     // short-circuit (SessionStart / compact / PreToolUse). Deposit may remain.
@@ -1657,7 +1727,10 @@ export function decideHook(input, seams = {}) {
                 scopePath: null,
             };
         }
-        return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: false });
+        return inspectMutationGates(input, toolName, seams, {
+            proposedLifecycleExempt: false,
+            observation,
+        });
     }
     // Tree-wide destructive git (#3917): always-on, independent of shellDestForms.
     // Dest-forms (#3438): recognized product mutations share inspectMutationGates
@@ -1668,11 +1741,11 @@ export function decideHook(input, seams = {}) {
         if (destructive !== null) {
             return attachLifecycleIdentityRewrite(input, toolName, destructive, seams);
         }
-        const writeReissue = decideShellWriteReissue(input, toolName, seams);
+        const writeReissue = decideShellWriteReissue(input, toolName, seams, observation);
         if (writeReissue !== null) {
             return attachLifecycleIdentityRewrite(input, toolName, writeReissue, seams);
         }
-        const decision = decideShellDestFormsThenRuntimeAuthority(input, toolName, seams);
+        const decision = decideShellDestFormsThenRuntimeAuthority(input, toolName, seams, observation);
         return attachLifecycleIdentityRewrite(input, toolName, decision, seams);
     }
     // Classifiable MCP: enforce scopes.push / scopes.merge (#2711).
@@ -1693,7 +1766,10 @@ export function decideHook(input, seams = {}) {
             scopePath: null,
         };
     }
-    return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: true });
+    return inspectMutationGates(input, toolName, seams, {
+        proposedLifecycleExempt: true,
+        observation,
+    });
 }
 /**
  * Soft AGENTS re-bind text for host injection when decision carries soft path (#3171).

package/dist/hooks/index.d.ts

@@ -4,6 +4,7 @@ export * from "./dest-form.js";
 export * from "./dispatcher.js";
 export * from "./fixtures/index.js";
 export * from "./git-destructive-log.js";
+export * from "./owner-liveness.js";
 export * from "./scope.js";
 export * from "./shell-write-targets.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.js

@@ -4,6 +4,7 @@ export * from "./dest-form.js";
 export * from "./dispatcher.js";
 export * from "./fixtures/index.js";
 export * from "./git-destructive-log.js";
+export * from "./owner-liveness.js";
 export * from "./scope.js";
 export * from "./shell-write-targets.js";
 //# sourceMappingURL=index.js.map

package/dist/hooks/owner-liveness.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Owner liveness on non-write hook activity (#3987).
+ *
+ * The occupancy lease renews on one signal: a gated product write
+ * (`evaluateOccupancyWriteGate`, refresh path, #3599). After #3990 widened the
+ * PreToolUse matchers, coverage is necessary and still not sufficient, because
+ * eligibility — not coverage — is what keeps shell traffic off that path. Only
+ * five write verbs are recognized, and a dest carrying `$` / `*` / `?`, a temp
+ * path, an out-of-root target, or any compound command is refused before the
+ * gate re-stamps. `cd <root>; <command>` is compound, and the mandated Windows
+ * body-file flow (#2646 / #2744) is compound, `$`-bearing and temp-targeted at
+ * once. So an owner can commit and push all session and still starve its own
+ * lease, which is the data-loss half of #3987.
+ *
+ * The remedy is the one `occupancy.ts` already names in the
+ * `OCCUPANCY_MAX_LEASE_MS` docblock: "refresh on non-write activity". The hook
+ * fires on every matched tool call and resolves the actor from the host
+ * payload, so the owner's presence is already proven there — no new identity
+ * has to travel anywhere.
+ *
+ * Bounds, each one load-bearing (5471374558 F4):
+ *
+ * - Host-authoritative actor only. An ambient inherited `DEFT_SESSION_ID` is
+ *   never enough. On Grok the owner id is a hook-sibling variable, and
+ *   publishing it so an agent shell could present it would hand lease renewal
+ *   to every descendant process — the widening the arc withdrew.
+ * - Owner only, via `heartbeatOccupancy`: it never claims, never mints, never
+ *   resurrects, and refuses a foreign or expired lease. Reusing it keeps one
+ *   renewal path with one set of refusal semantics.
+ * - `markWrite` stays false, so `last_write_at` still means "a product write
+ *   was recorded" and `no recorded write` stays honest for a would-be stealer.
+ * - Keyed on the lease's own worktree path, so a record describing another tree
+ *   is not renewed from this one. The caller supplies the tree the mutation
+ *   gates authorized against — a linked worktree, not the payload root — so a
+ *   worktree write renews the worktree's lease rather than the primary's.
+ * - `claimed_at` is untouched, so `OCCUPANCY_MAX_LEASE_MS` — 12 hours — is
+ *   unmoved. Liveness renewal cannot outlive the absolute cap.
+ * - Runs after the decision, never as an input to it. A liveness re-stamp must
+ *   not change any verdict, and re-stamping before the mutation gates would
+ *   suppress their own `markWrite = true` refresh by resetting the age floor.
+ *
+ * Bound this deliberately does not cross: a call with no write target proves
+ * only the tree the host named. `projectRootFromHookPayload` takes that from
+ * the payload's own `cwd`-class fields, so a session working inside a linked
+ * worktree names the worktree and renews it; a session whose host reports the
+ * primary checkout renews the primary. When those differ and nothing in the
+ * payload says which tree the work is in, this renews neither by guessing —
+ * keeping a lease alive for a tree nobody occupies is a widening, not a fix,
+ * and the TTL reclaiming an unused tree is the behaviour the lease exists for.
+ * `deft occupancy:heartbeat --session-id <owner>` stays the explicit path for
+ * a session whose tree the host does not report.
+ */
+import type { LockDeps } from "../slice/lock.js";
+export type OwnerLivenessSkipReason = 
+/** No host-authoritative owner resolved; ambient identity is not accepted. */
+"no-host-authoritative-owner"
+/** Nothing to renew: no lease, or the lease is expired or age-capped. */
+ | "no-live-lease"
+/** A lease exists but this actor is not its owner. */
+ | "not-owner"
+/** The lease record describes a different worktree than the one hooked. */
+ | "foreign-worktree"
+/** Younger than the shared re-stamp floor; renewing would rewrite per keystroke. */
+ | "within-refresh-floor"
+/** The lock was busy or the lease changed under us; the lease is left alone. */
+ | "refresh-unavailable";
+export type OwnerLivenessOutcome = {
+    readonly restamped: true;
+    readonly sessionId: string;
+    readonly heartbeatAt: Date;
+} | {
+    readonly restamped: false;
+    readonly reason: OwnerLivenessSkipReason;
+};
+export interface OwnerLivenessInput {
+    /** Tree the hook fired against; also the tree whose lease may be renewed. */
+    readonly projectRoot: string;
+    /** Owner id the host payload resolved to, or undefined when none did. */
+    readonly ownerSessionId: string | undefined;
+    /** False for ambient/environment identity — such an actor never renews. */
+    readonly hostAuthoritative: boolean;
+    readonly now?: Date;
+    readonly lockDeps?: LockDeps;
+}
+/**
+ * Renew the owner's lease from a hook event that proved the owner is alive.
+ *
+ * Pure side effect on `occupancy.json`: the caller's decision is already made
+ * and this never alters it. Every refusal path leaves the lease untouched.
+ */
+export declare function restampOwnerLivenessOnHookEvent(input: OwnerLivenessInput): OwnerLivenessOutcome;
+//# sourceMappingURL=owner-liveness.d.ts.map

package/dist/hooks/owner-liveness.js

@@ -0,0 +1,103 @@
+/**
+ * Owner liveness on non-write hook activity (#3987).
+ *
+ * The occupancy lease renews on one signal: a gated product write
+ * (`evaluateOccupancyWriteGate`, refresh path, #3599). After #3990 widened the
+ * PreToolUse matchers, coverage is necessary and still not sufficient, because
+ * eligibility — not coverage — is what keeps shell traffic off that path. Only
+ * five write verbs are recognized, and a dest carrying `$` / `*` / `?`, a temp
+ * path, an out-of-root target, or any compound command is refused before the
+ * gate re-stamps. `cd <root>; <command>` is compound, and the mandated Windows
+ * body-file flow (#2646 / #2744) is compound, `$`-bearing and temp-targeted at
+ * once. So an owner can commit and push all session and still starve its own
+ * lease, which is the data-loss half of #3987.
+ *
+ * The remedy is the one `occupancy.ts` already names in the
+ * `OCCUPANCY_MAX_LEASE_MS` docblock: "refresh on non-write activity". The hook
+ * fires on every matched tool call and resolves the actor from the host
+ * payload, so the owner's presence is already proven there — no new identity
+ * has to travel anywhere.
+ *
+ * Bounds, each one load-bearing (5471374558 F4):
+ *
+ * - Host-authoritative actor only. An ambient inherited `DEFT_SESSION_ID` is
+ *   never enough. On Grok the owner id is a hook-sibling variable, and
+ *   publishing it so an agent shell could present it would hand lease renewal
+ *   to every descendant process — the widening the arc withdrew.
+ * - Owner only, via `heartbeatOccupancy`: it never claims, never mints, never
+ *   resurrects, and refuses a foreign or expired lease. Reusing it keeps one
+ *   renewal path with one set of refusal semantics.
+ * - `markWrite` stays false, so `last_write_at` still means "a product write
+ *   was recorded" and `no recorded write` stays honest for a would-be stealer.
+ * - Keyed on the lease's own worktree path, so a record describing another tree
+ *   is not renewed from this one. The caller supplies the tree the mutation
+ *   gates authorized against — a linked worktree, not the payload root — so a
+ *   worktree write renews the worktree's lease rather than the primary's.
+ * - `claimed_at` is untouched, so `OCCUPANCY_MAX_LEASE_MS` — 12 hours — is
+ *   unmoved. Liveness renewal cannot outlive the absolute cap.
+ * - Runs after the decision, never as an input to it. A liveness re-stamp must
+ *   not change any verdict, and re-stamping before the mutation gates would
+ *   suppress their own `markWrite = true` refresh by resetting the age floor.
+ *
+ * Bound this deliberately does not cross: a call with no write target proves
+ * only the tree the host named. `projectRootFromHookPayload` takes that from
+ * the payload's own `cwd`-class fields, so a session working inside a linked
+ * worktree names the worktree and renews it; a session whose host reports the
+ * primary checkout renews the primary. When those differ and nothing in the
+ * payload says which tree the work is in, this renews neither by guessing —
+ * keeping a lease alive for a tree nobody occupies is a widening, not a fix,
+ * and the TTL reclaiming an unused tree is the behaviour the lease exists for.
+ * `deft occupancy:heartbeat --session-id <owner>` stays the explicit path for
+ * a session whose tree the host does not report.
+ */
+import { resolve } from "node:path";
+import { heartbeatOccupancy, isOccupancyExpired, OCCUPANCY_REFRESH_AFTER_MS, readOccupancy, } from "../session/occupancy.js";
+function skip(reason) {
+    return { restamped: false, reason };
+}
+/**
+ * Renew the owner's lease from a hook event that proved the owner is alive.
+ *
+ * Pure side effect on `occupancy.json`: the caller's decision is already made
+ * and this never alters it. Every refusal path leaves the lease untouched.
+ */
+export function restampOwnerLivenessOnHookEvent(input) {
+    if (!input.hostAuthoritative)
+        return skip("no-host-authoritative-owner");
+    const owner = input.ownerSessionId?.trim() ?? "";
+    if (owner.length === 0)
+        return skip("no-host-authoritative-owner");
+    const root = resolve(input.projectRoot);
+    const now = input.now ?? new Date();
+    const record = readOccupancy(root);
+    if (record === null || isOccupancyExpired(record, now))
+        return skip("no-live-lease");
+    // Owner only. A granted member's presence is not the owner's presence, and
+    // `heartbeatOccupancy` refuses it anyway — checking here keeps the reason honest.
+    if (record.sessionId !== owner)
+        return skip("not-owner");
+    if (resolve(record.worktreePath) !== root)
+        return skip("foreign-worktree");
+    // Same floor the write gate uses, for the same reason: the hook runs on a
+    // large fraction of tool calls, so an unconditional renew would rewrite the
+    // lease file continuously without lengthening the safe window at all.
+    if (now.getTime() - record.heartbeatAt.getTime() < OCCUPANCY_REFRESH_AFTER_MS) {
+        return skip("within-refresh-floor");
+    }
+    const beat = heartbeatOccupancy(root, {
+        sessionId: owner,
+        // Never fall back to an ambient owner: the resolved host identity is the
+        // only thing that proves who is here.
+        env: {},
+        now,
+        lockDeps: input.lockDeps,
+    });
+    if (beat.code !== 0 || beat.record === null)
+        return skip("refresh-unavailable");
+    return {
+        restamped: true,
+        sessionId: beat.record.sessionId,
+        heartbeatAt: beat.record.heartbeatAt,
+    };
+}
+//# sourceMappingURL=owner-liveness.js.map