claude-nomad 0.26.2 → 0.28.0

package/src/commands.pull.ts

@@ -1,16 +1,57 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
+import {
+  buildExtrasSection,
+  buildSessionsSection,
+  buildSettingsSection,
+} from './commands.push.sections.ts';
 import { HOME, HOST, REPO_HOME } from './config.ts';
 import { divergenceCheckExtras, remapExtrasPull } from './extras-sync.ts';
 import { applySharedLinks, regenerateSettings } from './links.ts';
+import { renderTree, section, addItem } from './output-tree.ts';
 import { computePreview } from './preview.ts';
 import { remapPull } from './remap.ts';
-import { emitSummary } from './summary.ts';
+import { emitSummary, summaryRow } from './summary.ts';
 import { die, fail, gitOrFatal, log, NomadFatal } from './utils.ts';
 import { freshBackupTs } from './utils.fs.ts';
 import { acquireLock, releaseLock } from './utils.lockfile.ts';
 
+/**
+ * Run the WET (non-dry-run) pull side effects in order and render the
+ * doctor-style grouped tree once at the end: a `pull on host=... (backup=<ts>)`
+ * header followed by `Settings` / `Sessions` / `Extras` / `Summary` sections.
+ * `applySharedLinks` stays silent (no Links group by design);
+ * `regenerateSettings` returns its override-source label so the Settings row
+ * surfaces what was written without logging inline. Sessions/Extras reuse the
+ * verb-agnostic builders shared with `cmdPush`, fed the pull-side `pulled`
+ * detail arrays. The combined session + extras unmapped count and the
+ * extras-skipped count drive the Summary row exactly as `emitSummary` did.
+ *
+ * @param ts - backup timestamp namespace shared by every WET side effect.
+ */
+function applyWetPull(ts: string): void {
+  applySharedLinks(ts);
+  const { label } = regenerateSettings(ts);
+  const remapResult = remapPull(ts);
+  const extrasResult = remapExtrasPull(ts);
+  // Combine session-unmapped and extras-unmapped into one user-visible count;
+  // from the operator's perspective both mean "couldn't sync this for the
+  // host". extras-skipped (non-whitelisted dirname) stays separate because it
+  // signals config misuse, not a host-config gap.
+  const summary = section('Summary');
+  addItem(
+    summary,
+    summaryRow('pull', remapResult.unmapped + extrasResult.unmapped, 0, extrasResult.skipped),
+  );
+  renderTree([
+    buildSettingsSection(label),
+    buildSessionsSection(remapResult.pulled, remapResult.unmapped),
+    buildExtrasSection(extrasResult.pulled, extrasResult.skipped),
+    summary,
+  ]);
+}
+
 /**
  * `nomad pull` command. Acquires the push/pull lock, takes a backup
  * timestamp, runs `git pull --rebase --autostash` in `REPO_HOME`, then
@@ -23,6 +64,19 @@ import { acquireLock, releaseLock } from './utils.lockfile.ts';
  *   5. `remapExtrasPull` (copy `shared/extras/<logical>/<dirname>/` back
  *      into each project's localRoot; SKIPPED under dryRun)
  *
+ * WET output is a doctor-style grouped tree (`applyWetPull`): a `pull on
+ * host=... (backup=<ts>)` header, then `Settings` / `Sessions` / `Extras` /
+ * `Summary` sections rendered with `├`/`└` connectors. The Settings row shows
+ * `✓ settings.json (base + <label>)`; pulled sessions and extras list as `✓`
+ * rows; the per-project "not in path-map" skips collapse to one `ℹ︎` count
+ * row. There is no Links group (`applySharedLinks` stays silent by design).
+ *
+ * The WET-path Summary row (including the warn glyph case) renders to STDOUT as
+ * part of the grouped tree via `renderTree`, not to stderr via `warn` as in the
+ * pre-tree behavior. The dry-run path still routes its summary through
+ * `emitSummary` (stderr). This wet-stdout/dry-stderr stream split is
+ * intentional (the dry-run output is left byte-identical) and not a regression.
+ *
  * `opts.dryRun` (default `false`): when `true`, the lock IS still acquired
  * and `git pull --rebase` still runs (so concurrent invocations cannot race
  * and the user sees the same network round-trip as a real pull).
@@ -30,7 +84,10 @@ import { acquireLock, releaseLock } from './utils.lockfile.ts';
  * `computePreview` runs in place of the four mutating steps. The per-run
  * backup directory under `~/.cache/claude-nomad/backup/<ts>/` is
  * intentionally NOT created (no backups are written under dryRun and an
- * empty dir would pollute the cache).
+ * empty dir would pollute the cache). The dry-run path is BYTE-IDENTICAL:
+ * it keeps the `pulling on host=... (backup=...; dry-run)` header, the
+ * `computePreview` adjacent diff, its standalone `emitSummary`, and the
+ * `dry-run complete; no mutation` line; it does NOT build the tree.
  *
  * Any `NomadFatal` thrown along the way is caught here so the `finally` block
  * releases the lock before exit (a raw `process.exit()` would skip `finally`
@@ -67,7 +124,14 @@ export function cmdPull(opts: { dryRun?: boolean } = {}): void {
         die(`could not create backup dir: ${(err as Error).message}`);
       }
     }
-    log(`pulling on host=${HOST} (backup=${ts}${dryRun ? '; dry-run' : ''})`);
+    // WET header becomes the tree header (no `pulling`/`ℹ︎` prefix). The
+    // dry-run header phrasing is LEFT byte-identical so the readable diff path
+    // does not regress.
+    log(
+      dryRun
+        ? `pulling on host=${HOST} (backup=${ts}; dry-run)`
+        : `pull on host=${HOST} (backup=${ts})`,
+    );
     gitOrFatal(['pull', '--rebase', '--autostash'], 'git pull --rebase', REPO_HOME);
     // Read-only pre-pull check: fires in BOTH wet and dry modes (D-08).
     // Runs AFTER the rebase (so origin content is fetched) and BEFORE any
@@ -78,19 +142,11 @@ export function cmdPull(opts: { dryRun?: boolean } = {}): void {
       const previewResult = computePreview(ts);
       // dryRun deliberately omits remapExtrasPull to preserve the
       // zero-mutation contract; users still see the divergence WARN above.
+      // BYTE-IDENTICAL dry-run output: standalone emitSummary, no tree.
       log('dry-run complete; no mutation');
       emitSummary('pull', previewResult.unmapped);
     } else {
-      applySharedLinks(ts);
-      regenerateSettings(ts);
-      const remapResult = remapPull(ts);
-      const extrasResult = remapExtrasPull(ts);
-      log('pull complete');
-      // Combine session-unmapped and extras-unmapped into one user-visible
-      // count; from the operator's perspective both mean "couldn't sync this
-      // for the host". extras-skipped (non-whitelisted dirname) stays
-      // separate because it signals config misuse, not a host-config gap.
-      emitSummary('pull', remapResult.unmapped + extrasResult.unmapped, 0, extrasResult.skipped);
+      applyWetPull(ts);
     }
   } catch (err) {
     // Catch fatal errors here so the finally block runs and releases the

package/src/commands.push.sections.ts

@@ -0,0 +1,171 @@
+/**
+ * Pure section-builder helpers shared by `cmdPush` and `cmdPull` for the
+ * doctor-style grouped tree. The builders are verb-agnostic: they take the
+ * already-selected detail array (the wet `pushed`/`pulled` list or the dry-run
+ * `wouldPush`/`wouldPull` list) plus the relevant skip count, so the same code
+ * renders both push and pull rows. Row shapes mirror `nomad doctor`: one
+ * `${green(okGlyph)} <item>` row per synced item, then a single collapsed
+ * `${dim(infoGlyph)} <N> <noun>` count row instead of one row per skip.
+ *
+ * Sections returned here may be empty; `renderTree` (in `./output-tree.ts`)
+ * skips empty sections, so a Sessions/Extras group with zero items and a zero
+ * skip count never prints a header.
+ */
+
+import { dim, green, infoGlyph, okGlyph } from './color.ts';
+import type { remapExtrasPush } from './extras-sync.ts';
+import { type DoctorSection, addItem, renderTree, section } from './output-tree.ts';
+import type { LeakVerdict } from './push-leak-verdict.ts';
+import type { remapPush } from './remap.ts';
+import { summaryRow } from './summary.ts';
+
+/**
+ * Build the single collapsed count row, or `null` when `n` is zero. Used for
+ * the "not in path-map" session skips and the "extras skipped" extras skips so
+ * the noisy per-project skip lines fold into one row that points at
+ * `nomad doctor` for the authoritative list.
+ *
+ * @param n - The skip count (no row is produced when `0`).
+ * @param noun - The collapsed-row phrasing after the count (e.g.
+ *   `'not in path-map (run nomad doctor to list)'` or `'extras skipped'`).
+ * @returns The rendered ℹ︎ count row, or `null` when `n` is `0`.
+ */
+export function collapsedSkipRow(n: number, noun: string): string | null {
+  if (n <= 0) return null;
+  return `${dim(infoGlyph)} ${n} ${noun}`;
+}
+
+/**
+ * Build the Settings section for `cmdPull`: a single
+ * `${green(okGlyph)} settings.json (base + <label>)` row. `label` is the
+ * override-source tag returned by `regenerateSettings` (`'<HOST>.json'` when a
+ * host override exists, else `'no host overrides'`), surfacing what was written
+ * without `regenerateSettings` logging the line inline. Push has no Settings
+ * section, so this helper is pull-only.
+ *
+ * @param label - The override-source tag from `regenerateSettings`.
+ * @returns A `Settings` `DoctorSection` holding the one settings row.
+ */
+export function buildSettingsSection(label: string): DoctorSection {
+  const s = section('Settings');
+  addItem(s, `${green(okGlyph)} settings.json (base + ${label})`);
+  return s;
+}
+
+/**
+ * Build the Sessions section: one ✓ row per synced logical name plus, when
+ * `unmapped > 0`, a single collapsed `${unmapped} not in path-map` count row.
+ * Verb-agnostic: pass `remapResult.pushed` (or `wouldPush`, or the pull-side
+ * `pulled`/`wouldPull`) as `items`.
+ *
+ * @param items - The logical names synced this run.
+ * @param unmapped - Count of path-map entries skipped for this host.
+ * @returns A `Sessions` `DoctorSection` (possibly empty).
+ */
+export function buildSessionsSection(items: string[], unmapped: number): DoctorSection {
+  const s = section('Sessions');
+  for (const logical of items) addItem(s, `${green(okGlyph)} ${logical}`);
+  const skip = collapsedSkipRow(unmapped, 'not in path-map (run nomad doctor to list)');
+  if (skip !== null) addItem(s, skip);
+  return s;
+}
+
+/**
+ * Build the Extras section: one ✓ row per synced `<logical>/<dirname>` entry
+ * plus, when `extrasSkipped > 0`, a single collapsed `${extrasSkipped} extras
+ * skipped` count row. Verb-agnostic: pass the wet or dry detail array as
+ * `items`.
+ *
+ * @param items - The `<logical>/<dirname>` entries synced this run.
+ * @param extrasSkipped - Count of dirnames the whitelist declined to sync.
+ * @returns An `Extras` `DoctorSection` (possibly empty).
+ */
+export function buildExtrasSection(items: string[], extrasSkipped: number): DoctorSection {
+  const s = section('Extras');
+  for (const entry of items) addItem(s, `${green(okGlyph)} ${entry}`);
+  const skip = collapsedSkipRow(extrasSkipped, 'extras skipped');
+  if (skip !== null) addItem(s, skip);
+  return s;
+}
+
+/**
+ * Collected per-run push state threaded through `cmdPush` so the grouped tree
+ * can be assembled once at the end. `remap`/`extras` carry the detail arrays +
+ * counts; `dryRun` selects the wet (`pushed`) vs would-* (`wouldPush`) arrays.
+ */
+export type PushState = {
+  dryRun: boolean;
+  remap: ReturnType<typeof remapPush>;
+  extras: ReturnType<typeof remapExtrasPush>;
+};
+
+/**
+ * Assemble the Sessions/Extras sections shared by the real and dry-run push
+ * paths, selecting the wet `pushed` detail arrays or the `wouldPush` arrays
+ * under `dryRun`. The Leak scan and Summary sections are appended by the caller
+ * in path-specific order.
+ *
+ * @param st - The collected push state.
+ * @returns The ordered `[Sessions, Extras]` sections (either may be empty).
+ */
+function syncedSections(st: PushState): DoctorSection[] {
+  const sessions = st.dryRun ? st.remap.wouldPush : st.remap.pushed;
+  const extras = st.dryRun ? st.extras.wouldPush : st.extras.pushed;
+  return [
+    buildSessionsSection(sessions, st.remap.unmapped),
+    buildExtrasSection(extras, st.extras.skipped),
+  ];
+}
+
+/**
+ * Build the single-row Summary section from the combined unmapped count
+ * (sessions + extras), the collision count, and the extras-skipped count.
+ * Phrasing is delegated to `summaryRow` so it matches `emitSummary` exactly.
+ *
+ * @param st - The collected push state.
+ * @returns A `Summary` `DoctorSection` holding the one summary row.
+ */
+function summarySection(st: PushState): DoctorSection {
+  const s = section('Summary');
+  const unmapped = st.remap.unmapped + st.extras.unmapped;
+  addItem(s, summaryRow('push', unmapped, st.remap.collisions, st.extras.skipped));
+  return s;
+}
+
+/**
+ * Render the grouped push tree with a Leak scan section (carrying `verdict`'s
+ * row) between Extras and Summary. The caller throws the recovery body as a
+ * `NomadFatal` AFTER this returns (real-push leak) or prints it via `fail`
+ * (dry-run) so the recovery block follows the tree.
+ *
+ * @param st - The collected push state.
+ * @param verdict - The leak verdict for the Leak scan section.
+ */
+export function renderPushTree(st: PushState, verdict: LeakVerdict): void {
+  const leakScan = section('Leak scan');
+  addItem(leakScan, verdict.verdictRow);
+  renderTree([...syncedSections(st), leakScan, summarySection(st)]);
+}
+
+/**
+ * Render the no-Leak-scan push tree: the Sessions/Extras rows (if any) plus the
+ * Summary row. `renderTree` skips empty sections, so an empty push prints only
+ * the Summary. Two callers: the real-push nothing-to-commit early return
+ * (`noMapHint` omitted) and the dry-run no-`path-map.json` case
+ * (`noMapHint: true`), which prepends a `Path map` section carrying a single
+ * `${dim(infoGlyph)} no path-map.json (nothing to preview)` row so a dry-run
+ * user sees WHY no Leak scan section rendered (no map means nothing to stage).
+ *
+ * @param st - The collected push state.
+ * @param opts.noMapHint - When `true`, prepend the no-path-map hint section.
+ * @returns Nothing; renders to stdout.
+ */
+export function renderNoScanTree(st: PushState, opts: { noMapHint?: boolean } = {}): void {
+  const sections: DoctorSection[] = [];
+  if (opts.noMapHint === true) {
+    const pathMap = section('Path map');
+    addItem(pathMap, `${dim(infoGlyph)} no path-map.json (nothing to preview)`);
+    sections.push(pathMap);
+  }
+  renderTree([...sections, ...syncedSections(st), summarySection(st)]);
+}

