@sema-agent/core 7.15.0 → 7.17.0

package/dist/tools/fs/safety.js

@@ -23,15 +23,6 @@ const SEP = "/";
 export function isAbsolutePathForm(p) {
     return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\");
 }
-function normalizeForCompare(p) {
-    let n = stripWin32ExtendedPrefix(p);
-    if (isUncPath(n) && isWinFormPath(n) && !isWin32DeviceNamespacePath(n))
-        n = foldUncLexically(n).key;
-    n = isWinFormPath(n) ? n.replace(/\\/g, "/") : n;
-    if (/^[A-Za-z]:(\/|$)/.test(n))
-        n = n[0].toLowerCase() + n.slice(1);
-    return n;
-}
 function nativeSepOf(p) {
     return isWinFormPath(p) && p.includes("\\") ? "\\" : "/";
 }
@@ -323,26 +314,137 @@ function foldUncLexically(p) {
     const anchor = `\\\\${host}${share !== undefined ? `\\${share}` : ""}`;
     return { key: out.length > 0 ? `${anchor}\\${out.join("\\")}` : anchor, climbedAboveShare: climbed };
 }
+export function pathFamilyOf(bases) {
+    const tree = bases.root ?? bases.cwd;
+    return tree === undefined ? undefined : isWinFormPath(tree) ? "win" : "posix";
+}
+function isUncSpelling(p) {
+    return /^[\\/]{2}[^\\/]+[\\/]+[^\\/]/.test(p);
+}
+export function isAbsoluteForFamily(family, p) {
+    return family === "win" ? /^[A-Za-z]:[\\/]/.test(p) || isUncSpelling(p) : p.startsWith("/");
+}
+export const WIN32_NAMESPACE_REFUSALS = ["device_namespace", "unmappable_namespace", "unc_on_posix_tree", "drive_relative"];
+export const WIN32_NAMESPACE_REFUSAL_TEXT = {
+    device_namespace: "is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file)",
+    unmappable_namespace: "is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files)",
+    unc_on_posix_tree: "is a UNC (\\\\host\\share) spelling, which names no file on a POSIX tree",
+    drive_relative: "is drive-relative (a drive letter with no separator after the colon), a location no tree can locate",
+};
+export function win32NamespaceScreen(spelled, family) {
+    if (family === "win" && /^[\\/]{2}[?.][\\/]/.test(spelled) && !/^\\\\[?.]\\/.test(spelled))
+        spelled = spelled.replace(/\//g, "\\");
+    if (isWin32DeviceNamespacePath(spelled))
+        return { ok: false, refuse: "device_namespace" };
+    const mapped = stripWin32ExtendedPrefix(spelled);
+    if (mapped.startsWith("\\\\?\\"))
+        return { ok: false, refuse: "unmappable_namespace" };
+    if (mapped.startsWith("\\\\") && family === "posix")
+        return { ok: false, refuse: "unc_on_posix_tree" };
+    if (family === "win" && /^[A-Za-z]:(?![\\/])/.test(mapped))
+        return { ok: false, refuse: "drive_relative" };
+    return { ok: true, spelled: mapped };
+}
+export function pathIdentityOf(spelled, family, anchor) {
+    if (typeof spelled !== "string")
+        return { ok: false, reason: "relative" };
+    if (family !== "win") {
+        if (!spelled.startsWith("/"))
+            return { ok: false, reason: "relative" };
+        return { ok: true, identity: mintIdentity("", spelled.split("/"), false) };
+    }
+    const screened = win32NamespaceScreen(spelled, "win");
+    if (!screened.ok)
+        return { ok: false, reason: screened.refuse };
+    let s = screened.spelled;
+    if (s.startsWith("/") && isAbsoluteForFamily("win", s.slice(1)))
+        s = s.slice(1);
+    if (isUncSpelling(s)) {
+        const segs = s.slice(2).split(/[\\/]+/).filter((x) => x !== "");
+        const host = segs.shift();
+        const share = segs.shift();
+        return { ok: true, identity: mintIdentity(`//${host}/${share}`, segs, true) };
+    }
+    const drive = /^([A-Za-z]):[\\/]/.exec(s) ?? /^[\\/]([A-Za-z])(?=[\\/]|$)/.exec(s);
+    if (drive !== null)
+        return { ok: true, identity: mintIdentity(`/${drive[1].toLowerCase()}`, s.slice(2).split(/[\\/]/), false) };
+    if (s.startsWith("/") || s.startsWith("\\")) {
+        const root = anchor === undefined ? undefined : pathIdentityOf(anchor, "win");
+        if (root === undefined || !root.ok)
+            return { ok: false, reason: "unanchored" };
+        return { ok: true, identity: mintIdentity(identityAnchorOf(root.identity), s.slice(1).split(/[\\/]/), false) };
+    }
+    return { ok: false, reason: "relative" };
+}
+function mintIdentity(anchor, segments, stripTail) {
+    const out = [];
+    for (const seg of segments) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..") {
+            if (out.length > 0)
+                out.pop();
+            continue;
+        }
+        const stripped = stripTail ? seg.replace(/[. ]+$/, "") : seg;
+        out.push(stripped.length > 0 ? stripped : seg);
+    }
+    return (out.length === 0 ? anchor || "/" : `${anchor}/${out.join("/")}`);
+}
+function identityAnchorOf(identity) {
+    return identity.startsWith("//") ? identity.split("/").slice(0, 4).join("/") : identity.slice(0, 2);
+}
+export function isUncIdentity(identity) {
+    return identity.startsWith("//");
+}
+export function isPathIdentity(s, family) {
+    const r = pathIdentityOf(s, family);
+    return r.ok && r.identity === s;
+}
+export function isIdentityDir(identity, family) {
+    if (family !== "win")
+        return identity !== "/";
+    return identity.length > identityAnchorOf(identity).length;
+}
+export function carriesDotSegment(spelled, family) {
+    return (family === "win" ? /(^|[\\/])\.{1,2}([\\/]|$)/ : /(^|\/)\.{1,2}(\/|$)/).test(spelled);
+}
+export function clipSpelling(spelled) {
+    return spelled.length > 512 ? `${spelled.slice(0, 512)}…` : spelled;
+}
+export function isShellRootedSpellingUnmapped(family, spelled) {
+    return family === "win" && (spelled.startsWith("/") || spelled.startsWith("\\"));
+}
+export function nativeUncSpellingOf(family, spelled) {
+    return family === "win" && isUncSpelling(spelled) ? `\\\\${spelled.slice(2).replace(/\//g, "\\")}` : spelled;
+}
+export function joinForFamily(family, base, rel) {
+    if (family === "posix")
+        return `${base.replace(/\/+$/, "")}/${rel}`;
+    if (rel.startsWith("/") || rel.startsWith("\\")) {
+        const root = /^[A-Za-z]:/.exec(base)?.[0] ?? /^[\\/]{2}[^\\/]+[\\/]+[^\\/]+/.exec(base)?.[0];
+        return root === undefined ? rel : root + rel;
+    }
+    return `${base.replace(/[\\/]+$/, "")}${base.includes("\\") ? "\\" : "/"}${rel}`;
+}
 export function lexicalViewOf(spelled, base) {
-    const abs = isAbsolutePathForm(spelled)
-        ? spelled
-        : `${base.replace(/[\\/]+$/, "")}${isWinFormPath(base) && base.includes("\\") ? "\\" : "/"}${spelled}`;
-    return normalizeAbsPathLexically(abs);
+    const family = pathFamilyOf({ root: base });
+    return normalizeAbsPathLexically(isAbsoluteForFamily(family, spelled) ? spelled : joinForFamily(family, base, spelled));
 }
 function within(rootCanonical, p) {
     if (!rootCanonical)
         return false;
-    const rootN = normalizeForCompare(rootCanonical);
-    const pN = normalizeForCompare(p);
-    if (!rootN)
+    const family = pathFamilyOf({ root: rootCanonical });
+    const rootN = pathIdentityOf(rootCanonical, family);
+    const pN = pathIdentityOf(p, family);
+    if (!rootN.ok || !pN.ok)
         return false;
-    if (pN === rootN)
+    if (pN.identity === rootN.identity)
         return true;
-    const base = rootN.endsWith(SEP) ? rootN : rootN + SEP;
-    return pN.startsWith(base);
+    return pN.identity.startsWith(rootN.identity.endsWith(SEP) ? rootN.identity : rootN.identity + SEP);
 }
 export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRootsCanonical, exactFileReadExemption, readDeny, readFace) {
-    const canon = await canonicalizeTarget(env, path, signal, baseCwd);
+    const canon = await canonicalizeTarget(env, path, signal, pathFamilyOf({ root: rootCanonical }), baseCwd);
     if (!canon.ok)
         return { ok: false, violation: { code: "invalid", message: canon.message } };
     const key = canon.key;
@@ -397,23 +499,21 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
     }
     return { ok: true, key };
 }
