@deftai/directive-core 0.109.0 → 0.109.1

package/dist/hooks/tools.d.ts

@@ -1,3 +1,4 @@
+import type { ClassifyHookHost } from "./classify/types.js";
 /** Host spellings that install-time matchers and runtime classification share. */
 export declare const DIRECT_WRITE_TOOL_NAMES: readonly ["Edit", "Write", "WriteFile", "CreateFile", "MultiEdit", "NotebookEdit", "StrReplace", "SearchReplace", "Delete", "DeleteFile", "ApplyPatch", "apply_patch", "write", "search_replace"];
 /** PreToolUse spawn / sub-agent dispatch tools (#1185 / #2437). */
@@ -5,8 +6,12 @@ export declare const SPAWN_TOOL_NAMES: readonly ["Task", "SubagentStart", "spawn
 /**
  * Host spellings for Shell/Bash execution tools (#2711).
  * Used for runtimeAuthority scopes.push / scopes.merge classification.
+ *
+ * `monitor` is Grok Build's second shell surface (#3987 audit): it executes an
+ * arbitrary shell command in the background, so leaving it out reproduces the
+ * `run_terminal_command` gap one tool over.
  */
-export declare const SHELL_TOOL_NAMES: readonly ["Shell", "Bash", "BashTool", "shell", "bash", "run_terminal_command"];
+export declare const SHELL_TOOL_NAMES: readonly ["Shell", "Bash", "BashTool", "shell", "bash", "run_terminal_command", "monitor"];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export declare const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 export declare function isDirectWriteTool(toolName: string): boolean;
@@ -32,23 +37,47 @@ export declare const MCP_PUSH_MERGE_BARE_NAMES: readonly ["merge_pull_request",
 export declare const DIRECT_WRITE_HOOK_MATCHER: string;
 export declare const SPAWN_HOOK_MATCHER: string;
 export declare const SHELL_HOOK_MATCHER: string;
-/** Known mutation tool names per host. Deposited matchers must cover each name (#3987). */
-export declare const GROK_MUTATION_TOOL_CATALOG: {
-    readonly directWrite: readonly ["write", "search_replace"];
-    readonly shell: readonly ["run_terminal_command"];
-    readonly spawn: readonly ["spawn_subagent"];
-};
-/** Tools on this host that are intentionally not mutation-gated. */
-export declare const GROK_NON_MUTATION_TOOLS: {
-    readonly read_file: "read";
-    readonly grep: "read";
-    readonly list_dir: "read";
-    readonly todo_write: "session-local non-product scratch";
-    readonly get_command_or_subagent_output: "poll, not a mutation; elapsed bound is evaluateInFlight";
-    readonly kill_command_or_subagent: "process control";
-    readonly search_tool: "read";
-    readonly web_search: "read";
-};
+/** Mutation tool names a host emits, grouped by the matcher that must carry them. */
+export interface HostMutationToolCatalog {
+    readonly directWrite: readonly string[];
+    readonly shell: readonly string[];
+    readonly spawn: readonly string[];
+}
+/**
+ * One host's audited tool surface (#3987 acceptance item 2).
+ *
+ * The audit answers one question per tool name the host emits: is it in
+ * `mutation` (and therefore required to be a literal token of the deposited
+ * matcher AND recognized by the runtime classifier), or is it in `nonMutation`
+ * with the written reason it stays outside the gate? A name in neither is the
+ * silent gap this record exists to make loud.
+ *
+ * `unobservedReason` is the honest third state. The deposit asserting a
+ * spelling is not evidence that the host emits it, so a host whose PreToolUse
+ * payloads have not been observed says so rather than publishing a guess as
+ * coverage.
+ */
+export interface HostToolSurfaceAudit {
+    readonly mutation: HostMutationToolCatalog;
+    readonly nonMutation: Readonly<Record<string, string>>;
+    /** Null when the audit covers every name the host emits. */
+    readonly unobservedReason: string | null;
+    /** Where the observation came from, so a reader can re-run it. */
+    readonly source: string;
+}
+/**
+ * Per-host tool-surface audit (#3987). Read by the deterministic deposit
+ * coverage check, which fails closed when a host is absent from this table —
+ * so a newly supported host cannot silently ship with no coverage claim.
+ */
+export declare const HOST_TOOL_SURFACE_AUDIT: Readonly<Record<ClassifyHookHost, HostToolSurfaceAudit>>;
+/**
+ * Known Grok mutation tool names. Deposited matchers must cover each name (#3987).
+ * Projection of the per-host audit; kept as a named export for the #3990 tests.
+ */
+export declare const GROK_MUTATION_TOOL_CATALOG: HostMutationToolCatalog;
+/** Grok tools that are intentionally not mutation-gated, each with its reason. */
+export declare const GROK_NON_MUTATION_TOOLS: Readonly<Record<string, string>>;
 export declare function matcherHasLiteralToken(matcher: string, toolName: string): boolean;
 /**
  * PreToolUse matcher for MCP-class push/merge tools (#2711).

package/dist/hooks/tools.js

@@ -26,6 +26,10 @@ export const SPAWN_TOOL_NAMES = [
 /**
  * Host spellings for Shell/Bash execution tools (#2711).
  * Used for runtimeAuthority scopes.push / scopes.merge classification.
+ *
+ * `monitor` is Grok Build's second shell surface (#3987 audit): it executes an
+ * arbitrary shell command in the background, so leaving it out reproduces the
+ * `run_terminal_command` gap one tool over.
  */
 export const SHELL_TOOL_NAMES = [
     "Shell",
@@ -34,6 +38,7 @@ export const SHELL_TOOL_NAMES = [
     "shell",
     "bash",
     "run_terminal_command",
+    "monitor",
 ];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
@@ -96,23 +101,84 @@ export const MCP_PUSH_MERGE_BARE_NAMES = [
 export const DIRECT_WRITE_HOOK_MATCHER = DIRECT_WRITE_TOOL_NAMES.join("|");
 export const SPAWN_HOOK_MATCHER = SPAWN_TOOL_NAMES.join("|");
 export const SHELL_HOOK_MATCHER = SHELL_TOOL_NAMES.join("|");
-/** Known mutation tool names per host. Deposited matchers must cover each name (#3987). */
-export const GROK_MUTATION_TOOL_CATALOG = {
-    directWrite: ["write", "search_replace"],
-    shell: ["run_terminal_command"],
-    spawn: ["spawn_subagent"],
-};
-/** Tools on this host that are intentionally not mutation-gated. */
-export const GROK_NON_MUTATION_TOOLS = {
-    read_file: "read",
-    grep: "read",
-    list_dir: "read",
-    todo_write: "session-local non-product scratch",
-    get_command_or_subagent_output: "poll, not a mutation; elapsed bound is evaluateInFlight",
-    kill_command_or_subagent: "process control",
-    search_tool: "read",
-    web_search: "read",
+/**
+ * Per-host tool-surface audit (#3987). Read by the deterministic deposit
+ * coverage check, which fails closed when a host is absent from this table —
+ * so a newly supported host cannot silently ship with no coverage claim.
+ */
+export const HOST_TOOL_SURFACE_AUDIT = {
+    grok: {
+        mutation: {
+            directWrite: ["write", "search_replace"],
+            shell: ["run_terminal_command", "monitor"],
+            spawn: ["spawn_subagent"],
+        },
+        nonMutation: {
+            read_file: "read",
+            grep: "read",
+            list_dir: "read",
+            search_tool: "read",
+            web_search: "read",
+            web_fetch: "read",
+            todo_write: "session-local non-product scratch",
+            get_command_or_subagent_output: "poll, not a mutation; elapsed bound is evaluateInFlight",
+            wait_commands_or_subagents: "poll over already-dispatched work",
+            kill_command_or_subagent: "process control",
+            scheduler_delete: "removes a scheduled task; mutates no product path",
+            scheduler_list: "read",
+            enter_plan_mode: "session posture",
+            exit_plan_mode: "session posture",
+            image_gen: "writes generated media to session scratch, never a tracked product path",
+            image_edit: "writes generated media to session scratch, never a tracked product path",
+            image_to_video: "writes generated media to session scratch, never a tracked product path",
+            reference_to_video: "writes generated media to session scratch, never a tracked product path",
+            scheduler_create: "spawn-class and NOT covered: gating it routes a scheduling primitive through the " +
+                "full spawn stack (ritual + active xBRIEF), a new deny class that needs a deliberate " +
+                "policy decision rather than a coverage edit (#3987 residual)",
+            use_tool: "mcp-class and NOT covered: the dispatcher classifies on the outer tool name, and the " +
+                "MCP tool actually invoked is nested in tool_input.tool_name, so a matcher entry alone " +
+                "buys a hook invocation and no enforcement; reading the inner name is a classifier " +
+                "change, not a matcher change (#3987 residual)",
+        },
+        unobservedReason: null,
+        source: "Observed directly on Grok Build: this host's published tool list, plus the 5,354-call " +
+            "session census recorded on issue #3987.",
+    },
+    claude: {
+        mutation: { directWrite: [], shell: ["Bash"], spawn: [] },
+        nonMutation: {},
+        unobservedReason: "Only the shell spelling is established (`Bash`, re-derived from the deposits by the " +
+            "#3987 panel's completing seat 5471374558 F8). No PreToolUse payload for this host has " +
+            "been observed in this tree, so the direct-write and spawn spellings stay unclaimed " +
+            "rather than asserted from the deposit that is supposed to be under test.",
+        source: "Issue #3987 comment 5471374558 finding F8.",
+    },
+    codex: {
+        mutation: { directWrite: ["apply_patch"], shell: ["shell"], spawn: [] },
+        nonMutation: {},
+        unobservedReason: "Shell (`shell`) and the apply_patch write form are established — F8 for the shell " +
+            "spelling, #3614 for the Codex apply_patch payload path. The rest of this host's surface " +
+            "has not been observed in this tree.",
+        source: "Issue #3987 comment 5471374558 finding F8; #3614 Codex apply_patch handling.",
+    },
+    cursor: {
+        mutation: { directWrite: [], shell: [], spawn: [] },
+        nonMutation: {},
+        unobservedReason: "Unverified. Nothing in this tree establishes which tool names Cursor emits on " +
+            "preToolUse: the deposit asserts a matcher string and the fixture corpus asserts the " +
+            "framework's own assumption, neither of which observes the host. Cursor could be a " +
+            "second zero-coverage host by the exact mechanism that produced #3987 (5471374558 F8), " +
+            "and claiming coverage here would hide that.",
+        source: "Issue #3987 comment 5471374558 finding F8.",
+    },
 };
+/**
+ * Known Grok mutation tool names. Deposited matchers must cover each name (#3987).
+ * Projection of the per-host audit; kept as a named export for the #3990 tests.
+ */
+export const GROK_MUTATION_TOOL_CATALOG = HOST_TOOL_SURFACE_AUDIT.grok.mutation;
+/** Grok tools that are intentionally not mutation-gated, each with its reason. */
+export const GROK_NON_MUTATION_TOOLS = HOST_TOOL_SURFACE_AUDIT.grok.nonMutation;
 export function matcherHasLiteralToken(matcher, toolName) {
     return matcher.split("|").includes(toolName);
 }

package/dist/init-deposit/agent-hooks.d.ts

@@ -27,6 +27,8 @@ export declare const CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS = 30;
 /** Nested Claude/Grok/Codex command-hook default timeout (seconds). */
 export declare const NESTED_HOOK_TIMEOUT_SECONDS = 5;
 export type AgentHookPath = (typeof AGENT_HOOK_PATHS)[number];
+/** Deposit file each supported host reads its PreToolUse registration from. */
+export declare const AGENT_HOOK_PATH_BY_HOST: Readonly<Record<HookHost, AgentHookPath>>;
 export type AgentHookRegistrationStatus = "healthy" | "disabled" | "missing" | "drifted";
 /** Whether the host receives a compact/resume hook deposit (#2113). */
 export type AgentHookCompactSupport = "deposited" | "unsupported";
@@ -43,6 +45,14 @@ export interface AgentHookDepositResult {
 }
 /** Merge Directive-owned project hook entries without replacing user configuration. */
 export declare function writeAgentHookDeposit(projectRoot: string, io?: InitDepositIo, hostHooksPolicy?: HostHooksPolicy, travelSeams?: HookRuntimeTravelSeams): AgentHookDepositResult;
+/**
+ * PreToolUse matchers a host would actually match against, read from the
+ * deposited file rather than regenerated from the constants (#3987).
+ *
+ * Null means the deposit is absent or unreadable — a different failure with a
+ * different remediation, already reported by `inspectAgentHookDeposit`.
+ */
+export declare function depositedPreToolUseMatchers(projectRoot: string, host: HookHost): readonly string[] | null;
 /** Read-only registration probe shared by verify and doctor. */
 export declare function inspectAgentHookDeposit(projectRoot: string, hostHooksPolicy?: HostHooksPolicy): AgentHookInspection[];
 //# sourceMappingURL=agent-hooks.d.ts.map

package/dist/init-deposit/agent-hooks.js

@@ -34,6 +34,13 @@ export const CURSOR_SESSION_HOOK_TIMEOUT_SECONDS = 5;
 export const CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS = 30;
 /** Nested Claude/Grok/Codex command-hook default timeout (seconds). */
 export const NESTED_HOOK_TIMEOUT_SECONDS = 5;
+/** Deposit file each supported host reads its PreToolUse registration from. */
+export const AGENT_HOOK_PATH_BY_HOST = {
+    claude: AGENT_HOOK_PATHS[0],
+    grok: AGENT_HOOK_PATHS[1],
+    cursor: AGENT_HOOK_PATHS[2],
+    codex: AGENT_HOOK_PATHS[3],
+};
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -404,6 +411,38 @@ function hasCursorRegistration(config) {
         preTool.some((entry) => isCursorToolBeforeEntry(entry, MCP_HOOK_MATCHER)) &&
         preCompact.some((entry) => object(entry)?.command === command("cursor", "session.compact")));
 }
+/**
+ * PreToolUse matchers a host would actually match against, read from the
+ * deposited file rather than regenerated from the constants (#3987).
+ *
+ * Null means the deposit is absent or unreadable — a different failure with a
+ * different remediation, already reported by `inspectAgentHookDeposit`.
+ */
+export function depositedPreToolUseMatchers(projectRoot, host) {
+    const path = join(resolve(projectRoot), AGENT_HOOK_PATH_BY_HOST[host]);
+    if (!existsSync(path))
+        return null;
+    let config;
+    try {
+        config = readConfig(path);
+    }
+    catch {
+        return null;
+    }
+    const hooks = object(config.hooks);
+    if (hooks === null)
+        return [];
+    const matcherOf = (entry) => {
+        const matcher = object(entry)?.matcher;
+        return typeof matcher === "string" ? [matcher] : [];
+    };
+    if (host === "cursor") {
+        const entries = Array.isArray(hooks.preToolUse) ? hooks.preToolUse : [];
+        return entries.filter(isManagedCursorEntry).flatMap(matcherOf);
+    }
+    const entries = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+    return entries.filter((entry) => isManagedNestedGroupForHost(entry, host)).flatMap(matcherOf);
+}
 /** Read-only registration probe shared by verify and doctor. */
 export function inspectAgentHookDeposit(projectRoot, hostHooksPolicy = loadHostHooksPolicyFromProject(projectRoot)) {
     const definitions = [

package/dist/init-deposit/host-tool-coverage.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Deterministic host tool-surface coverage check (#3987 acceptance item 3).
+ *
+ * #3990 shipped a Grok-only catalog asserted by a unit test against the
+ * generated matcher constants. That cannot catch what the acceptance item
+ * names: a host whose deposit went stale, or a host added with no coverage
+ * claim at all (5471374558 F7). This check reads the deposited files, walks
+ * every supported host, and fails closed on four distinct silences:
+ *
+ * 1. A supported host with no audit entry — the "new host drops out of
+ *    coverage" case. The typed `HOST_TOOL_SURFACE_AUDIT` record makes this a
+ *    compile error inside this package; the runtime check covers hosts added
+ *    to the deposit list alone.
+ * 2. A catalogued mutation tool name that is not a literal token of any
+ *    deposited matcher — the "renamed tool drops out of coverage" case. Read
+ *    from the deposit, so a stale file fails even when the constants are right.
+ * 3. A catalogued mutation tool name the runtime classifier does not place in
+ *    the same group. The deposited matcher is a literal alternation while the
+ *    classifier lowercases and strips punctuation, so the two layers can
+ *    disagree on a name that is present in both.
+ * 4. An audit entry that claims something without saying why: an empty
+ *    out-of-scope reason, a host claiming a fully observed surface while naming
+ *    no mutation tool, or a non-mutation entry the classifier actually gates.
+ */
+import { type HookHost } from "../hooks/dispatcher.js";
+import { type HostHooksPolicy } from "../policy/host-hooks.js";
+import { type AgentHookPath } from "./agent-hooks.js";
+export type HostToolCoverageFindingKind = 
+/** Supported host with no entry in the audit table. */
+"missing-audit"
+/** Catalogued mutation name absent from every deposited matcher. */
+ | "uncovered-tool"
+/** Deposited name the runtime classifier does not place in the same group. */
+ | "unclassified-tool"
+/** Audit entry that asserts without a written reason. */
+ | "unexplained-entry";
+export interface HostToolCoverageFinding {
+    readonly host: HookHost;
+    readonly path: AgentHookPath;
+    readonly kind: HostToolCoverageFindingKind;
+    readonly toolName: string | null;
+    readonly detail: string;
+}
+/**
+ * Read-only per-host coverage probe over the deposited matchers.
+ * A host whose deposit is missing or unreadable is skipped: that is a
+ * registration failure with its own remediation, reported by
+ * `inspectAgentHookDeposit`, and reporting it twice hides which one to fix.
+ */
+export declare function inspectHostToolCoverage(projectRoot: string, hostHooksPolicy: HostHooksPolicy): readonly HostToolCoverageFinding[];
+/** Remediation line for the coverage class, distinct from the deposit-refresh one. */
+export declare const HOST_TOOL_COVERAGE_RECOVERY: string;
+//# sourceMappingURL=host-tool-coverage.d.ts.map

package/dist/init-deposit/host-tool-coverage.js

@@ -0,0 +1,150 @@
+/**
+ * Deterministic host tool-surface coverage check (#3987 acceptance item 3).
+ *
+ * #3990 shipped a Grok-only catalog asserted by a unit test against the
+ * generated matcher constants. That cannot catch what the acceptance item
+ * names: a host whose deposit went stale, or a host added with no coverage
+ * claim at all (5471374558 F7). This check reads the deposited files, walks
+ * every supported host, and fails closed on four distinct silences:
+ *
+ * 1. A supported host with no audit entry — the "new host drops out of
+ *    coverage" case. The typed `HOST_TOOL_SURFACE_AUDIT` record makes this a
+ *    compile error inside this package; the runtime check covers hosts added
+ *    to the deposit list alone.
+ * 2. A catalogued mutation tool name that is not a literal token of any
+ *    deposited matcher — the "renamed tool drops out of coverage" case. Read
+ *    from the deposit, so a stale file fails even when the constants are right.
+ * 3. A catalogued mutation tool name the runtime classifier does not place in
+ *    the same group. The deposited matcher is a literal alternation while the
+ *    classifier lowercases and strips punctuation, so the two layers can
+ *    disagree on a name that is present in both.
+ * 4. An audit entry that claims something without saying why: an empty
+ *    out-of-scope reason, a host claiming a fully observed surface while naming
+ *    no mutation tool, or a non-mutation entry the classifier actually gates.
+ */
+import { HOOK_HOSTS } from "../hooks/dispatcher.js";
+import { HOST_TOOL_SURFACE_AUDIT, isDirectWriteTool, isShellTool, isSpawnTool, matcherHasLiteralToken, } from "../hooks/tools.js";
+import { isHostHookDepositEnabled } from "../policy/host-hooks.js";
+import { AGENT_HOOK_PATH_BY_HOST, depositedPreToolUseMatchers, } from "./agent-hooks.js";
+const CLASSIFIERS = {
+    directWrite: isDirectWriteTool,
+    shell: isShellTool,
+    spawn: isSpawnTool,
+};
+const MUTATION_GROUPS = ["directWrite", "shell", "spawn"];
+function auditFor(host) {
+    return HOST_TOOL_SURFACE_AUDIT[host];
+}
+function checkAuditShape(host, path, audit) {
+    const findings = [];
+    const mutationNames = MUTATION_GROUPS.flatMap((group) => audit.mutation[group]);
+    if (audit.unobservedReason !== null && audit.unobservedReason.trim().length === 0) {
+        findings.push({
+            host,
+            path,
+            kind: "unexplained-entry",
+            toolName: null,
+            detail: "unobservedReason is present but empty — say what was not observed, or set it null.",
+        });
+    }
+    if (audit.unobservedReason === null && mutationNames.length === 0) {
+        findings.push({
+            host,
+            path,
+            kind: "unexplained-entry",
+            toolName: null,
+            detail: "the audit claims a fully observed surface yet names no mutation tool. Either list the " +
+                "host's mutation spellings or record why the surface is unobserved.",
+        });
+    }
+    if (audit.source.trim().length === 0) {
+        findings.push({
+            host,
+            path,
+            kind: "unexplained-entry",
+            toolName: null,
+            detail: "source is empty — a coverage claim must name where it was observed.",
+        });
+    }
+    for (const [toolName, reason] of Object.entries(audit.nonMutation)) {
+        if (reason.trim().length === 0) {
+            findings.push({
+                host,
+                path,
+                kind: "unexplained-entry",
+                toolName,
+                detail: "listed out of scope with no written reason.",
+            });
+            continue;
+        }
+        const gated = MUTATION_GROUPS.find((group) => CLASSIFIERS[group](toolName));
+        if (gated !== undefined) {
+            findings.push({
+                host,
+                path,
+                kind: "unexplained-entry",
+                toolName,
+                detail: `recorded as out of scope, but the runtime classifier gates it as ${gated}.`,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Read-only per-host coverage probe over the deposited matchers.
+ * A host whose deposit is missing or unreadable is skipped: that is a
+ * registration failure with its own remediation, reported by
+ * `inspectAgentHookDeposit`, and reporting it twice hides which one to fix.
+ */
+export function inspectHostToolCoverage(projectRoot, hostHooksPolicy) {
+    const findings = [];
+    for (const host of HOOK_HOSTS) {
+        const path = AGENT_HOOK_PATH_BY_HOST[host];
+        if (!isHostHookDepositEnabled(host, hostHooksPolicy))
+            continue;
+        const audit = auditFor(host);
+        if (audit === undefined) {
+            findings.push({
+                host,
+                path,
+                kind: "missing-audit",
+                toolName: null,
+                detail: "supported host has no entry in HOST_TOOL_SURFACE_AUDIT, so nothing states which of " +
+                    "its tool names must be covered.",
+            });
+            continue;
+        }
+        findings.push(...checkAuditShape(host, path, audit));
+        const matchers = depositedPreToolUseMatchers(projectRoot, host);
+        if (matchers === null)
+            continue;
+        for (const group of MUTATION_GROUPS) {
+            for (const toolName of audit.mutation[group]) {
+                if (!matchers.some((matcher) => matcherHasLiteralToken(matcher, toolName))) {
+                    findings.push({
+                        host,
+                        path,
+                        kind: "uncovered-tool",
+                        toolName,
+                        detail: `${group} tool is absent from every deposited PreToolUse matcher.`,
+                    });
+                }
+                if (!CLASSIFIERS[group](toolName)) {
+                    findings.push({
+                        host,
+                        path,
+                        kind: "unclassified-tool",
+                        toolName,
+                        detail: `${group} tool is not recognized by the runtime ${group} classifier.`,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+/** Remediation line for the coverage class, distinct from the deposit-refresh one. */
+export const HOST_TOOL_COVERAGE_RECOVERY = "Recovery: run `deft update` to re-deposit the current matchers. If a finding survives that, " +
+    "the tool name is missing from Directive's own catalog rather than from your deposit — report " +
+    "it upstream with the host and tool name. Audit record: .deft/core/docs/host-tool-surface-audit.md (#3987).";
+//# sourceMappingURL=host-tool-coverage.js.map

package/dist/init-deposit/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./agent-hooks.js";
 export * from "./headless-manifest.js";
+export * from "./host-tool-coverage.js";
 export * from "./init-deposit.js";
 export * from "./init-dispatch.js";
 export * from "./legacy-detect.js";

package/dist/init-deposit/index.js

@@ -1,5 +1,6 @@
 export * from "./agent-hooks.js";
 export * from "./headless-manifest.js";
+export * from "./host-tool-coverage.js";
 export * from "./init-deposit.js";
 export * from "./init-dispatch.js";
 export * from "./legacy-detect.js";

package/dist/orchestration/subagent-monitor.d.ts

@@ -59,6 +59,12 @@ export interface SubagentMonitorArgs {
 }
 /** Parse CLI args mirroring Python argparse surface. */
 export declare function parseSubagentMonitorArgs(argv: string[]): SubagentMonitorArgs;
+/**
+ * On a terminal heartbeat, compare-and-release a dispatch-recorded child
+ * occupancy lease (#3999). Missing records and payload-kind skips are no-ops;
+ * liveness exit codes are unchanged.
+ */
+export declare function releaseTerminalChildOccupancy(records: readonly HeartbeatRecord[], cwd: string, now?: Date): void;
 /** Run subagent monitor; returns exit code. */
 export declare function cmdSubagentMonitor(argv: string[], cwd?: string): number;
 //# sourceMappingURL=subagent-monitor.d.ts.map

package/dist/orchestration/subagent-monitor.js

@@ -3,6 +3,7 @@
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
+import { releaseChildOccupancyOnTerminal, worktreeCandidatesForHeartbeat, } from "../session/child-occupancy.js";
 export const EXIT_OK = 0;
 export const EXIT_STALE = 1;
 export const EXIT_EXTERNAL_ERROR = 2;
@@ -372,6 +373,22 @@ export function parseSubagentMonitorArgs(argv) {
     }
     return parsed;
 }
+/**
+ * On a terminal heartbeat, compare-and-release a dispatch-recorded child
+ * occupancy lease (#3999). Missing records and payload-kind skips are no-ops;
+ * liveness exit codes are unchanged.
+ */
+export function releaseTerminalChildOccupancy(records, cwd, now = new Date()) {
+    for (const rec of records) {
+        if (!rec.is_terminal || rec.agent_id === null)
+            continue;
+        for (const root of worktreeCandidatesForHeartbeat(rec.path, cwd)) {
+            const released = releaseChildOccupancyOnTerminal(root, { agentId: rec.agent_id, now });
+            if (released.reason !== "missing-record")
+                break;
+        }
+    }
+}
 /** Run subagent monitor; returns exit code. */
 export function cmdSubagentMonitor(argv, cwd = process.cwd()) {
     const args = parseSubagentMonitorArgs(argv);
@@ -386,7 +403,12 @@ export function cmdSubagentMonitor(argv, cwd = process.cwd()) {
     const scratchEntries = args.scratchDirs.length > 0
         ? args.scratchDirs.map((p) => ({ readPath: resolve(cwd, p), label: p }))
         : [{ readPath: defaultScratchDir(cwd), label: defaultScratchDir(cwd) }];
-    const result = sweepScratchDirs(scratchEntries, { thresholdMinutes: args.thresholdMinutes });
+    const now = new Date();
+    const result = sweepScratchDirs(scratchEntries, {
+        thresholdMinutes: args.thresholdMinutes,
+        now,
+    });
+    releaseTerminalChildOccupancy(result.records, cwd, now);
     const configError = result.sweep_errors.length > 0 && result.records.length === 0;
     if (args.emitJson) {
         process.stdout.write(`${sweepToJson(result)}\n`);

package/dist/session/child-occupancy.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Dispatch-recorded child occupancy leases (#3999).
+ *
+ * A parent records the child's occupancy owner and the exact worktree root at
+ * dispatch in `.deft/child-occupancy/` — lease-gated, not `.deft-scratch/**`.
+ * The orchestration terminal transition already carries agent_id / parent_id /
+ * phase; this store is the missing occupancy-owner datum. Release reuses
+ * `releaseOccupancy` under the occupancy lock and only fires when the recorded
+ * child is still the current owner of the recorded tree.
+ *
+ * Per identity-source kind: `host-env` children are strangers and strand —
+ * that is the defect. `payload` parents share one id with their children, so
+ * the same transition is a no-op; auto-release would drop a live parent lease
+ * mid-flight. Swarm close-out of the launcher's occupancy_session_id is not
+ * the precedent and is not copied here.
+ */
+import type { LockDeps } from "../slice/lock.js";
+import { type OccupancyDecision } from "./occupancy.js";
+export declare const CHILD_OCCUPANCY_SCHEMA_VERSION = 1;
+export declare const CHILD_OCCUPANCY_DIR: readonly [".deft", "child-occupancy"];
+export declare const CHILD_OCCUPANCY_IDENTITY_SOURCE_KINDS: readonly ["host-env", "payload"];
+export type ChildOccupancyIdentitySourceKind = (typeof CHILD_OCCUPANCY_IDENTITY_SOURCE_KINDS)[number];
+export interface ChildOccupancyRecord {
+    readonly schemaVersion: number;
+    readonly agentId: string;
+    readonly parentId: string;
+    readonly occupancyOwner: string;
+    readonly worktreePath: string;
+    readonly identitySourceKind: ChildOccupancyIdentitySourceKind;
+}
+export interface ChildOccupancyDispatchInput {
+    readonly agentId: string;
+    readonly parentId: string;
+    readonly occupancyOwner: string;
+    readonly worktreePath: string;
+    readonly identitySourceKind: ChildOccupancyIdentitySourceKind;
+}
+export type ChildOccupancyReleaseReason = "released" | "already-free" | "owner-changed" | "payload-skip" | "missing-record" | "denied";
+export interface ChildOccupancyReleaseResult {
+    readonly reason: ChildOccupancyReleaseReason;
+    readonly record: ChildOccupancyRecord | null;
+    readonly occupancy: OccupancyDecision | null;
+}
+/** Filename-safe agent id; the payload keeps the original. */
+export declare function childOccupancyFileSegment(agentId: string): string;
+export declare function childOccupancyRelpath(agentId: string): string[];
+export declare function childOccupancyPath(storeRoot: string, agentId: string): string;
+export declare function childOccupancyIdentitySourceKind(host: string): ChildOccupancyIdentitySourceKind | null;
+export declare function readChildOccupancyLease(storeRoot: string, agentId: string): ChildOccupancyRecord | null;
+/**
+ * Parent-only write at dispatch. Workers cannot author this store: `.deft/` is
+ * not assist-scratch, so a mutation write is occupancy-gated and an assist
+ * writer does not get the scratch carve-out.
+ */
+export declare function recordChildOccupancyLease(storeRoot: string, input: ChildOccupancyDispatchInput): ChildOccupancyRecord;
+/**
+ * Compare-and-release under the occupancy lock. Caller identity is the id the
+ * parent recorded at dispatch — not the occupant currently named in the lease
+ * file, and not a field on a worker-authored heartbeat.
+ */
+export declare function releaseChildOccupancyOnTerminal(storeRoot: string, input: {
+    readonly agentId: string;
+    readonly now?: Date;
+    readonly lockDeps?: LockDeps;
+}): ChildOccupancyReleaseResult;
+/**
+ * Worktree guesses for a heartbeat file. Canonical layout is
+ * `<worktree>/.deft-scratch/subagent-status/<agent>.json`; cwd is the fallback
+ * when the scratch dir was passed as a custom path.
+ */
+export declare function worktreeCandidatesForHeartbeat(heartbeatPath: string, cwd: string): readonly string[];
+//# sourceMappingURL=child-occupancy.d.ts.map