@deftai/directive-core 0.107.0 → 0.109.0

package/dist/hooks/tools.d.ts

@@ -1,12 +1,12 @@
 /** 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"];
+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). */
 export declare const SPAWN_TOOL_NAMES: readonly ["Task", "SubagentStart", "spawn_subagent", "start_agent", "CreateAgent"];
 /**
  * Host spellings for Shell/Bash execution tools (#2711).
  * Used for runtimeAuthority scopes.push / scopes.merge classification.
  */
-export declare const SHELL_TOOL_NAMES: readonly ["Shell", "Bash", "BashTool", "shell", "bash"];
+export declare const SHELL_TOOL_NAMES: readonly ["Shell", "Bash", "BashTool", "shell", "bash", "run_terminal_command"];
 /** 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,6 +32,24 @@ 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";
+};
+export declare function matcherHasLiteralToken(matcher: string, toolName: string): boolean;
 /**
  * PreToolUse matcher for MCP-class push/merge tools (#2711).
  * Regex-friendly for Claude/nested hosts. Prefer broad install match +

package/dist/hooks/tools.js

@@ -12,6 +12,8 @@ export const DIRECT_WRITE_TOOL_NAMES = [
     "DeleteFile",
     "ApplyPatch",
     "apply_patch",
+    "write",
+    "search_replace",
 ];
 /** PreToolUse spawn / sub-agent dispatch tools (#1185 / #2437). */
 export const SPAWN_TOOL_NAMES = [
@@ -25,7 +27,14 @@ export const SPAWN_TOOL_NAMES = [
  * Host spellings for Shell/Bash execution tools (#2711).
  * Used for runtimeAuthority scopes.push / scopes.merge classification.
  */
-export const SHELL_TOOL_NAMES = ["Shell", "Bash", "BashTool", "shell", "bash"];
+export const SHELL_TOOL_NAMES = [
+    "Shell",
+    "Bash",
+    "BashTool",
+    "shell",
+    "bash",
+    "run_terminal_command",
+];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 function normalizedToolName(toolName) {
@@ -87,6 +96,26 @@ 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",
+};
+export function matcherHasLiteralToken(matcher, toolName) {
+    return matcher.split("|").includes(toolName);
+}
 /**
  * PreToolUse matcher for MCP-class push/merge tools (#2711).
  * Regex-friendly for Claude/nested hosts. Prefer broad install match +

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

@@ -1,6 +1,7 @@
 import type { HookHost } from "../hooks/dispatcher.js";
 import { type HostHooksPolicy } from "../policy/host-hooks.js";
 import type { InitDepositIo } from "./constants.js";
+import { type HookRuntimeTravelSeams } from "./hook-runtime-travel.js";
 export { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 export declare const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export declare const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
@@ -41,7 +42,7 @@ export interface AgentHookDepositResult {
     readonly changedPaths: AgentHookPath[];
 }
 /** Merge Directive-owned project hook entries without replacing user configuration. */
-export declare function writeAgentHookDeposit(projectRoot: string, io?: InitDepositIo, hostHooksPolicy?: HostHooksPolicy): AgentHookDepositResult;
+export declare function writeAgentHookDeposit(projectRoot: string, io?: InitDepositIo, hostHooksPolicy?: HostHooksPolicy, travelSeams?: HookRuntimeTravelSeams): AgentHookDepositResult;
 /** 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

@@ -4,6 +4,7 @@ import { assertDepositContained } from "../deposit/contain.js";
 import { containedRemove, containedRename, containedWrite } from "../fs/contained-write.js";
 import { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 import { isHostHookDepositEnabled, loadHostHooksPolicyFromProject, } from "../policy/host-hooks.js";
+import { inspectHookRuntimeTravel } from "./hook-runtime-travel.js";
 export { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 export const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
@@ -252,7 +253,7 @@ function writeJsonIfChanged(projectRoot, path, payload, kind) {
     return true;
 }
 /** Merge Directive-owned project hook entries without replacing user configuration. */
-export function writeAgentHookDeposit(projectRoot, io = { printf: () => undefined }, hostHooksPolicy = loadHostHooksPolicyFromProject(projectRoot)) {
+export function writeAgentHookDeposit(projectRoot, io = { printf: () => undefined }, hostHooksPolicy = loadHostHooksPolicyFromProject(projectRoot), travelSeams = {}) {
     const changedPaths = [];
     const strippedPaths = [];
     const definitions = [
@@ -332,6 +333,12 @@ export function writeAgentHookDeposit(projectRoot, io = { printf: () => undefine
     if (changedPaths.length === 0 && strippedPaths.length === 0 && adaptersRemoved === 0) {
         io.printf("Directive agent hooks already current.\n");
     }
+    // #3785: the registration is trackable and the deposit that implements it is
+    // born-ignored, so warn when a clone would inherit the fence without a way to
+    // obtain the runtime it names.
+    const travel = inspectHookRuntimeTravel(projectRoot, definitions.map((definition) => ({ host: definition.host, path: definition.path })), hostHooksPolicy, travelSeams);
+    if (travel.warning !== null)
+        io.printf(`${travel.warning}\n`);
     return {
         changed: changedPaths.length + strippedPaths.length + adaptersRemoved > 0,
         changedPaths: [...changedPaths, ...strippedPaths],

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

@@ -25,6 +25,13 @@ export interface ReconstituteDepositResult {
     readonly reconstituted: boolean;
 }
 export type GitLsFiles = (projectDir: string, paths: readonly string[]) => string | null;
+/**
+ * Strip leading/trailing slashes so `.deft/cache/` and `.deft/cache` match.
+ * Globs are not expanded: a writer covered only by a glob fails closed (#3612).
+ */
+export declare function normalizeGitignorePath(p: string): string;
+export declare function gitignoreRuleCoversPath(rule: string, relPath: string): boolean;
+export declare function ignoreSetCoversPath(rules: readonly string[], relPath: string): boolean;
 /**
  * Reports whether `.deft/core` is tracked in git. Returns `null` when git is
  * unavailable or the tree is not a repository (treated as greenfield).

package/dist/init-deposit/gitignore.js

@@ -31,6 +31,13 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/last-session.json",
     ".deft/occupancy.json",
     ".deft/routing.local.json",
+    // #3612: remaining runtime writer roots kept at historical names (on-disk
+    // contracts). Relocating them would break existing consumer state.
+    ".deft/authz/",
+    ".deft/delivery-attempts/",
+    ".deft/metrics/",
+    ".deft/escalations/",
+    ".deft/approved-scope/",
     // Agent-host working state (#3502). Selective, NEVER blanket `.claude/`:
     // `.claude/settings.json`, `.claude/skills/` and `.claude/commands/` are
     // MANAGED DEPOSITS (agent-hooks.ts / skill-discovery-hosts.ts) and must stay
@@ -105,6 +112,23 @@ function gitignoreCoversLine(present, line) {
     }
     return false;
 }
+/**
+ * Strip leading/trailing slashes so `.deft/cache/` and `.deft/cache` match.
+ * Globs are not expanded: a writer covered only by a glob fails closed (#3612).
+ */
+export function normalizeGitignorePath(p) {
+    return p.replaceAll("\\", "/").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+export function gitignoreRuleCoversPath(rule, relPath) {
+    const r = normalizeGitignorePath(stripGitignoreInlineComment(rule));
+    const p = normalizeGitignorePath(relPath);
+    if (!r || r.startsWith("#"))
+        return false;
+    return r === p || p.startsWith(`${r}/`);
+}
+export function ignoreSetCoversPath(rules, relPath) {
+    return rules.some((rule) => gitignoreRuleCoversPath(rule, relPath));
+}
 function collectPresentGitignoreLines(existing) {
     const present = new Set();
     for (const raw of existing.split("\n")) {

package/dist/init-deposit/hook-runtime-travel.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Hook-runtime travel warning (#3785).
+ *
+ * Directive keeps the agent-hook registration files trackable by design and
+ * born-ignores the deposit that implements them. When a registration travels
+ * with the tree and nothing in that tree lets a clone obtain `deft-hook`, the
+ * registration arrives and the runtime does not. A fresh clone, CI runner, or
+ * container without a global install then fail-closes every mutation on an
+ * opaque exit 127, and no Directive code runs to explain it.
+ *
+ * "Travels" means tracked OR trackable-and-not-ignored. A first `deft init`
+ * writes the registration unstaged, so a tracked-only probe would go quiet on
+ * exactly the run that precedes the commit carrying the fence into every clone.
+ *
+ * The committed `package.json` dependency on `@deftai/directive` (#2264) is the
+ * existing reconstitution anchor. With it a clone can install the runtime the
+ * registration names; without it the registration names a command no clone can
+ * host. The anchor is read from the commit, not from the working tree or the
+ * index: a consumer can commit the generated registration and leave the
+ * manifest merely present, staged, or edited, and that is the case that strands
+ * the clone.
+ *
+ * Warn-only. Refusing `deft init` / `deft update` on this condition would be
+ * the same lockout from the other side, so the deposit still writes and
+ * reports. Absence of the runtime stays a deny — fail-open-on-absence was
+ * refuted as unimplementable and as a bypass primitive (#3156).
+ *
+ * Refs #3785, #3736, #3571, #2752, #2264, #3156.
+ */
+import { type HookHost, type HostHooksPolicy } from "../policy/host-hooks.js";
+import { type PinReadResult } from "../resolution/pin.js";
+/**
+ * Hosts whose registration is deposited `failClosed: true`. Only these turn a
+ * missing runtime into a denial; the rest fail open and merely lose the gate.
+ */
+export declare const FAIL_CLOSED_HOOK_HOSTS: readonly HookHost[];
+/** Manifest carrying the committed runtime anchor. */
+export declare const RUNTIME_ANCHOR_MANIFEST = "package.json";
+/**
+ * Spec prefixes that name a location instead of a release. Each resolves
+ * against something outside the tree -- a path, a symlink target, a workspace
+ * member -- so the clone that receives the registration cannot install from it.
+ */
+export declare const LOCATION_SPEC_PREFIXES: readonly ["file:", "link:", "portal:", "workspace:", "git+file:"];
+export type GitLsFilesProbe = (projectDir: string, paths: readonly string[]) => string | null;
+/** Contents of a path as committed at `HEAD`, or null when there is none. */
+export type CommittedFileProbe = (projectDir: string, path: string) => string | null;
+export interface HookRuntimeTravelSeams {
+    readonly gitLsFiles?: GitLsFilesProbe;
+    readonly readCommittedFile?: CommittedFileProbe;
+    readonly readPin?: (projectRoot: string) => PinReadResult;
+}
+/** One deposited registration considered by the probe. */
+export interface HookRegistrationRef {
+    readonly host: HookHost;
+    readonly path: string;
+}
+export interface HookRuntimeTravelResult {
+    /** Enabled registrations that travel with this repository. */
+    readonly travelingRegistrations: readonly string[];
+    /** Subset of {@link travelingRegistrations} deposited fail-closed. */
+    readonly failClosedRegistrations: readonly string[];
+    /** A committed manifest declares `@deftai/directive`, so a clone can install it. */
+    readonly runtimeTravels: boolean;
+    /** Null when the pairing is safe or git could not answer. */
+    readonly warning: string | null;
+}
+/**
+ * Report whether any enabled agent-hook registration travels with this tree
+ * while no manifest travelling alongside it lets a clone install the runtime it
+ * names.
+ *
+ * Disabled hosts are excluded: their registration is stripped, so a leftover
+ * copy cannot deny anything.
+ */
+export declare function inspectHookRuntimeTravel(projectRoot: string, registrations: readonly HookRegistrationRef[], hostHooksPolicy: HostHooksPolicy, seams?: HookRuntimeTravelSeams): HookRuntimeTravelResult;
+//# sourceMappingURL=hook-runtime-travel.d.ts.map

package/dist/init-deposit/hook-runtime-travel.js

@@ -0,0 +1,269 @@
+/**
+ * Hook-runtime travel warning (#3785).
+ *
+ * Directive keeps the agent-hook registration files trackable by design and
+ * born-ignores the deposit that implements them. When a registration travels
+ * with the tree and nothing in that tree lets a clone obtain `deft-hook`, the
+ * registration arrives and the runtime does not. A fresh clone, CI runner, or
+ * container without a global install then fail-closes every mutation on an
+ * opaque exit 127, and no Directive code runs to explain it.
+ *
+ * "Travels" means tracked OR trackable-and-not-ignored. A first `deft init`
+ * writes the registration unstaged, so a tracked-only probe would go quiet on
+ * exactly the run that precedes the commit carrying the fence into every clone.
+ *
+ * The committed `package.json` dependency on `@deftai/directive` (#2264) is the
+ * existing reconstitution anchor. With it a clone can install the runtime the
+ * registration names; without it the registration names a command no clone can
+ * host. The anchor is read from the commit, not from the working tree or the
+ * index: a consumer can commit the generated registration and leave the
+ * manifest merely present, staged, or edited, and that is the case that strands
+ * the clone.
+ *
+ * Warn-only. Refusing `deft init` / `deft update` on this condition would be
+ * the same lockout from the other side, so the deposit still writes and
+ * reports. Absence of the runtime stays a deny — fail-open-on-absence was
+ * refuted as unimplementable and as a bypass primitive (#3156).
+ *
+ * Refs #3785, #3736, #3571, #2752, #2264, #3156.
+ */
+import { execFileSync } from "node:child_process";
+import { disableHostHooksInvocation, isHostHookDepositEnabled, } from "../policy/host-hooks.js";
+import { PIN_DEPENDENCY_NAME, readPin } from "../resolution/pin.js";
+/**
+ * Hosts whose registration is deposited `failClosed: true`. Only these turn a
+ * missing runtime into a denial; the rest fail open and merely lose the gate.
+ */
+export const FAIL_CLOSED_HOOK_HOSTS = ["cursor"];
+/** Manifest carrying the committed runtime anchor. */
+export const RUNTIME_ANCHOR_MANIFEST = "package.json";
+/**
+ * Spec prefixes that name a location instead of a release. Each resolves
+ * against something outside the tree -- a path, a symlink target, a workspace
+ * member -- so the clone that receives the registration cannot install from it.
+ */
+export const LOCATION_SPEC_PREFIXES = [
+    "file:",
+    "link:",
+    "portal:",
+    "workspace:",
+    "git+file:",
+];
+/** Prefixes any clone can fetch: a registry alias or a remote repository. */
+const REMOTE_SPEC_PREFIXES = [
+    "npm:",
+    "http:",
+    "https:",
+    "git:",
+    "git+http:",
+    "git+https:",
+    "git+ssh:",
+    "github:",
+    "gitlab:",
+    "bitbucket:",
+];
+/**
+ * Whether a clone could install `deft-hook` from this spec.
+ *
+ * Allowlist, not denylist. Location forms are open-ended -- `file:`,
+ * `git+file:`, `../directive`, `/opt/directive`, `C:\src\directive`, `~/dev` --
+ * so enumerating them leaves the next shape uncovered, and an uncovered shape
+ * silences the warning. Anything that is not recognisably a registry release or
+ * a fetchable remote is therefore treated as not travelling. A bare
+ * `owner/repo` shorthand is refused on the same rule: it warns where the
+ * runtime might in fact arrive, which is the harmless direction for a
+ * warn-only probe.
+ */
+function reconstitutesForAClone(rawSpec) {
+    const spec = rawSpec.trim();
+    if (spec.length === 0)
+        return false;
+    const lower = spec.toLowerCase();
+    if (LOCATION_SPEC_PREFIXES.some((prefix) => lower.startsWith(prefix)))
+        return false;
+    if (REMOTE_SPEC_PREFIXES.some((prefix) => lower.startsWith(prefix)))
+        return true;
+    // Bare paths: relative, home-anchored, POSIX-absolute, or a Windows drive.
+    if (/^[.~/\\]/.test(spec) || /^[a-z]:[\\/]/i.test(spec))
+        return false;
+    // Anything else with a separator is a path or a repository shorthand, not a
+    // version, a range, or a dist-tag.
+    return !(spec.includes("/") || spec.includes("\\"));
+}
+function defaultGitLsFiles(projectDir, paths) {
+    try {
+        // Ask git rather than looking for `.git`: a project deposited into a
+        // subdirectory of a repository has no `.git` of its own, yet its
+        // registration is trackable by the parent. `ls-files` answers from any
+        // depth, relative to this directory, and declines outside a repository.
+        //
+        // `--cached` reports what is in the index, `--others --exclude-standard`
+        // what a first `deft init` just wrote and the next `git add` would sweep
+        // in; ignored paths are omitted, since they cannot reach a clone.
+        return execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "--", ...paths], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            windowsHide: true,
+        });
+    }
+    catch {
+        // git absent, or not a repository: whether these paths travel has no answer
+        // here, so the caller stays silent rather than guessing.
+        return null;
+    }
+}
+/** Paths that travel, as reported by git, or null when git could not answer. */
+function travelingPaths(output) {
+    if (output === null)
+        return null;
+    return new Set(output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0));
+}
+function defaultReadCommittedFile(projectDir, path) {
+    try {
+        // `HEAD:./<path>` resolves relative to this directory, so a project nested
+        // in a repository reads its own manifest rather than the parent's.
+        return execFileSync("git", ["show", `HEAD:./${path}`], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            windowsHide: true,
+        });
+    }
+    catch {
+        // No commit, no such path in it, or no repository: nothing is committed
+        // here that a clone would receive.
+        return null;
+    }
+}
+/** The `@deftai/directive` spec as committed, or null when none is. */
+function committedRuntimeSpec(manifest) {
+    if (manifest === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(manifest);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const pkg = parsed;
+    for (const block of ["devDependencies", "dependencies"]) {
+        const deps = pkg[block];
+        if (typeof deps !== "object" || deps === null || Array.isArray(deps))
+            continue;
+        const spec = deps[PIN_DEPENDENCY_NAME];
+        if (typeof spec === "string" && spec.trim().length > 0)
+            return spec.trim();
+    }
+    return null;
+}
+function isFailClosed(host) {
+    return FAIL_CLOSED_HOOK_HOSTS.includes(host);
+}
+function recoveryHosts(failClosed) {
+    const hosts = [...new Set(failClosed.map((entry) => entry.host))];
+    return hosts
+        .map((host) => `\`${disableHostHooksInvocation(` --host ${host} --confirm`)}\``)
+        .join(" / ");
+}
+function causeLine(anchor) {
+    if (anchor.kind === "uncommitted") {
+        return `  ${RUNTIME_ANCHOR_MANIFEST} declares ${PIN_DEPENDENCY_NAME} but is not committed, so a fresh`;
+    }
+    if (anchor.kind === "non-portable") {
+        return `  ${RUNTIME_ANCHOR_MANIFEST} pins ${PIN_DEPENDENCY_NAME} to \`${anchor.spec}\`, which no clone can install, so a fresh`;
+    }
+    return `  No ${RUNTIME_ANCHOR_MANIFEST} dependency on ${PIN_DEPENDENCY_NAME} travels with this tree, so a fresh`;
+}
+function fixLine(anchor) {
+    if (anchor.kind === "uncommitted") {
+        return `  Fix: commit ${RUNTIME_ANCHOR_MANIFEST} so the runtime travels with the registration.`;
+    }
+    if (anchor.kind === "non-portable") {
+        return `  Fix: pin ${PIN_DEPENDENCY_NAME} to a published version so a clone can install it.`;
+    }
+    return `  Fix: commit a ${RUNTIME_ANCHOR_MANIFEST} dependency on ${PIN_DEPENDENCY_NAME} so the runtime travels too.`;
+}
+/**
+ * Judge the anchor from the commit, not the working tree or the index.
+ *
+ * A clone receives commits. A manifest that is merely present, merely staged,
+ * or edited-but-uncommitted declares the runtime to this machine only, and the
+ * consumer is free to commit the generated registration without it.
+ */
+function resolveAnchorState(committedSpec, workingSpec) {
+    if (committedSpec === null) {
+        return workingSpec === null ? { kind: "absent" } : { kind: "uncommitted" };
+    }
+    if (!reconstitutesForAClone(committedSpec)) {
+        return { kind: "non-portable", spec: committedSpec };
+    }
+    return { kind: "travels" };
+}
+function buildWarning(traveling, failClosed, anchor) {
+    const listed = traveling
+        .map((entry) => `${entry.path}${isFailClosed(entry.host) ? " (fail-closed)" : ""}`)
+        .join(", ");
+    const cause = causeLine(anchor);
+    const lines = [
+        `\u26a0 Hook registration travels without its runtime (#3785): ${listed}`,
+        cause,
+        "  clone, CI runner, or container cannot obtain the `deft-hook` command these files name.",
+    ];
+    if (failClosed.length > 0) {
+        lines.push("  Fail-closed hosts then deny every mutation on an opaque exit 127, and no Directive", "  code runs to say why. There is no in-session recovery on a host without Node.");
+    }
+    lines.push(fixLine(anchor));
+    if (failClosed.length > 0) {
+        lines.push(`  Or, accepting the capability cost: ${recoveryHosts(failClosed)}.`);
+    }
+    lines.push("  \u2297 Do not hand-edit `failClosed` in the deposited file -- the next `deft update` restores it.", "  Detail: .deft/core/docs/hook-runtime-unavailable.md");
+    return lines.join("\n");
+}
+/**
+ * Report whether any enabled agent-hook registration travels with this tree
+ * while no manifest travelling alongside it lets a clone install the runtime it
+ * names.
+ *
+ * Disabled hosts are excluded: their registration is stripped, so a leftover
+ * copy cannot deny anything.
+ */
+export function inspectHookRuntimeTravel(projectRoot, registrations, hostHooksPolicy, seams = {}) {
+    const enabled = registrations.filter((entry) => isHostHookDepositEnabled(entry.host, hostHooksPolicy));
+    const probePaths = [...enabled.map((entry) => entry.path), RUNTIME_ANCHOR_MANIFEST];
+    const gitLsFiles = seams.gitLsFiles ?? defaultGitLsFiles;
+    const traveling = travelingPaths(gitLsFiles(projectRoot, probePaths));
+    if (traveling === null) {
+        return {
+            travelingRegistrations: [],
+            failClosedRegistrations: [],
+            runtimeTravels: false,
+            warning: null,
+        };
+    }
+    // The two sides are judged asymmetrically, deliberately. A registration is
+    // dangerous as soon as it is trackable: one `git add` sends it to every
+    // clone. An anchor counts only once a commit carries it, because a clone
+    // receives commits -- present, staged, and edited-but-uncommitted manifests
+    // all declare the runtime to this machine alone.
+    const readCommittedFile = seams.readCommittedFile ?? defaultReadCommittedFile;
+    const committedSpec = committedRuntimeSpec(readCommittedFile(projectRoot, RUNTIME_ANCHOR_MANIFEST));
+    const anchor = resolveAnchorState(committedSpec, (seams.readPin ?? readPin)(projectRoot).rawSpec);
+    const runtimeTravels = anchor.kind === "travels";
+    const travelingRegistrations = enabled.filter((entry) => traveling.has(entry.path));
+    const failClosedRegistrations = travelingRegistrations.filter((entry) => isFailClosed(entry.host));
+    const unsafe = travelingRegistrations.length > 0 && !runtimeTravels;
+    return {
+        travelingRegistrations: travelingRegistrations.map((entry) => entry.path),
+        failClosedRegistrations: failClosedRegistrations.map((entry) => entry.path),
+        runtimeTravels,
+        warning: unsafe ? buildWarning(travelingRegistrations, failClosedRegistrations, anchor) : null,
+    };
+}
+//# sourceMappingURL=hook-runtime-travel.js.map

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

@@ -10,6 +10,7 @@ import { homedir, platform } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
 import { copyTree } from "../deposit/copy-tree.js";
+import { assertLiveProcedureDepositClean } from "../deposit/live-procedure-targets.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
@@ -173,8 +174,10 @@ export async function runInitDeposit(args, io, seams = {}) {
     const resolveContent = seams.resolveContentRoot ?? resolveInstalledContentRoot;
     const copyContent = seams.copyContent ?? copyTree;
     const contentRoot = await resolveContent();
+    assertLiveProcedureDepositClean(contentRoot);
     await reconstituteDepositFromContent(contentRoot, deftDir, copyContent);
     await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
+    assertLiveProcedureDepositClean(deftDir);
     ensureInitGitignoreLines(projectDir, io);
     ensurePrettierIgnoreLines(projectDir, io);
     const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));

package/dist/init-deposit/refresh.js

@@ -13,6 +13,7 @@ import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
 import { replaceTree } from "../deposit/copy-tree.js";
+import { assertLiveProcedureDepositClean } from "../deposit/live-procedure-targets.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
@@ -476,9 +477,12 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const strategy = alreadyCurrent ? "no-op" : "file-swap";
     if (alreadyCurrent) {
         io.printf("[deft update] Framework payload already current; skipping payload copy.\n");
+        // C3 even when VERSION matches: skip-copy is not skip-validation (#3602).
+        assertLiveProcedureDepositClean(contentRoot);
         // #2913: still fail-closed reconcile so dst-only leftovers cannot linger when
         // VERSION already matches (e.g. pre-#2804 additive deposits). Does not re-stamp.
         await reconcileDepositToContentPackage(deftDir, contentRoot, io);
+        assertLiveProcedureDepositClean(deftDir);
         migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
         // #3117: ensure a readable live generation token exists without advancing
         // when the payload did not swap (already-current). stampLiveGeneration is a
@@ -504,8 +508,11 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     }
     else {
         // Full-tree replace (or injected seam). Additive copy is no longer the default.
+        // C3 the incoming package BEFORE replace so a reject cannot leave a broken deposit.
+        assertLiveProcedureDepositClean(contentRoot);
         await copyContent(contentRoot, deftDir);
         await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
+        assertLiveProcedureDepositClean(deftDir);
         // #2913 / #2804 / #2347: fail-closed delete-not-in-source BEFORE VERSION stamp.
         // replaceTree already drops dst-only paths; reconcile verifies and covers
         // additive seams. Throws => no VERSION rewrite (refuse stamp until clean).

package/dist/init-deposit/runtime-writers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Runtime writer paths that land in a consumer working tree (#3612).
+ *
+ * The ignore baselines and this list are coupled: every exported writer path
+ * constant MUST appear here, and a fail-closed test asserts the ignore set
+ * covers each entry on both shipped surfaces. New writers join this registry;
+ * they do not get a silent extra .deft/ name.
+ */
+/**
+ * Imported writer path constants. Order is the lockstep contract with
+ * runtime-writer-paths.json (Go reads that file).
+ */
+export declare const RUNTIME_WRITER_PATHS: readonly string[];
+//# sourceMappingURL=runtime-writers.d.ts.map

package/dist/init-deposit/runtime-writers.js

@@ -0,0 +1,33 @@
+/**
+ * Runtime writer paths that land in a consumer working tree (#3612).
+ *
+ * The ignore baselines and this list are coupled: every exported writer path
+ * constant MUST appear here, and a fail-closed test asserts the ignore set
+ * covers each entry on both shipped surfaces. New writers join this registry;
+ * they do not get a silent extra .deft/ name.
+ */
+import { AUTHZ_DIR } from "../authz/types.js";
+import { DEFAULT_TASK_CACHE_ROOT } from "../cache/task-cache/constants.js";
+import { SESSION_COMPLETED_MARKER_REL } from "../check/session-completed-ac.js";
+import { DELIVERY_ATTEMPT_DIR } from "../delivery-attempt/types.js";
+import { ESCALATION_DIR } from "../escalation/types.js";
+import { PROJECT_LOCAL_METRICS_DIR } from "../metrics/resolve-metrics-home.js";
+import { APPROVED_SCOPE_DIR } from "../scope-provenance/digest.js";
+import { AC_PASS_BANK_DIR } from "../session/ac-pass-banking.js";
+import { VERIFY_AC_SESSION_CACHE_DIR } from "../session/verify-ac-session-cache.js";
+/**
+ * Imported writer path constants. Order is the lockstep contract with
+ * runtime-writer-paths.json (Go reads that file).
+ */
+export const RUNTIME_WRITER_PATHS = Object.freeze([
+    AC_PASS_BANK_DIR,
+    VERIFY_AC_SESSION_CACHE_DIR,
+    SESSION_COMPLETED_MARKER_REL.join("/"),
+    AUTHZ_DIR,
+    DELIVERY_ATTEMPT_DIR,
+    PROJECT_LOCAL_METRICS_DIR,
+    ESCALATION_DIR,
+    APPROVED_SCOPE_DIR,
+    DEFAULT_TASK_CACHE_ROOT,
+]);
+//# sourceMappingURL=runtime-writers.js.map