claude-nomad 0.25.0 → 0.25.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.25.1](https://github.com/funkadelic/claude-nomad/compare/v0.25.0...v0.25.1) (2026-05-26)
+
+
+### Fixed
+
+* **doctor:** scan --check-shared like push to fix false negatives ([#134](https://github.com/funkadelic/claude-nomad/issues/134)) ([5063028](https://github.com/funkadelic/claude-nomad/commit/5063028c6a695709f7f2d2dfe3cceabedecc17f9))
+
+
+### Changed
+
+* split over-cap source and test files under the ~200-line cap ([#136](https://github.com/funkadelic/claude-nomad/issues/136)) ([0cc7eed](https://github.com/funkadelic/claude-nomad/commit/0cc7eed13abbc85084b04cfc8b686e53b26133c6))
+
 ## [0.25.0](https://github.com/funkadelic/claude-nomad/compare/v0.24.0...v0.25.0) (2026-05-25)
 
 

package/README.md

@@ -409,7 +409,7 @@ Exit codes:
 - `0` on any drop, including an idempotent re-run.
 - `1` with `✗ no staged session matches <id>` on stderr when neither a `shared/projects/*/<id>.jsonl` nor a `shared/projects/*/<id>/` directory with staged entries matches.
 
-What it does NOT do: touch the local `~/.claude/projects/<encoded>/<id>.jsonl` file or the local `<id>/` subagent tree. The local copies are preserved for `claude --resume`, grep recovery, or whatever the user wants. If the underlying secret is real, scrub the local files separately.
+What it does NOT do: touch the local `~/.claude/projects/<encoded>/<id>.jsonl` file or the local `<id>/` subagent tree. The local copies are preserved for `claude --resume`, grep recovery, or whatever the user wants. If the underlying secret is real, scrubbing or removing the local files is REQUIRED for durability, not optional housekeeping: `remapPush` (in `src/remap.ts`) re-mirrors the local content into the staged tree on the next push, so a drop without a local scrub re-stages the same secret.
 
 ### Recovery flow: gitleaks FATAL on a session JSONL
 
@@ -427,7 +427,7 @@ After recovery, re-run nomad push.
 
 Two branches from here:
 
-1. **Real secret.** Rotate the credential at its provider (revoke in dashboard, issue replacement), then run `nomad drop-session <sid-aaaa>` to remove the contaminated staged copy, then re-run `nomad push`. To clear the secret from the local transcript as well, edit `~/.claude/projects/<encoded>/<sid-aaaa>.jsonl` to scrub the offending lines; the next `remapPush` copies the cleaned version forward. If the local file is not important to you, leave it alone, the staged-tree drop is enough to publish the push.
+1. **Real secret.** Rotate the credential at its provider first (revoke in dashboard, issue replacement) before touching anything else. Running `nomad drop-session <sid-aaaa>` clears the contaminated copy from the current staged tree, but that alone is NOT durable: `remapPush` (in `src/remap.ts`) does a full rm-and-copy mirror of your LOCAL transcripts into `shared/projects/` on every push, so the next `nomad push` re-copies the un-scrubbed local file forward and re-stages the same secret. The durable fix is to rotate AND scrub or remove the local transcript at `~/.claude/projects/<encoded>/<sid-aaaa>.jsonl` (plus the sibling `<sid-aaaa>/` subagent directory under that encoded dir, if present) so the next `remapPush` carries clean content forward. Do not leave the local file un-scrubbed and expect the staged-tree drop to hold.
 
 2. **False positive.** Add an allowlist regex to `.gitleaks.toml` at the repo root that matches the noise pattern but not real-secret formats, commit it, then re-run `nomad push`. The new allowlist propagates to deploy hosts via `nomad update`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "type": "module",
   "description": "Sync Claude Code config (~/.claude/) across machines via a private Git repo, with path remapping and per-host settings overrides.",
   "keywords": [

package/src/commands.doctor.check-shared.scan.ts

@@ -0,0 +1,158 @@
+/**
+ * Scan-result classification and row emission for the `nomad doctor
+ * --check-shared` preflight. Split out of `commands.doctor.check-shared.ts` to
+ * keep both files under the line cap; `reportCheckShared` (the public reporter)
+ * stays in the sibling and calls `scanAndReport` after staging the temp tree.
+ *
+ * Owns the post-stage block: run the shared `scanStagedTree` (the same git
+ * init + add + `gitleaks protect --staged` mechanism push uses), classify the
+ * findings via `partitionFindings`, and emit the doctor glyph rows (clean,
+ * per-session leak with rotate-and-scrub guidance, and the nested "other"
+ * bucket). All external work flows through `scanStagedTree`; this module spawns
+ * nothing itself.
+ */
+
+import { join } from 'node:path';
+
+import { green, red, okGlyph, failGlyph } from './color.ts';
+import { addItem, type DoctorSection } from './commands.doctor.format.ts';
+import { CLAUDE_HOME } from './config.ts';
+import { type Finding, partitionFindings, scanStagedTree } from './push-gitleaks.ts';
+
+/**
+ * Recover the absolute live transcript path
+ * `~/.claude/projects/<encoded>/<sid>.jsonl` by mapping the finding's
+ * `<logical>` through the staging association, falling back to the logical name
+ * when the association is missing (defensive; the temp-tree build guarantees a hit).
+ */
+function scrubPath(logical: string, sid: string, logicalToEncoded: Map<string, string>): string {
+  /* c8 ignore next -- the `?? logical` fallback is defensive; the temp-tree build keys every staged logical */
+  const encoded = logicalToEncoded.get(logical) ?? logical;
+  return join(CLAUDE_HOME, 'projects', encoded, `${sid}.jsonl`);
+}
+
+/**
+ * Emit one fail row per affected session plus rotate-and-scrub + allowlist
+ * guidance, and set `process.exitCode = 1`. `logicalBySession` carries the
+ * `<logical>` captured from the same match that keyed `bySession`, so the
+ * scrub-path hint reuses the authoritative parse. The hint guard omits a row
+ * rather than print a wrong path if the invariant ever breaks; the leak row is
+ * always emitted.
+ */
+function reportSessionFindings(
+  section: DoctorSection,
+  bySession: Map<string, Map<string, number>>,
+  logicalBySession: Map<string, string>,
+  logicalToEncoded: Map<string, string>,
+): void {
+  for (const [sid, counts] of bySession) {
+    const summary = [...counts.entries()].map(([rule, n]) => `${rule} (${n})`).join(', ');
+    addItem(section, `${red(failGlyph)} session ${sid}: ${summary}`);
+    const logical = logicalBySession.get(sid);
+    /* c8 ignore next -- false branch is defensive; every bySession sid is keyed in logicalBySession */
+    if (logical !== undefined) {
+      addItem(
+        section,
+        `  rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`,
+      );
+    }
+    addItem(section, `  false positive? add a pattern to .gitleaks.toml`);
+  }
+  process.exitCode = 1;
+}
+
+/**
+ * Emit one fail row per non-session ("other"-bucket) finding and set
+ * `process.exitCode = 1`. These are findings whose `File` did not match the
+ * flat `SESSION_PATH` shape (nested transcripts under `subagents/`, `memory/`,
+ * which `nomad push` would still stage). Names the repo-relative path and
+ * RuleID only, never the matched secret.
+ */
+function reportOtherFindings(section: DoctorSection, other: Finding[]): void {
+  for (const f of other) {
+    addItem(section, `${red(failGlyph)} leak in ${f.File}: ${f.RuleID}`);
+  }
+  process.exitCode = 1;
+}
+
+/**
+ * Captures both the `<logical>` segment and the `<sid>` from a repo-relative
+ * `shared/projects/<logical>/<sid>.jsonl` path. The session-id group matches
+ * the exported `SESSION_PATH` shape; the `<logical>` group lets the scrub-path
+ * hint reuse this single authoritative parse.
+ */
+const SESSION_PATH_LOGICAL = /^shared\/projects\/([^/]+)\/([^/]+)\.jsonl$/;
+
+/**
+ * Emit the single canonical clean row reporting the scanned-project count
+ * (`staged` is the number of mapped project dirs staged, not a transcript
+ * total). Centralizing the literal keeps every clean path (zero-staged,
+ * scanned-clean, findings-but-no-`other`) phrased consistently.
+ */
+export function emitClean(section: DoctorSection, staged: number): void {
+  addItem(section, `${green(okGlyph)} ${staged} project(s) scanned, no leaks`);
+}
+
+/**
+ * Build the `sid -> <logical>` association from the findings, capturing both
+ * groups from the same `SESSION_PATH_LOGICAL` match so the scrub-path hint
+ * never re-derives the logical name. First match per sid wins (the scrub path
+ * is per session, not per finding).
+ */
+function buildLogicalBySession(findings: Finding[]): Map<string, string> {
+  const logicalBySession = new Map<string, string>();
+  for (const f of findings) {
+    const m = SESSION_PATH_LOGICAL.exec(f.File);
+    if (m?.[2] !== undefined && !logicalBySession.has(m[2])) {
+      /* c8 ignore next -- `?? ''` is defensive; group 1 is always captured when the match succeeds */
+      logicalBySession.set(m[2], m[1] ?? '');
+    }
+  }
+  return logicalBySession;
+}
+
+/**
+ * Scan the staged temp tree through the shared `scanStagedTree` and emit the
+ * result rows. Isolates the deepest nesting from `reportCheckShared`: the scan
+ * try/catch (failure -> fail row + exit 1, carrying `err.message` only, never
+ * stderr/stdout), the unparseable `findings === null` branch, `partitionFindings`,
+ * and the clean / `other` / `bySession` rows. BOTH buckets gate the clean row: a
+ * finding in `other` (nested transcripts matching neither the flat `SESSION_PATH`
+ * nor any session) is still a stageable secret push would catch, so a
+ * `bySession`-only gate would make the preflight weaker than the push scan.
+ */
+export function scanAndReport(
+  section: DoctorSection,
+  tmpRoot: string,
+  staged: number,
+  logicalToEncoded: Map<string, string>,
+): void {
+  let findings: Finding[] | null;
+  try {
+    findings = scanStagedTree(tmpRoot);
+  } catch (err) {
+    // ENOENT (binary vanished mid-flow) or a git failure. The top-of-flow probe
+    // WARN-skips a truly missing gitleaks; this catch reports a scan-failed FAIL
+    // row with err.message only (never stderr/stdout, which can echo
+    // redacted-but-sensitive scan output).
+    addItem(section, `${red(failGlyph)} scan failed: ${(err as Error).message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (findings === null) {
+    // Non-zero gitleaks exit with no parseable report. Carry no stream output,
+    // matching runGitleaksScan on the push side.
+    addItem(section, `${red(failGlyph)} scan failed: no parseable gitleaks report`);
+    process.exitCode = 1;
+    return;
+  }
+  const { bySession, other } = partitionFindings(findings);
+  if (bySession.size === 0 && other.length === 0) {
+    emitClean(section, staged);
+    return;
+  }
+  if (other.length > 0) reportOtherFindings(section, other);
+  if (bySession.size > 0) {
+    reportSessionFindings(section, bySession, buildLogicalBySession(findings), logicalToEncoded);
+  }
+}

package/src/commands.doctor.check-shared.ts

@@ -1,23 +1,18 @@
 /**
  * Owns the `nomad doctor --check-shared` preflight reporter.
  *
- * Read-only diagnostic that runs gitleaks against the LOCAL session
- * transcripts `nomad push` would stage (each path-map entry mapped to this
- * host), surfacing secret leaks BEFORE the push pipeline fires. Mirrors the
- * push-time scan (`runGitleaksScan` in `./push-gitleaks.ts`) but: scans a
- * temp COPY of the live transcripts (never the live dir), uses the
- * purpose-built `gitleaks dir` subcommand, and emits doctor-flavored glyph
- * rows + `process.exitCode` instead of throwing a push-flavored FATAL.
+ * Read-only diagnostic that runs gitleaks against the LOCAL session transcripts
+ * `nomad push` would stage (each path-map entry mapped to this host), surfacing
+ * leaks BEFORE the push pipeline fires. Stages a temp COPY of the live
+ * transcripts into a throwaway git repo and delegates the scan + row emission
+ * to `scanAndReport` (`./commands.doctor.check-shared.scan.ts`), which runs the
+ * shared `scanStagedTree` (`gitleaks protect --staged`, the same mechanism push
+ * uses), so the preflight cannot miss a secret the push gate would catch. Emits
+ * doctor glyph rows + `process.exitCode` instead of throwing a FATAL.
  *
- * Composition only: reuses `partitionFindings` / `readGitleaksReport` /
- * `SESSION_PATH` (the gitleaks JSON parser) and `copyDirJsonlOnly` (the
- * push-fidelity source filter) verbatim. The doctor-flavored guidance
- * composer is new (push's `buildSessionAwareFatal` is wrong at doctor time:
- * `nomad drop-session` operates on the staged tree, and nothing is staged
- * during a preflight).
- *
- * All external calls use `execFileSync` argv-array form (no shell), the
- * codebase PUSH-04 invariant.
+ * This file owns probe-readiness, temp-tree staging, and orchestration; the
+ * findings classification + guidance composer live in the `.scan.ts` sibling.
+ * All external calls use `execFileSync` argv-array form (PUSH-04).
  */
 
 import { randomBytes } from 'node:crypto';
@@ -26,19 +21,18 @@ import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-import { green, red, yellow, okGlyph, failGlyph, warnGlyph } from './color.ts';
+import { red, yellow, failGlyph, warnGlyph } from './color.ts';
+import { emitClean, scanAndReport } from './commands.doctor.check-shared.scan.ts';
 import { addItem, type DoctorSection } from './commands.doctor.format.ts';
 import { CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
-import { type Finding, partitionFindings, readGitleaksReport } from './push-gitleaks.ts';
 import { copyDirJsonlOnly } from './remap.ts';
-import { encodePath, nowTimestamp, readJson } from './utils.ts';
+import { nowTimestamp } from './utils.fs.ts';
+import { encodePath, readJson } from './utils.json.ts';
 
 /**
  * Result of staging the scan tree. `malformed` is true when `path-map.json`
  * exists but does not parse as JSON; the caller emits a FAIL row and stops
- * (mirroring `reportPathMap`'s `readJsonSafe` degradation) rather than letting
- * the `SyntaxError` propagate past `nomad.ts`'s `NomadFatal`-only handler and
- * abort the whole doctor run with a stack trace.
+ * rather than letting the `SyntaxError` abort the whole doctor run.
  */
 type ScanTree = {
   logicalToEncoded: Map<string, string>;
@@ -48,12 +42,10 @@ type ScanTree = {
 
 /**
  * Build the temp staging tree under `tmpRoot/shared/projects/<logical>/` by
- * copying each local encoded session dir that resolves to a path-map logical
- * for this host. Returns the `logical -> encoded-dir` association so the
- * scrub-path hint can name the live `~/.claude/projects/<encoded>/<sid>.jsonl`
- * file, plus the count of session dirs staged. Skips `TBD`/unmapped entries
- * (the D-03 scope: exactly what `remapPush` would stage). Uses the same
- * depth-0 `*.jsonl` filter as push via `copyDirJsonlOnly`. A malformed
+ * copying each local encoded session dir that maps to a path-map logical for
+ * this host (exactly what `remapPush` would stage; same depth-0 `*.jsonl`
+ * filter via `copyDirJsonlOnly`). Returns the `logical -> encoded-dir`
+ * association (for the scrub-path hint) plus the count staged. A malformed
  * `path-map.json` sets `malformed: true` rather than throwing.
  */
 function buildScanTree(tmpRoot: string): ScanTree {
@@ -93,11 +85,9 @@ function buildScanTree(tmpRoot: string): ScanTree {
 
 /**
  * Probe for the gitleaks binary on PATH, distinguishing the not-installed case
- * (ENOENT -> `'missing'`, a WARN skip per the read-only doctor contract) from a
- * real probe failure (EACCES, corrupt binary -> `{ fail: message }`, a FAIL).
- * Mirrors `reportGitleaksProbe`'s ENOENT-vs-other split rather than collapsing
- * every failure into "not on PATH". Probes directly (not via `probeGitleaks`)
- * so the doctor flavor stays read-only and need not unwrap a `NomadFatal`.
+ * (ENOENT -> `'missing'`, a WARN skip) from a real probe failure (EACCES,
+ * corrupt binary -> `{ fail: message }`, a FAIL). Mirrors `reportGitleaksProbe`'s
+ * ENOENT-vs-other split; probes directly so the doctor flavor stays read-only.
  */
 function probeGitleaksForScan(): 'ok' | 'missing' | { fail: string } {
   try {
@@ -110,123 +100,46 @@ function probeGitleaksForScan(): 'ok' | 'missing' | { fail: string } {
 }
 
 /**
- * Recover the live encoded-dir for a finding by mapping its `<logical>`
- * segment through the staging association. Returns the absolute live
- * transcript path `~/.claude/projects/<encoded>/<sid>.jsonl`, falling back to
- * the logical name when the association is missing (defensive; the temp-tree
- * model guarantees a hit).
+ * Probe-readiness guard ladder. Returns true to proceed to the scan, false to
+ * stop after emitting an early row. When the orchestrator already probed
+ * (`gitleaksReady === true`) the subcommand is not re-invoked; otherwise this
+ * probes for itself, mapping `missing` to a WARN skip (exit untouched) and a
+ * non-ENOENT failure to a FAIL row + `process.exitCode = 1`.
  */
-function scrubPath(logical: string, sid: string, logicalToEncoded: Map<string, string>): string {
-  /* c8 ignore next -- the `?? logical` fallback is defensive; the temp-tree build keys every staged logical */
-  const encoded = logicalToEncoded.get(logical) ?? logical;
-  return join(CLAUDE_HOME, 'projects', encoded, `${sid}.jsonl`);
-}
-
-/**
- * Emit one fail row per affected session plus rotate-and-scrub + allowlist
- * guidance, and set `process.exitCode = 1`. `logicalBySession` carries the
- * `<logical>` segment captured from the same `SESSION_PATH` match that keyed
- * `bySession`, so the scrub-path hint reuses the authoritative parse rather
- * than re-deriving the logical name from the finding `File`. Every `bySession`
- * sid is keyed in `logicalBySession` (both come from the identical sid capture),
- * so the scrub hint always renders; the guard omits the hint rather than
- * printing a wrong path if that invariant ever breaks, and the leak row itself
- * is always emitted.
- */
-function reportSessionFindings(
-  section: DoctorSection,
-  bySession: Map<string, Map<string, number>>,
-  logicalBySession: Map<string, string>,
-  logicalToEncoded: Map<string, string>,
-): void {
-  for (const [sid, counts] of bySession) {
-    const summary = [...counts.entries()].map(([rule, n]) => `${rule} (${n})`).join(', ');
-    addItem(section, `${red(failGlyph)} session ${sid}: ${summary}`);
-    const logical = logicalBySession.get(sid);
-    /* c8 ignore next -- false branch is defensive; every bySession sid is keyed in logicalBySession */
-    if (logical !== undefined) {
-      addItem(
-        section,
-        `  rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`,
-      );
-    }
-    addItem(section, `  false positive? add a pattern to .gitleaks.toml`);
+function ensureGitleaksReady(section: DoctorSection, gitleaksReady?: boolean): boolean {
+  if (gitleaksReady === true) return true;
+  const probe = probeGitleaksForScan();
+  if (probe === 'missing') {
+    addItem(section, `${yellow(warnGlyph)} gitleaks not on PATH; shared scan skipped`);
+    return false;
   }
-  process.exitCode = 1;
-}
-
-/**
- * Emit one fail row per non-session ("other"-bucket) finding and set
- * `process.exitCode = 1`. These are findings whose `File` did not match the
- * flat `SESSION_PATH` shape (nested transcripts under `subagents/`, `memory/`,
- * etc., which `copyDirJsonlOnly` copies recursively and `nomad push` would
- * stage). Names the repo-relative path and RuleID only, never the matched
- * secret. Mirrors the push-side guarantee that any finding outside `bySession`
- * still fails the scan (`buildSessionAwareFatal`'s `LEGACY_FATAL` fallback).
- */
-function reportOtherFindings(section: DoctorSection, other: Finding[]): void {
-  for (const f of other) {
-    addItem(section, `${red(failGlyph)} leak in ${f.File}: ${f.RuleID}`);
+  if (probe !== 'ok') {
+    addItem(section, `${red(failGlyph)} gitleaks probe failed: ${probe.fail}`);
+    process.exitCode = 1;
+    return false;
   }
-  process.exitCode = 1;
-}
-
-/**
- * Captures both the `<logical>` segment and the `<sid>` from a repo-relative
- * `shared/projects/<logical>/<sid>.jsonl` path. The session-id group matches
- * the exported `SESSION_PATH` shape; the extra `<logical>` group lets the
- * scrub-path hint reuse this single authoritative parse.
- */
-const SESSION_PATH_LOGICAL = /^shared\/projects\/([^/]+)\/([^/]+)\.jsonl$/;
-
-/**
- * Emit the single canonical clean row reporting the scanned-project count
- * (`staged` is the number of mapped project directories whose transcripts were
- * staged, not a transcript total). Centralizing the literal (zero-staged,
- * scanned-clean, and the findings-but-no-`other` paths all route through here)
- * keeps the phrasing consistent and prevents one copy drifting from another,
- * which is what let a "no session findings == clean" path slip past the
- * `other`-bucket gate.
- */
-function emitClean(section: DoctorSection, staged: number): void {
-  addItem(section, `${green(okGlyph)} ${staged} project(s) scanned, no leaks`);
+  return true;
 }
 
 /**
  * Run the `--check-shared` preflight and append its rows to `section`.
  *
- * Flow (D-01..D-10): probe gitleaks (missing -> one WARN row, exit untouched;
- * a non-ENOENT probe failure -> FAIL row + exit 1, mirroring
- * `reportGitleaksProbe`); stage a temp copy of this-host mapped session dirs
- * (a malformed `path-map.json` -> FAIL row + exit 1, no crash); scan with the
- * positional `gitleaks dir shared/projects` invocation (NOT `--source`, which
- * `gitleaks dir` rejects with exit 126); on a clean scan emit one ok row
- * reporting the scanned-project count; on findings emit per-session fail rows
- * with rotate-and-scrub guidance and set `process.exitCode = 1`; on a non-zero
- * exit with no parseable report emit a scan-failed fail row carrying the
- * gitleaks error message (never its stderr/stdout, which may hold secrets) +
- * exit 1 (do not chase phantom sessions). Removes both the temp report and the
- * temp tree in `finally` on success and failure. Never writes to stderr
- * (read-only doctor contract).
+ * Thin orchestrator (D-01..D-10): `ensureGitleaksReady` gates entry (a missing
+ * binary WARN-skips, a probe failure FAILs); `buildScanTree` stages a temp copy
+ * of this-host mapped session dirs (a malformed `path-map.json` -> FAIL row,
+ * no crash); `scanAndReport` runs the shared `scanStagedTree` (the same
+ * mechanism push uses, so the preflight cannot miss what push catches) and
+ * emits the clean / leak / scan-failed rows, setting `process.exitCode = 1` on
+ * any failure. The temp report + tree (including the injected throwaway `.git`)
+ * are removed in `finally` on every path. Never writes to stderr (read-only
+ * doctor contract: `scanStagedTree` runs with `forwardStreams` left false).
  *
- * `gitleaksReady` lets the doctor orchestrator pass the result of the
- * Repository section's gitleaks probe so the `version` subcommand is not
- * invoked a second time on a `--check-shared` run. When omitted (the module's
- * standalone contract) this reporter probes for itself.
+ * `gitleaksReady` lets the doctor orchestrator pass the Repository section's
+ * probe result so `version` is not invoked twice on a `--check-shared` run;
+ * when omitted (the standalone contract) this reporter probes for itself.
  */
 export function reportCheckShared(section: DoctorSection, gitleaksReady?: boolean): void {
-  if (gitleaksReady !== true) {
-    const probe = probeGitleaksForScan();
-    if (probe === 'missing') {
-      addItem(section, `${yellow(warnGlyph)} gitleaks not on PATH; shared scan skipped`);
-      return;
-    }
-    if (probe !== 'ok') {
-      addItem(section, `${red(failGlyph)} gitleaks probe failed: ${probe.fail}`);
-      process.exitCode = 1;
-      return;
-    }
-  }
+  if (!ensureGitleaksReady(section, gitleaksReady)) return;
 
   const cacheDir = join(homedir(), '.cache', 'claude-nomad');
   mkdirSync(cacheDir, { recursive: true });
@@ -252,56 +165,12 @@ export function reportCheckShared(section: DoctorSection, gitleaksReady?: boolea
       emitClean(section, 0);
       return;
     }
-    const tomlPath = join(REPO_HOME, '.gitleaks.toml');
-    const args: string[] = [
-      'dir',
-      'shared/projects',
-      '--redact',
-      '-v',
-      '--report-format=json',
-      `--report-path=${reportPath}`,
-    ];
-    if (existsSync(tomlPath)) args.push('--config', tomlPath);
-
-    try {
-      execFileSync('gitleaks', args, { cwd: tmpRoot, stdio: ['ignore', 'pipe', 'pipe'] });
-      emitClean(section, staged);
-    } catch (err) {
-      const findings = readGitleaksReport(reportPath);
-      if (findings === null) {
-        // Carry the gitleaks error message only (never e.stderr/e.stdout, which
-        // can echo the redacted-but-still-sensitive scan output), matching
-        // runGitleaksScan on the push side.
-        const msg = (err as Error).message;
-        addItem(section, `${red(failGlyph)} scan failed: no parseable gitleaks report (${msg})`);
-        process.exitCode = 1;
-        return;
-      }
-      const { bySession, other } = partitionFindings(findings);
-      // Both buckets must gate the clean row. A finding routed to `other`
-      // (nested transcripts that match neither the flat SESSION_PATH nor any
-      // session) is still a stageable secret push would catch, so reporting
-      // clean on `bySession.size === 0` alone would make the preflight weaker
-      // than the push scan it stands in for.
-      if (bySession.size === 0 && other.length === 0) {
-        emitClean(section, staged);
-        return;
-      }
-      if (other.length > 0) reportOtherFindings(section, other);
-      if (bySession.size > 0) {
-        // Capture <logical> alongside <sid> from the same authoritative match
-        // so the scrub hint never re-derives the logical name independently.
-        const logicalBySession = new Map<string, string>();
-        for (const f of findings) {
-          const m = SESSION_PATH_LOGICAL.exec(f.File);
-          if (m?.[2] !== undefined && !logicalBySession.has(m[2])) {
-            /* c8 ignore next -- `?? ''` is defensive; group 1 is always captured when the match succeeds */
-            logicalBySession.set(m[2], m[1] ?? '');
-          }
-        }
-        reportSessionFindings(section, bySession, logicalBySession, logicalToEncoded);
-      }
-    }
+    // Scan the temp tree through the SAME mechanism push uses (scanStagedTree:
+    // git init + add + gitleaks protect --staged), so the preflight cannot miss
+    // a secret the push gate would catch. forwardStreams stays false so the
+    // read-only doctor never writes gitleaks output to stderr; the injected
+    // throwaway .git under tmpRoot is removed by the finally below.
+    scanAndReport(section, tmpRoot, staged, logicalToEncoded);
   } finally {
     rmSync(reportPath, { force: true });
     rmSync(tmpRoot, { recursive: true, force: true });

package/src/commands.doctor.checks.pathmap.ts

@@ -0,0 +1,101 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { blue, cyan, dim, failGlyph, green, infoGlyph, okGlyph, red } from './color.ts';
+import { HOST, NEVER_SYNC, REPO_HOME, type PathMap } from './config.ts';
+import { addItem, readJsonSafe, type DoctorSection } from './commands.doctor.format.ts';
+import { encodePath } from './utils.json.ts';
+
+/**
+ * Path-map reporters for `cmdDoctor`: the mapped-projects listing, the
+ * path-encoding collision scan, and the never-sync visibility line. Each helper
+ * appends items to its target `DoctorSection` and signals failure by setting
+ * `process.exitCode = 1`. Read-only: FAIL lines stay on stdout.
+ */
+
+/** Emits the mapped-projects header for the current host and one line per mapped project. */
+function reportMappedProjects(section: DoctorSection, map: PathMap): void {
+  const mapped = Object.entries(map.projects).filter(([, hosts]) => hosts[HOST]);
+  addItem(
+    section,
+    `${dim(infoGlyph)} mapped projects for ${cyan(HOST)}: ${dim(String(mapped.length))}`,
+  );
+  for (const [name, hosts] of mapped) {
+    addItem(section, `${dim(infoGlyph)} ${name} -> ${blue(hosts[HOST])}`);
+  }
+}
+
+/** Scans every host of every project for encodePath collisions; emits failGlyph per collision (sets exitCode=1), okGlyph when clean. */
+function reportPathCollisions(section: DoctorSection, map: PathMap): void {
+  const seen = new Map<string, string>();
+  let collisionCount = 0;
+  for (const hosts of Object.values(map.projects)) {
+    for (const abspath of Object.values(hosts)) {
+      if (!abspath || abspath === 'TBD') continue;
+      const encoded = encodePath(abspath);
+      const prior = seen.get(encoded);
+      if (prior !== undefined && prior !== abspath) {
+        addItem(
+          section,
+          `${red(failGlyph)} path-encoding collision: ${prior} and ${abspath} both encode to ${encoded}`,
+        );
+        collisionCount++;
+      } else {
+        seen.set(encoded, abspath);
+      }
+    }
+  }
+  if (collisionCount > 0) process.exitCode = 1;
+  else addItem(section, `${green(okGlyph)} path-encoding: no collisions`);
+}
+
+/** Pushes mapped projects for the current host and FAILs on path-encoding collisions across hosts; FAILs when path-map.json is missing. */
+export function reportPathMap(section: DoctorSection): void {
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  if (!existsSync(mapPath)) {
+    addItem(section, `${red(failGlyph)} path-map.json missing at ${blue(mapPath)}`);
+    process.exitCode = 1;
+    return;
+  }
+  const map = readJsonSafe<PathMap>(mapPath, mapPath, section);
+  if (map === null) return;
+  // Guard non-object `projects` and per-project non-object `hosts` so the
+  // helpers' `hosts[HOST]` / `Object.values(hosts)` cannot throw mid-output
+  // and break the tolerant-doctor contract.
+  const projects: unknown = (map as { projects?: unknown }).projects;
+  if (projects === null || typeof projects !== 'object' || Array.isArray(projects)) {
+    addItem(
+      section,
+      `${red(failGlyph)} path-map.json invalid schema: "projects" must be an object`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  for (const [name, hosts] of Object.entries(projects as Record<string, unknown>)) {
+    if (hosts === null || typeof hosts !== 'object' || Array.isArray(hosts)) {
+      addItem(
+        section,
+        `${red(failGlyph)} path-map.json invalid schema: project "${name}" hosts must be an object`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    for (const [hostName, mappedPath] of Object.entries(hosts as Record<string, unknown>)) {
+      if (typeof mappedPath !== 'string') {
+        addItem(
+          section,
+          `${red(failGlyph)} path-map.json invalid schema: project "${name}" host "${hostName}" path must be a string`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+  reportMappedProjects(section, map);
+  reportPathCollisions(section, map);
+}
+
+/** Pushes the comma-joined NEVER_SYNC set for informational visibility. */
+export function reportNeverSync(section: DoctorSection): void {
+  addItem(section, `${dim(infoGlyph)} never-sync items: ${[...NEVER_SYNC].join(', ')}`);
+}