claude-nomad 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.24.0](https://github.com/funkadelic/claude-nomad/compare/v0.23.0...v0.24.0) (2026-05-24)
+
+
+### Added
+
+* **doctor:** add --check-shared preflight gitleaks scan ([#117](https://github.com/funkadelic/claude-nomad/issues/117)) ([0089d09](https://github.com/funkadelic/claude-nomad/commit/0089d09ef91ff7b6778b065bcfe8be97f4c54d1b))
+
+
+### Documentation
+
+* **readme:** document nomad doctor --check-shared preflight ([#119](https://github.com/funkadelic/claude-nomad/issues/119)) ([d08ed91](https://github.com/funkadelic/claude-nomad/commit/d08ed91bbfd4c976f56c510b086e375c4595e682))
+
 ## [0.23.0](https://github.com/funkadelic/claude-nomad/compare/v0.22.3...v0.23.0) (2026-05-23)
 
 

package/README.md

@@ -287,10 +287,11 @@ nomad init --keep-actions
 Edit `path-map.json` to add your logical projects (see [Path remapping](#path-remapping)), then:
 
 ```bash
-nomad doctor     # read-only state check; reports host, repo state, every check as ✓ (pass) / ✗ (fail) / ⚠︎ (warn)
-nomad diff       # preview what nomad pull would change on this host; no lock, no network, no mutation
-nomad push       # send current state to the private remote
-nomad pull       # apply on another host (or this one after a remote update)
+nomad doctor                # read-only state check; reports host, repo state, every check as ✓ (pass) / ✗ (fail) / ⚠︎ (warn)
+nomad doctor --check-shared # read-only gitleaks preflight over the session transcripts a push would stage
+nomad diff                  # preview what nomad pull would change on this host; no lock, no network, no mutation
+nomad push                  # send current state to the private remote
+nomad pull                  # apply on another host (or this one after a remote update)
 ```
 
 `nomad pull --dry-run` is the network-aware twin of `nomad diff`: it acquires the lock and runs `git pull` so you see what the next real pull would do given the latest remote, then exits without mutating.
@@ -358,21 +359,22 @@ If you installed an earlier version via `./install.sh` and a shell alias (the pr
 
 ## Commands
 
-| Command                          | Description                                                                                                                                                                                                             |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nomad init`                     | Scaffold empty `shared/`, `hosts/`, `path-map.json` on a fresh clone. Refuses to clobber existing scaffold. Auto-disables Actions on a detected private GitHub mirror (see [Privacy by default](#privacy-by-default)).  |
-| `nomad init --snapshot`          | Overlay current host's `~/.claude/` into `shared/` and write `~/.claude/settings.json` verbatim into `hosts/<NOMAD_HOST>.json`. Originals not modified. Same auto-disable behavior as `nomad init`.                     |
-| `nomad init --keep-actions`      | Skip the auto-disable. Combinable with `--snapshot`. Use when an upstream org policy already governs Actions, or you intentionally want CI on the private mirror.                                                       |
-| `nomad pull`                     | `git pull --rebase --autostash`, apply symlinks, regenerate `settings.json`, remap session paths, and pull opted-in per-project extras. FATAL if scaffold missing.                                                      |
-| `nomad pull --dry-run`           | Network-aware preview: acquire lock + `git pull --rebase`, print planned changes (symlink moves, `settings.json` diff, transcript overwrites), exit without writing.                                                    |
-| `nomad diff`                     | Offline, lockless twin of `pull --dry-run`. No network, no lock. Works against the current local repo state.                                                                                                            |
-| `nomad push`                     | Export local sessions and opted-in per-project extras to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                 |
-| `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list); skip stage, scan, commit, and push.                                                                                       |
-| `nomad drop-session <id>`        | Surgically unstage every `shared/projects/*/<id>.jsonl` from the staged tree of `~/claude-nomad/`. Idempotent; the local `~/.claude/projects/<encoded>/<id>.jsonl` is preserved. See [Recovery flows](#recovery-flows). |
-| `nomad update`                   | Topology-aware upgrade to the latest upstream. Flags: `--dry-run`, `--force`, `--push-origin`. See [Upgrading the tool](#upgrading-the-tool).                                                                           |
-| `nomad doctor`                   | Read-only health check. Each line carries a status glyph (`✓` pass, `✗` fail, `⚠︎` warn); any `✗` sets `process.exitCode = 1` (`⚠︎` does not). Includes an offline-tolerant release-version staleness check.              |
-| `nomad doctor --resume-cmd <id>` | Print a host-local `cd ... && claude --resume <id>` line for a session (see [Cross-OS resume](#cross-os-resume)).                                                                                                       |
-| `nomad --version`                | Print the installed CLI version as bare semver to stdout; exits 0. Used by the npm-publish smoke test and useful for ad-hoc upgrade checks.                                                                             |
+| Command                          | Description                                                                                                                                                                                                                                                                                                                                              |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nomad init`                     | Scaffold empty `shared/`, `hosts/`, `path-map.json` on a fresh clone. Refuses to clobber existing scaffold. Auto-disables Actions on a detected private GitHub mirror (see [Privacy by default](#privacy-by-default)).                                                                                                                                   |
+| `nomad init --snapshot`          | Overlay current host's `~/.claude/` into `shared/` and write `~/.claude/settings.json` verbatim into `hosts/<NOMAD_HOST>.json`. Originals not modified. Same auto-disable behavior as `nomad init`.                                                                                                                                                      |
+| `nomad init --keep-actions`      | Skip the auto-disable. Combinable with `--snapshot`. Use when an upstream org policy already governs Actions, or you intentionally want CI on the private mirror.                                                                                                                                                                                        |
+| `nomad pull`                     | `git pull --rebase --autostash`, apply symlinks, regenerate `settings.json`, remap session paths, and pull opted-in per-project extras. FATAL if scaffold missing.                                                                                                                                                                                       |
+| `nomad pull --dry-run`           | Network-aware preview: acquire lock + `git pull --rebase`, print planned changes (symlink moves, `settings.json` diff, transcript overwrites), exit without writing.                                                                                                                                                                                     |
+| `nomad diff`                     | Offline, lockless twin of `pull --dry-run`. No network, no lock. Works against the current local repo state.                                                                                                                                                                                                                                             |
+| `nomad push`                     | Export local sessions and opted-in per-project extras to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                                                                                                                                                  |
+| `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list); skip stage, scan, commit, and push.                                                                                                                                                                                                                        |
+| `nomad drop-session <id>`        | Surgically unstage every `shared/projects/*/<id>.jsonl` from the staged tree of `~/claude-nomad/`. Idempotent; the local `~/.claude/projects/<encoded>/<id>.jsonl` is preserved. See [Recovery flows](#recovery-flows).                                                                                                                                  |
+| `nomad update`                   | Topology-aware upgrade to the latest upstream. Flags: `--dry-run`, `--force`, `--push-origin`. See [Upgrading the tool](#upgrading-the-tool).                                                                                                                                                                                                            |
+| `nomad doctor`                   | Read-only health check. Each line carries a status glyph (`✓` pass, `✗` fail, `⚠︎` warn); any `✗` sets `process.exitCode = 1` (`⚠︎` does not). Includes an offline-tolerant release-version staleness check.                                                                                                                                               |
+| `nomad doctor --resume-cmd <id>` | Print a host-local `cd ... && claude --resume <id>` line for a session (see [Cross-OS resume](#cross-os-resume)).                                                                                                                                                                                                                                        |
+| `nomad doctor --check-shared`    | Read-only gitleaks preflight: stages the session transcripts a `push` would publish into a temp tree and scans them, failing (`✗`, exit 1) per affected session with rotate-and-scrub guidance. Skips with a `⚠︎` when gitleaks is not on PATH. See [Recovery flow: gitleaks FATAL on a session JSONL](#recovery-flow-gitleaks-fatal-on-a-session-jsonl). |
+| `nomad --version`                | Print the installed CLI version as bare semver to stdout; exits 0. Used by the npm-publish smoke test and useful for ad-hoc upgrade checks.                                                                                                                                                                                                              |
 
 The version-check emits ``⚠︎ version: <local> -> <latest> (run `nomad update`)`` when the local install is behind the latest upstream release, and `✓ version: <local> (latest)` when current. It silently skips on network failures.
 
@@ -409,7 +411,7 @@ What it does NOT do: touch the local `~/.claude/projects/<encoded>/<id>.jsonl` f
 
 ### Recovery flow: gitleaks FATAL on a session JSONL
 
-`nomad push` runs `gitleaks protect --staged` before commit. When findings live in a session transcript, the FATAL names every affected session id and the recovery command:
+`nomad push` runs `gitleaks protect --staged` before commit. To catch the same findings before you push (and without mutating anything), run the read-only preflight `nomad doctor --check-shared`, which stages and scans the exact transcripts a push would publish. When findings live in a session transcript, the push FATAL names every affected session id and the recovery command:
 
 ```text
 ✗ gitleaks detected secrets in 1 session transcript(s).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "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.ts

@@ -0,0 +1,309 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+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 { 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';
+
+/**
+ * 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.
+ */
+type ScanTree = {
+  logicalToEncoded: Map<string, string>;
+  staged: number;
+  malformed: boolean;
+};
+
+/**
+ * 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
+ * `path-map.json` sets `malformed: true` rather than throwing.
+ */
+function buildScanTree(tmpRoot: string): ScanTree {
+  const logicalToEncoded = new Map<string, string>();
+  let staged = 0;
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  if (!existsSync(mapPath)) return { logicalToEncoded, staged, malformed: false };
+  let map: PathMap;
+  try {
+    map = readJson<PathMap>(mapPath);
+  } catch {
+    return { logicalToEncoded, staged, malformed: true };
+  }
+  if (typeof map.projects !== 'object' || map.projects === null) {
+    return { logicalToEncoded, staged, malformed: false };
+  }
+
+  const reverse = new Map<string, string>();
+  for (const [logical, hosts] of Object.entries(map.projects)) {
+    if (typeof hosts !== 'object' || hosts === null) continue;
+    const p = hosts[HOST];
+    if (!p || p === 'TBD') continue;
+    reverse.set(encodePath(p), logical);
+  }
+
+  const localProjects = join(CLAUDE_HOME, 'projects');
+  if (!existsSync(localProjects)) return { logicalToEncoded, staged, malformed: false };
+  for (const dir of readdirSync(localProjects)) {
+    const logical = reverse.get(dir);
+    if (!logical) continue;
+    copyDirJsonlOnly(join(localProjects, dir), join(tmpRoot, 'shared', 'projects', logical));
+    logicalToEncoded.set(logical, dir);
+    staged++;
+  }
+  return { logicalToEncoded, staged, malformed: false };
+}
+
+/**
+ * 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`.
+ */
+function probeGitleaksForScan(): 'ok' | 'missing' | { fail: string } {
+  try {
+    execFileSync('gitleaks', ['version'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    return 'ok';
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';
+    return { fail: (err as Error).message };
+  }
+}
+
+/**
+ * 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).
+ */
+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`);
+  }
+  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}`);
+  }
+  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`);
+}
+
+/**
+ * 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).
+ *
+ * `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.
+ */
+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;
+    }
+  }
+
+  const cacheDir = join(homedir(), '.cache', 'claude-nomad');
+  mkdirSync(cacheDir, { recursive: true });
+  // nowTimestamp() is second-resolution and --check-shared takes no lock
+  // (read-only), so two same-second, same-pid invocations would otherwise
+  // share a stamp and clobber each other's temp tree / report. The random
+  // suffix makes the stamp collision-resistant, matching the push report path.
+  const stamp = `${nowTimestamp()}-${process.pid}-${randomBytes(4).toString('hex')}`;
+  const reportPath = join(cacheDir, `check-shared-${stamp}.json`);
+  const tmpRoot = join(cacheDir, `check-shared-tree-${stamp}`);
+
+  try {
+    const { logicalToEncoded, staged, malformed } = buildScanTree(tmpRoot);
+    if (malformed) {
+      addItem(section, `${red(failGlyph)} path-map.json malformed JSON; shared scan skipped`);
+      process.exitCode = 1;
+      return;
+    }
+    if (staged === 0) {
+      // No path-map entry maps to this host (or all are TBD). Nothing would be
+      // staged by push either, so report clean without invoking gitleaks (a
+      // scan of a non-existent dir would exit non-zero and misfire).
+      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);
+      }
+    }
+  } finally {
+    rmSync(reportPath, { force: true });
+    rmSync(tmpRoot, { recursive: true, force: true });
+  }
+}

package/src/commands.doctor.checks.ts

@@ -272,13 +272,19 @@ export function reportNeverSync(section: DoctorSection): void {
   addItem(section, `${dim(infoGlyph)} never-sync items: ${[...NEVER_SYNC].join(', ')}`);
 }
 
-/** Probes for gitleaks on PATH; emits okGlyph with version, or failGlyph with ENOENT vs other-error distinction (sets exitCode=1). */
-export function reportGitleaksProbe(section: DoctorSection): void {
+/**
+ * Probes for gitleaks on PATH; emits okGlyph with version, or failGlyph with
+ * ENOENT vs other-error distinction (sets exitCode=1). Returns `true` when a
+ * usable binary was found so the caller can skip a redundant second `version`
+ * probe (e.g. the `--check-shared` Shared scan section).
+ */
+export function reportGitleaksProbe(section: DoctorSection): boolean {
   try {
     const v = execFileSync('gitleaks', ['version'], { stdio: ['ignore', 'pipe', 'pipe'] })
       .toString()
       .trim();
     addItem(section, `${green(okGlyph)} gitleaks: ${dim(v)}`);
+    return true;
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
       addItem(section, `${red(failGlyph)} gitleaks: not on PATH (required for nomad push)`);
@@ -286,6 +292,7 @@ export function reportGitleaksProbe(section: DoctorSection): void {
       addItem(section, `${red(failGlyph)} gitleaks: probe failed: ${(err as Error).message}`);
     }
     process.exitCode = 1;
+    return false;
   }
 }
 

package/src/commands.doctor.ts

@@ -12,6 +12,7 @@ import {
   reportRepoState,
   reportSharedLinks,
 } from './commands.doctor.checks.ts';
+import { reportCheckShared } from './commands.doctor.check-shared.ts';
 import { reportNodeEngineCheck } from './commands.doctor.engine.ts';
 import { renderDoctor, section } from './commands.doctor.format.ts';
 import { reportVersionCheck } from './commands.doctor.version.ts';
@@ -24,8 +25,13 @@ import { reportVersionCheck } from './commands.doctor.version.ts';
  * inside the individual reporters, so a piped
  * `nomad doctor 2>/dev/null` still exposes failures to scripts. Differs from
  * `cmdPull` / `cmdPush` / `resumeCmd`, where FATAL is on stderr.
+ *
+ * `opts.checkShared` (the `--check-shared` sub-flag) appends a "Shared scan"
+ * section that runs the gitleaks preflight over the session transcripts a
+ * `nomad push` would stage. It is OFF by default so plain `nomad doctor`
+ * stays the fast read-only smoke test (no scan, no temp tree).
  */
-export function cmdDoctor(): void {
+export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
   const host = section('Host');
   reportHostAndPaths(host);
   reportRepoState(host);
@@ -45,7 +51,7 @@ export function cmdDoctor(): void {
   reportNeverSync(neverSync);
 
   const repository = section('Repository');
-  reportGitleaksProbe(repository);
+  const gitleaksReady = reportGitleaksProbe(repository);
   reportGitlinks(repository);
   reportRemote(repository);
   reportRebaseClean(repository);
@@ -54,5 +60,11 @@ export function cmdDoctor(): void {
   reportVersionCheck(version);
   reportNodeEngineCheck(version);
 
-  renderDoctor([version, host, links, settings, pathMap, neverSync, repository]);
+  const sharedScan = section('Shared scan');
+  // Pass the Repository-section probe result so gitleaks `version` is not
+  // invoked a second time on a --check-shared run; reportCheckShared still
+  // probes for itself when called standalone.
+  if (opts.checkShared === true) reportCheckShared(sharedScan, gitleaksReady);
+
+  renderDoctor([version, host, links, settings, pathMap, neverSync, repository, sharedScan]);
 }

package/src/nomad.ts

@@ -62,6 +62,8 @@ const DEFAULT_HELP = [
   '',
   '  doctor                  Read-only health check (symlinks, host file, path-map,',
   '                          gitleaks, gitlinks).',
+  '       --check-shared     Preflight gitleaks scan of the session transcripts a',
+  '                          `nomad push` would stage (a temp copy, never the live dir).',
   '       --resume-cmd <id>  Print `cd <abspath> && claude --resume <id>` for a session id',
   '                          from ~/.claude/projects/.',
   '',
@@ -188,17 +190,26 @@ try {
       break;
     }
     case 'doctor':
-      // Sub-flag: `doctor --resume-cmd <session-id>` dispatches to the
-      // read-only sidecar that prints `cd <abspath> && claude --resume <id>`.
-      if (process.argv[3] === '--resume-cmd') {
+      // Sub-flags: `doctor --resume-cmd <session-id>` dispatches to the
+      // read-only sidecar that prints `cd <abspath> && claude --resume <id>`;
+      // `doctor --check-shared` (no positional) appends the gitleaks preflight
+      // scan of the transcripts a push would stage. Bare `doctor` runs the
+      // plain read-only health check. Any other shape (unknown flag, extra
+      // positional, `--check-shared` with trailing args) is a usage error.
+      if (process.argv[3] === undefined) {
+        cmdDoctor();
+      } else if (process.argv[3] === '--check-shared' && process.argv.length === 4) {
+        cmdDoctor({ checkShared: true });
+      } else if (process.argv[3] === '--resume-cmd') {
         const id = process.argv[4];
-        if (typeof id !== 'string' || id.length === 0) {
+        if (process.argv.length !== 5 || typeof id !== 'string' || id.length === 0) {
           console.error('usage: nomad doctor --resume-cmd <session-id>');
           process.exit(1);
         }
         resumeCmd(id);
       } else {
-        cmdDoctor();
+        console.error('usage: nomad doctor [--check-shared | --resume-cmd <session-id>]');
+        process.exit(1);
       }
       break;
     case 'drop-session': {

package/src/push-gitleaks.ts

@@ -43,7 +43,7 @@ export type Finding = {
  * paths (e.g., `shared/projects/<logical>/subagents/<id>.jsonl`) fall
  * through to the non-session `other` bucket.
  */
-const SESSION_PATH = /^shared\/projects\/[^/]+\/([^/]+)\.jsonl$/;
+export const SESSION_PATH = /^shared\/projects\/[^/]+\/([^/]+)\.jsonl$/;
 
 /**
  * Legacy fallback FATAL emitted when no finding's File matches the session
@@ -129,7 +129,7 @@ export function buildSessionAwareFatal(
  * the failure path must NOT cascade into a parse-error stack trace; the
  * caller falls back to the legacy FATAL string in that case.
  */
-function readGitleaksReport(reportPath: string): Finding[] | null {
+export function readGitleaksReport(reportPath: string): Finding[] | null {
   try {
     const raw = readFileSync(reportPath, 'utf8');
     const parsed: unknown = JSON.parse(raw);

package/src/remap.ts

@@ -27,7 +27,7 @@ function copyDir(src: string, dst: string): void {
  * keeps the unfiltered copyDir because the repo side is already curated
  * by the push gate.
  */
-function copyDirJsonlOnly(src: string, dst: string): void {
+export function copyDirJsonlOnly(src: string, dst: string): void {
   rmSync(dst, { recursive: true, force: true });
   cpSync(src, dst, {
     recursive: true,