@sabaiway/agent-workflow-kit 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.2.0 — a search whose pattern contains `>` no longer has to ask (AD-080)
+
+**Read this if you have ever approved `grep -rn "=>" src`.** 4.1.0 explained why that prompt cannot
+be fixed inside the guard. This release stops routing the search through the guard at all.
+
+**New: `tools/repo-search.mjs`** — a literal, read-only repository search with two lanes.
+
+- `--pattern <literal>` for an ordinary pattern.
+- `--pattern-file <path>` for a pattern containing `>`, `` ` `` or `$(` — the bytes the residual scan
+  actually matches (`|` and `&&` do not trip it; they only take a command off the compound
+  read-lane). Write the pattern with your host's file-write tool and pass the plain path. **The
+  pattern's bytes never enter the command string**, so the scan has nothing to scan. That is not
+  obfuscation — encoding would disguise bytes that stay on the shell surface where bash can still run
+  them; these leave the surface entirely.
+
+**You do not have to remember which lane to use.** The tool's invocation prefix is now in the hook's
+scanned list, so picking the inline lane for a byte-carrying pattern earns a refusal that NAMES
+`--pattern-file`. A wrong choice costs one guiding prompt; it never costs silence.
+
+**The hook gained coverage, it did not lose any.** A non-core command never reached the residual scan
+before — that is exactly why a plain kit tool is promptless — so a real redirection or command
+substitution on this tool's own invocation would have gone unexamined. It is examined now, by the
+UNCHANGED scan run over one more prefix. Nothing about what a byte MEANS was re-litigated; AD-079
+stands, and the tool is deliberately NOT in the seeded read-only core, so it inherits no compound
+read-lane allow.
+
+**Scope, kept narrow on purpose.** Literal search only — an arbitrary synchronous regex cannot be
+bounded by checks between work units, so the class is removed rather than mitigated. Only regular
+files are read (a FIFO or device read hangs and defeats every bound). Any bound that fires returns a
+structured `incomplete` naming which bound it was — never a silent empty result. The pattern file is
+excluded from its own search by resolved path, so an exotic query cannot match itself.
+
+**Honest residual.** Nothing forces the lane on a caller who ignores it: a bare `grep` prompts exactly
+as before. A literal inline `$(` is still indistinguishable from an active one, permanently — use the
+file lane. Bytes in search PATHS still over-ask. And promptlessness rests on your settings honouring
+the tool's allow rule: the hook returning "no decision" is not the same as an allow.
+
 ## 4.1.0 — why the gate hook still over-asks, established rather than assumed (AD-079)
 
 **Read this if the hook has ever made you approve `grep -rn "=>" src` or a plain read wearing

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.1.0'
+  version: '4.2.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "4.1.0",
+  "version": "4.2.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

@@ -261,6 +261,33 @@ export const matchSeededCorePrefix = (command) => {
   return matched ? matched.join(' ') : null;
 };
 
+// Kit tools whose invocations rung (b) scans even though they are NOT in the seeded read-only core.
+// The distinction is deliberate and load-bearing: CORING one of these would also hand it the
+// rung (c) read-lane allow, which is exactly what a tool taking caller-supplied arguments must not
+// have. This SEPARATE list buys the residual coverage without that side effect.
+//
+// AD-079 line: this is the SAME unchanged scan run over a different prefix — it never asks what a
+// byte MEANS, so it is on the permitted side. Nothing here parses or deletes a span.
+// KIT-QUALIFIED, forward-slash canonical. Matching on the bare basename was the first attempt and
+// 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']);
+
+// 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
+// just the one after `node`: both reviewers found the strict form under-inclusive, one through node
+// flags (`node --no-warnings <tool>`), one through an operator attached to the path
+// (`node <tool>>out`). A missed invocation silently restores the unscanned behaviour on exactly the
+// 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) => {
+  const tokens = tokenizeCommand(command).map(canonicalToken);
+  const hit = SCANNED_TOOL_PATHS.find((path) => tokens.some((token) => token.includes(path)));
+  return hit ?? null;
+};
+
 // String-level, conservative: the hook sees the PRE-SHELL command string, so every class is a raw
 // substring scan (never a whitespace-token check — a token check misses `"--output=f"` / `'>' f`
 // where the quotes are still in the string but the shell will strip them). A quoted metacharacter
@@ -380,6 +407,19 @@ export const decideBashCall = ({ command, permissionMode, cwdIsProjectRoot, gate
       };
     }
   }
+  // (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 residualClasses = detectResidualClasses(trimmed);
+    if (residualClasses.length > 0) {
+      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`,
+      };
+    }
+  }
   // (c) read-lane allow — opt-in (lanes.json), mode-fenced like (a) but cwd-agnostic (a read is a
   // read from any directory). Runs AFTER (b), so a residual-carrying core command still ASKs.
   if (readLaneOn === true && ALLOW_PERMISSION_MODES.includes(permissionMode) && isReadLaneCommand(trimmed)) {

package/references/modes/velocity.md

@@ -33,10 +33,11 @@ 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/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** — 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 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.
 
 **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

@@ -16,6 +16,14 @@ and improvised shapes are where approval prompts come from. The bar:
   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.
+- **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.
 
 **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

package/tools/repo-search.mjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+// repo-search.mjs — the promptless repository search lane (LITERAL search, read-only).
+//
+// WHY THIS EXISTS. A search whose pattern carries a shell-significant byte (`>`, `` ` ``, `$(`)
+// cannot be issued as a seeded-core command without raising the residual ASK: the guard scans the
+// raw command string AND a quote-stripped copy, so no quoting protects the byte. That is not a bug
+// to fix in the guard — AD-079 closed that direction on four verified counterexamples. This tool
+// routes around it instead, in two lanes:
+//
+//   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
+//
+// 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.
+//
+// CONTRACT
+//   LITERAL only — no regex dialect, and none is planned for this slice: a bounded walk cannot
+//   interrupt a catastrophically backtracking RegExp call, so the class is removed, not mitigated.
+//   Multiline patterns DO match (the search runs over the whole decoded buffer; a hit reports the
+//   line it starts on).
+//   Four outcomes, never collapsed: matches (0), no matches (0 with an explicitly empty result),
+//   INCOMPLETE (3, naming the bound that fired), invalid input (2), I/O failure (1).
+//   CONTAINMENT is decided on the REAL path, never lexically — a symlinked ancestor resolves out of
+//   the root while passing every `..` check, and on Windows `relative()` across drives returns an
+//   absolute path that contains no `..` at all.
+//   Every file is opened NO-FOLLOW and NON-BLOCKING, then `fstat`-ed on the descriptor actually
+//   opened: an lstat-then-read pair loses to a swap between the two calls, and the swapped-in FIFO
+//   is precisely the blocking read this tool promises cannot happen.
+//   Directories are walked INCREMENTALLY with the budget checked before each entry — reading and
+//   sorting a whole directory first is unbounded work in exactly the case bounds exist for.
+//
+//   THREAT MODEL, stated rather than implied. Explicit `--path`/`--pattern-file` targets are
+//   resolved (so a symlink INSIDE the root is followed by design) and then containment-checked on
+//   the real path; the WALK never traverses a symlink at all. What is NOT defended against is an
+//   adversary mutating the tree DURING the walk: a directory swapped for a symlink between its
+//   lstat and its opendir would be traversed, and closing that needs descriptor-relative traversal
+//   (`openat` semantics) which dependency-free Node does not expose. This tool searches a workspace
+//   its own agent controls; concurrent hostile mutation is out of scope, and saying so is the
+//   honest close — an unstated residual would be the defect.
+//   Pure reader — no writes, no subprocess, no network. Dependency-free, Node >= 22, no side
+//   effects on import (the isDirectRun idiom).
+
+import { openSync, fstatSync, readSync, closeSync, opendirSync, realpathSync, lstatSync, constants } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve, relative, isAbsolute, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_INCOMPLETE = 3;
+
+export const DEFAULT_MAX_RESULTS = 200;
+export const DEFAULT_MAX_FILE_BYTES = 2 * 1024 * 1024;
+export const DEFAULT_WALK_BUDGET = 20000;
+// Hard ceilings: a caller-supplied bound may lower these, never raise them. Without a ceiling the
+// bounds are advisory, which is the same as absent.
+export const HARD_MAX_RESULTS = 100000;
+export const HARD_MAX_FILE_BYTES = 64 * 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
+// matched in many places accumulate, because the match itself rode into every snippet. With a total
+// cap the stored size per match is a constant, so no size of pattern or file can grow it.
+const SNIPPET_CONTEXT = 200;
+const SNIPPET_MAX = 512;
+const NEVER_WALKED = Object.freeze(['.git', 'node_modules']);
+// O_NOFOLLOW refuses a symlinked leaf at open time; O_NONBLOCK means a FIFO that slipped in returns
+// instead of hanging. Both are POSIX; on a platform lacking them the flags degrade to 0 and the
+// fstat check below is the remaining guard.
+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 {}
+
+// 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
+// bytes; a digest separates them and survives any byte.
+export const patternDigest = (pattern) => {
+  const buf = Buffer.from(pattern, 'utf8');
+  return { digest: createHash('sha256').update(buf).digest('hex').slice(0, 16), bytes: buf.length };
+};
+
+// Exactly ONE trailing line ending is stripped — CRLF as one unit: a pattern file written by an
+// editor almost always ends in one, while a pattern that deliberately ends in a blank line keeps it.
+// Leaving a stray `\r` would make the search silently fail against LF content, which is the worst
+// possible failure mode for a tool whose whole job is finding text.
+export const resolvePattern = (raw) => {
+  if (raw.endsWith('\r\n')) return raw.slice(0, -2);
+  return raw.endsWith('\n') ? raw.slice(0, -1) : raw;
+};
+
+// `Number()` turns a long digit string into Infinity, which would disable the very bound being
+// parsed. Safe-integer and a hard ceiling are both required.
+export 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 = { pattern: null, patternFile: null, paths: [], max: DEFAULT_MAX_RESULTS, maxBytes: DEFAULT_MAX_FILE_BYTES, 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 === '--pattern') opts.pattern = next();
+    else if (arg === '--pattern-file') opts.patternFile = next();
+    else if (arg === '--path') opts.paths.push(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 === '--json') opts.json = true;
+    else throw new UsageError(`unknown argument: ${arg} (see --help)`);
+  }
+  if (opts.pattern !== null && opts.patternFile !== null) {
+    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('.');
+  return opts;
+};
+
+// 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) => {
+  const lexical = resolve(realRoot, target);
+  let real;
+  try {
+    real = realpathSync(lexical);
+  } catch (err) {
+    if (err?.code === 'ENOENT') throw new IoError(`no such path: ${target}`);
+    throw new IoError(`cannot resolve ${target} (${err?.code ?? err?.message ?? err})`);
+  }
+  const rel = relative(realRoot, real);
+  if (rel !== '' && (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))) {
+    throw new IoError(`target resolves outside the search root: ${target}`);
+  }
+  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 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) {
+    // ELOOP is a symlink refused by O_NOFOLLOW — a counted skip, not an error.
+    if (err?.code === 'ELOOP') state.skipped.symlinks += 1;
+    else state.skipped.unreadable += 1;
+    return null;
+  }
+  try {
+    const stat = fstat(fd);
+    if (!stat.isFile()) {
+      state.skipped.special += 1;
+      return null;
+    }
+    if (stat.size > maxBytes) {
+      state.skipped.large += 1;
+      // 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` };
+      }
+      return null;
+    }
+    const buf = Buffer.allocUnsafe(stat.size);
+    let got = 0;
+    while (got < stat.size) {
+      const n = read(fd, buf, got, stat.size - got, got);
+      if (n <= 0) break;
+      got += 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
+    // instead, which is counted and visible.
+    if (got !== stat.size) {
+      state.skipped.unreadable += 1;
+      return null;
+    }
+    return buf;
+  } catch {
+    state.skipped.unreadable += 1;
+    return null;
+  } finally {
+    close(fd);
+  }
+};
+
+const isBinary = (buf) => buf.subarray(0, BINARY_SNIFF_BYTES).includes(0);
+
+// Whole-buffer search, so a MULTILINE pattern matches; the line number is derived from the offset.
+// The newline cursor is carried ACROSS matches rather than recounted from zero for each one — with
+// the result cap at six figures, recounting is quadratic in the file length and burns the event
+// loop on exactly the large files a search is aimed at.
+const searchBuffer = (buf, pattern, relPath, state) => {
+  const text = buf.toString('utf8');
+  let from = 0;
+  let line = 1;
+  let counted = 0;
+  for (;;) {
+    const at = text.indexOf(pattern, from);
+    if (at === -1) return;
+    if (state.matches.length >= state.max) {
+      state.incomplete = { bound: 'max-results', detail: `stopped at ${state.max} result(s); more may exist` };
+      return;
+    }
+    for (let i = counted; i < at; i += 1) if (text.charCodeAt(i) === 10) line += 1;
+    counted = at;
+    // A pattern that STARTS on a newline would otherwise take that same byte as its own line start
+    // and report an empty snippet; searching back from the byte BEFORE it reports the line the match
+    // actually begins on.
+    const back = text.charCodeAt(at) === 10 ? Math.max(0, at - 1) : at;
+    const lineStart = text.lastIndexOf('\n', back) + 1;
+    // The snippet must span the WHOLE match: taking the line end from the match's START truncates a
+    // multiline pattern at its first newline, so the snippet could exclude the very text that
+    // matched (`\nbeta` in "alpha\nbeta" reported "alpha"). It is taken from the match's END.
+    const lineEndRaw = text.indexOf('\n', at + pattern.length);
+    const lineEnd = lineEndRaw === -1 ? text.length : lineEndRaw;
+    // The snippet is WINDOWED around the match, not the whole line. A minified file is one enormous
+    // line, and storing it per match turns a 200-result search into hundreds of megabytes — the
+    // bound has to apply to what is kept, not only to how many are kept.
+    const from0 = Math.max(lineStart, at - SNIPPET_CONTEXT);
+    const to0 = Math.min(lineEnd, at + pattern.length + SNIPPET_CONTEXT);
+    const windowed = `${from0 > lineStart ? '…' : ''}${text.slice(from0, to0)}${to0 < lineEnd ? '…' : ''}`;
+    const snippet = windowed.length > SNIPPET_MAX ? `${windowed.slice(0, SNIPPET_MAX - 1)}…` : windowed;
+    state.matches.push({ file: relPath, line, text: snippet });
+    from = at + Math.max(1, pattern.length);
+  }
+};
+
+const spend = (state) => {
+  if (state.walked >= state.walkBudget) {
+    if (state.incomplete === null) {
+      state.incomplete = { bound: 'walk-budget', detail: `stopped after ${state.walkBudget} entries; the tree was not fully traversed` };
+    }
+    return false;
+  }
+  state.walked += 1;
+  return true;
+};
+
+const walk = (root, abs, pattern, state, isExplicitTarget = false) => {
+  if (state.incomplete !== null || !spend(state)) return;
+
+  let stat;
+  try {
+    stat = (state.io.lstat ?? lstatSync)(abs);
+  } catch {
+    state.skipped.unreadable += 1;
+    return;
+  }
+  if (stat.isSymbolicLink()) {
+    state.skipped.symlinks += 1;
+    return;
+  }
+  if (stat.isDirectory()) {
+    // The default prune never applies to a directory the caller NAMED: `--path node_modules` asking
+    // for nothing back, silently, is a worse answer than searching it.
+    if (!isExplicitTarget && NEVER_WALKED.includes(abs.split(sep).pop())) return;
+    let dir;
+    try {
+      dir = (state.io.opendir ?? opendirSync)(abs);
+    } catch {
+      state.skipped.unreadable += 1;
+      return;
+    }
+    try {
+      // Incremental: the budget is consulted before each entry, so one enormous directory cannot
+      // force unbounded work (or unbounded memory) before the first check.
+      for (;;) {
+        const entry = dir.readSync();
+        if (entry === null) break;
+        if (state.incomplete !== null) break;
+        walk(root, join(abs, entry.name), pattern, state);
+      }
+    } finally {
+      dir.closeSync();
+    }
+    return;
+  }
+  if (state.excludePath !== null && abs === state.excludePath) {
+    state.skipped.patternFile += 1;
+    return;
+  }
+  const buf = readRegularFile(abs, state.maxBytes, state, state.io);
+  if (buf === null) return;
+  if (isBinary(buf)) {
+    state.skipped.binary += 1;
+    return;
+  }
+  searchBuffer(buf, pattern, relative(root, abs) || abs, state);
+};
+
+// `io` injects the filesystem primitives so the failure branches — a vanished entry, an unopenable
+// 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 = {} }) => {
+  const state = {
+    matches: [],
+    incomplete: null,
+    skipped: { symlinks: 0, binary: 0, special: 0, unreadable: 0, large: 0, patternFile: 0 },
+    excludePath,
+    io,
+    walked: 0,
+    walkBudget,
+    max,
+    maxBytes,
+  };
+  for (const target of paths) {
+    // The target list is bounded too: a caller passing thousands of --path values would otherwise
+    // spend unbounded work resolving them while walk() returns immediately.
+    if (state.incomplete !== null) break;
+    walk(root, resolveTarget(root, target), pattern, state, true);
+  }
+  return {
+    pattern: patternDigest(pattern),
+    matches: state.matches,
+    incomplete: state.incomplete,
+    skipped: state.skipped,
+    scanned: state.walked,
+  };
+};
+
+const formatResult = (result) => {
+  const lines = [
+    `repo-search — literal pattern sha256:${result.pattern.digest} (${result.pattern.bytes} byte(s)) · ${result.scanned} entr(ies) scanned`,
+  ];
+  for (const m of result.matches) lines.push(`${m.file}:${m.line}: ${m.text}`);
+  if (result.matches.length === 0) lines.push('  no matches');
+  const skips = Object.entries(result.skipped).filter(([, n]) => n > 0);
+  if (skips.length) lines.push(`  skipped: ${skips.map(([k, n]) => `${k}=${n}`).join(', ')}`);
+  if (result.incomplete) lines.push(`  ⚠ INCOMPLETE (${result.incomplete.bound}): ${result.incomplete.detail}`);
+  return lines.join('\n');
+};
+
+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]
+
+--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.
+
+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
+dropped silently; an oversized file additionally makes the whole search INCOMPLETE.
+
+Exit codes: 0 search completed (matches or an explicitly empty result) · 1 I/O failure or refusal ·
+2 usage / invalid input · 3 completed but INCOMPLETE (a bound fired; the bound is named).`;
+
+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);
+    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');
+    } 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 stdout = opts.json ? JSON.stringify(result, null, 2) : formatResult(result);
+    return { code: result.incomplete ? EXIT_INCOMPLETE : EXIT_OK, stdout, stderr: '', result };
+  } catch (err) {
+    if (err instanceof UsageError) return { code: EXIT_USAGE, stdout: '', stderr: `repo-search: ${err.message}`, result: null };
+    if (err instanceof IoError) return { code: EXIT_ERROR, stdout: '', stderr: `repo-search: ${err.message}`, result: null };
+    return { code: EXIT_ERROR, stdout: '', stderr: `repo-search: ${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/velocity-profile.mjs

@@ -144,6 +144,11 @@ export const KIT_READONLY_TOOLS = Object.freeze([
   KIT_RUN_GATES_TOOL,
   'tools/manifest/validate.mjs',
   'tools/release-scan.mjs',
+  // The literal search lane. It is in the tier for the ordinary reason (a pure reader the agent
+  // calls constantly), and its promptlessness additionally depends on it: a non-core command gets
+  // 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',
 ]);
 // 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