@sabaiway/agent-workflow-kit 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 4.4.0 — the guard stops charging you for answers it already has (AD-082)
+
+**If the agent keeps asking you to approve its own `2>/dev/null`, this release is for you.** Two
+things changed, and neither refuses anything.
+
+**1. The ask now talks to the AGENT, not only to you.** Until now, when the guard stopped a read
+carrying a redirection it explained itself in *your* approval dialog — and the agent that composed the
+command never heard a word of it. So it composed the same shape again next turn. The ask now also
+carries a hint back to the agent naming the lane that would not have prompted at all. Nothing is
+blocked and nothing new is approved; if your host does not support the field, you get exactly the old
+behaviour. **You should see the same class of prompt arrive less often, not disappear** — the honest
+claim, stated because the alternative would be a promise this cannot keep.
+
+**2. Two lanes so several small questions stop becoming one composed shell.**
+
+- **`path-inventory.mjs` (new).** Does this exist, what type is it, how big, how many lines, what is
+  in that directory, what does this small config say — for any number of paths, in ONE call, promptless.
+  **A path that does not exist is a normal answer** (`exists:false`, exit 0), because "does either of
+  these exist" is a question whose interesting answer is "no", and a tool that errors on it sends you
+  straight back to writing a shell one-liner. Symlinks are reported by type and never followed;
+  binaries are reported, never decoded; every bound names itself instead of truncating quietly.
+- **`repo-search.mjs --paths-file`.** The pattern half already had a file lane; the TARGET half did
+  not, so a path containing a backtick or `$(` could not be searched without a prompt however you
+  quoted it. Now it can. Both lane files are excluded from the search itself, by real path.
+
+**What you must do to get the promptless part.** Re-run `/agent-workflow-kit velocity --kit-tools`.
+Allow rules are values already written into your `.claude/settings.json`; upgrading the kit does not
+edit them. The advisor now tells you exactly which entries you are missing.
+
+**Also in this release:** the guard's recovery advice is derived per tool (it used to name
+`--pattern-file` for every scanned tool, which was wrong the moment a second one existed), and it now
+names both possibilities — pass the byte out of band if it is part of an argument, drop it if it is a
+real redirect — because the guard cannot tell those apart and should not pretend to.
+
+**One consequence worth knowing about.** The guard's scanned-tool match is a substring match across
+the command, deliberately inclusive because an over-match only ever costs an extra prompt. Adding a
+second tool extends that: a command that merely MENTIONS `path-inventory.mjs` and carries a
+redirection now asks where it previously got no decision at all. That is the same licensed over-ask
+`repo-search.mjs` has had since 4.2.0, on one more path string.
+
+**One rule worth knowing if you pass paths to either tool.** A target must name exactly one thing:
+no empty value, no NUL byte, no `..` component (Node collapses it before the filesystem is consulted,
+so the tool could answer about a different file than you named). A trailing `/` or `/.` is not
+rejected — it asserts "this is a directory", exactly as it does to your shell. Awkward names are
+still supported: spaces at the edges, backticks, control bytes — that is what the file lanes carry.
+
+**Not in this release, deliberately.** A guard rung that DENIES instead of asking was designed,
+reviewed and withdrawn — for the second time — because a command substitution can embed an arbitrary
+command with no separator byte, so any such refusal can destroy work it never meant to touch. The
+guard still never denies.
+
 ## 4.3.0 — the coverage gate no longer certifies evidence it cannot bind to your tree (AD-081)
 
 **Read this if you have ever run `coverage-check --check` on its own.** Until now it read whatever

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '4.3.0'
+  version: '4.4.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/hooks/gate-approve.mjs

@@ -45,6 +45,12 @@
 //   (d) everything else → NO decision: exit 0, no output — the normal permission flow proceeds
 //       unchanged. The hook NEVER emits `deny`.
 //
+// EVERY ASK ALSO CARRIES A CALLER-FACING HINT (`additionalContext`). The ask itself goes to the
+// HUMAN and its reason never reaches the caller that composed the command — so the guard knew the
+// right lane and could not say it, which is the one thing every withdrawn deny design was buying.
+// The hint is that channel without the refusal, and a host that ignores the field degrades to
+// silence, i.e. to the previous behaviour. See the note above `HINT_CORE`.
+//
 // WHY THERE IS NO DENY RUNG, AND WHY THE DIRECTION IS RETIRED (kit 4.0.0 built one, AD-078
 // removed it; the class was closed from the other side instead). The withdrawn rung refused a
 // seeded read-only command that provably DISCARDED its output, on the argument that such a refusal
