@mnemonik/shared 7.97.2 → 7.98.0

package/src/codeScanner.ts

@@ -2,13 +2,15 @@
  * Code Scanner - Parse and chunk source files for embedding
  */
 
-import { readdir, readFile, stat, lstat, realpath } from 'fs/promises';
-import { join, relative, extname, sep } from 'path';
+import { readdir, open, lstat, realpath } from 'fs/promises';
+import { constants, type Stats } from 'fs';
+import { join, relative, extname, sep, resolve, dirname } from 'path';
 import { createHash } from 'crypto';
 import ignore, { type Ignore } from 'ignore';
 import { debug as logDebug, info as logInfo, warn as logWarn } from './logger.js';
 import { withTimeout } from './asyncUtils.js';
 import { scrubSecrets } from './secretPatterns.js';
+import { isProtectedLocalPath, protectedLocalPaths } from './protectedPaths.js';
 import { MAX_AST_PARSE_BYTES, chunkWithAst, type AstChunk } from './ast/astChunker.js';
 import { astArtifactReport, resolveAstLanguage } from './ast/grammars.js';
 
@@ -20,14 +22,14 @@ const FILE_OP_TIMEOUT_MS = 5000;
 /**
  * The one file-size ceiling in Mnemonik. A file at or below this is scanned,
  * chunked, AND pushed verbatim; a file above it is uniformly outside the
- * system — not scanned, not chunked, not citable. "Scanned ⟺ verifiable".
+ * system - not scanned, not chunked, not citable. "Scanned ⟺ verifiable".
  *
  * This is deliberately a single exported constant rather than a number
  * repeated per layer. Three ceilings previously existed and had drifted:
  * the scan ceiling here (10 MB), a 5 MB whole-file push cap in the scanner
  * daemon, and a 5 MB `content` cap in the server's scanPushSchema. Files
  * between 5 and 10 MB were therefore indexed as chunks whose source content
- * the server never received — chunks that could be retrieved but never
+ * the server never received - chunks that could be retrieved but never
  * verified against, a silent fidelity split. Every consumer now imports this:
  *
  * - `CodeScanner.MAX_FILE_SIZE` / `collectAuthorityFilesWithStatus` (this file)
@@ -39,6 +41,9 @@ const FILE_OP_TIMEOUT_MS = 5000;
  */
 export const MAX_SCANNED_FILE_BYTES = 10 * 1024 * 1024; // 10MB
 