-export async function canonicalizeTarget(env, path, signal, baseCwd) {
-    if (isWin32DeviceNamespacePath(path)) {
-        return { ok: false, message: `path "${path}" is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file); refused.` };
-    }
-    const unprefixed = stripWin32ExtendedPrefix(path);
-    if (unprefixed.startsWith("\\\\?\\")) {
-        return { ok: false, message: `path "${path}" is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files); refused.` };
+export async function canonicalizeTarget(env, path, signal, family, baseCwd) {
+    const screened = win32NamespaceScreen(path, family);
+    if (!screened.ok) {
+        return { ok: false, message: `path "${clipSpelling(path)}" ${WIN32_NAMESPACE_REFUSAL_TEXT[screened.refuse]}; refused (${screened.refuse}).`, refused: screened.refuse };
     }
-    if (isUncPath(unprefixed) && isWinFormPath(unprefixed)) {
+    const unprefixed = screened.spelled;
+    if (family === "win" && isUncSpelling(unprefixed)) {
         const folded = foldUncLexically(unprefixed);
         if (folded.climbedAboveShare) {
             return { ok: false, message: `path "${path}" climbs above its UNC share root via ".." (\\\\host\\share is the root of a network path); refused.` };
         }
         return { ok: true, key: folded.key };
     }
-    const spelled = unprefixed.startsWith("//") ? unprefixed.replace(/^\/+/, "/") : unprefixed;
-    const target = baseCwd && !isAbsolutePathForm(spelled) ? `${baseCwd.replace(/[\\/]+$/, "")}/${spelled}` : spelled;
+    const spelled = family === "posix" && unprefixed.startsWith("//") ? unprefixed.replace(/^\/+/, "/") : unprefixed;
+    const target = baseCwd && !isAbsoluteForFamily(family, spelled) ? joinForFamily(family, baseCwd, spelled) : spelled;
     const absR = await env.absolutePath(target, signal);
     if (!absR.ok)
         return { ok: false, message: `cannot resolve path "${path}": ${absR.error.message}` };
@@ -451,7 +551,7 @@ export async function canonicalizeTarget(env, path, signal, baseCwd) {
         if (!link.ok) {
             return { ok: false, message: `cannot read symlink "${path}": ${link.error.message}`, unresolvedSymlink: true };
         }
-        const linkTarget = isAbsolutePathForm(link.value) ? link.value : `${parentDir(abs)}${nativeSepOf(abs)}${link.value}`;
+        const linkTarget = isAbsoluteForFamily(family, link.value) ? link.value : joinForFamily(family, parentDir(abs), link.value);
         const reabs = await env.absolutePath(linkTarget, signal);
         if (!reabs.ok) {
             return { ok: false, message: `cannot resolve symlink target "${linkTarget}" for "${path}": ${reabs.error.message}`, unresolvedSymlink: true };

package/dist/tools/fs/search.d.ts

@@ -1,16 +1,13 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
-/** backlog #310 — the JS scanner's own output ceiling, in bytes of emitted content rows. Pinned to the
+/** The JS scanner's own output ceiling, in bytes of emitted content rows. Pinned to the
  *  ripgrep leg's figure ({@link MAX_EXEC_OUTPUT_BYTES}, the exec pipe's rolling-tail bound) so the two
  *  legs cannot disagree about how much one search may return; see the collection site in {@link jsGrep}
  *  for why this leg bounds the HEAD where the pipe bounds the tail. */
 export declare const JS_GREP_OUTPUT_MAX_BYTES: number;
-/** Directories never worth crawling (design/64 §10.3) — dependency/build/cache trees, PLUS the VCS
- *  metadata directories CC names explicitly (RB-200 F1, 220 @368402: `Ok_ = [".git",".svn",".hg",
- *  ".bzr",".jj",".sl"]` — git/svn/mercurial/bazaar/jujutsu/sapling). `.bzr`/`.jj`/`.sl` are additive here
- *  (the other three VCS dirs already lived in this list for the build/cache reason above; they're
- *  identical either way). See {@link buildIgnore}'s own comment for why this list is now the ENTIRE
- *  directory-skip story — the blanket "any dot-prefixed name is invisible" rule this list used to sit
- *  beside is gone. */
+/** Directories never worth crawling — dependency/build/cache trees, PLUS the six VCS metadata
+ *  directories CC names explicitly (git/svn/mercurial/bazaar/jujutsu/sapling). See {@link buildIgnore}'s
+ *  own comment for why this list is the ENTIRE directory-skip story: there is deliberately no blanket
+ *  "any dot-prefixed name is invisible" rule beside it. */
 export declare const DEFAULT_IGNORE_DIRS: ReadonlySet<string>;
 export interface GrepParams {
     /** Regular expression (ripgrep semantics) — CC 2.1.209 parity: the pattern is ALWAYS a regex; the
@@ -19,12 +16,12 @@ export interface GrepParams {
     pattern: string;
     /** Restrict the search to this sub-path (relative to root, or absolute within root). */
     path?: string;
-    /** Only search files matching this glob (e.g. `*.ts`, `*.{ts,tsx}`). 批④ #6 (CC parity): a
+    /** Only search files matching this glob (e.g. `*.ts`, `*.{ts,tsx}`). CC parity: a
      *  comma/whitespace-separated list (`"*.ts,*.tsx"`) is split into multiple globs (brace globs kept whole). */
     glob?: string;
-    /** 批④ #5 (CC 2.1.201 `-o`): print only the matched (non-empty) parts of each matching line, one match
-     *  per output line (rg -o / --only-matching). content mode only; ignored otherwise (CC parity).
-     *  1.253: with `multiline` the JS fallback emits the matched SEGMENT's lines (rg -U -o shape). */
+    /** CC `-o`: print only the matched (non-empty) parts of each matching line, one match per output
+     *  line (rg -o / --only-matching). content mode only; ignored otherwise (CC parity). With
+     *  `multiline` the JS fallback emits the matched SEGMENT's lines (rg -U -o shape). */
     only_matching?: boolean;
     /** content: `path:line:text`. files_with_matches (default, CC 2.1.209): `path`. count: `path:count`. */
     output_mode?: "content" | "files_with_matches" | "count";
@@ -46,7 +43,7 @@ export interface GrepParams {
     /** Skip the first N output lines — CC's `offset` (pagination partner of head_limit). */
     offset?: number;
 }
-/** 批④ #6 (CC 2.1.198 Grep call, bundle :333383-333390): split the `glob` param into individual glob
+/** CC 2.1.198 Grep parity: split the `glob` param into individual glob
  *  tokens — whitespace-separated first; a token WITHOUT braces is further split on commas
  *  (`"*.ts,*.tsx"` → two globs), while a brace token (`*.{ts,tsx}`) is kept whole (its commas are
  *  alternation syntax, not separators). CC-verbatim splitting rules. */
@@ -54,28 +51,26 @@ export declare function splitGlobParam(glob: string): string[];
 /**
  * POSIX-safe single-quote so an arbitrary model-supplied string can't break out of the shell command that
  * runs ripgrep. Wraps in single quotes (inside which the shell expands nothing — no `$()`, backtick, `;`, or
- * glob) and escapes any embedded single quote via the `'\''` idiom (close, escaped-quote, reopen). Exported
- * for direct injection testing (council [R145]). Renamed from `shq` for legibility.
+ * glob) and escapes any embedded single quote via the `'\''` idiom (close, escaped-quote, reopen).
+ * Exported for direct injection testing.
  */
 export declare function shellQuote(s: string): string;
 /**
- * RB-284 ③ (成批, CC 220 `xGg`/`MCu` @240961-240967 亲核) — the tokens of a `glob` argument that this
- * engine CANNOT compile as glob syntax, i.e. the ones whose metacharacter would silently degrade to a
- * literal match.
+ * The tokens of a `glob` argument that this engine CANNOT compile as glob syntax, i.e. the ones whose
+ * metacharacter would silently degrade to a literal match.
  *
  * The harm this closes is specific and asymmetric. An unknown `type` degrades to searching EVERY file —
  * a SUPERSET of what was asked, wrong but self-evidently over-broad, and sema already discloses it with
  * a `[note: unknown type …]` line. An unparseable `glob` degrades the other way: `src/[ab.ts` stops
  * being a character class and becomes a request for a file literally NAMED `src/[ab.ts`, so the filter
- * silently narrows to (almost always) nothing and the search answers a clean "No matches." — a
- * false negative wearing the exact shape of a successful exhaustive search. That is the RB-264 G2
- * failure class, and this repo's standing verdict on it is: no real data ⇒ isError, never a degraded
- * answer.
+ * silently narrows to (almost always) nothing and the search answers a clean "No matches." — a false
+ * negative wearing the exact shape of a successful exhaustive search. This repo's standing verdict on
+ * that class is: no real data ⇒ isError, never a degraded answer.
  *
  * CC hard-errors on the same input class rather than searching at all — its ripgrep stderr matcher
- * `xGg` covers `error parsing glob` (alongside regex-parse / unrecognized-file-type / flag-parse
- * errors) and raises `Search failed — ripgrep rejected the pattern, glob, or file type without
- * searching`. sema rejects at the INPUT level instead of waiting for a stderr string, because sema has
+ * covers `error parsing glob` (alongside regex-parse / unrecognized-file-type / flag-parse errors) and
+ * raises `Search failed — ripgrep rejected the pattern, glob, or file type without searching`. sema
+ * rejects at the INPUT level instead of waiting for a stderr string, because sema has
  * two search engines (rg + the JS fallback) and only the rg one would ever produce that stderr: a
  * rejection that fires only when ripgrep happens to be installed is not a contract. The `type` leg
  * deliberately does NOT get this treatment (see the `typeNote` site) — over-broad-with-a-note is an
@@ -85,20 +80,18 @@ export declare function invalidGlobTokens(glob: string): string[];
 /** Lightweight `.gitignore` matcher (handles comments, negation, dir-only `/`, anchoring, `*`/`?`). */
 export declare function gitignoreMatcher(content: string): (rel: string, isDir: boolean) => boolean;
 /** Build the combined ignore predicate (ignore-set ∪ .gitignore) for a JS-fallback walk.
- *  Exported so repo-map (design/72 §1) walks with the SAME ignore semantics as grep/glob.
+ *  Exported so repo-map walks with the SAME ignore semantics as grep/glob.
  *
- * RB-200 F1 (CC 220 corpus-confirmed, @368590-368592 Grep `T=["--hidden"]; for(N of Ok_) T.push("--glob",
- * "!"+N)`, @367957/367959-367965 Glob `CLAUDE_CODE_GLOB_HIDDEN` defaults to true and also passes `--hidden`): CC's own
- * "keep it quiet" posture is NOT "every dot-prefixed name is invisible" — it's `--hidden` (show
+ * CC's "keep it quiet" posture is NOT "every dot-prefixed name is invisible" — it is `--hidden` (show
  * everything dot-prefixed) plus an explicit VCS-directory exclusion list ({@link DEFAULT_IGNORE_DIRS}).
- * The blanket rule this function used to apply here (`base.startsWith(".")`) instead made EVERY hidden
- * file/dir invisible with no caveat — `.github/`, `.claude/`, `.env.example` never existed as far as
- * Grep/Glob/repo-map were concerned, not even as an honest "search skipped this" note (A-8 posture: an
- * unflagged gap reads as exhaustive). Removed; {@link DEFAULT_IGNORE_DIRS} (dependency/build/cache trees
- * + the 6 VCS metadata dirs) and `.gitignore` are now the entire directory-skip story, matching CC. */
+ * A blanket `base.startsWith(".")` rule here would make EVERY hidden file/dir invisible with no caveat
+ * — `.github/`, `.claude/`, `.env.example` would not exist as far as Grep/Glob/repo-map are concerned,
+ * not even as an honest "search skipped this" note, and an unflagged gap reads as exhaustive. So
+ * {@link DEFAULT_IGNORE_DIRS} (dependency/build/cache trees + the 6 VCS metadata dirs) and `.gitignore`
+ * are the entire directory-skip story, matching CC. */
 export declare function buildIgnore(env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<(rel: string, isDir: boolean) => boolean>;
-/** What a bounded walk actually saw — so consumers can be HONEST about incompleteness (A-4 class sweep:
- *  silently bounded results must never read as exhaustive). */
+/** What a bounded walk actually saw — so consumers can be HONEST about incompleteness: silently
+ *  bounded results must never read as exhaustive. */
 export interface WalkResult {
     /** Greppable text files (binary-extension and oversize files excluded). */
     files: string[];
@@ -113,35 +106,34 @@ export interface WalkResult {
     /** Non-binary files skipped by content search for being over {@link FILE_MAX_BYTES} (also in
      *  `nameOnly`). Surfaced by grep so "No matches." can't silently mean "didn't look". */
     skippedLarge: number;
-    /** fidelity-sweep F2: directories whose listing FAILED (EACCES, transient I/O) — whole subtrees the
-     *  walk never saw. */
+    /** Directories whose listing FAILED (EACCES, transient I/O) — whole subtrees the walk never saw. */
     skippedUnreadable: number;
-    /** F2: the walk was cut short by an abort — the result is a prefix, not a survey. */
+    /** The walk was cut short by an abort — the result is a prefix, not a survey. */
     aborted: boolean;
-    /** CC 2.1.209 Glob parity (batch A2): modification time (ms epoch) per walked path (files AND
+    /** CC 2.1.209 Glob parity: modification time (ms epoch) per walked path (files AND
      *  name-only entries), captured from the listing that discovered them — so glob can sort by mtime
      *  without a second stat pass. An env whose listings carry no numeric `mtimeMs` simply leaves
      *  entries out of this map (consumers fall back to name order). */
     mtimes: Map<string, number>;
-    /** design/199 件B — entries withheld by the sensitive-path read deny list: PRUNE-ROOT count only
+    /** Entries withheld by the sensitive-path read deny list: PRUNE-ROOT count only
      *  (a denied directory's descendants are not enumerated, so they cannot be counted — the note says
      *  so). 0 when no deny judge was supplied or nothing matched. */
     denyPruned: number;
     /** The deny patterns that pruned something, first-seen order (for the disclosure note). */
     denyPatterns: string[];
 }
-/** F2: any-cause incompleteness — a result built on this walk must not present itself as exhaustive. */
+/** Any-cause incompleteness — a result built on this walk must not present itself as exhaustive. */
 export declare function walkIsPartial(w: WalkResult): boolean;
 /** Bounded, ignore-aware recursive walk. Returns absolute file paths under `start`. Exported for
- *  repo-map (design/72 §1) — same bounded/ignore-aware traversal as grep/glob, one source of truth. */
+ *  repo-map — same bounded/ignore-aware traversal as grep/glob, one source of truth. */
 export declare function walk(env: ExecutionEnv, root: string, start: string, ignore: (rel: string, isDir: boolean) => boolean, signal?: AbortSignal, deny?: {
     matchPath(path: string): {
         pattern: string;
     } | null;
 }): Promise<WalkResult>;
-/** design/199 件B — the JS-leg withholding disclosure (§3.1: an empty result must stay
- *  distinguishable from searched-and-empty, so this note rides EVERY output shape when something was
- *  pruned). Distinct from {@link walkCaveat}: pruning is deliberate withholding, not incompleteness.
+/** The JS-leg withholding disclosure: an empty result must stay distinguishable from
+ *  searched-and-empty, so this note rides EVERY output shape when something was pruned. Distinct from
+ *  {@link walkCaveat}: pruning is deliberate withholding, not incompleteness.
  *  The `[note:` prefix keeps it out of the tool layer's structured row extraction. */
 export declare function denyWithheldNote(w: Pick<WalkResult, "denyPruned" | "denyPatterns">): string;
 /** Injectable execution boundaries for the JS-fallback scan (tests shrink them; callers use defaults). */
@@ -150,13 +142,13 @@ export interface JsGrepGuards {
     budgetMs?: number;
     /** Longest line/content (chars) a gray-zone pattern may be matched against. */
     longLineLimit?: number;
-    /** backlog #310 — bytes of content rows this scan may accumulate before it stops collecting and
+    /** Bytes of content rows this scan may accumulate before it stops collecting and
      *  says so (default {@link JS_GREP_OUTPUT_MAX_BYTES}). A seam for the same reason the two above
      *  are: the boundary is pinnable at a testable size instead of only at an 8MB harness. */
     outputMaxBytes?: number;
 }
-/** design/199 件B — what a traversal withheld under the sensitive-path read deny list, structured
- *  (the prose note is the model-facing twin). Three shapes (§3.1): `pruned_count` = the JS walker
+/** What a traversal withheld under the sensitive-path read deny list, structured (the prose note is
+ *  the model-facing twin). Three shapes: `pruned_count` = the JS walker
  *  counted its prune roots; `existence` = the rg leg's bounded probe CONFIRMED matching entries exist
  *  under the scope (rg's own exclusions are silent, so the count is unknowable); `probe_failed` =
  *  the probe itself failed — entries MAY have been withheld. */
@@ -180,11 +172,11 @@ export interface ReadDenyJudge {
     }>;
 }
 /** JS-fallback grep: ignore-aware walk + per-line scan, honoring output_mode / context / head_limit.
- *  design/199 件B: `deny` prunes the walk (note appended to every output shape); `denyOut` is the
+ *  `deny` prunes the walk (note appended to every output shape); `denyOut` is the
  *  structured twin — a sink because this function's dozen error returns predate the facts (the sink
  *  is written the moment the walk lands, whatever the scan then returns).
  *
- *  backlog #313 — the SERVED rows ride back next to the text. This scanner knows every result's
+ *  The SERVED rows ride back next to the text. This scanner knows every result's
  *  identity natively (the walk hands it whole paths), so a row's `path` is that walked identity,
  *  never a cut of the rendered line — the mis-split family the text re-parse carries cannot exist
  *  here. The rows ARE the window `text` shows: post offset, post row cap, post byte ceiling, in the
@@ -222,7 +214,7 @@ export type GrepDegradation = {
 };
 /** Structured grep result: the model-facing text plus the degradation facts, so the tool layer can
  *  ship them on the structured frame instead of leaving them prose-only. */
-/** #313 — one SERVED result RECORD with its path taken from the engine's own knowledge, exactly the
+/** One SERVED result RECORD with its path taken from the engine's own knowledge, exactly the
  *  window `text` shows (post cap/offset): ripgrep's `--null` path field ({@link parseRgRecords}) on
  *  the rg legs, the walked file identity ({@link jsGrepDetailed}) on the JS-scanner legs. A record is
  *  one rendered line except where a path carries a newline (see {@link formatRgRecords}), which is
@@ -247,50 +239,50 @@ export interface GrepRow {
 }
 export interface GrepRunResult {
     text: string;
-    /** Served rows (#313): present on BOTH engine legs — ripgrep's and the JS scanner's, including the
-     *  rescan legs. Absent only when the JS scanner refused the search outright (a typed
+    /** Served rows: present on BOTH engine legs — ripgrep's and the JS scanner's, including the
+     *  re-scan legs. Absent only when the JS scanner refused the search outright (a typed
      *  `Error (grep): …` text): a refusal has no row set, truthfully, rather than an empty one. */
     rows?: readonly GrepRow[];
     degraded?: GrepDegradation;
-    /** design/199 件B — deny-list withholding facts (see {@link ReadDenyWithheld}); absent = nothing
+    /** Deny-list withholding facts (see {@link ReadDenyWithheld}); absent = nothing
      *  withheld / no deny judge in play. */
     withheld?: ReadDenyWithheld;
 }
 /** The output modes the rg leg and {@link jsGrep} share. */
 type GrepOutputMode = "content" | "files_with_matches" | "count";
 /**
- * backlog #303 (rescan-hardened form) — the rg leg's deny TRIPWIRE. rg's exclusion globs are spelled
+ * The rg leg's deny TRIPWIRE. rg's exclusion globs are spelled
  * from the pattern text and cannot express the win32 component-alias family (`.aws.` / `.aws ` —
  * trailing dots/spaces the win32 namespace strips), so a directory planted under an alias spelling
  * slips past the globs while the shared `matchPath` (two-view, read-deny.ts) correctly names it —
  * the JS leg pruned it, the rg leg returned its contents, and the same tree answered differently
  * depending on whether ripgrep was installed.
  *
- * The first fix FILTERED rg's text output line-by-line. The rescan killed that shape twice over:
- * ripgrep prints filenames verbatim, so a path component containing a NEWLINE splits one record
- * across physical lines whose fragments carry no `:line:` boundary — the filter kept them and the
- * deny-listed content passed (a protection hole, not a precision residual); and pruning every line
- * of a partial run fabricated a `No matches.` row inside the structured card. So this function no
- * longer edits anything: it JUDGES. Any deny hit — or any record the format cannot account for —
+ * FILTERING rg's text output line-by-line is not an option, on two counts: ripgrep prints filenames
+ * verbatim, so a path component containing a NEWLINE splits one record across physical lines whose
+ * fragments carry no `:line:` boundary — the filter keeps them and the deny-listed content passes (a
+ * protection hole, not a precision residual); and pruning every line of a partial run fabricates a
+ * `No matches.` row inside the structured card. So this function edits nothing: it JUDGES. Any deny
+ * hit — or any record the format cannot account for —
  * trips, and the caller abandons the rg run for the JS scanner, whose walk prunes with the
  * authoritative judge and needs no path parsing at all. rg stays the fast path for the common case
  * (no guarded entries in the result); the moment a guarded spelling is involved, the engine that
  * cannot mis-parse it owns the answer.
  *
- * backlog #306 — what it judges is now ripgrep's OWN path field ({@link parseRgRecords}, `--null`),
+ * What it judges is ripgrep's OWN path field ({@link parseRgRecords}, `--null`),
  * not a prefix cut at a guessed separator. Trip conditions, all three modes alike: a record whose
  * path the deny judge names trips as `deny-hit`; a record with no path field at all (rg's binary-file
  * notice, a no-filename row, an unterminated tail, output from an env that ignored `--null`) is
  * unaccountable and trips as `ambiguous-record` — same abandonment, same reason code as before.
  * `dropIncompleteTail` mirrors {@link parseRgRecords}: on the partial legs the cut tail is dropped
  * BEFORE judging, because judging a record the caller will never receive can only cost an
- * unnecessary rescan — every record that does reach the output is still judged, which is what the
+ * unnecessary re-scan — every record that does reach the output is still judged, which is what the
  * rule is for. (A killed stream ending mid-record is an EXPECTED shape with a rule of its own; the
  * unaccountable arm is for records that survive that rule.)
  * `--` group separators and empty lines carry no path by construction and pass. The `:digits:` /
- * `-digits-` boundary family this used to reason about is gone with the guessing: both of #303's
- * declared residuals (over-tripping on a cluster inside match TEXT, and the dedup key folding two
- * denied files whose own names carry a cluster) were artifacts of that decision, not of the judge.
+ * `-digits-` boundary family a guessing parser would have to reason about is gone: both of its
+ * residuals (over-tripping on a cluster inside match TEXT, and the dedup key folding two denied files
+ * whose own names carry a cluster) were artifacts of that decision, not of the judge.
  */
 export declare function rgOutputDenyTripwire(stdout: string, mode: GrepOutputMode, judge: Pick<ReadDenyJudge, "matchPath">, opts?: {
     dropIncompleteTail?: boolean;
@@ -303,21 +295,21 @@ export declare function rgOutputDenyTripwire(stdout: string, mode: GrepOutputMod
 };
 /** ripgrep grep: build flags from params, run, normalize to the same output as {@link jsGrep}.
  *  Result-fidelity contract: output ripgrep DID produce is never silently replaced by a fallback
- *  rescan — partial results ship with a caveat; only a zero-output failure degrades to
+ *  re-scan — partial results ship with a caveat; only a zero-output failure degrades to
  *  {@link jsGrep}, and that degradation is declared in both text and structure. An external abort
  *  propagates as the interruption it is (no fallback rerun). */
 export declare function rgGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, deny?: ReadDenyJudge): Promise<GrepRunResult>;
-/** grep dispatch: ripgrep when the env has it, else the hardened JS fallback (design/64 §10.3).
+/** grep dispatch: ripgrep when the env has it, else the hardened JS fallback.
  *  Returns the degradation facts alongside the text so the tool layer can surface them structurally. */
 export declare function runGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, deny?: ReadDenyJudge): Promise<GrepRunResult>;
 /** Text-only wrapper of {@link runGrepDetailed}. */
 export declare function runGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<string>;
-/** glob: find files by name pattern, with optional sub-path scoping; returns RELATIVE paths (design/64 §10.4). */
+/** glob: find files by name pattern, with optional sub-path scoping; returns RELATIVE paths. */
 export declare function runGlob(env: ExecutionEnv, root: string, pattern: string, opts?: {
     path?: string;
     max?: number;
 }, signal?: AbortSignal): Promise<string>;
-/** Structured sibling of {@link runGlob} (design/116 W3): same walk/match, plus the CC-shaped facts a
+/** Structured sibling of {@link runGlob}: same walk/match, plus the CC-shaped facts a
  *  shell renders (`filenames`/`numFiles`/`truncated`/`durationMs`/`totalMatches`/`countIsComplete`)
  *  without re-parsing the text.
  *

package/dist/tools/fs/search.js

@@ -1,6 +1,6 @@
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MAX_EXEC_OUTPUT_BYTES } from "../../core/exec-output-tail.js";
-import { hasBinaryExtension, isAbsolutePathForm, isWinFormPath } from "./safety.js";
+import { hasBinaryExtension, isAbsoluteForFamily, isWinFormPath, joinForFamily, pathFamilyOf } from "./safety.js";
 const WALK_MAX_FILES = 5000;
 const WALK_MAX_DEPTH = 32;
 const GREP_DEFAULT_CAP = 250;
@@ -776,7 +776,8 @@ export async function jsGrepDetailed(env, root, p, signal, guards, deny, denyOut
     }
     const ignore = await buildIgnore(env, root, signal);
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
-    const start = p.path ? (isAbsolutePathForm(p.path) ? p.path : `${rootPrefix}${p.path}`) : root;
+    const family = pathFamilyOf({ root });
+    const start = p.path ? (isAbsoluteForFamily(family, p.path) ? p.path : joinForFamily(family, root, p.path)) : root;
     let walked;
     if (p.path) {
         const info = await env.fileInfo(start, signal);
@@ -1054,10 +1055,10 @@ export function detectRipgrep(env) {
 async function sortRgFilesByMtime(env, root, records, signal) {
     if (records.length === 0)
         return [...records];
-    const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
+    const family = pathFamilyOf({ root });
     const toAbs = (p) => {
         const stripped = p.startsWith("./") ? p.slice(2) : p;
-        return isAbsolutePathForm(stripped) ? stripped : `${rootPrefix}${stripped}`;
+        return isAbsoluteForFamily(family, stripped) ? stripped : joinForFamily(family, root, stripped);
     };
     const paths = records.map((r) => r.path ?? r.text);
     const infos = await Promise.all(paths.map((p) => env.fileInfo(toAbs(p), signal)));
@@ -1231,7 +1232,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
         if (deny === undefined || deny.rgExclusionGlobs.length === 0)
             return { note: "" };
         if (p.path) {
-            const startPath = isAbsolutePathForm(p.path) ? p.path : `${root.replace(/[\\/]+$/, "")}${root.includes("\\") ? "\\" : "/"}${p.path}`;
+            const startPath = isAbsoluteForFamily(pathFamilyOf({ root }), p.path) ? p.path : joinForFamily(pathFamilyOf({ root }), root, p.path);
             const info = await env.fileInfo(startPath, signal);
             if (info.ok && info.value.kind === "file")
                 return { note: "" };
@@ -1322,7 +1323,8 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
     const t0 = Date.now();
     const baseIgnore = await buildIgnore(env, root, signal);
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
-    const start = opts.path ? (isAbsolutePathForm(opts.path) ? opts.path : `${rootPrefix}${opts.path}`) : root;
+    const family = pathFamilyOf({ root });
+    const start = opts.path ? (isAbsoluteForFamily(family, opts.path) ? opts.path : joinForFamily(family, root, opts.path)) : root;
     if (opts.path !== undefined) {
         const probe = await env.fileInfo(start, signal);
         if (!probe.ok && probe.error.code === "not_found") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.15.0",
+  "version": "7.17.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -83,7 +83,11 @@
     "gate:tool-names": "node scripts/verify-tool-name-tables.mjs",
     "gate:tool-docs": "node scripts/gen-tool-spec-fields.mjs --check",
     "gate:backlog-ledger": "node scripts/verify-backlog-ledger.mjs",
-    "gate:all": "node scripts/gate-all.mjs"
+    "gate:docs-tool-names": "node scripts/verify-docs-tool-names.mjs",
+    "gate:comment-ratio": "vitest run test/comment-ratio-ratchet.test.ts",
+    "gate:negative-controls": "vitest run test/gate-negative-controls.test.ts",
+    "gate:all": "node scripts/gate-all.mjs",
+    "car:gate": "node scripts/car-gate.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",