@@ -272,7 +278,16 @@ export const matchSeededCorePrefix = (command) => {
 // review killed it: it would pull ANY unrelated `repo-search.mjs` into rung (b2), turning a
 // pre-existing NO decision into an ASK — a change to a decision path this release has no business
 // touching.
-export const SCANNED_TOOL_PATHS = Object.freeze(['agent-workflow-kit/tools/repo-search.mjs']);
+// The RECOVERY is per tool, not a constant. When repo-search was the only entry the reason named the
+// literal `--pattern-file`, and that was wrong the moment a second tool joined: wrong for a tool with
+// no such flag, and already incomplete for repo-search itself once its TARGET half gained a lane. An
+// ask whose named recovery does not exist is worse than an ask with no advice, so the advice is
+// derived from whichever tool matched.
+export const SCANNED_TOOL_LANES = Object.freeze({
+  'agent-workflow-kit/tools/repo-search.mjs': '--pattern-file / --paths-file',
+  'agent-workflow-kit/tools/path-inventory.mjs': '--paths-file',
+});
+export const SCANNED_TOOL_PATHS = Object.freeze(Object.keys(SCANNED_TOOL_LANES));
 
 // Quotes stripped and separators canonicalised, so a relative, absolute, quoted or Windows-separated
 // spelling all compare the same. SUBSTRING, not equality, and scanned across EVERY token rather than
@@ -282,10 +297,13 @@ export const SCANNED_TOOL_PATHS = Object.freeze(['agent-workflow-kit/tools/repo-
 // surface this exists to cover, while a spurious match merely over-asks — so inclusiveness wins.
 const canonicalToken = (token) => token.replace(/["']/gu, '').replace(/\\/gu, '/');
 
-export const matchScannedToolPrefix = (command) => {
+export const matchScannedToolPrefix = (command) => matchScannedTools(command)[0] ?? null;
+
+// ALL matches, not just the first. A command naming two scanned tools would otherwise be advised
+// about whichever happens to sit earlier in the registry, and the residual may belong to the other.
+export const matchScannedTools = (command) => {
   const tokens = tokenizeCommand(command).map(canonicalToken);
-  const hit = SCANNED_TOOL_PATHS.find((path) => tokens.some((token) => token.includes(path)));
-  return hit ?? null;
+  return SCANNED_TOOL_PATHS.filter((path) => tokens.some((token) => token.includes(path)));
 };
 
 // String-level, conservative: the hook sees the PRE-SHELL command string, so every class is a raw
@@ -381,6 +399,35 @@ export const isReadLaneCommand = (command) => {
   });
 };
 
+// ── the caller-facing hint (rides an ask; refuses nothing) ────────────────────────────
+//
+// WHY THIS EXISTS, AND WHY IT IS NOT A DENY. An ask is answered by the HUMAN: `permissionDecisionReason`
+// is context for THEIR dialog and never reaches the caller that composed the command. So for the whole
+// life of this guard it has known the right lane and had no way to say it — which is the single reason
+// every withdrawn deny design looked attractive, since a deny is refusal-shaped and does reach the
+// caller. `additionalContext` is the same channel without the refusal. Probed live on 2026-07-28 with
+// a throwaway hook: a distinct marker was delivered to the model on `allow`, on `ask`, AND on no
+// decision at all.
+// FAIL-SAFE BY CONSTRUCTION: a host that does not honour the field simply drops it, which is exactly
+// the behaviour that existed before — silence. Nothing is refused, so a hint that is wrong for a
+// particular command costs the caller a sentence, never their work. That is the property no deny
+// design could ever claim.
+export const HINT_CORE = 'agent-workflow: this read left the promptless lane — a plain read-only command with no redirection, no banner and no quotes stays inside it. If the byte is a decoration you do not need, drop it and re-issue; if it is ordinary text inside an argument, a search belongs in `repo-search.mjs` (`--pattern-file`), and several path questions (exists / size / line count / listing / small-file contents) are ONE `path-inventory.mjs` call. If the byte is a deliberate operator, keep it and confirm by hand.';
+
+// The hint must not GUESS which of the two causes produced the residual — the guard cannot tell a
+// byte that is ordinary text inside an argument from a real shell operator, and pretending otherwise
+// is the exact claim AD-079 closed. So it names BOTH recoveries and lets the caller pick: the one
+// that fits is always present, and the one that does not costs a clause.
+// The hint never tells the caller to delete an operator it cannot read the intent of: dropping a
+// real `> report.json` would change what the command DOES, and a guard that silently edits meaning is
+// the failure this whole area was built to avoid. It names the out-of-band lane, notes that these
+// tools already bound and print their own result (so a decoration is usually redundant), and leaves a
+// deliberate operator to the human confirmation that already exists.
+const hintForScannedTools = (tools) => {
+  const lanes = tools.map((tool) => `\`${tool}\` → ${SCANNED_TOOL_LANES[tool]}`).join('; ');
+  return `agent-workflow: the residual guard stopped this. If the byte is part of an ARGUMENT, pass it out of band — ${lanes} — and its bytes then never enter the command string, so this guard has nothing to scan (whether the clean form still prompts depends on your settings allow rules, which this hook does not read). If the byte is a decoration you do not need, drop it: these tools bound and print their own result. If it is a deliberate operator, keep it and confirm by hand — that is what the prompt is for.`;
+};
+
 // ── the decision ladder (pure core) ───────────────────────────────────────────────────
 
 export const decideBashCall = ({ command, permissionMode, cwdIsProjectRoot, gates, readLaneOn = false }) => {
@@ -404,19 +451,23 @@ export const decideBashCall = ({ command, permissionMode, cwdIsProjectRoot, gate
       return {
         permissionDecision: DECISION_ASK,
         permissionDecisionReason: `agent-workflow residual guard: read-only-seeded "${corePrefix}" carries ${residualClasses.join(' + ')} — a settings allow rule cannot see runtime shape; confirm by hand`,
+        additionalContext: HINT_CORE,
       };
     }
   }
   // (b2) the same guard over the scanned kit tools. The refusal NAMES the lane that avoids it, so a
   // caller who picked the inline lane for a shell-significant pattern is corrected by the mechanism
   // rather than expected to have remembered the rule.
-  const scannedTool = matchScannedToolPrefix(trimmed);
-  if (scannedTool !== null) {
+  const scannedTools = matchScannedTools(trimmed);
+  if (scannedTools.length > 0) {
     const residualClasses = detectResidualClasses(trimmed);
     if (residualClasses.length > 0) {
+      const named = scannedTools.map((tool) => `"${tool}"`).join(' + ');
+      const lanes = [...new Set(scannedTools.map((tool) => SCANNED_TOOL_LANES[tool]))].join(' / ');
       return {
         permissionDecision: DECISION_ASK,
-        permissionDecisionReason: `agent-workflow residual guard: "${scannedTool}" carries ${residualClasses.join(' + ')} — pass the pattern with --pattern-file (its bytes then never enter the command string), or confirm by hand if the byte is really part of the invocation`,
+        permissionDecisionReason: `agent-workflow residual guard: ${named} carries ${residualClasses.join(' + ')} — pass the byte-carrying argument out of band with ${lanes} (its bytes then never enter the command string), or confirm by hand if the byte is really part of the invocation`,
+        additionalContext: hintForScannedTools(scannedTools),
       };
     }
   }

package/references/modes/velocity.md

@@ -33,11 +33,12 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [
 - `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd ${PROJECT_ROOT}` (wildcard — the read-only deployment advisor; its rendered apply one-liners are writers and still prompt)
 - `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs --strict <skill-dir>` (wildcard)
 - `node ${CLAUDE_SKILL_DIR}/tools/release-scan.mjs <path>` (wildcard)
-- `node ${CLAUDE_SKILL_DIR}/tools/repo-search.mjs --pattern <literal> --path <p>` (wildcard — the LITERAL search lane; for a pattern carrying a shell-significant byte use `--pattern-file <p>` instead, so the bytes never enter the command string. This is the ONE tier tool that DOES carry hook residual coverage — see the honesty note below)
+- `node ${CLAUDE_SKILL_DIR}/tools/repo-search.mjs --pattern <literal> --path <p>` (wildcard — the LITERAL search lane; for a pattern carrying a shell-significant byte use `--pattern-file <p>` instead, and for a TARGET PATH carrying one use `--paths-file <p>` — either way the bytes never enter the command string. one of the TWO tier tools that carry hook residual coverage — see the honesty note below)
+- `node ${CLAUDE_SKILL_DIR}/tools/path-inventory.mjs --path <p>` (wildcard — the read-only inventory lane: exists / type / size / `wc -l` lines / one-level listing / small-file contents for N paths in ONE call, so small path questions never need a composed shell. `--paths-file <p>` is its out-of-band target lane; hook residual coverage as with repo-search)
 - `node ${CLAUDE_SKILL_DIR}/tools/run-gates.mjs --cwd ${PROJECT_ROOT}` — **EXACT byte-string only**, and honestly **project-exec, not read-only**: it runs YOUR declared `docs/ai/gates.json` commands — the same trust boundary the opt-in hook grants byte-exact per-cmd. A wildcard would be BROADER than that boundary (`--cwd <dir>` executes another project's declared gates), so the bare cwd-defaulting form, any other `--cwd`, `--only`, and **`--final`** forms all still prompt (`--final` WRITES the final-run receipt into the core-evidence store — a recording run is never auto-approved).
 - Writer previews, **exact arg-free dry-run byte-strings only** (the SEEDED tier byte-string is the arg-free preview of each): `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs` · `node ${CLAUDE_SKILL_DIR}/tools/cheap-agents.mjs` · `node ${CLAUDE_SKILL_DIR}/tools/gate-hook.mjs` — every `--apply`/`--write`/`--yes` still prompts, always. (`gate-hook` also has a **`--read-lane`** flagged preview — the opt-in read-only compound lane, `${CLAUDE_SKILL_DIR}/references/modes/hook.md`; that flagged form is NOT the seeded arg-free byte-string, so it may **prompt once** — it IS a consent flow, stated, no silent cap.)
 
-Honesty notes: tier entries get **NO PreToolUse-hook residual coverage — with ONE deliberate exception, `repo-search.mjs`**, whose invocation prefix is in the hook's scanned list precisely because it takes caller-supplied argument bytes: a real redirection or command substitution on ITS invocation raises the ask, and the refusal names the `--pattern-file` lane that avoids it. It is NOT in the seeded core, so it never inherits the read-lane compound allow. Every other tier entry: the opt-in hook's residual ask-net guards only the seeded read-only CORE prefixes, so the tier rides the same settings-level residual posture as the core (redirection / command substitution are not inspectable at the settings layer; see the residual notice). A skill or project path that cannot survive UNQUOTED in a byte-exact rule (spaces, metacharacters, non-POSIX) **STOPs the tier up front with a clear error** — nothing is seeded. Anything you want covered beyond the tier — such paths, this repo's own relative-path spellings, other tools — stays a **BY-HAND add** to your settings, with the path your project actually reaches the kit by. Pre-existing `node …` allow entries that do NOT match the seeded tier byte-forms stay flagged by the advisory for hand review.
+Honesty notes: tier entries get **NO PreToolUse-hook residual coverage — with TWO deliberate exceptions, `repo-search.mjs` and `path-inventory.mjs`**, whose prefixes are in the hook's scanned list because they take caller-supplied argument bytes: a redirection or substitution on THEIR invocation raises the ask, whose reason names that tool's out-of-band lane (`--pattern-file` / `--paths-file`) — context for the HUMAN deciding, not a message to the caller. Neither is in the seeded core, so neither inherits the read-lane allow. Every other tier entry: the opt-in hook's residual ask-net guards only the seeded read-only CORE prefixes, so the tier rides the same settings-level residual posture as the core (redirection / command substitution are not inspectable at the settings layer; see the residual notice). A skill or project path that cannot survive UNQUOTED in a byte-exact rule (spaces, metacharacters, non-POSIX) **STOPs the tier up front with a clear error** — nothing is seeded. Anything you want covered beyond the tier — such paths, this repo's own relative-path spellings, other tools — stays a **BY-HAND add** to your settings, with the path your project actually reaches the kit by. Pre-existing `node …` allow entries that do NOT match the seeded tier byte-forms stay flagged by the advisory for hand review.
 
 **Invariants:** creates `.claude/` if absent and writes **only** `.claude/settings.json` (no other file); **never** allowlists commit/push/publish; **never** writes `settings.local.json`; never commits; opt-in `acceptEdits`, never silent.
 

package/references/shared/command-shapes.md

@@ -1,30 +1,31 @@
 ### Command shapes — the promptless bar for instructed reads & probes
 
-When a mode doc tells you to read a file or probe project state WITHOUT prescribing the exact
-command (a recon read, the version-stamp read, any "check X" instruction), the shape is yours —
-and improvised shapes are where approval prompts come from. The bar:
+When a mode doc tells you to read a file or probe state WITHOUT prescribing the exact command (a
+recon read, the version-stamp read, any "check X"), the shape is yours — and improvised shapes are
+where approval prompts come from. The bar:
 
-- **Reads ride the host's file-read tool** (Read/Grep/Glob in Claude Code, or your agent's
-  equivalent) whenever one exists — a file-read tool never fires a shell approval prompt.
+- **Reads ride the host's file-read tool** (Read/Grep/Glob, or your agent's equivalent) whenever one
+  exists — a file-read tool never fires a shell approval prompt.
 - **No file-read tool → ONE plain undecorated command per probe:** no `;`/`&&` compounds, no
-  redirects, no pipes, no command substitution — one probe per invocation. This applies the
-  deployed agent-rules lens’s «plain pipeline per call» discipline here as a stricter
-  single-command shape. Any decorated or chained form falls outside this contract’s baseline
-  guarantee; behavior is then host/config-dependent — it may prompt, an opt-in read-lane may
-  auto-approve a vetted compound, and command substitution may even slip past a prefix allow
-  rule. The plain single-command shape is the only shell fallback this contract treats as
-  promptless by construction.
-- **Improvised file writes ride the host's file-edit tools** (Write/Edit or the equivalent) —
-  never an ad-hoc heredoc or shell-redirect write.
+  redirects, no pipes, no command substitution — one probe per invocation (the lens’s «plain pipeline
+  per call», stricter). A decorated or chained form is outside this contract’s guarantee: behavior is
+  host/config-dependent — it may prompt, an opt-in read-lane may auto-approve a vetted compound, and
+  command substitution may even slip past a prefix allow rule. The plain single-command shape is the
+  only shell fallback that is promptless by construction.
+- **Improvised file writes ride the host's file-edit tools** (Write/Edit or equivalent) — never an
+  ad-hoc heredoc or shell-redirect write.
 - **Searching for TEXT is its own case.** A pattern carrying `>`, `` ` `` or `$(` prompts on a
-  seeded-core command however it is quoted — the guard scans the raw string and a quote-stripped
-  copy. Quoting is not a workaround. (`|`/`&&` do not trip it.) Use the host's search tool if it has
-  one; else, where the kit tier is seeded, `node <kit>/tools/repo-search.mjs --pattern <literal>`,
-  switching to `--pattern-file <path>` for a byte-carrying pattern — written with the file-write tool
-  above, so its bytes never enter the command string; else one plain command, accepting the prompt.
-  A wrong lane earns a refusal that NAMES the file lane. Residual: a bare `grep` still prompts, and
-  the file lane needs promptless host writes.
+  seeded-core command however quoted — the guard scans the raw string and a quote-stripped copy.
+  Quoting is not a workaround. (`|`/`&&` do not trip it.) Use the host's search tool if it has
+  one; else, with the kit tier seeded, `node <kit>/tools/repo-search.mjs --pattern <literal>`,
+  switching to `--pattern-file <path>` for a byte-carrying pattern and `--paths-file <path>` for a
+  byte-carrying TARGET — written with the file-write tool above, so their bytes never enter the
+  command string; else one plain command, taking the prompt. A wrong lane earns an ask naming the
+  right lane back to YOU, not just the human. **PATH questions too:** exists / size / lines / listing
+  (file text needs `--contents`), any number of paths, is ONE
+  `node <kit>/tools/path-inventory.mjs --path <p>` — not a bannered compound. Residual: a bare `grep` still prompts, and the file lanes need
+  promptless writes.
 
-**Scope — improvised shapes only.** The executable commands a mode doc itself prescribes (the
-`node …/tools/…` dispatch lines, `--apply` lanes, install/symlink steps) are OUTSIDE this
-contract: run them exactly as prescribed, as plain single invocations.
+**Scope — improvised shapes only.** The commands a mode doc itself prescribes (`node …/tools/…`
+dispatch lines, `--apply` lanes, install/symlink steps) are OUTSIDE this contract: run them exactly
+as prescribed, as plain single invocations.

package/tools/path-inventory.mjs

@@ -0,0 +1,516 @@
+#!/usr/bin/env node
+// path-inventory.mjs — the promptless path-inventory lane (read-only).
+//
+// WHY THIS EXISTS. The «useless approves» corpus keeps recording the same authoring shape: several
+// small read-only questions about paths — does it exist, how big is it, how many lines, what is in
+// that directory, what does this small config say — batched into ONE composed shell with `echo`
+// banners and a defensive `2>/dev/null`, because no single call answers them. The composition is
+// what raises the prompt: a redirect takes the command out of the read-lane before it is even split,
+// `echo` is outside the frozen read-only core, and the banner's quotes are forbidden per segment.
+// The corpus has only ever responded to removing the REASON to compose a shell. This tool is that
+// reason removed for the inventory half, the way repo-search.mjs is for the search half.
+//
+//   lane 1  --path <p>          repeatable, for a path with no shell-significant byte
+//   lane 2  --paths-file <p>    the targets' bytes NEVER enter the command string
+//
+// CONTRACT
+//   A MISSING path is a RESULT (`exists:false`, exit 0), never a failure. That is the whole point:
+//   "does either of these exist" is a question whose interesting answer is "no", and a tool that
+//   errors on it sends the caller straight back to a composed shell. Only a CONTAINMENT refusal or a
+//   real I/O fault is an error.
+//   CONTAINMENT is decided on the REAL path of the nearest EXISTING ancestor, so a target that does
+//   not exist is still refused when it lives behind a symlink pointing out of the root — a lexical
+//   check passes exactly that case.
+//   Symlinks are reported BY TYPE and never followed; a dangling one is reported as a symlink that
+//   does not resolve. Binary and special files are reported by type and never decoded.
+//   Line count is `wc -l` compatible — newline CHARACTERS — so a final line without one is not
+//   counted. A tool that answers a different question than the command it replaces is a trap.
+//   Results are DETERMINISTIC: targets in input order, directory entries in code-unit order.
+//   Four outcomes, never collapsed: results (0), INCOMPLETE (3, naming the bound that fired),
+//   invalid input (2), I/O failure or containment refusal (1). No bound ever truncates silently.
+//   Pure reader — no writes, no subprocess, no network. Dependency-free, Node >= 22, no side effects
+//   on import (the isDirectRun idiom).
+//
+//   THREAT MODEL, stated rather than inherited in silence. Containment is decided on the REAL path of
+//   the nearest existing ancestor, and every leaf is opened NO-FOLLOW; the directory listing never
+//   follows a symlink and never descends. What is NOT defended against is an adversary mutating the
+//   tree BETWEEN the containment check and the read: a directory swapped for a symlink in that window
+//   would be traversed, and closing it needs descriptor-relative traversal (`openat` semantics) which
+//   dependency-free Node does not expose. This is the SAME boundary `repo-search.mjs:33-40` states for
+//   the same reason — both tools inspect a workspace their own agent controls, and concurrent hostile
+//   mutation is out of scope. An unstated residual would be the defect; the residual itself is not.
+//
+// The paths-file FORMAT and the two failure classes are imported from repo-search.mjs rather than
+// restated: one definition means the two file lanes cannot drift into classifying the same failure
+// differently, which is the parity a copied helper would only promise.
+
+import { openSync, fstatSync, readSync, closeSync, opendirSync, realpathSync, lstatSync, constants } from 'node:fs';
+import { resolve, relative, isAbsolute, sep, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  UsageError,
+  IoError,
+  assertNameableTarget,
+  requiresDirectory,
+  decodeLaneFile,
+  parsePathsFile,
+  HARD_MAX_TARGETS,
+  HARD_MAX_PATHS_FILE_BYTES,
+} from './repo-search.mjs';
+
+export { HARD_MAX_TARGETS, HARD_MAX_PATHS_FILE_BYTES };
+
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_INCOMPLETE = 3;
+
+// One bound governs every byte this tool reads out of a file: the line count needs the bytes just as
+// much as `--contents` does, so a single named ceiling keeps "why is `lines` null" answerable.
+export const DEFAULT_MAX_CONTENT_BYTES = 1024 * 1024;
+export const HARD_MAX_CONTENT_BYTES = 16 * 1024 * 1024;
+export const DEFAULT_MAX_ENTRIES = 500;
+export const HARD_MAX_ENTRIES = 20000;
+// The AGGREGATE budget, and it is the load-bearing one. Per-file and per-directory ceilings bound a
+// SINGLE target; with up to HARD_MAX_TARGETS of them the run is still unbounded, and every result
+// accumulates in memory before anything is formatted. A cumulative ceiling is what makes the total
+// cost a constant no number of targets can grow.
+export const DEFAULT_MAX_TOTAL_BYTES = 8 * 1024 * 1024;
+export const HARD_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+export const DEFAULT_MAX_TOTAL_ENTRIES = 20000;
+export const HARD_MAX_TOTAL_ENTRIES = 200000;
+const BINARY_SNIFF_BYTES = 8192;
+const NEWLINE = 0x0a;
+
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const NONBLOCK = constants.O_NONBLOCK ?? 0;
+const OPEN_FLAGS = constants.O_RDONLY | NOFOLLOW | NONBLOCK;
+
+export const countLines = (buf) => {
+  let n = 0;
+  for (let i = 0; i < buf.length; i += 1) if (buf[i] === NEWLINE) n += 1;
+  return n;
+};
+
+// Over the WHOLE bounded buffer, not a sniff window: the contract says a binary is never decoded, and
+// a NUL past the window would otherwise be handed back as text in direct contradiction of it. The
+// buffer is already in memory and already bounded, so scanning all of it costs nothing extra.
+const isBinary = (buf) => buf.includes(0);
+
+const parseCount = (raw, flag, ceiling) => {
+  if (!/^\d{1,15}$/u.test(raw ?? '')) throw new UsageError(`${flag} needs a plain non-negative integer, got: ${raw ?? '(missing)'}`);
+  const n = Number(raw);
+  if (!Number.isSafeInteger(n)) throw new UsageError(`${flag} is not a safe integer: ${raw}`);
+  if (n > ceiling) throw new UsageError(`${flag} exceeds the hard ceiling ${ceiling}: ${raw}`);
+  return n;
+};
+
+const parseArgs = (argv) => {
+  const opts = {
+    paths: [],
+    pathsFile: null,
+    contents: false,
+    maxContentBytes: DEFAULT_MAX_CONTENT_BYTES,
+    maxEntries: DEFAULT_MAX_ENTRIES,
+    maxTotalBytes: DEFAULT_MAX_TOTAL_BYTES,
+    maxTotalEntries: DEFAULT_MAX_TOTAL_ENTRIES,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      i += 1;
+      if (i >= argv.length) throw new UsageError(`${arg} requires a value`);
+      return argv[i];
+    };
+    if (arg === '--path') {
+      const value = next();
+      // An empty value passes a bare count check and then resolves to the ROOT — precisely the
+      // accidental whole-root walk the "name at least one target" rule exists to prevent.
+      if (value === '') throw new UsageError('--path needs a non-empty target');
+      opts.paths.push(value);
+    }
+    else if (arg === '--paths-file') opts.pathsFile = next();
+    else if (arg === '--contents') opts.contents = true;
+    else if (arg === '--max-content-bytes') opts.maxContentBytes = parseCount(next(), '--max-content-bytes', HARD_MAX_CONTENT_BYTES);
+    else if (arg === '--max-entries') opts.maxEntries = parseCount(next(), '--max-entries', HARD_MAX_ENTRIES);
+    else if (arg === '--max-total-bytes') opts.maxTotalBytes = parseCount(next(), '--max-total-bytes', HARD_MAX_TOTAL_BYTES);
+    else if (arg === '--max-total-entries') opts.maxTotalEntries = parseCount(next(), '--max-total-entries', HARD_MAX_TOTAL_ENTRIES);
+    else if (arg === '--json') opts.json = true;
+    else throw new UsageError(`unknown argument: ${arg} (see --help)`);
+  }
+  // No implicit target. A tool that walks the whole root when asked about nothing turns a typo into
+  // an unbounded read, and the caller's question was always about NAMED paths.
+  if (opts.paths.length === 0 && opts.pathsFile === null) {
+    throw new UsageError('name at least one target with --path or --paths-file');
+  }
+  return opts;
+};
+
+// Containment on the REAL path of the nearest EXISTING ancestor. A target that does not exist has no
+// real path of its own, and a lexical check on the parent is exactly what a symlinked ancestor
+// defeats — so walk up until something resolves, and judge THAT.
+export const resolveContained = (realRoot, target) => {
+  assertNameableTarget(target);
+  const lexical = resolve(realRoot, target);
+  // Start the probe at the PARENT, never at the target itself: `realpathSync` on the target would
+  // dereference a symlink leaf, and this tool promises to report a symlink BY TYPE and never follow
+  // it. Probing the leaf turned a symlink pointing outside the root into a refusal instead of a
+  // result — a contract violation the contract itself names. The leaf is still safe: it is `lstat`-ed
+  // (which never follows) and opened O_NOFOLLOW (which refuses a symlink outright).
+  let probe = lexical === realRoot ? lexical : dirname(lexical);
+  for (;;) {
+    let real;
+    try {
+      real = realpathSync(probe);
+    } catch (err) {
+      // ENOTDIR walks up for the same reason ENOENT does: a regular file used as an intermediate
+      // component means the rest of the path does not exist, and "does not exist" is an ANSWER here,
+      // not a fault. Refusing it would break the tool's central promise on an ordinary typo.
+      if (err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR') {
+        throw new IoError(`cannot resolve ${target} (${err?.code ?? err?.message ?? err})`);
+      }
+      const parent = dirname(probe);
+      if (parent === probe) throw new IoError(`cannot resolve ${target}`);
+      probe = parent;
+      continue;
+    }
+    const rel = relative(realRoot, real);
+    if (rel !== '' && (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))) {
+      throw new IoError(`target resolves outside the root: ${target}`);
+    }
+    return lexical;
+  }
+};
+
+// Exported so the `special` fallback is testable: a FIFO, socket or device cannot be created inside
+// the sandbox this suite runs in (a unix socket `listen` is EPERM), and a test that quietly skips
+// when it cannot build its fixture is a test that checks nothing. These are pure maps from a stats
+// shape to a type name, so a stub exercises exactly the branch a device would.
+export const typeOfStats = (st) => {
+  if (st.isSymbolicLink()) return 'symlink';
+  if (st.isDirectory()) return 'directory';
+  if (st.isFile()) return 'file';
+  return 'special';
+};
+
+export const typeOfDirent = (entry) => {
+  if (entry.isSymbolicLink()) return 'symlink';
+  if (entry.isDirectory()) return 'directory';
+  if (entry.isFile()) return 'file';
+  return 'special';
+};
+
+// Open → fstat the DESCRIPTOR → read bounded. O_NOFOLLOW refuses a symlinked leaf at open time and
+// O_NONBLOCK means a special file that slipped in returns instead of hanging; fstat-ing the
+// descriptor that was actually opened is what a swap between check and read cannot defeat.
+// Returns a TAGGED outcome, never a bare null. An open that failed, a node that turned out not to be
+// a regular file, and a read that stopped short are three different facts, and collapsing any of them
+// into "here is your answer, lines are just null" is the silent failure this project forbids: the
+// caller cannot tell "empty" from "unreadable" from "half-read".
+const READ_OK = 'ok';
+const READ_UNREADABLE = 'unreadable';
+const READ_OVER_BOUND = 'over-bound';
+const READ_SHORT = 'short';
+
+// `io` is injectable so the SHORT-READ branch has a test. A read that stops early is a real race (the
+// file shrinks between the fstat and the read) that no test can stage honestly on a real filesystem,
+// and an untested defensive branch is indistinguishable from a wrong one.
+export const readBounded = (abs, maxBytes, io = {}) => {
+  const open = io.open ?? openSync;
+  const fstat = io.fstat ?? fstatSync;
+  const read = io.read ?? readSync;
+  const close = io.close ?? closeSync;
+  let fd;
+  try {
+    fd = open(abs, OPEN_FLAGS);
+  } catch (err) {
+    return { kind: READ_UNREADABLE, detail: err?.code ?? String(err) };
+  }
+  try {
+    const st = fstat(fd);
+    if (!st.isFile()) return { kind: READ_UNREADABLE, detail: 'not a regular file' };
+    const size = Number(st.size);
+    if (size > maxBytes) return { kind: READ_OVER_BOUND, size };
+    const buf = Buffer.allocUnsafe(size);
+    let got = 0;
+    for (;;) {
+      if (got >= size) break;
+      const n = read(fd, buf, got, size - got, got);
+      if (n <= 0) break;
+      got += n;
+    }
+    if (got !== size) return { kind: READ_SHORT, got, want: size };
+    // The size travels WITH the buffer: the caller must report and budget the size the read was
+    // actually sized by, never an earlier stat of the path. A file that grew in between would
+    // otherwise be published at the wrong size, charged the wrong amount, and returned as complete.
+    return { kind: READ_OK, buf, size };
+  } finally {
+    close(fd);
+  }
+};
+
+const noteBound = (state, bound, detail) => {
+  state.incomplete = state.incomplete ?? { bound, detail };
+};
+
+// Returns the entries AND the bound that cut them short, if any: a directory truncated by one
+// ceiling while a later target hits a different one must still be able to say which one truncated IT.
+const listDirectory = (abs, opts, state, rel) => {
+  const entries = [];
+  let bound = null;
+  const dir = opendirSync(abs);
+  try {
+    for (;;) {
+      const entry = dir.readSync();
+      if (entry === null) break;
+      if (entries.length >= opts.maxEntries) {
+        bound = '--max-entries';
+        noteBound(state, bound, `${rel} holds more than ${opts.maxEntries} entries`);
+        break;
+      }
+      if (state.entries >= opts.maxTotalEntries) {
+        bound = '--max-total-entries';
+        noteBound(state, bound, `the run reached ${opts.maxTotalEntries} listed entries at ${rel}`);
+        break;
+      }
+      state.entries += 1;
+      entries.push({ name: entry.name, type: typeOfDirent(entry) });
+    }
+  } finally {
+    dir.closeSync();
+  }
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { entries, bound };
+};
+
+const inspectTarget = (realRoot, rel, opts, state) => {
+  const abs = resolveContained(realRoot, rel);
+  let st;
+  try {
+    st = lstatSync(abs);
+  } catch (err) {
+    // ENOTDIR is the same answer as ENOENT: a component along the way is a regular file, so the path
+    // is not there. Anything else is a genuine fault and stays one.
+    if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') return { path: rel, exists: false };
+    throw new IoError(`cannot stat ${rel} (${err?.code ?? err?.message ?? err})`);
+  }
+  const type = typeOfStats(st);
+  // A trailing separator or `.` asserts a directory; the OS answers ENOTDIR when it is not one, and
+  // ENOTDIR is "not there" everywhere else in this tool.
+  if (requiresDirectory(rel) && type !== 'directory') return { path: rel, exists: false };
+  if (type === 'symlink') {
+    // Only "the target is not there" means it does not resolve. A permission error, an I/O error or a
+    // symlink LOOP are real faults, and reporting them as `(dangling)` with a clean exit would hide a
+    // failure behind a normal-looking answer — the silent-failure class this tool refuses elsewhere.
+    let resolves = true;
+    try {
+      realpathSync(abs);
+    } catch (err) {
+      if (err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR') {
+        throw new IoError(`cannot resolve the symlink ${rel} (${err?.code ?? err?.message ?? err})`);
+      }
+      resolves = false;
+    }
+    return { path: rel, exists: true, type, resolves };
+  }
+  if (type === 'directory') {
+    const listed = listDirectory(abs, opts, state, rel);
+    return {
+      path: rel,
+      exists: true,
+      type,
+      entries: listed.entries,
+      ...(listed.bound === null ? {} : { withheld: listed.bound }),
+    };
+  }
+  if (type !== 'file') return { path: rel, exists: true, type, bytes: Number(st.size) };
+
+  const size = Number(st.size);
+  const base = { path: rel, exists: true, type, bytes: size, readable: true };
+  // The bound that withheld THIS entry is recorded on the entry itself. `incomplete` keeps only the
+  // first event for the run, so a later target hitting a different ceiling would otherwise come back
+  // unread with no stated reason of its own.
+  const withheld = (bound, detail, observedBytes = size) => {
+    noteBound(state, bound, detail);
+    return { ...base, bytes: observedBytes, withheld: bound, lines: null, binary: null, ...(opts.contents ? { contents: null } : {}) };
+  };
+
+  // The read is bounded by whichever ceiling binds FIRST — the per-file one or what is LEFT of the
+  // run's budget. Checking the aggregate only afterwards would let every target read a full
+  // `--max-content-bytes` before being rejected, so the aggregate ceiling would bound the accounting
+  // and not the work, which is the opposite of what it is for.
+  const remaining = Math.max(0, opts.maxTotalBytes - state.bytes);
+  const limit = Math.min(opts.maxContentBytes, remaining);
+  const read = readBounded(abs, limit, opts.io);
+  // An unreadable file and a truncated read are I/O FAILURES, not bounds. The exit-code contract
+  // reserves 3 for a ceiling that fired and 1 for an I/O failure, and a failed `opendir` already
+  // exits 1 — reporting these as "incomplete" put a real fault under a code that means "bounded".
+  if (read.kind === READ_UNREADABLE) throw new IoError(`cannot read ${rel} (${read.detail})`);
+  if (read.kind === READ_SHORT) throw new IoError(`${rel} yielded ${read.got} of ${read.want} byte(s) — the file changed under the read`);
+  if (read.kind === READ_OVER_BOUND) {
+    // Which ceiling actually bound it is decided by the descriptor's size, so a file rejected because
+    // the RUN had no budget left is never blamed on the per-file limit.
+    // `bytes` comes from the DESCRIPTOR here too: the entry must not publish an earlier `lstat` size
+    // while the reason beside it quotes a different one.
+    // Blame the ceiling that FORMED the limit. Comparing against the per-file bound alone would name
+    // it even when the run's remaining budget was the smaller of the two and did the actual cutting.
+    return limit === opts.maxContentBytes
+      ? withheld('--max-content-bytes', `${rel} is ${read.size} byte(s), above ${opts.maxContentBytes}`, read.size)
+      : withheld('--max-total-bytes', `${rel} needs ${read.size} byte(s) and the run has ${remaining} left of ${opts.maxTotalBytes}`, read.size);
+  }
+  state.bytes += read.size;
+  const binary = isBinary(read.buf);
+  return {
+    ...base,
+    bytes: read.size,
+    lines: binary ? null : countLines(read.buf),
+    binary,
+    ...(opts.contents ? { contents: binary ? null : read.buf.toString('utf8') } : {}),
+  };
+};
+
+export const inventory = ({
+  root,
+  paths,
+  contents = false,
+  maxContentBytes = DEFAULT_MAX_CONTENT_BYTES,
+  maxEntries = DEFAULT_MAX_ENTRIES,
+  maxTotalBytes = DEFAULT_MAX_TOTAL_BYTES,
+  maxTotalEntries = DEFAULT_MAX_TOTAL_ENTRIES,
+  io = {},
+}) => {
+  const state = { incomplete: null, bytes: 0, entries: 0 };
+  const opts = { contents, maxContentBytes, maxEntries, maxTotalBytes, maxTotalEntries, io };
+  const results = paths.map((rel) => inspectTarget(root, rel, opts, state));
+  return { results, incomplete: state.incomplete };
+};
+
+// Control and ANSI bytes reach the terminal through a NAME the tool did not choose. Escaping them is
+// not cosmetic: a report about a hostile filename must not be a way to drive the reader's terminal.
+export const escapeForDisplay = (text) =>
+  [...text].map((ch) => {
+    const code = ch.codePointAt(0);
+    if (code < 0x20 || code === 0x7f) return `\\x${code.toString(16).padStart(2, '0')}`;
+    return ch;
+  }).join('');
+
+// The bound that withheld an entry is printed WITH that entry: a run-level `incomplete` line names
+// only the first event, so a reader of the human shape would otherwise see `unread` with no reason.
+const withheldSuffix = (entry) => (entry.withheld === undefined ? '' : ` [withheld: ${entry.withheld}]`);
+
+const formatEntry = (entry) => {
+  const name = escapeForDisplay(entry.path);
+  if (!entry.exists) return `${name}: absent`;
+  if (entry.type === 'symlink') return `${name}: symlink${entry.resolves ? '' : ' (dangling)'}`;
+  if (entry.type === 'directory') {
+    const head = `${name}: directory, ${entry.entries.length} entr(ies)${withheldSuffix(entry)}`;
+    return [head, ...entry.entries.map((e) => `    ${escapeForDisplay(e.name)}${e.type === 'directory' ? '/' : ''}`)].join('\n');
+  }
+  if (entry.type !== 'file') return `${name}: ${entry.type}, ${entry.bytes} byte(s)`;
+  const lines = entry.lines === null ? (entry.binary ? 'binary' : 'unread') : `${entry.lines} line(s)`;
+  const head = `${name}: file, ${entry.bytes} byte(s), ${lines}${withheldSuffix(entry)}`;
+  if (entry.contents === undefined || entry.contents === null) return head;
+  return [head, ...entry.contents.split('\n').map((l) => `    ${escapeForDisplay(l)}`)].join('\n');
+};
+
+const formatResult = (result) => {
+  const lines = result.results.map(formatEntry);
+  if (result.incomplete) lines.push(`  ⚠ INCOMPLETE (${result.incomplete.bound}): ${escapeForDisplay(result.incomplete.detail)}`);
+  return lines.join('\n');
+};
+
+const HELP = `path-inventory — read-only facts about named paths, without composing a shell.
+
+Usage:
+  node path-inventory.mjs --path <p> [--path <p>]... [--contents] [--json]
+  node path-inventory.mjs --paths-file <path> [--contents] [--json]
+
+Answers, for each named target: does it exist, what type is it, how many bytes, how many lines
+(wc -l compatible), what a directory holds (one level, sorted), and with --contents what a small
+text file says. A MISSING path is a normal result, not an error.
+
+--paths-file is the lane for targets carrying shell-significant bytes (\`>\`, \`$(\`, a backtick):
+one target per line, their bytes never enter the command string. Write it with your host's
+file-write tool; this tool never writes.
+
+Symlinks are reported by type and never followed. Binary and special files are reported by type and
+never decoded.
+
+Bounds — a bound that fires is NAMED on the run AND on the entry it withheld, never a silent
+truncation:
+  --max-content-bytes <n>   per file, for the line count and --contents
+  --max-entries <n>         per directory listing
+  --max-total-bytes <n>     the whole run, across every target
+  --max-total-entries <n>   the whole run, across every listing
+
+A target must NAME EXACTLY ONE filesystem object: no empty value, no NUL byte, and no ".."
+component (resolve() collapses it before the filesystem sees it). A trailing "/" or "/." is NOT
+rejected — it ASSERTS the target is a directory, exactly as it does to the OS: it holds for a real
+directory, and anything else answers exists:false. Awkward-but-unambiguous names — edge whitespace,
+backticks, control bytes — are supported, and --paths-file is the lane for the ones a command string
+cannot carry.
+
+Exit codes: 0 answered · 1 I/O failure or a containment refusal · 2 usage / invalid input ·
+3 answered but INCOMPLETE (a bound fired; the bound is named). A path that does not exist is a
+RESULT, not a failure — an unreadable one that DOES exist is an I/O failure.`;
+
+const readLaneFile = (root, rel, maxBytes) => {
+  const abs = resolveContained(root, rel);
+  const read = readBounded(abs, maxBytes);
+  if (read.kind !== READ_OK) {
+    throw new IoError(`cannot read --paths-file ${rel} as a regular file within ${maxBytes} byte(s) (${read.kind})`);
+  }
+  return decodeLaneFile(read.buf, '--paths-file');
+};
+
+export const main = (argv, ctx = {}) => {
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: EXIT_OK, stdout: HELP, stderr: '', result: null };
+    const root = realpathSync(resolve(ctx.cwd ?? process.cwd()));
+    const opts = parseArgs(argv);
+    const named = [...opts.paths];
+    if (opts.pathsFile !== null) {
+      named.push(...parsePathsFile(readLaneFile(root, opts.pathsFile, HARD_MAX_PATHS_FILE_BYTES)));
+    }
+    // Dedupe across the UNION, not only within each lane. Here it is more than tidiness: a duplicate
+    // target would be READ twice and charged twice against the run's aggregate byte budget.
+    const paths = [...new Set(named)];
+    // EVERY target is validated BEFORE any of them is inspected. Validating lazily means an invalid
+    // target late in the list is refused only if the run gets that far — so whether the invocation is
+    // accepted would depend on how much work happened first. A refusal must not depend on scheduling.
+    for (const target of paths) assertNameableTarget(target);
+    if (paths.length > HARD_MAX_TARGETS) {
+      throw new UsageError(`more than the ceiling of ${HARD_MAX_TARGETS} targets`);
+    }
+    const result = inventory({
+      root,
+      paths,
+      contents: opts.contents,
+      maxContentBytes: opts.maxContentBytes,
+      maxEntries: opts.maxEntries,
+      maxTotalBytes: opts.maxTotalBytes,
+      maxTotalEntries: opts.maxTotalEntries,
+    });
+    const stdout = opts.json ? JSON.stringify(result, null, 2) : formatResult(result);
+    return { code: result.incomplete ? EXIT_INCOMPLETE : EXIT_OK, stdout, stderr: '', result };
+  } catch (err) {
+    // Errors carry the caller's own path, so they are escaped exactly like the success output. A
+    // refusal that hands a hostile filename's control bytes straight to the terminal would make the
+    // safe path the only safe one, which is the wrong half to protect.
+    const say = (message) => `path-inventory: ${escapeForDisplay(String(message))}`;
+    if (err instanceof UsageError) return { code: EXIT_USAGE, stdout: '', stderr: say(err.message), result: null };
+    if (err instanceof IoError) return { code: EXIT_ERROR, stdout: '', stderr: say(err.message), result: null };
+    return { code: EXIT_ERROR, stdout: '', stderr: say(err?.message ?? err), result: null };
+  }
+};
+
+const emitResult = (r) => {
+  if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
+  if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);
+  process.exitCode = r.code;
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) emitResult(main(process.argv.slice(2)));

package/tools/repo-search.mjs

@@ -9,10 +9,16 @@
 //
 //   lane 1  --pattern <literal>        for a pattern with no shell-significant byte
 //   lane 2  --pattern-file <path>      the pattern's bytes NEVER enter the command string
+//   lane 3  --paths-file <path>        the TARGETS' bytes never enter it either
 //
-// The selection rule is enforced by the hook, not by memory: this tool's invocation is in the
-// hook's scanned list, so choosing lane 1 for a byte-carrying pattern earns an ASK whose reason
-// names lane 2. A wrong choice costs one guiding prompt; it never costs silence.
+// Lane 3 exists because lanes 1-2 answered only half the arguments: a search could name a pattern it
+// could not spell in a shell, but not a PATH it could not spell, and this kit ships shell-byte
+// fixtures as a genre. Both lane files are excluded from the search itself, by REAL path.
+//
+// The hook covers this tool's invocation: choosing lane 1 for a byte-carrying pattern raises an ASK
+// whose reason names lane 2. Stated exactly: that ask goes to the HUMAN, and the reason is context for
+// their decision — it is not delivered to the caller that composed the command. So the ask costs one
+// human decision and never costs silence, but it is not by itself a correction mechanism.
 //
 // CONTRACT
 //   LITERAL only — no regex dialect, and none is planned for this slice: a bounded walk cannot
@@ -58,6 +64,15 @@ export const DEFAULT_WALK_BUDGET = 20000;
 // bounds are advisory, which is the same as absent.
 export const HARD_MAX_RESULTS = 100000;
 export const HARD_MAX_FILE_BYTES = 64 * 1024 * 1024;
+// The `--paths-file` lane's own bounds. A target list arrives as a FILE, so neither its size nor its
+// entry count is visible in the command string the caller composed — without ceilings here the lane
+// would be the one unbounded input on a tool whose every other input is bounded.
+export const HARD_MAX_TARGETS = 5000;
+export const HARD_MAX_PATHS_FILE_BYTES = 4 * 1024 * 1024;
+// The AGGREGATE read budget. The walk budget counts ENTRIES; without a byte ceiling a run may read up
+// to the per-file limit for every one of them, which is unbounded work no bound was consulted about.
+export const DEFAULT_MAX_TOTAL_BYTES = 256 * 1024 * 1024;
+export const HARD_MAX_TOTAL_BYTES = 4 * 1024 * 1024 * 1024;
 const BINARY_SNIFF_BYTES = 8192;
 // Characters of context kept on EACH side of a match, and a HARD ceiling on the whole snippet.
 // The ceiling is the load-bearing one: bounding only the context still lets a huge --pattern-file
@@ -73,8 +88,12 @@ const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
 const NONBLOCK = constants.O_NONBLOCK ?? 0;
 const OPEN_FLAGS = constants.O_RDONLY | NOFOLLOW | NONBLOCK;
 
-class UsageError extends Error {}
-class IoError extends Error {}
+// Exported so a sibling kit tool reusing `parsePathsFile` maps the SAME failure to the SAME exit
+// code by construction — an `instanceof` against a private class would silently degrade a usage
+// error into a generic one, and exit-code parity between the two file lanes would be a promise
+// instead of a mechanism.
+export class UsageError extends Error {}
+export class IoError extends Error {}
 
 // The pattern is echoed as a DIGEST plus a byte length — never as a first content line. A first
 // line cannot separate two multiline patterns that share it, and it is unsafe for NUL/control
@@ -104,7 +123,7 @@ export const parseCount = (raw, flag, ceiling) => {
 };
 
 const parseArgs = (argv) => {
-  const opts = { pattern: null, patternFile: null, paths: [], max: DEFAULT_MAX_RESULTS, maxBytes: DEFAULT_MAX_FILE_BYTES, json: false };
+  const opts = { pattern: null, patternFile: null, paths: [], pathsFile: null, max: DEFAULT_MAX_RESULTS, maxBytes: DEFAULT_MAX_FILE_BYTES, maxTotalBytes: DEFAULT_MAX_TOTAL_BYTES, json: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     const next = () => {
@@ -115,8 +134,10 @@ const parseArgs = (argv) => {
     if (arg === '--pattern') opts.pattern = next();
     else if (arg === '--pattern-file') opts.patternFile = next();
     else if (arg === '--path') opts.paths.push(next());
+    else if (arg === '--paths-file') opts.pathsFile = next();
     else if (arg === '--max') opts.max = parseCount(next(), '--max', HARD_MAX_RESULTS);
     else if (arg === '--max-bytes') opts.maxBytes = parseCount(next(), '--max-bytes', HARD_MAX_FILE_BYTES);
+    else if (arg === '--max-total-bytes') opts.maxTotalBytes = parseCount(next(), '--max-total-bytes', HARD_MAX_TOTAL_BYTES);
     else if (arg === '--json') opts.json = true;
     else throw new UsageError(`unknown argument: ${arg} (see --help)`);
   }
@@ -124,14 +145,107 @@ const parseArgs = (argv) => {
     throw new UsageError('--pattern and --pattern-file are mutually exclusive — the lane must be unambiguous');
   }
   if (opts.pattern === null && opts.patternFile === null) throw new UsageError('one of --pattern or --pattern-file is required');
-  if (opts.paths.length === 0) opts.paths.push('.');
+  // The default target is applied only when the caller named NEITHER lane: `--paths-file` supplies
+  // targets after argv is parsed, so defaulting here on an empty `--path` list would silently union
+  // the whole root into an explicitly named list.
+  if (opts.paths.length === 0 && opts.pathsFile === null) opts.paths.push('.');
   return opts;
 };
 
+// The `--paths-file` format, pinned rather than discovered: one target per line, UTF-8, LF or CRLF, a
+// trailing delimiter is not an extra entry, EMPTY lines are ignored, duplicates collapse. There is no
+// comment syntax and no escaping, so a filename containing a newline CANNOT be expressed by this lane
+// — stated here because an unstated gap in a lane that exists to carry awkward names is the defect,
+// not the gap.
+//
+// A line is NOT trimmed. This lane exists to carry names a command string cannot, and a leading or
+// trailing space is exactly such a name: trimming would silently rewrite the caller's target, which is
+// the failure mode the lane was built to remove. A whitespace-only line is therefore a real target and
+// either resolves or fails loudly — never a silent stand-in for the root.
+//
+// THREE name classes this lane CANNOT express, stated rather than discovered: one containing a
+// newline (there is no escaping); one ENDING in a carriage return (a trailing CR is stripped as the
+// CRLF delimiter it almost always is, and no line-oriented format can tell those apart without an
+// encoding this lane deliberately does not have); and one whose bytes are not valid UTF-8. The first
+// two are refused by silence — the target simply will not be found, loudly. The third is refused
+// EXPLICITLY, because `Buffer.toString('utf8')` would replace the offending bytes with U+FFFD and the
+// lane would then search a DIFFERENT path that happens to exist, which is worse than any refusal.
+// `ignoreBOM: true` means "do not TREAT a leading U+FEFF as a byte-order mark", i.e. keep it as a
+// character. The default strips it, which would rewrite a legitimate name beginning with U+FEFF into
+// a different one — the same silent-substitution class as a lossy decode, one layer down.
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+export const decodeLaneFile = (buf, flag) => {
+  try {
+    return strictUtf8.decode(buf);
+  } catch {
+    throw new UsageError(`${flag} is not valid UTF-8 — a lossy decode would silently name a different path`);
+  }
+};
+export const parsePathsFile = (raw, flag = '--paths-file') => {
+  const entries = raw.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line)).filter((line) => line !== '');
+  // The ceiling counts TARGETS, so it is applied after dedupe: a file repeating one path 5001 times
+  // names one target and refusing it would be a bound on the file's shape rather than on the work.
+  const unique = [...new Set(entries)];
+  if (unique.length > HARD_MAX_TARGETS) {
+    throw new UsageError(`${flag} lists ${unique.length} distinct targets, above the ceiling of ${HARD_MAX_TARGETS}`);
+  }
+  if (unique.length === 0) throw new UsageError(`${flag} names no target — a blank list is never "search everything"`);
+  return unique;
+};
+
+// ── the acceptance predicate for a caller-supplied TARGET ─────────────────────────────
+//
+// ONE closed rule set, applied before any target reaches `resolve()`. It replaces what were seven
+// checks discovered one review round at a time, all of which turned out to be the same defect: a
+// caller string is handed to `path.resolve()` / `realpathSync`, whose semantics differ from the
+// operating system's, so the tool can end up answering about a DIFFERENT object than the string
+// denotes. That is the one outcome worse than any refusal.
+//
+// The rule the predicate enforces: **a target is accepted only if it names exactly one filesystem
+// object unambiguously.** Awkward-but-unambiguous names are supported on purpose — edge whitespace,
+// backticks, control bytes — because carrying those is what the out-of-band lane exists for.
+//
+// Separators are PLATFORM-CORRECT, and that is load-bearing: on POSIX a backslash is an ordinary
+// byte in a filename, so splitting on it would refuse `\..` — a legal file the OS answers about
+// normally. An over-refusal is a smaller defect than a wrong answer, but it is still a defect.
+const TARGET_SEPARATORS = Object.freeze(sep === '\\' ? ['/', '\\'] : ['/']);
+const TARGET_SEPARATOR_SPLIT = sep === '\\' ? /[\\/]/u : /\//u;
+
+// A trailing separator, or a trailing `.` component, is an ASSERTION by the caller that the target is
+// a DIRECTORY — that is what it means to the operating system, which answers ENOTDIR when it is not.
+// `resolve()` erases both forms before the filesystem sees them, so the assertion has to be carried
+// separately and checked after resolution. Refusing these outright was wrong in both directions: it
+// rejected `existing-directory/`, which names one object unambiguously, while still accepting
+// `regular-file/.`, which the OS refuses.
+//
+// Stated divergence, and it differs per tool. `path-inventory` reports a symlink BY TYPE and never
+// follows it, so `symlink-to-a-directory/` is not a directory there, while the OS would dereference
+// it — following it would contradict that tool's louder promise. `repo-search` DOES resolve an
+// explicitly named target (its threat model says so at the top of this file), so the assertion is
+// checked against the resolved object and it agrees with the OS.
+export const requiresDirectory = (target) => {
+  if (TARGET_SEPARATORS.some((separator) => target.endsWith(separator))) return true;
+  const components = target.split(TARGET_SEPARATOR_SPLIT);
+  return components[components.length - 1] === '.';
+};
+
+export const assertNameableTarget = (target, flag = '--path') => {
+  const refuse = (why) => {
+    throw new UsageError(`${flag} ${why} — got ${JSON.stringify(target)}`);
+  };
+  if (target === '') refuse('must not be empty; an empty target resolves to the whole root');
+  if (target.includes('\0')) refuse('must not contain a NUL byte; no filesystem path can hold one');
+  if (target.split(TARGET_SEPARATOR_SPLIT).includes('..')) {
+    refuse('must not contain a ".." component; resolve() collapses it lexically, so the answer could be about a different object than the OS would reach');
+  }
+};
+
 // Containment on the REAL path. A lexical check passes `link/secret.txt` whenever `link` resolves
 // outside, and on Windows a cross-drive `relative()` returns an absolute path carrying no `..` —
 // both were live review findings, not hypotheticals.
 export const resolveTarget = (realRoot, target) => {
+  assertNameableTarget(target);
   const lexical = resolve(realRoot, target);
   let real;
   try {
@@ -144,12 +258,15 @@ export const resolveTarget = (realRoot, target) => {
   if (rel !== '' && (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))) {
     throw new IoError(`target resolves outside the search root: ${target}`);
   }
+  if (requiresDirectory(target) && !lstatSync(real).isDirectory()) {
+    throw new IoError(`no such path: ${target} — a trailing separator or "." asserts a directory, and this is not one`);
+  }
   return real;
 };
 
 // Open → fstat the DESCRIPTOR → read bounded. The descriptor is what was actually opened, so a swap
 // after the check cannot substitute a different node; O_NOFOLLOW refuses a symlinked leaf outright.
-const readRegularFile = (abs, maxBytes, state, io = {}) => {
+const readRegularFile = (abs, maxBytes, state, io = {}, boundName = 'max-file-bytes') => {
   const open = io.open ?? openSync;
   const fstat = io.fstat ?? fstatSync;
   const read = io.read ?? readSync;
@@ -174,7 +291,7 @@ const readRegularFile = (abs, maxBytes, state, io = {}) => {
       // A skipped file is NOT a silent omission: the search is incomplete and says which bound did
       // it. Reporting it only as a counter would let a partial search read as "no matches".
       if (state.incomplete === null) {
-        state.incomplete = { bound: 'max-file-bytes', detail: `at least one file exceeds ${maxBytes} byte(s) and was not searched` };
+        state.incomplete = { bound: boundName, detail: `at least one file exceeds ${maxBytes} byte(s) and was not searched` };
       }
       return null;
     }
@@ -184,6 +301,10 @@ const readRegularFile = (abs, maxBytes, state, io = {}) => {
       const n = read(fd, buf, got, stat.size - got, got);
       if (n <= 0) break;
       got += n;
+      // Charged INSIDE the loop, per successful chunk. After the loop is too late: a `read` that
+      // throws mid-file skips the charge entirely, so a series of partial reads that end in a fault
+      // would move real bytes the aggregate budget never learns about.
+      state.bytesRead += n;
     }
     // A short read means the file changed under us. Returning the partial buffer would let a
     // truncated file come back as a confident "no matches" — the file is classified unreadable
@@ -293,11 +414,29 @@ const walk = (root, abs, pattern, state, isExplicitTarget = false) => {
     }
     return;
   }
-  if (state.excludePath !== null && abs === state.excludePath) {
-    state.skipped.patternFile += 1;
+  const excludedAs = state.excludePaths.get(abs);
+  if (excludedAs !== undefined) {
+    state.skipped[excludedAs] += 1;
+    return;
+  }
+  // The walk budget counts ENTRIES, not bytes, so without this a run may read up to the per-file
+  // ceiling for every one of them — twenty thousand files at the hard per-file ceiling is work no
+  // bound was ever consulted about. The sibling inventory tool already carries an aggregate byte
+  // budget for exactly this reason; this closes the asymmetry rather than stating it.
+  const remaining = state.maxTotalBytes - state.bytesRead;
+  if (remaining <= 0) {
+    state.incomplete = state.incomplete ?? {
+      bound: '--max-total-bytes',
+      detail: `stopped after reading ${state.bytesRead} byte(s); the tree was not fully searched`,
+    };
     return;
   }
-  const buf = readRegularFile(abs, state.maxBytes, state, state.io);
+  // The read is bounded by whichever ceiling binds FIRST. Checking the aggregate only BEFORE the file
+  // and then handing the reader the full per-file limit lets a single file larger than the remaining
+  // budget be read whole — the budget would bound the accounting, not the work.
+  const limit = Math.min(state.maxBytes, remaining);
+  const boundName = limit < state.maxBytes ? '--max-total-bytes' : 'max-file-bytes';
+  const buf = readRegularFile(abs, limit, state, state.io, boundName);
   if (buf === null) return;
   if (isBinary(buf)) {
     state.skipped.binary += 1;
@@ -310,15 +449,20 @@ const walk = (root, abs, pattern, state, isExplicitTarget = false) => {
 // directory, a symlink refused by O_NOFOLLOW, a file truncated mid-read — are reachable from tests.
 // Every one of them is a COUNTED skip in production, and a counted skip that no test ever exercises
 // is indistinguishable from a silent one.
-export const search = ({ root, pattern, paths, max, maxBytes, excludePath = null, walkBudget = DEFAULT_WALK_BUDGET, io = {} }) => {
+// `excludePaths` maps a REAL path to the skip counter it belongs to: BOTH lane files must be kept out
+// of their own search (a `--paths-file` under a searched target would otherwise match on its own
+// contents), and a skip that is not attributed to its lane is indistinguishable from a silent one.
+export const search = ({ root, pattern, paths, max, maxBytes, excludePaths = new Map(), walkBudget = DEFAULT_WALK_BUDGET, maxTotalBytes = DEFAULT_MAX_TOTAL_BYTES, io = {} }) => {
   const state = {
     matches: [],
     incomplete: null,
-    skipped: { symlinks: 0, binary: 0, special: 0, unreadable: 0, large: 0, patternFile: 0 },
-    excludePath,
+    skipped: { symlinks: 0, binary: 0, special: 0, unreadable: 0, large: 0, patternFile: 0, pathsFile: 0 },
+    excludePaths,
     io,
     walked: 0,
     walkBudget,
+    bytesRead: 0,
+    maxTotalBytes,
     max,
     maxBytes,
   };
@@ -334,6 +478,9 @@ export const search = ({ root, pattern, paths, max, maxBytes, excludePath = null
     incomplete: state.incomplete,
     skipped: state.skipped,
     scanned: state.walked,
+    // Reported so the aggregate budget is observable rather than internal: a bound that nobody can
+    // read is a bound nobody can test.
+    bytesRead: state.bytesRead,
   };
 };
 
@@ -351,14 +498,27 @@ const formatResult = (result) => {
 
 const HELP = `repo-search — literal repository search that never has to ride a shell metacharacter.
 
-Usage:
-  node repo-search.mjs --pattern <literal> [--path <p>]... [--max <n>] [--max-bytes <n>] [--json]
-  node repo-search.mjs --pattern-file <path> [--path <p>]... [--max <n>] [--max-bytes <n>] [--json]
+Usage — pick ONE pattern lane and ANY combination of target lanes:
+  pattern lane   --pattern <literal>   |   --pattern-file <path>          (mutually exclusive)
+  target lanes   [--path <p>]...       and/or   --paths-file <path>       (union; default: .)
+  shared flags   [--max <n>] [--max-bytes <n>] [--max-total-bytes <n>] [--json]
+
+A target must NAME EXACTLY ONE filesystem object: no empty value, no NUL byte, and no ".."
+component (resolve() collapses it before the filesystem sees it). A trailing "/" or "/." is NOT
+rejected — it ASSERTS the target is a directory, exactly as it does to the OS: it holds for a real
+directory and fails for anything else. Awkward-but-unambiguous names — edge whitespace, backticks,
+control bytes — are supported, and --paths-file is the lane for the ones a command string cannot
+carry.
+
+Two out-of-band lanes, one per argument half — their bytes never enter the command string, so the
+residual guard has nothing to scan:
+  --pattern-file <path>   a PATTERN carrying shell-significant bytes (\`>\`, \`$(\`, a backtick)
+  --paths-file <path>     TARGET paths carrying the same, one per line
 
---pattern-file is the lane for a pattern carrying shell-significant bytes (\`>\`, \`$(\`, a backtick):
-its bytes never enter the command string, so the residual guard has nothing to scan. Write the file
-with your host's file-write tool, then pass the plain path here, and delete it when you are done —
-this tool never writes.
+Write either file with your host's file-write tool, pass the plain path here, and delete it when you
+are done — this tool never writes. --paths-file format: one target per line, UTF-8, LF or CRLF; blank
+lines ignored; duplicates collapse; no comment syntax and no escaping, so a filename containing a
+newline cannot be expressed by this lane. Both lane files are excluded from the search itself.
 
 LITERAL only, multiline patterns supported. Reads regular files only, opened no-follow. Skipped
 entries (symlinks, non-regular, binary, oversized, unreadable) are counted and reported, never
@@ -372,21 +532,49 @@ export const main = (argv, ctx = {}) => {
     if (argv.includes('--help') || argv.includes('-h')) return { code: EXIT_OK, stdout: HELP, stderr: '', result: null };
     const root = realpathSync(resolve(ctx.cwd ?? process.cwd()));
     const opts = parseArgs(argv);
+    const excludePaths = new Map();
+    // ONE reader for both out-of-band lanes, so their failure classification cannot drift: a missing,
+    // unreadable or non-regular lane file is an IoError (exit 1) for the pattern lane and for the
+    // target lane alike.
+    const readLaneFile = (rel, flag, maxBytes, counter) => {
+      const abs = resolveTarget(root, rel);
+      // `bytesRead` is present but SEPARATE from the search's budget: reading a lane file is the
+      // caller's own instruction, not tree traversal, so it is accounted and then discarded.
+      const state = { skipped: { symlinks: 0, special: 0, unreadable: 0, large: 0 }, incomplete: null, bytesRead: 0 };
+      const buf = readRegularFile(abs, maxBytes, state);
+      if (buf === null) throw new IoError(`cannot read ${flag} ${rel} as a regular file`);
+      excludePaths.set(abs, counter);
+      return decodeLaneFile(buf, flag);
+    };
     let raw;
-    let excludePath = null;
     if (opts.patternFile !== null) {
-      excludePath = resolveTarget(root, opts.patternFile);
-      const state = { skipped: { symlinks: 0, special: 0, unreadable: 0, large: 0 }, incomplete: null };
-      const buf = readRegularFile(excludePath, HARD_MAX_FILE_BYTES, state);
-      if (buf === null) throw new IoError(`cannot read --pattern-file ${opts.patternFile} as a regular file`);
-      raw = buf.toString('utf8');
+      raw = readLaneFile(opts.patternFile, '--pattern-file', HARD_MAX_FILE_BYTES, 'patternFile');
     } else {
       raw = opts.pattern;
     }
     const pattern = opts.patternFile !== null ? resolvePattern(raw) : raw;
     if (pattern === '') throw new UsageError('the pattern is empty — it would match every line of every file');
 
-    const result = search({ root, pattern, paths: opts.paths, max: opts.max, maxBytes: opts.maxBytes, excludePath });
+    const named = [...opts.paths];
+    if (opts.pathsFile !== null) {
+      const listed = readLaneFile(opts.pathsFile, '--paths-file', HARD_MAX_PATHS_FILE_BYTES, 'pathsFile');
+      named.push(...parsePathsFile(listed));
+    }
+    // Dedupe across the UNION, not only within each lane: the same target named by `--path` and by
+    // the file would otherwise be walked twice.
+    const paths = [...new Set(named)];
+    // EVERY target is validated BEFORE any of them is walked. Validating lazily per target means an
+    // invalid one late in the list is only refused if the walk gets that far — and a bound that fires
+    // on an earlier target ends the loop first, so the same invocation would be accepted or refused
+    // depending on how much work happened to be done. A refusal must not depend on scheduling.
+    for (const target of paths) assertNameableTarget(target);
+    // The ceiling holds over the UNION. `parsePathsFile` bounds the file, but thousands of `--path`
+    // values would otherwise walk straight past it.
+    if (paths.length > HARD_MAX_TARGETS) {
+      throw new UsageError(`more than the ceiling of ${HARD_MAX_TARGETS} targets`);
+    }
+
+    const result = search({ root, pattern, paths, max: opts.max, maxBytes: opts.maxBytes, maxTotalBytes: opts.maxTotalBytes, excludePaths });
     const stdout = opts.json ? JSON.stringify(result, null, 2) : formatResult(result);
     return { code: result.incomplete ? EXIT_INCOMPLETE : EXIT_OK, stdout, stderr: '', result };
   } catch (err) {

package/tools/velocity-profile.mjs

@@ -149,6 +149,10 @@ export const KIT_READONLY_TOOLS = Object.freeze([
   // NO decision from the hook, which is not the same as an allow, so without this rule the lane
   // falls through to whatever the host policy happens to be.
   'tools/repo-search.mjs',
+  // The inventory lane, in the tier for the same reason and with the same dependency: the corpus of
+  // useless approvals is mostly small path questions batched into a composed shell because no single
+  // call answered them, and a lane the agent must still ask about is not a lane.
+  'tools/path-inventory.mjs',
 ]);
 // Writer previews: ONLY writers whose ARG-FREE invocation is a documented dry-run ("Default is
 // --dry-run" in their usage) seed an EXACT preview byte-string — every --apply/--write/--yes keeps
@@ -342,7 +346,7 @@ const USAGE = `usage: velocity-profile [--dry-run | --apply] [--kit-tools] [--br
 
 Allowlist mode (default): seeds the fixed read-only Claude Code allowlist into .claude/settings.json.
 Default is --dry-run. --apply writes; --accept-edits only sets defaultMode when applying.
---kit-tools additionally seeds the audited kit-tool tier: 9 read-only kit tools by resolved
+--kit-tools additionally seeds the audited kit-tool tier: ${KIT_WILDCARD_TOOLS.length} read-only kit tools by resolved
 absolute path (args wildcard), run-gates.mjs as ONE exact project-root-pinned byte-string
 (project-exec - it runs YOUR declared gates.json), and the writers' exact arg-free dry-run
 preview byte-strings. Never touches settings.local.json.
@@ -644,7 +648,7 @@ const formatAllowlist = (result) => [
 // The tier's honest posture, printed on every --kit-tools run: run-gates is project-exec (never
 // "read-only"), previews stay dry-run-only, and the tier gets none of the hook's residual ask-net.
 const KIT_TIER_NOTICE =
-  'kit-tools tier: paths are resolved absolute at seed time (fail-safe - a moved skill or stale path simply prompts again); run-gates.mjs is seeded as ONE exact byte-string pinned to this project root and is project-exec - it runs YOUR declared gates.json commands, never "read-only"; writer previews are exact dry-run byte-strings - every --apply/--write/--yes still prompts; tier entries get NO PreToolUse-hook residual coverage (settings-level posture only - see the velocity mode notes).';
+  'kit-tools tier: paths are resolved absolute at seed time (fail-safe - a moved skill or stale path simply prompts again); run-gates.mjs is seeded as ONE exact byte-string pinned to this project root and is project-exec - it runs YOUR declared gates.json commands, never "read-only"; writer previews are exact dry-run byte-strings - every --apply/--write/--yes still prompts; tier entries get NO PreToolUse-hook residual coverage EXCEPT repo-search.mjs and path-inventory.mjs, whose invocations the hook scans because they take caller-supplied argument bytes (settings-level posture only for the rest - see the velocity mode notes).';
 
 const formatKitTier = (result) =>
   result.kitTools