claude-nomad 0.26.2 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.27.0](https://github.com/funkadelic/claude-nomad/compare/v0.26.2...v0.27.0) (2026-05-28)
+
+
+### Added
+
+* **output:** grouped tree output for push/pull and dry-run leak preview ([#163](https://github.com/funkadelic/claude-nomad/issues/163)) ([fff6f1e](https://github.com/funkadelic/claude-nomad/commit/fff6f1e28116b072ee4eceda36d87c13f4c1bc1c))
+
 ## [0.26.2](https://github.com/funkadelic/claude-nomad/compare/v0.26.1...v0.26.2) (2026-05-28)
 
 

package/README.md

@@ -525,7 +525,7 @@ point under your npm prefix's `bin/`), then delete the alias line from your shel
 | `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 push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list) and a read-only gitleaks leak preview over a throwaway temp copy of the sessions and extras this host would stage; skip stage, commit, and push. Exits 1 if a leak is found in the preview. Nothing is written to the sync repo.                            |
 | `nomad drop-session <id>`        | Surgically unstage every `shared/projects/*/<id>.jsonl` and the sibling `shared/projects/*/<id>/` subagent directory from the staged tree of `~/claude-nomad/`. Idempotent; the local `~/.claude/projects/<encoded>/<id>.jsonl` and `<id>/` tree are 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 plus two `⚠︎`-only drift checks: gitleaks version drift and, on a private GitHub mirror, re-enabled Actions.                                    |
@@ -547,20 +547,82 @@ re-enabled, complementing the auto-disable that runs on `nomad init` (see
 [Privacy by default](#privacy-by-default)); it is silent on every prerequisite miss (non-GitHub
 origin, `gh` unauthed, public repo, or Actions already off).
 
-Every `nomad pull`, `nomad push`, and `nomad diff` run ends with a single `summary:` line. The
-status glyph (`✓` green / `⚠︎` yellow / `✗` red / `ℹ︎` dim) carries the severity, mirroring
-`nomad doctor`'s left-gutter format:
+### Reading push and pull output
+
+`nomad push` and `nomad pull` print a grouped tree, the same left-gutter layout you already see from
+`nomad doctor`. There is a header line naming the command and host, then a few named sections
+(`Sessions`, `Extras`, and so on), each with its items hanging off `├`/`└` connectors. A status
+glyph leads every line: `✓` green for something that synced, `ℹ︎` dim for an informational count, `⚠︎`
+yellow for a warning, and `✗` red for a failure. What this means for you: instead of one long flat
+list with a line per project, related work is grouped and the noise is collapsed.
+
+A clean `nomad push` looks like this (one `✓` row per project whose sessions were copied up, the
+projects this host does not track folded into a single count, then the secret-scan result and a
+one-line summary):
+
+```text
+push on host=workstation
+Sessions
+  ├ ✓ claude-nomad
+  ├ ✓ my-side-project
+  └ ℹ︎ 4 not in path-map (run nomad doctor to list)
+Extras
+  └ ✓ claude-nomad/.planning
+Leak scan
+  └ ✓ no leaks
+Summary
+  └ ✓ summary: clean
+```
+
+The `ℹ︎ 4 not in path-map` row is the collapse: rather than printing one line per project that this
+host does not sync, push and pull now show a single count and point you at `nomad doctor`, which
+lists those projects by name if you want the detail. The `Leak scan` section is the secret check
+that runs before anything is published: `✓ no leaks` when the staged transcripts are clean. If a
+secret IS found, that row turns into `✗ gitleaks detected secrets in N session transcript(s)` and
+the full recovery block (which sessions, how to scrub them) still prints below the tree, exactly as
+before (see
+[Recovery flow: gitleaks FATAL on a session JSONL](#recovery-flow-gitleaks-fatal-on-a-session-jsonl)).
+The same `Leak scan` row shows up under `nomad push --dry-run`, which runs that secret scan as a
+read-only preview (nothing is written to the sync repo) and exits non-zero if the preview finds
+anything.
+
+A `nomad pull` is the mirror image, leading with the settings file it regenerated and then the
+sessions and extras it copied down for this host:
+
+```text
+pull on host=workstation (backup=2026-05-27T14-02-09Z)
+Settings
+  └ ✓ settings.json (base + workstation.json)
+Sessions
+  ├ ✓ claude-nomad
+  └ ℹ︎ 2 not in path-map (run nomad doctor to list)
+Extras
+  └ ✓ claude-nomad/.planning
+Summary
+  └ ✓ summary: clean
+```
+
+The `Summary` row is the final verdict for the run. It reads `✓ summary: clean` when everything
+synced, or a `⚠︎` warning naming the counts when something was skipped:
 
 ```text
-✓ summary: clean
 ⚠︎ summary: 3 unmapped on pull (run nomad doctor to list)
 ⚠︎ summary: 2 unmapped on push, 1 collisions (run nomad doctor to list)
 ```
 
-`✓` lines go to stdout; `⚠︎` and `✗` lines go to stderr. The summary is suppressed when a fatal (`✗`)
-fires mid-run so you do not see "summary: clean" stacked under an error. Drive-by projects that have
-no entry in `path-map.json` for this host count as unmapped; the hint points at `nomad doctor`,
-which lists them by logical name.
+`✓` lines go to stdout; `⚠︎` and `✗` lines go to stderr. An early, pre-tree fatal abort (for example
+gitleaks missing when push checks for it, or a rebase conflict before anything is staged) suppresses
+the tree entirely, so you do not see "summary: clean" stacked under an error. A later leak-scan
+finding is different: by then the tree has already been built, so it still renders in full with a
+`✗` Leak scan row and the recovery block below it (see "Recovery flow: gitleaks FATAL on a session
+JSONL"). Projects with no entry in `path-map.json` for this host count as unmapped and fold into the
+collapsed `ℹ︎ ... not in path-map` count; the hint points at `nomad doctor`, which lists them by
+logical name.
+
+`nomad pull --dry-run` keeps its own readable preview format (a unified diff of the `settings.json`
+changes plus the transcripts a real pull would overwrite) rather than the grouped tree, so that
+preview stays easy to scan; only a real `nomad pull` prints the tree above. `nomad diff` is
+unchanged.
 
 ## Recovery flows
 
@@ -603,9 +665,15 @@ same secret.
 ### Recovery flow: gitleaks FATAL on a session JSONL
 
 `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 aborts and names every affected session id and the recovery command:
+push (and without mutating anything), two read-only options are available:
+`nomad doctor --check-shared` scans the session transcripts a push would publish;
+`nomad push --dry-run` runs the same scan AND also covers opted-in extras (`.planning`,
+`CLAUDE.md`), which `--check-shared` does not. Both stage content into a throwaway temp copy and
+never write to the sync repo. A leak-scan finding is the contrast to an early, pre-tree fatal:
+because the scan runs after the tree is built, the push aborts but the grouped tree still renders in
+full, with a `✗ gitleaks detected secrets in N session transcript(s)` row in its `Leak scan`
+section, and then the full recovery block prints below it, naming 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.26.2",
+  "version": "0.27.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.format.ts

@@ -1,43 +1,8 @@
 import { failGlyph, red } from './color.ts';
+import { addItem, type DoctorSection } from './output-tree.ts';
 import { readJson } from './utils.json.ts';
 
-/**
- * Bare `failGlyph` codepoint (`✗`, U+2717) without any WSL padding the
- * `failGlyph` constant may carry. Header rendering composes its own
- * spacing (`${red(failGlyph)} ${header}`), so the section-header path
- * must use the unpadded codepoint to avoid a double space on WSL.
- */
-const FAIL_GLYPH_BARE = '✗';
-
-/**
- * Tree-style output builder for `cmdDoctor`. Doctor builds an ordered list of
- * `DoctorSection`s, each reporter pushes plain-text items into the relevant
- * section, then the orchestrator calls `renderDoctor` to emit a Claude Code
- * `/doctor`-style tree (`Header` / `  ├ item` / `  └ last`) on stdout.
- *
- * Color and status glyphs (okGlyph/warnGlyph/failGlyph/infoGlyph) already
- * live inside the item text; this module never re-colors or re-tokenizes.
- * Sections with zero items are skipped at render time (no empty headers).
- *
- * Output goes directly through `console.log` rather than `utils.log` so the
- * dim `ℹ︎` info glyph used by `pull` / `push` / `init` does NOT appear in
- * doctor output (doctor has its own glyphs per row). Test assertions continue
- * to spy on `console.log`.
- */
-export type DoctorSection = {
-  header: string;
-  items: string[];
-};
-
-/** Construct an empty section with the given header. */
-export function section(header: string): DoctorSection {
-  return { header, items: [] };
-}
-
-/** Append one rendered line to a section. */
-export function addItem(s: DoctorSection, text: string): void {
-  s.items.push(text);
-}
+export { section, addItem, renderTree, renderDoctor, type DoctorSection } from './output-tree.ts';
 
 /**
  * Tolerant JSON reader for `cmdDoctor`. Doctor reads three JSON files
@@ -55,47 +20,3 @@ export function readJsonSafe<T>(path: string, label: string, section: DoctorSect
     return null;
   }
 }
-
-/**
- * True when any item in the section contains the FAIL glyph.
- * Color-wrapped failGlyph (`✗`) still contains the
- * glyph as a substring, so this works for both color-on and color-off output.
- */
-function sectionFailed(s: DoctorSection): boolean {
-  return s.items.some((line) => line.includes(failGlyph));
-}
-
-/**
- * Emit the full doctor report. Skips empty sections, prefixes failed-section
- * headers with a red `✗ ` glyph (U+2717, same as the per-item FAIL glyph so
- * `grep -F '✗'` catches both row and header failures), and writes one blank
- * line between rendered sections (no leading or trailing blank).
- *
- * An empty-string item renders as a true blank line (no tree connector), which
- * lets a reporter set off a footer block (e.g. the `--check-shared` description
- * legend) with vertical whitespace. The `└` connector attaches to the last
- * non-empty item rather than the last array slot so a trailing blank does not
- * strand the elbow on an empty line.
- */
-/**
- * Render one section: a (possibly fail-glyph-prefixed) header followed by its
- * items as a tree. Empty-string items print as true blank lines; the `└` elbow
- * attaches to the last non-empty item so a trailing blank cannot strand it.
- */
-function renderSection(s: DoctorSection): void {
-  const header = sectionFailed(s) ? `${red(FAIL_GLYPH_BARE)} ${s.header}` : s.header;
-  console.log(header);
-  const lastContent = s.items.reduce((acc, item, j) => (item !== '' ? j : acc), -1);
-  for (let j = 0; j < s.items.length; j++) {
-    if (s.items[j] === '') console.log('');
-    else console.log(`${j === lastContent ? '  └ ' : '  ├ '}${s.items[j]}`);
-  }
-}
-
-export function renderDoctor(sections: DoctorSection[]): void {
-  const visible = sections.filter((s) => s.items.length > 0);
-  for (let i = 0; i < visible.length; i++) {
-    if (i > 0) console.log('');
-    renderSection(visible[i]);
-  }
-}

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)]);
+}