+/** Transport ceiling; ordinary chunking may exceed maxChunkSize but never this bound. */
+export const MAX_PUSH_CHUNK_CONTENT_LENGTH = 500_000;
+
 export interface CodeChunk {
   content: string;
   filePath: string;
@@ -75,12 +80,14 @@ export interface ScanOptions {
    * mock.
    */
   maxAstParseBytes?: number;
+  /** Additional protected paths for isolated homes/tests; defaults can only be extended. */
+  protectedPaths?: readonly string[];
 }
 
 /**
  * Mutable per-walk state threaded through the recursive traversals.
  * `complete` starts true and is latched false by any caught fs error
- * (readdir failure, per-entry lstat/realpath/stat throw) — meaning the
+ * (readdir failure, per-entry lstat/realpath/stat throw) - meaning the
  * result may be missing entries that still exist on disk. Callers that
  * derive *removals* from a walk must treat an incomplete walk as
  * untrustworthy; adds/changes are unaffected.
@@ -90,12 +97,12 @@ interface WalkState {
 }
 
 /**
- * Directory basenames the scanner never indexes, across every ecosystem —
+ * Directory basenames the scanner never indexes, across every ecosystem -
  * generated output, package-manager/build caches, and vendored deps. SINGLE
  * SOURCE OF TRUTH: the scanner package's discovery + watch walks import this
  * (`packages/scanner/src/{discovery,watcher}.ts`) and `src/core/utils.ts`
  * derives from it, so every ignore surface agrees instead of drifting (the
- * pre-2026-07 state had four divergent copies). Add only UNAMBIGUOUS names —
+ * pre-2026-07 state had four divergent copies). Add only UNAMBIGUOUS names -
  * a project's own `.gitignore` / `.mnemonikignore` covers the ambiguous,
  * project-specific cases (`vendor/`, custom dirs) hierarchically.
  */
@@ -124,7 +131,7 @@ export const BUILT_IN_IGNORE_DIRS: readonly string[] = [
   '.mypy_cache',
   '.pytest_cache',
   '.ruff_cache',
-  // Native mobile — iOS / Android / React Native / Flutter (2026-07-11 Pods incident)
+  // Native mobile - iOS / Android / React Native / Flutter (2026-07-11 Pods incident)
   'Pods',
   'DerivedData',
   '.gradle',
@@ -148,7 +155,7 @@ export const BUILT_IN_IGNORE_DIRS: readonly string[] = [
   // an agent's own shell state into the user's searchable memory.
   //
   // Scoped to this one directory name deliberately. `.claude/` at large holds
-  // real project content — `.claude/rules.md` is indexed on purpose
+  // real project content - `.claude/rules.md` is indexed on purpose
   // (tests/CodeScannerIgnorePatterns.test.ts), and only `.claude/worktrees/`
   // is suppressed, by the generic nested-git-boundary rule.
   'shell-snapshots',
@@ -159,7 +166,7 @@ export const BUILT_IN_IGNORE_DIRS: readonly string[] = [
  * anchored fixture rule), combined with BUILT_IN_IGNORE_DIRS to form
  * DEFAULT_OPTIONS.ignorePatterns. See `shouldIgnore` for match semantics.
  *
- * `/tests/fixtures/*`: leading '/' = segment-anchored — matches tests/fixtures/
+ * `/tests/fixtures/*`: leading '/' = segment-anchored - matches tests/fixtures/
  * at the path root or immediately after a '/', so nested packages/x/tests/
  * fixtures/ are excluded but integration-tests/fixtures/ is NOT. Fixture
  * snapshot dirs were being indexed as real source and outranking the genuine
@@ -186,19 +193,19 @@ const BUILT_IN_IGNORE_FILE_PATTERNS: readonly string[] = [
 
 /**
  * Files whose CONTENT is a credential rather than code. Today these are
- * excluded only INCIDENTALLY — `.pem`, `.key` and friends carry no
+ * excluded only INCIDENTALLY - `.pem`, `.key` and friends carry no
  * allowlisted extension, so nothing chunks them. That protection evaporates
  * the moment the extension allowlist widens (as it did for `.sh`/`.lua`), so
  * the exclusion is made explicit here and becomes a defended invariant:
  * unlike `ignorePatterns`, this predicate is NOT caller-overridable.
  *
  * Expressed as a predicate rather than glob strings because `shouldIgnore`'s
- * engine has no negation and matches globs as unanchored substrings — neither
+ * engine has no negation and matches globs as unanchored substrings - neither
  * property can state "every `.env.*` EXCEPT `.env.example`".
  *
  * Precision notes (over-exclusion is a fidelity failure in its own right):
  * - `.env` family: `/^\.env(\..+)?$/` matches `.env`, `.env.local`,
- *   `.env.production` — and deliberately NOT `.envrc` or `.environment.ts`.
+ *   `.env.production` - and deliberately NOT `.envrc` or `.environment.ts`.
  * - `.env.example` is carved out: it is authority-collected on purpose
  *   (AUTHORITY_FILE_MATCHERS) and holds placeholder values, not secrets.
  *   It is the doc-truth env_vars authority; excluding it would blind that
@@ -206,7 +213,7 @@ const BUILT_IN_IGNORE_FILE_PATTERNS: readonly string[] = [
  * - `credentials` is matched ONLY directly inside a dot-directory
  *   (`.aws/credentials`, `.docker/credentials`). A bare `credentials/` is a
  *   real, common SOURCE directory name (gRPC, auth libraries) and
- *   `shouldIgnore` cannot tell a file from a directory at its call sites —
+ *   `shouldIgnore` cannot tell a file from a directory at its call sites -
  *   an unqualified rule would silently delete that subtree from the index.
  * - `.tfvars` is excluded whole rather than per-basename: the credential file
  *   is conventionally `terraform.tfvars` but the name is free-form, and the
@@ -222,7 +229,7 @@ const SECRET_FILE_BASENAME_PATTERNS: readonly RegExp[] = [
   /\.(?:pem|key|p12|pfx|keystore|jks|kubeconfig)$/i,
   // Terraform variable files: `terraform.tfvars` is the conventional home for
   // provider credentials, and unlike the entries above nothing else was
-  // keeping it out — it is excluded here rather than merely left off
+  // keeping it out - it is excluded here rather than merely left off
   // `DEFAULT_INCLUDE_EXTENSIONS`, so a future widening of the allowlist cannot
   // quietly opt a project into embedding its own cloud keys.
   /\.tfvars(\.json)?$/i,
@@ -260,7 +267,7 @@ const IGNORE_FILE_NAMES = ['.gitignore', '.mnemonikignore'] as const;
  * Exported because this list IS the product's language coverage: a project
  * written in something absent from it indexes zero code, and `code_search`
  * reports that as "no indexed matches" rather than "I do not read this
- * language" — invisible to the developer and to us. Coverage is a separate
+ * language" - invisible to the developer and to us. Coverage is a separate
  * dial from parse quality: a language with no structured extractor falls
  * through to `chunkRaw`, which is what Go, Java and C already get in
  * production, and crude chunks beat no chunks by an enormous margin.
@@ -268,7 +275,7 @@ const IGNORE_FILE_NAMES = ['.gitignore', '.mnemonikignore'] as const;
  * Data formats (`.json`, `.yaml`, `.toml`, `.lock`) are deliberately absent:
  * the ones that carry meaning are already collected verbatim by
  * `AUTHORITY_FILE_MATCHERS`, and blanket-indexing the extension would pull in
- * lockfiles and generated output. `.tfvars` is absent for a different reason —
+ * lockfiles and generated output. `.tfvars` is absent for a different reason -
  * `terraform.tfvars` is a conventional home for provider credentials and
  * `isSecretFile` now excludes it outright.
  */
@@ -289,7 +296,7 @@ export const DEFAULT_INCLUDE_EXTENSIONS: readonly string[] = [
   '.php',
   '.swift',
   '.kt',
-  // Shell and Lua are the working languages of whole real projects —
+  // Shell and Lua are the working languages of whole real projects -
   // deployment tooling, container entrypoints, imapfilter/nginx/redis
   // configuration. Omitting them meant such a project indexed ZERO code and
   // code_search could not answer anything about it, while reporting that as
@@ -300,7 +307,7 @@ export const DEFAULT_INCLUDE_EXTENSIONS: readonly string[] = [
   '.lua',
   '.md',
 
-  // ── Variants of languages already on the list. `.mjs`/`.cjs`/`.mts`/`.cts`/
+  // -- Variants of languages already on the list. `.mjs`/`.cjs`/`.mts`/`.cts`/
   // `.pyi` inherit their language string from a listed extension, so their
   // absence was oversight rather than policy. The C++ spellings are a choice,
   // not an inheritance: `.h` stays 'c' (C headers dominate, and reading a C++
@@ -318,7 +325,7 @@ export const DEFAULT_INCLUDE_EXTENSIONS: readonly string[] = [
   '.cxx',
   '.kts',
 
-  // ── Languages the scanner could not read at all.
+  // -- Languages the scanner could not read at all.
   '.dart',
   '.m',
   '.mm',
@@ -347,7 +354,7 @@ export const DEFAULT_INCLUDE_EXTENSIONS: readonly string[] = [
   '.vue',
   '.svelte',
 
-  // ── Infrastructure and schema DSLs, where real logic lives and where "how
+  // -- Infrastructure and schema DSLs, where real logic lives and where "how
   // is this deployed?" and "what does this table hold?" go unanswered today.
   '.tf',
   '.sql',
@@ -360,12 +367,12 @@ export const DEFAULT_INCLUDE_EXTENSIONS: readonly string[] = [
 ];
 
 /**
- * Extension → language string, the value carried on every chunk and on the
+ * Extension -> language string, the value carried on every chunk and on the
  * wire (`/scan/push` accepts any non-empty string up to 50 chars).
  *
  * A string no grammar claims is correct and expected: the AST layer resolves
  * such a language to `null` and the heuristic chunker takes over. Keep this in
- * sync with `DEFAULT_INCLUDE_EXTENSIONS` — an allowlisted extension that lands
+ * sync with `DEFAULT_INCLUDE_EXTENSIONS` - an allowlisted extension that lands
  * on 'unknown' still gets chunked, but nothing downstream can reason about it.
  *
  * Two extensions are genuinely ambiguous and are resolved rather than fudged:
@@ -453,7 +460,7 @@ export function languageForExtension(filePathOrExt: string): string {
   // `extname` FIRST. A dotfile that carries a real extension ('.eslintrc.js',
   // '.mocharc.cjs', '.prettierrc.ts') starts with '.' and contains no '/', so
   // a bare-extension-first reading swallowed the whole name and answered
-  // 'unknown' — while the same file spelled 'src/.eslintrc.js' answered
+  // 'unknown' - while the same file spelled 'src/.eslintrc.js' answered
   // 'javascript'. Those extensions are allowlisted, so the files are indexed
   // and reach the server with exactly the root-relative spelling that failed.
   const fromPath = EXTENSION_LANGUAGES[extname(filePathOrExt).toLowerCase()];
@@ -466,16 +473,16 @@ export function languageForExtension(filePathOrExt: string): string {
 
 /**
  * THE definition of "this path is a SQL migration the schema_columns authority
- * collects verbatim". One predicate, referenced by both halves of the deal —
+ * collects verbatim". One predicate, referenced by both halves of the deal -
  * `AUTHORITY_FILE_MATCHERS` (collect it) and `isAuthorityOnlyPath` (therefore
- * do not chunk it) — because two hand-written regexes drifted once already and
+ * do not chunk it) - because two hand-written regexes drifted once already and
  * the failure is silent in both directions.
  *
  * Root-anchored and CASE-SENSITIVE on purpose: it mirrors the server-side
  * extractor, which does `listFiles('migrations/')` (LIKE 'migrations/%') then
  * `endsWith('.sql')`, both case-sensitive. `Migrations/001.sql` (the .NET/EF
  * Core spelling) and `migrations/002.SQL` are NOT collected, so they must not
- * be suppressed from chunking either — that would index them nowhere. Same
+ * be suppressed from chunking either - that would index them nowhere. Same
  * reason a nested `packages/x/migrations/y.sql` is left alone.
  */
 const isMigrationSqlAuthorityPath = (posixRelPath: string): boolean =>
@@ -489,7 +496,7 @@ const isMigrationSqlAuthorityPath = (posixRelPath: string): boolean =>
  * through.
  *
  * `migrations/**.sql` is the live case: adding `.sql` to the allowlist without
- * this exclusion would dual-collect every migration — once verbatim, once
+ * this exclusion would dual-collect every migration - once verbatim, once
  * chunked and embedded. On this repo alone that is 208 files of append-only
  * DDL (140 forward, the rest rollback/manual), embedded to answer questions
  * the authority path already answers exactly.
@@ -504,7 +511,7 @@ const AUTHORITY_ONLY_PATH_PREDICATES: readonly ((posixRelPath: string) => boolea
 
 /**
  * True when `relPath` is collected verbatim as authority content and must not
- * additionally be chunked. Accepts OS-native or POSIX separators.
+ * also be chunked. Accepts OS-native or POSIX separators.
  */
 export function isAuthorityOnlyPath(relPath: string): boolean {
   if (!relPath) return false;
@@ -518,6 +525,7 @@ const DEFAULT_OPTIONS: Required<ScanOptions> = {
   ignorePatterns: [...BUILT_IN_IGNORE_DIRS, ...BUILT_IN_IGNORE_FILE_PATTERNS],
   includeExtensions: [...DEFAULT_INCLUDE_EXTENSIONS],
   maxAstParseBytes: MAX_AST_PARSE_BYTES,
+  protectedPaths: [],
 };
 
 /**
@@ -547,7 +555,7 @@ export const AUTHORITY_FILE_MATCHERS: Array<(relPath: string) => boolean> = [
 ];
 
 /**
- * Segment-anchored match for the `tests/fixtures/` ignore pattern above —
+ * Segment-anchored match for the `tests/fixtures/` ignore pattern above -
  * matches at the path root or immediately after a `/`, mirroring exactly
  * what `shouldIgnore` compiles `'/tests/fixtures/*'` to. Exported so
  * server-side consumers (e.g. the `/scan/push` route) and query-time
@@ -567,7 +575,7 @@ const BUILT_IN_IGNORE_DIR_SET = new Set<string>(BUILT_IN_IGNORE_DIRS);
  * (segment-exact) with a project's uploaded .gitignore/.mnemonikignore patterns
  * (gitignore syntax via the `ignore` package). Built once per request and reused
  * across all pushed paths (root-relative, forward-slash). This does NOT replace
- * the daemon's precise hierarchical walk — it backstops it so a buggy, stale, or
+ * the daemon's precise hierarchical walk - it backstops it so a buggy, stale, or
  * malicious client cannot index a path the project ignores, making .mnemonikignore
  * a hard guarantee rather than best-effort.
  */
@@ -599,7 +607,7 @@ export function makeIgnoreMatcher(
  * being scanned: it carries its own `.git` entry. A `.git` FILE marks a
  * linked git worktree (wherever the user keeps them) or a submodule
  * checkout; a `.git` DIRECTORY marks a nested clone. Files under such a
- * boundary belong to that repository's own project identity — scanning them
+ * boundary belong to that repository's own project identity - scanning them
  * into the parent project is wrong attribution for any codebase, so the
  * walkers skip these subtrees. Convention-free: this is git's own marker,
  * not a host/tool path layout. The scan ROOT is exempt by construction
@@ -620,7 +628,7 @@ export async function isGitBoundary(dirPath: string): Promise<boolean> {
 
 /**
  * One directory's compiled ignore-file rules, keyed by its path relative to
- * the scan root (`''` = root). A stack of these, root→leaf, is threaded
+ * the scan root (`''` = root). A stack of these, root->leaf, is threaded
  * through the walkers; `ignoredByStack` tests deepest-first so a nested
  * `.gitignore` overrides a shallower one (git precedence).
  */
@@ -649,7 +657,7 @@ let astCapabilityLog: Promise<void> | null = null;
 const reportedGrammarFallbacks = new Set<string>();
 
 /**
- * Log which grammars this install ships — ONCE per process, at daemon start,
+ * Log which grammars this install ships - ONCE per process, at daemon start,
  * never per file.
  *
  * A missing grammar silently degrades every file of that language to the
@@ -660,8 +668,8 @@ const reportedGrammarFallbacks = new Set<string>();
  *
  * Deliberately a `statSync` of the artifacts (`astArtifactReport`) and not a
  * load of them (`astCapabilityReport`). Loading all 18 to print this line costs
- * ~690 ms and ~75 MB of RSS that is never returned — web-tree-sitter exposes no
- * `Language.delete` — which is a permanent tax on a daemon watching a pure
+ * ~690 ms and ~75 MB of RSS that is never returned - web-tree-sitter exposes no
+ * `Language.delete` - which is a permanent tax on a daemon watching a pure
  * TypeScript repo, paid to pre-answer a question about seventeen languages it
  * will never see. Grammars load lazily instead, on the first file of a language,
  * and the two failure modes only a load can detect (`wasm_load_failed`,
@@ -691,23 +699,44 @@ export function logAstCapabilityOnce(): Promise<void> {
 
 export class CodeScanner {
   private options: Required<ScanOptions>;
+  private readonly protectedPaths: readonly string[];
+  /** Cumulative observations since this scanner started, including repeated walks. */
+  readonly skipReasons = { symlink_skipped: 0 };
+
+  private skipSymlink(stats: Stats): boolean {
+    if (!stats.isSymbolicLink()) return false; // Includes Windows junctions.
+    this.skipReasons.symlink_skipped++;
+    return true;
+  }
 
   /**
    * `includeExtensions` folded to lowercase for matching. The gate used to
    * compare `extname()` verbatim while `detectLanguage` lowercased, so a
-   * project spelling its files the canonical way — `.R` for R, `.SQL`/`.PS1`
-   * on Windows, `.C`/`.H` in older C trees — indexed zero of them and nothing
+   * project spelling its files the canonical way - `.R` for R, `.SQL`/`.PS1`
+   * on Windows, `.C`/`.H` in older C trees - indexed zero of them and nothing
    * said why.
    */
   private readonly includeExtensionSet: ReadonlySet<string>;
 
   constructor(options: ScanOptions = {}) {
     this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.protectedPaths = [
+      ...new Set([...protectedLocalPaths(), ...(options.protectedPaths ?? [])]),
+    ];
     this.includeExtensionSet = new Set(
       this.options.includeExtensions.map((ext) => ext.toLowerCase())
     );
   }
 
+  private isProtected(path: string): boolean {
+    return isProtectedLocalPath(path, this.protectedPaths);
+  }
+
+  private async isProtectedRead(path: string): Promise<boolean> {
+    if (this.isProtected(path)) return true;
+    return isProtectedLocalPath(await realpath(path), this.protectedPaths);
+  }
+
   /**
    * The chunkable-file gate, shared by every walker and by the explicit
    * file-list path so all three agree on what exists. `relPath` is the path
@@ -724,7 +753,7 @@ export class CodeScanner {
 
   /**
    * Read `.gitignore` + `.mnemonikignore` in `absDir` and compile them into one
-   * ignore layer (the two files are unioned — `.mnemonikignore` is just an
+   * ignore layer (the two files are unioned - `.mnemonikignore` is just an
    * additional gitignore-syntax exclusion list). Returns null when neither file
    * exists. FAIL-CLOSED: a non-ENOENT read error (EISDIR, EACCES, timeout)
    * latches `walk.complete = false` so callers deriving *removals* from the walk
@@ -733,19 +762,22 @@ export class CodeScanner {
   private async loadIgnoreLayer(
     absDir: string,
     baseRel: string,
-    walk: WalkState
+    walk: WalkState,
+    rootPath: string
   ): Promise<IgnoreLayer | null> {
+    if (this.isProtected(absDir)) return null;
     const patterns: string[] = [];
     for (const name of IGNORE_FILE_NAMES) {
       const filePath = join(absDir, name);
       try {
         const content = await withTimeout(
-          readFile(filePath, 'utf-8'),
+          this.readConfined(filePath, rootPath),
           FILE_OP_TIMEOUT_MS,
           `readFile timed out: ${filePath}`
         );
         for (const line of content.split(/\r?\n/)) patterns.push(line);
       } catch (err) {
+        if ((err as Error).message === 'symlink_skipped') continue;
         if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') {
           walk.complete = false;
           logDebug('Ignore-file read failed (fail-closed)', { path: filePath, err });
@@ -787,7 +819,7 @@ export class CodeScanner {
   }
 
   /**
-   * Reconstruct the root→parent ignore-layer stack for a single file, for the
+   * Reconstruct the root->parent ignore-layer stack for a single file, for the
    * incremental `scanFiles` path (which has a flat file list, not a recursive
    * walk). Layers are memoized per directory in `cache` across a batch.
    */
@@ -807,7 +839,12 @@ export class CodeScanner {
     for (const dir of dirs) {
       let layer = cache.get(dir);
       if (layer === undefined) {
-        layer = await this.loadIgnoreLayer(dir === '' ? rootPath : join(rootPath, dir), dir, walk);
+        layer = await this.loadIgnoreLayer(
+          dir === '' ? rootPath : join(rootPath, dir),
+          dir,
+          walk,
+          rootPath
+        );
         cache.set(dir, layer);
       }
       if (layer) stack.push(layer);
@@ -818,7 +855,7 @@ export class CodeScanner {
   /**
    * True when any directory strictly between `rootPath` and `filePath`
    * carries its own `.git` entry (see isGitBoundary). Paths that don't
-   * resolve under `rootPath` are not judged here (return false) — the
+   * resolve under `rootPath` are not judged here (return false) - the
    * server's path validation handles escapes.
    */
   private async insideNestedGitBoundary(filePath: string, rootPath: string): Promise<boolean> {
@@ -842,17 +879,89 @@ export class CodeScanner {
    */
   private static readonly MAX_DEPTH = 10;
 
-  /**
-   * Symlink confinement shared by every walker (traverseDirectory,
-   * traversePaths, collectAuthorityFiles): true when the symlink at
-   * `fullPath` resolves inside `rootPath` and may be followed, false when
-   * it escapes the project root. A dangling link (realpath ENOENT) throws
-   * to the caller's per-entry handler.
-   */
-  private async confineSymlink(fullPath: string, rootPath: string): Promise<boolean> {
-    const resolved = await realpath(fullPath);
-    const resolvedRoot = await realpath(rootPath);
-    return resolved.startsWith(resolvedRoot + '/') || resolved === resolvedRoot;
+  private canonicalRoots = new Map<string, string>();
+  private async canonicalRoot(root: string): Promise<string> {
+    let canonical = this.canonicalRoots.get(root);
+    if (!canonical) {
+      canonical = await realpath(root);
+      this.canonicalRoots.set(root, canonical);
+    }
+    return canonical;
+  }
+
+  static containsCanonical(
+    candidate: string,
+    root: string,
+    paths = { sep, resolve },
+    caseInsensitive = process.platform === 'win32'
+  ): boolean {
+    // realpath expands filesystem aliases (including Windows 8.3 names). Never guess a short name.
+    candidate = paths.resolve(candidate);
+    root = paths.resolve(root);
+    if (caseInsensitive) {
+      candidate = candidate.toLowerCase();
+      root = root.toLowerCase();
+    }
+    return (
+      candidate === root || candidate.startsWith(root.endsWith(paths.sep) ? root : root + paths.sep)
+    );
+  }
+
+  private async confineSymlink(fullPath: string, canonicalRoot: string): Promise<boolean> {
+    // Check each component: explicit-file callers must not bypass the walkers'
+    // no-symlink policy by supplying a path through an in-root directory link.
+    let path = resolve(fullPath);
+    if (!CodeScanner.containsCanonical(path, canonicalRoot)) return false;
+    for (;;) {
+      if (this.skipSymlink(await lstat(path))) throw new Error('symlink_skipped');
+      if (CodeScanner.containsCanonical(canonicalRoot, path)) break;
+      path = dirname(path);
+    }
+    return CodeScanner.containsCanonical(await realpath(fullPath), canonicalRoot);
+  }
+
+  async readConfined(fullPath: string, canonicalRoot: string, enumerated?: Stats): Promise<string> {
+    const expected = enumerated ?? (await lstat(fullPath));
+    if (this.skipSymlink(expected)) throw new Error('symlink_skipped');
+    if (!expected.isFile()) throw new Error('scanner_not_regular');
+    if (!(await this.confineSymlink(fullPath, canonicalRoot)))
+      throw new Error('scanner_containment');
+    const canonical = await realpath(fullPath);
+    if (
+      !CodeScanner.containsCanonical(canonical, canonicalRoot) ||
+      (await this.isProtectedRead(canonical))
+    )
+      throw new Error('scanner_containment');
+    // O_NONBLOCK also prevents a substituted FIFO from hanging before fstat.
+    const flags =
+      constants.O_RDONLY |
+      (constants.O_NONBLOCK ?? 0) |
+      (process.platform === 'win32' ? 0 : (constants.O_NOFOLLOW ?? 0));
+    const handle = await open(fullPath, flags).catch((error: NodeJS.ErrnoException) => {
+      if (error.code === 'ELOOP') {
+        this.skipReasons.symlink_skipped++;
+        throw new Error('symlink_skipped');
+      }
+      throw error;
+    });
+    try {
+      const actual = await handle.stat();
+      if (!actual.isFile()) throw new Error('scanner_not_regular');
+      if (actual.dev !== expected.dev || actual.ino !== expected.ino)
+        throw new Error('scanner_identity_changed');
+      // Windows has no O_NOFOLLOW; lstat is Node's junction/reparse-link check.
+      if (process.platform === 'win32' && this.skipSymlink(await lstat(fullPath)))
+        throw new Error('symlink_skipped');
+      // Linux also proves the opened object is still at the checked path.
+      if (
+        process.platform === 'linux' &&
+        (await realpath(`/proc/self/fd/${handle.fd}`)) !== canonical
+      )
+        throw new Error('scanner_containment');
+      return await handle.readFile('utf-8');
+    } finally {
+      await handle.close();
+    }
   }
 
   /**
@@ -867,7 +976,7 @@ export class CodeScanner {
   /**
    * Completeness-aware variant of `scanDirectory`. `complete === false`
    * means at least one fs error was swallowed during the walk, so the
-   * chunk set may be missing files that still exist on disk — callers
+   * chunk set may be missing files that still exist on disk - callers
    * deriving removals from the result must not trust it as an inventory.
    * Chunks are secret-scrubbed before returning (same daemon-side
    * redaction guarantee as `scanFiles`).
@@ -875,6 +984,7 @@ export class CodeScanner {
   async scanDirectoryWithStatus(
     rootPath: string
   ): Promise<{ chunks: CodeChunk[]; complete: boolean }> {
+    rootPath = await this.canonicalRoot(rootPath);
     const chunks: CodeChunk[] = [];
     const walk: WalkState = { complete: true };
     await this.traverseDirectory(rootPath, rootPath, chunks, 0, walk);
@@ -885,7 +995,7 @@ export class CodeScanner {
    * Enumerate scan-eligible relative file paths under `rootPath` without
    * reading or chunking content. Same walk + ignorePatterns + extension
    * filter as `scanDirectory`, but bounded to O(file count) directory ops
-   * — cheap enough to call on every periodic reconcile tick.
+   * - cheap enough to call on every periodic reconcile tick.
    *
    * Returns relative paths normalized against `rootPath`, matching the
    * shape the server stores in `memories.metadata->>'filePath'`. Use this
@@ -904,12 +1014,13 @@ export class CodeScanner {
 
   /**
    * Completeness-aware variant of `listFiles`. `complete === false` means
-   * an fs error truncated part of the walk — the returned paths may be
+   * an fs error truncated part of the walk - the returned paths may be
    * missing files that still exist on disk. The daemon's reconcile channel
    * MUST NOT derive removedFiles from an incomplete inventory (a truncated
    * walk otherwise reads as mass deletion and deprecates live memories).
    */
   async listFilesWithStatus(rootPath: string): Promise<{ paths: string[]; complete: boolean }> {
+    rootPath = await this.canonicalRoot(rootPath);
     const paths: string[] = [];
     const walk: WalkState = { complete: true };
     await this.traversePaths(rootPath, rootPath, paths, 0, walk);
@@ -928,8 +1039,11 @@ export class CodeScanner {
     stack: IgnoreStack = []
   ): Promise<void> {
     if (depth >= CodeScanner.MAX_DEPTH) return;
+    if (this.isProtected(currentPath)) return;
     let entries: string[];
     try {
+      if (!(await this.confineSymlink(currentPath, rootPath)))
+        throw new Error('scanner_containment');
       entries = await withTimeout(
         readdir(currentPath),
         FILE_OP_TIMEOUT_MS,
@@ -942,28 +1056,25 @@ export class CodeScanner {
     }
     const dirRel =
       currentPath === rootPath ? '' : relative(rootPath, currentPath).split(sep).join('/');
-    const localLayer = await this.loadIgnoreLayer(currentPath, dirRel, walk);
+    const localLayer = await this.loadIgnoreLayer(currentPath, dirRel, walk, rootPath);
     const localStack = localLayer ? [...stack, localLayer] : stack;
     for (const entry of entries) {
       const fullPath = join(currentPath, entry);
       const relativePath = relative(rootPath, fullPath);
+      if (this.isProtected(fullPath)) continue;
       if (this.shouldIgnore(relativePath)) continue;
 
       // Per-entry isolation: a single bad entry (dangling symlink, raced
       // deletion, permission denial, fs timeout) must not abort the rest of
-      // the directory — but the inventory is no longer removal-trustworthy.
+      // the directory - but the inventory is no longer removal-trustworthy.
       try {
         const lstats = await withTimeout(
           lstat(fullPath),
           FILE_OP_TIMEOUT_MS,
           `lstat timed out: ${fullPath}`
         );
-        if (lstats.isSymbolicLink() && !(await this.confineSymlink(fullPath, rootPath))) {
-          continue;
-        }
-        const stats = lstats.isSymbolicLink()
-          ? await withTimeout(stat(fullPath), FILE_OP_TIMEOUT_MS, `stat timed out: ${fullPath}`)
-          : lstats;
+        if (this.skipSymlink(lstats)) continue;
+        const stats = lstats;
 
         if (stats.isDirectory()) {
           if (this.ignoredByStack(relativePath, true, localStack)) continue; // .gitignore/.mnemonikignore
@@ -987,12 +1098,15 @@ export class CodeScanner {
    * Pass rootPath to compute proper relative file paths in chunk metadata.
    */
   async scanFiles(filePaths: string[], rootPath: string): Promise<CodeChunk[]> {
+    rootPath = await this.canonicalRoot(rootPath);
     const chunks: CodeChunk[] = [];
     const ignoreCache = new Map<string, IgnoreLayer | null>();
     const walk: WalkState = { complete: true };
 
     for (const filePath of filePaths) {
       try {
+        if (!(await this.confineSymlink(filePath, rootPath))) continue;
+        if (this.isProtected(filePath) || (rootPath && this.isProtected(rootPath))) continue;
         const fileRel = rootPath ? relative(rootPath, filePath).split(sep).join('/') : filePath;
         if (this.shouldIgnore(fileRel)) {
           continue;
@@ -1007,7 +1121,7 @@ export class CodeScanner {
           }
         }
         // Explicit file lists arrive from watcher events, which can race a
-        // worktree/nested-clone appearing — apply the same nested-git-boundary
+        // worktree/nested-clone appearing - apply the same nested-git-boundary
         // rule the walks use (an ancestor between root and the file carrying
         // its own .git means the file belongs to another repository).
         if (rootPath && (await this.insideNestedGitBoundary(filePath, rootPath))) {
@@ -1037,14 +1151,26 @@ export class CodeScanner {
    * honor the same redaction guarantee.
    */
   private scrubChunks(chunks: CodeChunk[]): CodeChunk[] {
-    return chunks.map((chunk) => {
+    return chunks.flatMap((chunk) => {
       const scrubbed = scrubSecrets(chunk.content);
-      if (scrubbed === chunk.content) return chunk;
-      return {
-        ...chunk,
-        content: scrubbed,
-        contentHash: this.hash(scrubbed),
-      };
+      if (scrubbed.length <= MAX_PUSH_CHUNK_CONTENT_LENGTH) {
+        return scrubbed === chunk.content
+          ? [chunk]
+          : [{ ...chunk, content: scrubbed, contentHash: this.hash(scrubbed) }];
+      }
+      const pieces: CodeChunk[] = [];
+      let startLine = chunk.startLine;
+      for (let offset = 0; offset < scrubbed.length;) {
+        let end = Math.min(offset + MAX_PUSH_CHUNK_CONTENT_LENGTH, scrubbed.length);
+        // Keep a UTF-16 surrogate pair together at a transport boundary.
+        if (end < scrubbed.length && /[\uD800-\uDBFF]/.test(scrubbed.charAt(end - 1))) end--;
+        const content = scrubbed.slice(offset, end);
+        const endLine = startLine + (content.match(/\n/g)?.length ?? 0);
+        pieces.push({ ...chunk, content, startLine, endLine, contentHash: this.hash(content) });
+        startLine = endLine;
+        offset = end;
+      }
+      return pieces;
     });
   }
 
@@ -1065,10 +1191,13 @@ export class CodeScanner {
       logDebug('Max directory depth reached, skipping', { path: currentPath, depth });
       return;
     }
+    if (this.isProtected(currentPath)) return;
 
     // Wrap readdir with timeout to prevent hanging
     let entries: string[];
     try {
+      if (!(await this.confineSymlink(currentPath, rootPath)))
+        throw new Error('scanner_containment');
       entries = await withTimeout(
         readdir(currentPath),
         FILE_OP_TIMEOUT_MS,
@@ -1083,12 +1212,13 @@ export class CodeScanner {
     // Layer this directory's .gitignore/.mnemonikignore onto the inherited stack.
     const dirRel =
       currentPath === rootPath ? '' : relative(rootPath, currentPath).split(sep).join('/');
-    const localLayer = await this.loadIgnoreLayer(currentPath, dirRel, walk);
+    const localLayer = await this.loadIgnoreLayer(currentPath, dirRel, walk, rootPath);
     const localStack = localLayer ? [...stack, localLayer] : stack;
 
     for (const entry of entries) {
       const fullPath = join(currentPath, entry);
       const relativePath = relative(rootPath, fullPath);
+      if (this.isProtected(fullPath)) continue;
 
       // Check ignore patterns
       if (this.shouldIgnore(relativePath)) {
@@ -1097,7 +1227,7 @@ export class CodeScanner {
 
       // Per-entry isolation: a single bad entry (dangling symlink, raced
       // deletion, permission denial, fs timeout) must not abort the rest of
-      // the directory — but the scan is no longer removal-trustworthy.
+      // the directory - but the scan is no longer removal-trustworthy.
       try {
         const lstats = await withTimeout(
           lstat(fullPath),
@@ -1105,14 +1235,8 @@ export class CodeScanner {
           `lstat timed out: ${fullPath}`
         );
 
-        if (lstats.isSymbolicLink() && !(await this.confineSymlink(fullPath, rootPath))) {
-          logDebug('Skipping symlink escaping project root', { fullPath, rootPath });
-          continue;
-        }
-
-        const stats = lstats.isSymbolicLink()
-          ? await withTimeout(stat(fullPath), FILE_OP_TIMEOUT_MS, `stat timed out: ${fullPath}`)
-          : lstats;
+        if (this.skipSymlink(lstats)) continue;
+        const stats = lstats;
 
         if (stats.isDirectory()) {
           if (this.ignoredByStack(relativePath, true, localStack)) continue; // .gitignore/.mnemonikignore
@@ -1121,7 +1245,7 @@ export class CodeScanner {
         } else if (stats.isFile()) {
           if (this.ignoredByStack(relativePath, false, localStack)) continue;
           if (this.isChunkable(fullPath, relativePath)) {
-            const fileChunks = await this.parseFile(fullPath, rootPath);
+            const fileChunks = await this.parseFile(fullPath, rootPath, stats);
             chunks.push(...fileChunks);
           }
         }
@@ -1142,7 +1266,7 @@ export class CodeScanner {
    */
   private shouldIgnore(path: string): boolean {
     // Credential-bearing file kinds first, and outside the overridable
-    // `ignorePatterns` list — a caller-supplied pattern set must not be able
+    // `ignorePatterns` list - a caller-supplied pattern set must not be able
     // to opt a project back into indexing its own private keys.
     if (isSecretFile(path)) return true;
     const segments = path.split('/');
@@ -1151,10 +1275,10 @@ export class CodeScanner {
         // A leading '/' opts a glob pattern into SEGMENT-ANCHORED matching:
         // the pattern body must start at the beginning of the path or right
         // after a '/'. Without it, glob patterns keep their historical
-        // unanchored substring semantics — anchoring is opt-in per pattern so
+        // unanchored substring semantics - anchoring is opt-in per pattern so
         // this change cannot alter any existing pattern's behavior.
         // (Motivating bug: unanchored 'tests/fixtures/*' also matched
-        // 'integration-tests/fixtures/…' in every indexed project.)
+        // 'integration-tests/fixtures/...' in every indexed project.)
         const anchored = pattern.startsWith('/');
         const body = anchored ? pattern.slice(1) : pattern;
         // Escape regex special chars, then replace all * with .*
@@ -1171,21 +1295,23 @@ export class CodeScanner {
 
   /**
    * Parse a file and extract code chunks.
-   * Size limit is the shared `MAX_SCANNED_FILE_BYTES` ceiling — the same
+   * Size limit is the shared `MAX_SCANNED_FILE_BYTES` ceiling - the same
    * number the daemon and the server's scanPushSchema enforce, so anything
    * chunked here can always be shipped and stored verbatim.
    */
   private static readonly MAX_FILE_SIZE = MAX_SCANNED_FILE_BYTES;
 
-  private async parseFile(filePath: string, rootPath: string): Promise<CodeChunk[]> {
+  private async parseFile(
+    filePath: string,
+    rootPath: string,
+    enumerated?: Stats
+  ): Promise<CodeChunk[]> {
     try {
       // Check file size before reading to avoid memory issues
       // Wrap stat with timeout
-      const stats = await withTimeout(
-        stat(filePath),
-        FILE_OP_TIMEOUT_MS,
-        `stat timed out: ${filePath}`
-      );
+      const stats =
+        enumerated ??
+        (await withTimeout(lstat(filePath), FILE_OP_TIMEOUT_MS, `stat timed out: ${filePath}`));
       if (stats.size > CodeScanner.MAX_FILE_SIZE) {
         logDebug('Skipping file exceeding size limit', {
           filePath,
@@ -1197,15 +1323,15 @@ export class CodeScanner {
 
       // Wrap readFile with timeout
       let content = await withTimeout(
-        readFile(filePath, 'utf-8'),
+        this.readConfined(filePath, rootPath, stats),
         FILE_OP_TIMEOUT_MS,
         `readFile timed out: ${filePath}`
       );
       // NUL sanitation (ingestion boundary, daemon side): Postgres `text`
-      // columns reject the literal NUL byte (U+0000) — a single one aborts
+      // columns reject the literal NUL byte (U+0000) - a single one aborts
       // the whole INSERT/UPDATE. Some source files legitimately contain
       // them. Strip before any chunking so every chunk's content, its
-      // contentHash, and its embedding all agree — mirrors the server-side
+      // contentHash, and its embedding all agree - mirrors the server-side
       // strip in ProjectManager (kept as defense in depth for content that
       // reaches the server via an older scanner) but doing it here means
       // the daemon never even transmits the NUL bytes.
@@ -1227,7 +1353,7 @@ export class CodeScanner {
       };
 
       // AST first for the languages with a vendored grammar. `null` means "no
-      // grammar for this" — the honest majority of the allowlist — and the
+      // grammar for this" - the honest majority of the allowlist - and the
       // heuristic path below takes over with no log, because that is not a
       // degradation.
       const astLanguage = resolveAstLanguage(fileMetadata.extension, language);
@@ -1250,8 +1376,8 @@ export class CodeScanner {
           }
           // `errorNodes` is handed back precisely so this degradation is not
           // silent, and discarding it made it silent. One ERROR node can swallow
-          // the rest of a file — `typeof import(...)` in a type argument does
-          // exactly that to tree-sitter-typescript — after which no definition is
+          // the rest of a file - `typeof import(...)` in a type argument does
+          // exactly that to tree-sitter-typescript - after which no definition is
           // captured and the file arrives as one unnamed whole-file chunk. Naming
           // the file, the error count and how many definitions survived is what
           // makes that visible in a scan log.
@@ -1259,7 +1385,7 @@ export class CodeScanner {
           // Deliberately NOT a fallback to the heuristic path: measured on the
           // real construct (tests/AgentInjectionDeliveryWiring.test.ts), the
           // heuristic path names nothing either (its name pattern needs a
-          // leading `function`/`class`/`const`) AND covers less — it emitted 3
+          // leading `function`/`class`/`const`) AND covers less - it emitted 3
           // chunks starting at line 18 and dropped lines 1-17, because the
           // uncovered-region supplement only fires above 50 lines. Trading
           // total coverage for no gain is worse than one honest blob, so the
@@ -1281,8 +1407,8 @@ export class CodeScanner {
           // file cannot be bounded on line boundaries at all.
           const bounded = this.boundAstChunks(ast.chunks);
           if (bounded) {
-            // Zero chunks here means the file has no non-whitespace line — the AST
-            // chunker covers every other line by construction — so returning
+            // Zero chunks here means the file has no non-whitespace line - the AST
+            // chunker covers every other line by construction - so returning
             // nothing is the correct answer, not a lost file.
             return bounded.map(
               ({ symbolName, symbolKind, signature, symbolContainer, ...chunk }) => ({
@@ -1300,7 +1426,7 @@ export class CodeScanner {
               })
             );
           }
-          // One line longer than `maxChunkSize` — a generated `*_pb2.py` carries
+          // One line longer than `maxChunkSize` - a generated `*_pb2.py` carries
           // the whole serialized descriptor on one. Splitting it would have to
           // cut mid-line, and two chunks over one line range collide on the
           // `filePath:startLine-endLine` staleness key, so the whole file goes to
@@ -1318,7 +1444,7 @@ export class CodeScanner {
         } else if (ast.unsupported === 'grammar_unavailable') {
           // Process-global, not per file: `loadGrammar` caches its failures, so
           // every file of this language degrades for the same reason. Warned per
-          // file, this printed 1,037 identical lines in one scan of this repo —
+          // file, this printed 1,037 identical lines in one scan of this repo -
           // the log flood `logAstCapabilityOnce` exists to avoid. Once per
           // (reason, grammar); the file-specific reasons below stay per file.
           const key = `${ast.unsupported}:${astLanguage}`;
@@ -1335,7 +1461,7 @@ export class CodeScanner {
         } else {
           // Not a silent no-op: name the file AND the reason, then degrade to the
           // heuristic path. A degraded scan indistinguishable from a healthy one
-          // is the defect class this routing exists to avoid — and degrading to
+          // is the defect class this routing exists to avoid - and degrading to
           // zero chunks would delete the file from the index instead.
           logWarn('AST chunking unavailable; falling back to heuristic chunking', {
             filePath: relativePath,
@@ -1405,8 +1531,8 @@ export class CodeScanner {
    * chunk that came from a definition is exactly as big as the definition, and a
    * span that is one enormous line is left whole on purpose. Both used to reach
    * the wire verbatim, where `scanChunkSchema` caps content at 500,000 chars and
-   * rejects the WHOLE push if any chunk is over — so one generated file stopped
-   * all scanning for that push — and where anything past 8191 tokens is only
+   * rejects the WHOLE push if any chunk is over - so one generated file stopped
+   * all scanning for that push - and where anything past 8191 tokens is only
    * partially embedded.
    *
    * The invariants, all of which the split preserves:
@@ -1414,8 +1540,8 @@ export class CodeScanner {
    *   joined by '\n', never a join of disjoint regions and never an elision;
    * - total coverage is unchanged: the pieces tile the original range, in order,
    *   with no gap and no overlap;
-   * - the definition's identity rides on the piece that carries its signature —
-   *   the first one — and the continuations are plain `raw` spans, because a
+   * - the definition's identity rides on the piece that carries its signature -
+   *   the first one - and the continuations are plain `raw` spans, because a
    *   continuation is not the definition and must not claim its name.
    *
    * `null` (the caller degrades the whole file to the heuristic chunker) is
@@ -1624,7 +1750,7 @@ export class CodeScanner {
         continue;
       }
 
-      // Regex literal — heuristic: / after operator chars or keywords that precede expressions
+      // Regex literal - heuristic: / after operator chars or keywords that precede expressions
       if (c === '/' && i > 0) {
         // Look back for operator context (skip whitespace)
         let j = i - 1;
@@ -1658,7 +1784,7 @@ export class CodeScanner {
             if (content.charAt(i) === '\\') {
               i++; // skip escaped char
             } else if (content.charAt(i) === '[') {
-              // character class — skip to ]
+              // character class - skip to ]
               i++;
               while (i < len && content.charAt(i) !== ']') {
                 if (content.charAt(i) === '\\') i++;
@@ -1780,7 +1906,7 @@ export class CodeScanner {
             regex: '(?:export\\s+)?const\\s+\\w+\\s*=\\s*(?:async\\s+)?\\([^)]*\\)\\s*=>\\s*\\{',
             type: 'function',
           },
-          // Class methods — matches indented methods with optional modifiers.
+          // Class methods - matches indented methods with optional modifiers.
           // Excludes control flow keywords (if, for, while, switch, catch, return).
           {
             regex:
@@ -1813,13 +1939,9 @@ export class CodeScanner {
   /**
    * Raw chunking with overlap, bounded by character count (not line count).
    *
-   * The previous implementation took `floor(maxChunkSize / 80)` lines per
-   * chunk on the assumption of ~80 chars/line. Long-line files (minified
-   * JS, JSON blobs, generated code) produced chunks many times larger than
-   * `maxChunkSize`, which then exceeded OpenAI's 8191-token embedding
-   * limit and surfaced as 400s on /scan/push (Sentry MNEMONIK-58).
-   *
-   * Now: walk lines and accumulate character length; emit when the next
+   * Line-count estimates do not bound long-line files such as minified JS,
+   * JSON blobs and generated code. Walk lines and accumulate character
+   * length; emit when the next
    * line would push the running total past `maxChunkSize`. Single lines
    * longer than `maxChunkSize` are force-split into char-based segments.
    * 10% overlap is carried by character count from the tail of the
@@ -1929,7 +2051,7 @@ export class CodeScanner {
   /**
    * Walk the project for authority manifest/config/CI files and return their
    * verbatim content. Reuses ignorePatterns; matches AUTHORITY_FILE_MATCHERS
-   * (not includeExtensions). Content-only — no chunking, no embeddings.
+   * (not includeExtensions). Content-only - no chunking, no embeddings.
    */
   async collectAuthorityFiles(
     projectRoot: string
@@ -1941,67 +2063,65 @@ export class CodeScanner {
   /**
    * Completeness-aware variant of `collectAuthorityFiles`. `complete ===
    * false` means an fs error hid part of the walk, so authority paths may
-   * be missing — the daemon folds this into the same removal gate as
+   * be missing - the daemon folds this into the same removal gate as
    * `listFilesWithStatus` (a partial authority walk would likewise drop
    * inventory entries and read as deletion).
    */
-  async collectAuthorityFilesWithStatus(projectRoot: string): Promise<{
+  async collectAuthorityFilesWithStatus(
+    projectRoot: string,
+    onFile?: (file: { path: string; content: string; hash: string }) => Promise<void>
+  ): Promise<{
     files: Array<{ path: string; content: string; hash: string }>;
     complete: boolean;
   }> {
+    projectRoot = await this.canonicalRoot(projectRoot);
     const out: Array<{ path: string; content: string; hash: string }> = [];
     const walkState: WalkState = { complete: true };
 
     // M2: cap walk depth to match the scanner's MAX_DEPTH (10)
     const walk = async (dir: string, depth: number, stack: IgnoreStack = []): Promise<void> => {
       if (depth >= CodeScanner.MAX_DEPTH) return;
+      if (this.isProtected(dir)) return;
       let entries;
       try {
+        if (!(await this.confineSymlink(dir, projectRoot))) throw new Error('scanner_containment');
         entries = await readdir(dir, { withFileTypes: true });
       } catch {
         walkState.complete = false;
         return;
       }
       const dirRel = dir === projectRoot ? '' : relative(projectRoot, dir).split(sep).join('/');
-      const localLayer = await this.loadIgnoreLayer(dir, dirRel, walkState);
+      const localLayer = await this.loadIgnoreLayer(dir, dirRel, walkState, projectRoot);
       const localStack = localLayer ? [...stack, localLayer] : stack;
       for (const ent of entries) {
         const full = join(dir, ent.name);
         const rel = relative(projectRoot, full).split(sep).join('/');
+        if (this.isProtected(full)) continue;
         if (this.shouldIgnore(rel)) continue;
 
-        // Resolve the entry kind through symlinks, confined to the project
-        // root: a symlink named like an authority file (`package.json`,
-        // `.env.example`, ...) pointing outside the root would otherwise be
-        // read verbatim and exfiltrated to the server. Same predicate as
-        // traverseDirectory/traversePaths (confineSymlink). Confined
-        // symlinked directories are traversed (Dirent.isDirectory() is
-        // false for them, so they were previously silently skipped).
-        let isDir = ent.isDirectory();
-        let isFile = ent.isFile();
-        if (ent.isSymbolicLink()) {
-          try {
-            if (!(await this.confineSymlink(full, projectRoot))) continue;
-            const stats = await stat(full);
-            isDir = stats.isDirectory();
-            isFile = stats.isFile();
-          } catch {
-            /* dangling/unreadable link — skip just this entry */
-            walkState.complete = false;
-            continue;
-          }
+        let stats: Stats;
+        try {
+          stats = await lstat(full);
+        } catch {
+          walkState.complete = false;
+          continue;
         }
+        if (this.skipSymlink(stats)) continue;
+        const isDir = stats.isDirectory(),
+          isFile = stats.isFile();
 
         if (this.ignoredByStack(rel, isDir, localStack)) continue; // .gitignore/.mnemonikignore
         if (isDir) {
           if (await isGitBoundary(full)) continue; // another repo's subtree
           await walk(full, depth + 1, localStack);
         } else if (isFile && AUTHORITY_FILE_MATCHERS.some((m) => m(rel))) {
+          let file: { path: string; content: string; hash: string } | undefined;
           try {
-            let content = await readFile(full, 'utf-8');
+            if (stats.size > MAX_SCANNED_FILE_BYTES) continue;
+            let content = await this.readConfined(full, projectRoot, stats);
             // Authority files honor the same single ceiling as chunked files
             // (MAX_SCANNED_FILE_BYTES). Manifests are tiny; one this large is
-            // anomalous, so say so rather than dropping it silently — a
+            // anomalous, so say so rather than dropping it silently - a
             // missing authority file otherwise looks identical to a project
             // that simply has no manifest.
             if (content.length > MAX_SCANNED_FILE_BYTES) {
@@ -2020,11 +2140,16 @@ export class CodeScanner {
               content = content.replace(/\0/g, '');
             }
             const hash = createHash('sha256').update(content).digest('hex');
-            out.push({ path: rel, content, hash });
+            file = { path: rel, content, hash };
           } catch {
-            /* unreadable — skip */
+            /* unreadable - skip */
             walkState.complete = false;
           }
+          // The consumer owns backpressure; its abort must leave the walk immediately.
+          if (file) {
+            if (onFile) await onFile(file);
+            else out.push(file);
+          }
         }
       }
     };