package/src/commands.push.ts

@@ -1,18 +1,93 @@
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 
-import { HOME, HOST, REPO_HOME } from './config.ts';
+import { HOME, HOST, type PathMap, REPO_HOME } from './config.ts';
 import { enforceAllowList } from './commands.push.allowlist.ts';
+import { type PushState, renderNoScanTree, renderPushTree } from './commands.push.sections.ts';
 import { remapExtrasPush } from './extras-sync.ts';
+import { scanPushVerdict } from './push-leak-verdict.ts';
 import { findGitlinks, probeGitleaks, rebaseBeforePush } from './push-checks.ts';
-import { runGitleaksScan } from './push-gitleaks.ts';
+import { previewPushLeaks } from './push-preview.ts';
 import { remapPush } from './remap.ts';
-import { emitSummary } from './summary.ts';
 import { die, fail, gitOrFatal, gitStatusPorcelainZ, log, NomadFatal } from './utils.ts';
 import { freshBackupTs } from './utils.fs.ts';
 import { readPathMap } from './utils.json.ts';
 import { acquireLock, releaseLock } from './utils.lockfile.ts';
 
+/**
+ * Walk `shared/` for nested `.git` entries copied in from a host's encoded
+ * session dir. A gitlink would otherwise push as a submodule via the
+ * `shared/projects/<logical>/` prefix. Emits a per-hit FATAL line on stderr and
+ * throws a summarizing `NomadFatal` (caught by `cmdPush` so the lock releases).
+ * Runs AFTER `remapPush` so it inspects the post-copy tree.
+ */
+function guardGitlinks(): void {
+  const gitlinks = findGitlinks(join(REPO_HOME, 'shared'));
+  if (gitlinks.length === 0) return;
+  for (const p of gitlinks) {
+    const rel = relative(REPO_HOME, p);
+    fail(`gitlink: ${rel} would push as submodule (run: rm -rf ${rel} or remove the nested repo)`);
+  }
+  const noun = gitlinks.length === 1 ? 'entry' : 'entries';
+  throw new NomadFatal(
+    `gitlink trap: ${gitlinks.length} nested .git ${noun} in shared/; remove before retry`,
+  );
+}
+
+/**
+ * The staged-tree leak gate + commit/push for the REAL push path. Runs
+ * `scanPushVerdict` AFTER `git add -A` (sees what would push) but BEFORE commit
+ * (a detection unwinds cleanly with no commit to revert). On a leak it renders
+ * the tree (with the ✗ Leak scan row + Summary) so the tree precedes the
+ * recovery block, then throws the recovery body as a `NomadFatal` (the catch
+ * prints it and sets a non-zero exit). On a clean scan it commits, pushes, and
+ * renders the tree with the `✓ no leaks` row.
+ *
+ * @param st - The collected push state for the final tree render.
+ */
+function commitAndPush(st: PushState): void {
+  // gitOrFatal uses execFileSync (no shell) so NOMAD_HOST cannot escape quoting.
+  gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
+  const verdict = scanPushVerdict();
+  if (verdict.leak) {
+    renderPushTree(st, verdict);
+    // Every `leak: true` branch of scanPushVerdict sets a non-null recovery
+    // body, so the `?? fallback` is defensively unreachable (excluded from
+    // coverage rather than contorting a test to fake an impossible state).
+    /* c8 ignore next */
+    throw new NomadFatal(verdict.recovery ?? 'gitleaks detected secrets');
+  }
+  gitOrFatal(['commit', '-m', `chore: sync from ${HOST}`], 'git commit', REPO_HOME);
+  gitOrFatal(['push'], 'git push', REPO_HOME);
+  renderPushTree(st, verdict);
+}
+
+/**
+ * Render the dry-run leak-scan tree. With `map === null` (a dry-run with no
+ * `path-map.json`) there is nothing to stage, so it renders the no-scan tree
+ * with the `noMapHint` row and returns. Otherwise it runs `previewPushLeaks`
+ * (which stages its OWN temp
+ * tree from the map, independent of `REPO_HOME` status, and sets
+ * `process.exitCode = 1` on findings), renders the push tree with the verdict
+ * row in the Leak scan section, and prints the recovery body BELOW the tree via
+ * `fail` (stderr) when one is present.
+ *
+ * Extracted from `cmdPush` so the command body and this helper each stay under
+ * the sonarjs cognitive-complexity threshold.
+ *
+ * @param st - The collected push state for the tree render.
+ * @param map - The parsed path-map, or `null` when a dry-run has no map.
+ */
+function runDryRunPreview(st: PushState, map: PathMap | null): void {
+  if (map === null) {
+    renderNoScanTree(st, { noMapHint: true });
+    return;
+  }
+  const verdict = previewPushLeaks(map);
+  renderPushTree(st, verdict);
+  if (verdict.recovery !== null) fail(verdict.recovery);
+}
+
 /**
  * `nomad push` command. Acquires the lock, runs the four pre-push safety
  * checks in the order from CONTEXT.md, stages, and pushes:
@@ -26,20 +101,48 @@ import { acquireLock, releaseLock } from './utils.lockfile.ts';
  *   5. `findGitlinks` walk of `shared/` (refuse to push nested .git entries)
  *   6. allow-list enforcement on the resulting `git status` (runtime
  *      `shared/extras/<logical>/` prefix per declared logical added)
- *   7. `git add -A` -> `runGitleaksScan` on staged tree -> `git commit` -> `git push`
+ *   7. `git add -A` -> `scanPushVerdict` on staged tree -> `git commit` -> `git push`
+ *
+ * Output is a doctor-style grouped tree: a `push on host=...` header, then
+ * `Sessions` / `Extras` / `Leak scan` / `Summary` sections rendered with
+ * `├`/`└` connectors. Pushed sessions and extras list as `✓` rows; the
+ * per-project "not in path-map" skips collapse to one `ℹ︎` count row. The Leak
+ * scan section shows `✓ no leaks` on a clean scan; on a leak it shows a `✗`
+ * one-line verdict row and the full `buildSessionAwareFatal` recovery block
+ * still prints BELOW the rendered tree.
+ *
+ * The WET-path Summary row (including the warn `⚠︎` case) renders to STDOUT as
+ * part of the grouped tree via `renderTree`, not to stderr via `warn` as in the
+ * pre-tree behavior. The dry-run preview likewise renders via `renderTree`
+ * (push has no dry-run `emitSummary` path; `cmdPull`'s dry-run does, see its
+ * JSDoc for the intentional wet-stdout/dry-pull-stderr stream split).
  *
  * The gitleaks scan runs AFTER staging so it sees what would actually be
  * pushed, but BEFORE commit so a detection unwinds cleanly without leaving a
  * commit to amend or revert. Any `NomadFatal` is caught here so `finally`
- * releases the lock.
+ * releases the lock; a real-push leak re-raises the recovery body as a
+ * `NomadFatal` AFTER the tree renders so the recovery block follows the tree.
  *
  * `opts.dryRun` (default `false`): when `true`, the network round-trip
  * (`rebaseBeforePush`) still runs so users see what a real push would see,
- * but `remapPush` runs with `dryRun: true` (no session copies into shared/),
- * and the `git add` / `runGitleaksScan` / `git commit` / `git push` quartet
- * is skipped. The allow-list check still classifies the existing `git
- * status` so a pre-existing violation surfaces before the user thinks
- * everything is fine. Mirrors `cmdPull`'s `dryRun` contract.
+ * and `remapPush` / `remapExtrasPush` run with `dryRun: true` (no copies
+ * into `shared/`). The `git add` / `git commit` / `git push` steps are
+ * skipped. Instead, `previewPushLeaks` runs a READ-ONLY gitleaks leak
+ * preview against a temp copy of the would-be-staged sessions AND extras
+ * (no `REPO_HOME/shared` mutation), returning a structured verdict whose
+ * `verdictRow` lands in the Leak scan section and whose `recovery` (if any)
+ * prints below the tree; `process.exitCode = 1` is set on findings.
+ *
+ * The dry-run preview runs REGARDLESS of `REPO_HOME` `git status`: in dry-run
+ * nothing is copied into `shared/`, so an empty status is the normal case for
+ * the headline target (a clean repo with new mapped sessions). `previewPushLeaks`
+ * stages its own temp tree from the path-map, so the empty-status
+ * `'nothing to commit'` early return is REAL-PUSH-ONLY. A dry-run with NO
+ * path-map renders the no-scan tree and returns without dying (a real push with
+ * a non-empty status and no map still dies on the allow-list check). The
+ * allow-list still classifies a non-empty `git status` (dry or wet) so a
+ * pre-existing violation surfaces; an empty status has nothing to classify.
+ * Mirrors `cmdPull`'s `dryRun` contract.
  */
 export function cmdPush(opts: { dryRun?: boolean } = {}): void {
   const dryRun = opts.dryRun === true;
@@ -47,7 +150,7 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
   const handle = acquireLock('push');
   if (handle === null) process.exit(0);
   try {
-    log(dryRun ? `pushing on host=${HOST} (dry-run)` : `pushing on host=${HOST}`);
+    console.log(dryRun ? `push on host=${HOST} (dry-run)` : `push on host=${HOST}`);
     // Probe at top of flow: fail fast if gitleaks is missing, before any mutation.
     probeGitleaks();
     // Rebase BEFORE any local mutation: surfaces remote conflicts against the
@@ -59,29 +162,14 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     const ts = freshBackupTs(backupBase);
     // remapPush runs BEFORE the empty-status check: it produces the diffs status
     // observes, so swapping the order would short-circuit before anything is staged.
-    const remapResult = remapPush(ts, { dryRun });
+    const remap = remapPush(ts, { dryRun });
     // remapExtrasPush lands between remapPush and findGitlinks so the
     // produced `shared/extras/<logical>/<dirname>/` paths are visible to
     // both the gitlink walk and the downstream allow-list classification.
     // dryRun is forwarded so a preview push reports the same skipped count.
-    const extrasResult = remapExtrasPush(ts, { dryRun });
-    // Gitlink walk of shared/ AFTER remapPush so it inspects the post-copy tree.
-    // A nested .git copied in from a host's encoded session dir would slip past a
-    // pre-remap scan and reach the remote via the shared/projects/<logical>/ prefix.
-    // Per-hit FATAL on stderr plus a summarizing throw, mirroring enforceAllowList.
-    const sharedDir = join(REPO_HOME, 'shared');
-    const gitlinks = findGitlinks(sharedDir);
-    if (gitlinks.length > 0) {
-      for (const p of gitlinks) {
-        const rel = relative(REPO_HOME, p);
-        fail(
-          `gitlink: ${rel} would push as submodule (run: rm -rf ${rel} or remove the nested repo)`,
-        );
-      }
-      throw new NomadFatal(
-        `gitlink trap: ${gitlinks.length} nested .git ${gitlinks.length === 1 ? 'entry' : 'entries'} in shared/; remove before retry`,
-      );
-    }
+    const extras = remapExtrasPush(ts, { dryRun });
+    const st: PushState = { dryRun, remap, extras };
+    guardGitlinks();
     // Routed through the shell-free, untrimmed helper because `sh` would .trim()
     // the leading status-space and shift parsePorcelainZ's offsets.
     // `untrackedAll` (issue #111): the allow-list runs on this snapshot BEFORE
@@ -91,53 +179,30 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     // match, so the first extras push is rejected. Expanding to per-file paths
     // lets the existing allow-list accept them while keeping the gate order.
     const status = gitStatusPorcelainZ(REPO_HOME, { untrackedAll: true });
-    if (!status) {
+    // REAL-PUSH-ONLY early return: a dry-run copies nothing into shared/, so an
+    // empty status is the normal headline case (clean repo, new mapped
+    // sessions) and must still reach the dry-run preview below.
+    if (!dryRun && !status) {
       log('nothing to commit');
-      // Combine session-unmapped and extras-unmapped into one user-visible
-      // count; both mean "couldn't sync this for the host". extras-skipped
-      // (non-whitelisted dirname) stays separate because it signals config
-      // misuse, not a host-config gap.
-      emitSummary(
-        'push',
-        remapResult.unmapped + extrasResult.unmapped,
-        remapResult.collisions,
-        extrasResult.skipped,
-      );
+      renderNoScanTree(st);
       return;
     }
     const mapPath = join(REPO_HOME, 'path-map.json');
-    if (!existsSync(mapPath)) die('path-map.json missing, cannot enforce push allow-list');
+    // A dry-run with no map cannot enforce nor scan: render the no-scan tree and
+    // return without dying. A real push with a non-empty status still dies.
+    if (!existsSync(mapPath)) {
+      if (dryRun) return runDryRunPreview(st, null);
+      die('path-map.json missing, cannot enforce push allow-list');
+    }
     // readPathMap routes parse failures through NomadFatal so finally releases the lock.
     const map = readPathMap(mapPath);
-    enforceAllowList(status, map);
-    if (dryRun) {
-      // Skip the staging quartet so no commit lands and nothing is pushed.
-      // The user has already seen probeGitleaks pass, the rebase result, the
-      // remap preview, the gitlink scan, and the allow-list classification.
-      log('push: dry-run; skipping git add, gitleaks scan, commit, and push');
-      emitSummary(
-        'push',
-        remapResult.unmapped + extrasResult.unmapped,
-        remapResult.collisions,
-        extrasResult.skipped,
-      );
-      return;
-    }
-    // gitOrFatal uses execFileSync (no shell) so NOMAD_HOST cannot escape quoting.
-    gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
-    // Gitleaks scan AFTER staging (sees what would push), BEFORE commit (no cleanup
-    // needed on detection). The empty-status early return above guarantees the
-    // index is non-empty here.
-    runGitleaksScan();
-    gitOrFatal(['commit', '-m', `chore: sync from ${HOST}`], 'git commit', REPO_HOME);
-    gitOrFatal(['push'], 'git push', REPO_HOME);
-    log('push complete');
-    emitSummary(
-      'push',
-      remapResult.unmapped + extrasResult.unmapped,
-      remapResult.collisions,
-      extrasResult.skipped,
-    );
+    // Classify only a non-empty status; an empty status (dry-run on a clean
+    // repo) has nothing to gate.
+    if (status) enforceAllowList(status, map);
+    // dryRun skips git add / commit / push: run the read-only leak preview,
+    // which prints any recovery below the rendered tree.
+    if (dryRun) return runDryRunPreview(st, map);
+    commitAndPush(st);
   } catch (err) {
     if (err instanceof NomadFatal) {
       fail(err.message);

package/src/config.ts

@@ -36,6 +36,14 @@ export const REPO_HOME = process.env.NOMAD_REPO || resolve(HOME, 'claude-nomad')
  */
 export const UPSTREAM_REPO_SLUG = 'funkadelic/claude-nomad';
 
+/**
+ * The official Claude Code settings JSON schema. Source of truth for
+ * `SCHEMA_KEYS` (kept current by `scripts/sync-settings-keys.ts`) and the
+ * on-demand `nomad doctor --check-schema` reporter, which fetches it live to
+ * flag local `settings.json` keys absent from the published schema.
+ */
+export const SETTINGS_SCHEMA_URL = 'https://json.schemastore.org/claude-code-settings.json';
+
 /**
  * Pinned gitleaks version. Single source of truth for the gitleaks pin used by
  * `nomad doctor`'s version-drift check (`reportGitleaksVersionCheck`), which
@@ -103,48 +111,11 @@ export const NEVER_SYNC = new Set([
   'ide',
 ]);
 
-/**
- * Schema-drift baseline for `~/.claude/settings.json`. Top-level keys not in
- * this set trigger a `nomad doctor` WARN line so we notice when Anthropic
- * adds new settings before they silently round-trip through pull. Update on
- * Anthropic settings.json schema changes.
- */
-export const KNOWN_SETTINGS_KEYS = new Set<string>([
-  '$schema',
-  'agent',
-  'agents',
-  'agentPushNotifEnabled',
-  'allowedHttpHookUrls',
-  'apiKeyHelper',
-  'apiKeyHelperTimeoutMs',
-  'awsAuthRefresh',
-  'awsCredentialExport',
-  'awsLoginRefresh',
-  'awsRegion',
-  'awsRetryMode',
-  'cleanupPeriodDays',
-  'disableNonEssentialModelCalls',
-  'enabledExperimentalFeatures',
-  'enabledPlugins',
-  'env',
-  'forceLoginMethod',
-  'forceLoginOrgUUID',
-  'hooks',
-  'includeCoAuthoredBy',
-  'installMethod',
-  'model',
-  'outputStyle',
-  'permissions',
-  'pluginGroups',
-  'pluginRepositoryEnabled',
-  'pluginsLocalConfig',
-  'proxy',
-  'skipAutoPermissionPrompt',
-  'statsig',
-  'statusLine',
-  'subagents',
-  'theme',
-]);
+// Schema-drift baseline for `~/.claude/settings.json`; top-level keys not in
+// this set trigger a `nomad doctor` WARN. Defined in ./settings-keys.ts so the
+// schema-derived half can be re-synced mechanically; re-exported here so
+// existing `from './config.ts'` imports keep resolving.
+export { KNOWN_SETTINGS_KEYS } from './settings-keys.ts';
 
 /**
  * Static half of the push allow-list. Entries with trailing `/` are prefix