claude-nomad 0.26.2 → 0.28.0

package/src/extras-sync.core.ts

@@ -0,0 +1,96 @@
+import { cpSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { HOST, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { assertSafeLocalRoot, assertSafeLogical } from './extras-sync.guards.ts';
+import { log } from './utils.ts';
+import { readPathMap } from './utils.json.ts';
+
+/** Parsed `path-map.json` plus its validated `extras` block. */
+export type ValidatedExtras = { map: PathMap; extrasMap: Record<string, string[]> };
+
+/** Skip counts: `unmapped` per-project (no host path / `'TBD'`), `skipped` per-dirname (not whitelisted). */
+export type ExtrasCounts = { unmapped: number; skipped: number };
+
+/**
+ * Load and validate `path-map.json` for an extras op, owning the guard order
+ * so the "FATAL before any filesystem mutation" contract holds for every
+ * caller. Returns the parsed map plus its `extras` block, or `null` on a clean
+ * early-exit (missing `path-map.json`, a missing repo extras dir when
+ * `requireRepoExtras`, or an empty/absent `extras` key). THE VALIDATION PASS
+ * runs here, up-front over the whole map (`assertSafeLogical` per logical,
+ * `assertSafeLocalRoot` per mapped non-`'TBD'` path) so a clean entry ahead of
+ * a poisoned one cannot let a `mkdirSync`/`cpSync` land before the FATAL fires.
+ *
+ * @param opts.requireRepoExtras - Also require `shared/extras/` (pull side).
+ * @param opts.missingMsg - `log()` line on the missing-prereq exit (omitted for
+ *   the divergence check, which skips silently).
+ */
+export function loadValidatedExtras(opts: {
+  requireRepoExtras?: boolean;
+  missingMsg?: string;
+}): ValidatedExtras | null {
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  const repoExtras = join(REPO_HOME, 'shared', 'extras');
+  if (!existsSync(mapPath) || (opts.requireRepoExtras === true && !existsSync(repoExtras))) {
+    if (opts.missingMsg !== undefined) log(opts.missingMsg);
+    return null;
+  }
+
+  const map = readPathMap(mapPath);
+  const extrasMap = map.extras ?? {};
+  if (Object.keys(extrasMap).length === 0) return null;
+
+  for (const logical of Object.keys(extrasMap)) {
+    assertSafeLogical(logical);
+    const localRoot = map.projects[logical]?.[HOST];
+    if (localRoot && localRoot !== 'TBD') assertSafeLocalRoot(localRoot, logical);
+  }
+  return { map, extrasMap };
+}
+
+/**
+ * Yield every surviving `{ logical, localRoot, dirname }` extras target after
+ * the per-project and per-dirname skip filters, mutating `counts` as it goes
+ * (`unmapped++` for a project with no host path / `'TBD'`, then skip it;
+ * `skipped++` for a dirname outside `SUPPORTED_EXTRAS`). Shared by push, pull,
+ * and the divergence check so all three walk identical skip/count semantics;
+ * the caller builds src/dst from the yielded triple.
+ *
+ * @param v - validated path-map plus its extras block.
+ * @param counts - mutated in place as targets are skipped or yielded. Skips are
+ *   counted silently (no per-skip log line); the caller's detail arrays and the
+ *   collapsed count row carry that information to the tree renderer.
+ */
+export function* eachExtrasTarget(
+  v: ValidatedExtras,
+  counts: ExtrasCounts,
+): Generator<{ logical: string; localRoot: string; dirname: string }> {
+  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
+  for (const [logical, dirnames] of Object.entries(v.extrasMap)) {
+    const localRoot = v.map.projects[logical]?.[HOST];
+    if (!localRoot || localRoot === 'TBD') {
+      counts.unmapped++;
+      continue;
+    }
+    for (const dirname of dirnames) {
+      if (!whitelist.includes(dirname)) {
+        counts.skipped++;
+        continue;
+      }
+      yield { logical, localRoot, dirname };
+    }
+  }
+}
+
+/**
+ * Recursive mirror copy: `rmSync` then `cpSync` so dst-only entries are
+ * removed (true mirror, not just overwrite). Passes `verbatimSymlinks: true`
+ * to keep relative symlink targets unrewritten across hosts (Pitfall 1;
+ * nodejs/node issue 41693). Exported so the test file can call it directly;
+ * `remapExtrasPush` and `remapExtrasPull` are the primary public API.
+ */
+export function copyExtras(src: string, dst: string): void {
+  rmSync(dst, { recursive: true, force: true });
+  cpSync(src, dst, { recursive: true, force: true, verbatimSymlinks: true });
+}

package/src/extras-sync.remap.ts

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { REPO_HOME } from './config.ts';
+import {
+  copyExtras,
+  eachExtrasTarget,
+  loadValidatedExtras,
+  type ExtrasCounts,
+  type ValidatedExtras,
+} from './extras-sync.core.ts';
+import { backupExtrasWrite, backupRepoWrite } from './utils.fs.ts';
+
+/** Detail lists returned by an extras op: items copied (wet) and would-copy (dry). */
+type ExtrasDetail = ExtrasCounts & { done: string[]; would: string[] };
+
+/** One yielded extras target: a (logical, host localRoot, dirname) triple. */
+type ExtrasTarget = { logical: string; localRoot: string; dirname: string };
+
+/**
+ * Shared copy loop for `remapExtrasPush` / `remapExtrasPull`. Walks every
+ * surviving extras target (counts mutated via `eachExtrasTarget`; skips are
+ * counted silently, no per-skip log line), resolves src/dst through the
+ * side-specific `paths(...)`, and either records the would-copy item under
+ * `dryRun` or backs up + copies and records the done item. Returns
+ * `{ unmapped, skipped, done, would }`; the public wrappers rename
+ * `done`/`would` to push/pull-specific field names. No per-item log lines: the
+ * detail arrays carry that information to the tree renderer.
+ *
+ * @param v - validated path-map plus its extras block.
+ * @param dryRun - when `true`, collect `would` without mutating.
+ * @param paths - resolves `{ src, dst }` for one target (side-specific).
+ * @param backup - snapshots the dst before clobber (side-specific).
+ * @returns the counts plus the done/would detail lists.
+ */
+function runExtrasOp(
+  v: ValidatedExtras,
+  dryRun: boolean,
+  paths: (t: ExtrasTarget) => { src: string; dst: string },
+  backup: (dst: string, localRoot: string) => void,
+): ExtrasDetail {
+  const counts: ExtrasCounts = { unmapped: 0, skipped: 0 };
+  const done: string[] = [];
+  const would: string[] = [];
+  for (const t of eachExtrasTarget(v, counts)) {
+    const { src, dst } = paths(t);
+    if (!existsSync(src)) continue;
+    const item = `${t.logical}/${t.dirname}`;
+    if (dryRun) {
+      would.push(item);
+      continue;
+    }
+    backup(dst, t.localRoot);
+    copyExtras(src, dst);
+    done.push(item);
+  }
+  return { ...counts, done, would };
+}
+
+/**
+ * Push: copy whitelisted extras directories under each project's localRoot
+ * into the repo at `shared/extras/<logical>/<dirname>/`. Returns
+ * `{ unmapped, skipped, pushed, wouldPush }` with intentionally asymmetric
+ * count granularity (see `eachExtrasTarget`): `unmapped` per-project, `skipped`
+ * per-dirname; both feed the summary row. `pushed` / `wouldPush` hold
+ * `<logical>/<dirname>` strings copied (wet) or that would copy under
+ * `opts.dryRun` so cmdPush can render a grouped tree. Skips are counted
+ * silently and per-item log lines are dropped; counts are unchanged. Legacy
+ * `path-map.json` without an `extras` key returns empty arrays and zero counts
+ * cleanly.
+ *
+ * @param ts - backup timestamp namespace.
+ * @param opts.dryRun - when `true`, collect `wouldPush` without mutating.
+ */
+export function remapExtrasPush(
+  ts: string,
+  opts: { dryRun?: boolean } = {},
+): ExtrasCounts & { pushed: string[]; wouldPush: string[] } {
+  const dryRun = opts.dryRun === true;
+  const v = loadValidatedExtras({ missingMsg: 'no path-map.json; skipping extras push' });
+  if (v === null) return { unmapped: 0, skipped: 0, pushed: [], wouldPush: [] };
+
+  const repoExtras = join(REPO_HOME, 'shared', 'extras');
+  if (!dryRun) mkdirSync(repoExtras, { recursive: true });
+
+  const { unmapped, skipped, done, would } = runExtrasOp(
+    v,
+    dryRun,
+    ({ localRoot, logical, dirname }) => ({
+      src: join(localRoot, dirname),
+      dst: join(repoExtras, logical, dirname),
+    }),
+    (dst) => backupRepoWrite(dst, ts, REPO_HOME),
+  );
+  return { unmapped, skipped, pushed: done, wouldPush: would };
+}
+
+/**
+ * Pull: copy whitelisted extras from `shared/extras/<logical>/<dirname>/`
+ * back into each project's localRoot on this host. Returns
+ * `{ unmapped, skipped, pulled, wouldPull }` with the same asymmetric count
+ * granularity as `remapExtrasPush`; `pulled` / `wouldPull` hold
+ * `<logical>/<dirname>` strings for the grouped tree. Skips are counted
+ * silently and per-item log lines are dropped; counts are unchanged. Uses
+ * `backupExtrasWrite` (not `backupBeforeWrite`) because
+ * `<localRoot>/<dirname>` lives outside `CLAUDE_HOME` and the standard helper's
+ * relative-path guard would no-op and lose prior content. Legacy
+ * `path-map.json` without an `extras` key, or a missing `shared/extras/`, both
+ * produce a clean no-op.
+ *
+ * @param ts - backup timestamp namespace.
+ * @param opts.dryRun - when `true`, collect `wouldPull` without mutating.
+ */
+export function remapExtrasPull(
+  ts: string,
+  opts: { dryRun?: boolean } = {},
+): ExtrasCounts & { pulled: string[]; wouldPull: string[] } {
+  const dryRun = opts.dryRun === true;
+  const v = loadValidatedExtras({
+    requireRepoExtras: true,
+    missingMsg: 'no path-map or repo extras dir; skipping extras remap',
+  });
+  if (v === null) return { unmapped: 0, skipped: 0, pulled: [], wouldPull: [] };
+
+  const repoExtras = join(REPO_HOME, 'shared', 'extras');
+  const { unmapped, skipped, done, would } = runExtrasOp(
+    v,
+    dryRun,
+    ({ localRoot, logical, dirname }) => ({
+      src: join(repoExtras, logical, dirname),
+      dst: join(localRoot, dirname),
+    }),
+    // Snapshot the host-side dst BEFORE copyExtras clobbers it. Anchor on
+    // localRoot so the backup tree mirrors the project layout.
+    (dst, localRoot) => backupExtrasWrite(dst, ts, localRoot),
+  );
+  return { unmapped, skipped, pulled: done, wouldPull: would };
+}

package/src/extras-sync.ts

@@ -1,102 +1,27 @@
-import { cpSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { HOME, HOST, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { HOME, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
 import { listDivergingFiles } from './extras-sync.diff.ts';
-import { assertSafeLocalRoot, assertSafeLogical } from './extras-sync.guards.ts';
-import { log, warn } from './utils.ts';
-import { backupExtrasWrite, backupRepoWrite } from './utils.fs.ts';
-import { encodePath, readPathMap } from './utils.json.ts';
-
-/** Parsed `path-map.json` plus its validated `extras` block. */
-type ValidatedExtras = { map: PathMap; extrasMap: Record<string, string[]> };
-
-/** Skip counts: `unmapped` per-project (no host path / `'TBD'`), `skipped` per-dirname (not whitelisted). */
-type ExtrasCounts = { unmapped: number; skipped: number };
-
-/**
- * Load and validate `path-map.json` for an extras op, owning the guard order
- * so the "FATAL before any filesystem mutation" contract holds for every
- * caller. Returns the parsed map plus its `extras` block, or `null` on a clean
- * early-exit (missing `path-map.json`, a missing repo extras dir when
- * `requireRepoExtras`, or an empty/absent `extras` key). THE VALIDATION PASS
- * runs here, up-front over the whole map (`assertSafeLogical` per logical,
- * `assertSafeLocalRoot` per mapped non-`'TBD'` path) so a clean entry ahead of
- * a poisoned one cannot let a `mkdirSync`/`cpSync` land before the FATAL fires.
- *
- * @param opts.requireRepoExtras - Also require `shared/extras/` (pull side).
- * @param opts.missingMsg - `log()` line on the missing-prereq exit (omitted for
- *   the divergence check, which skips silently).
- */
-function loadValidatedExtras(opts: {
-  requireRepoExtras?: boolean;
-  missingMsg?: string;
-}): ValidatedExtras | null {
-  const mapPath = join(REPO_HOME, 'path-map.json');
-  const repoExtras = join(REPO_HOME, 'shared', 'extras');
-  if (!existsSync(mapPath) || (opts.requireRepoExtras === true && !existsSync(repoExtras))) {
-    if (opts.missingMsg !== undefined) log(opts.missingMsg);
-    return null;
-  }
-
-  const map = readPathMap(mapPath);
-  const extrasMap = map.extras ?? {};
-  if (Object.keys(extrasMap).length === 0) return null;
-
-  for (const logical of Object.keys(extrasMap)) {
-    assertSafeLogical(logical);
-    const localRoot = map.projects[logical]?.[HOST];
-    if (localRoot && localRoot !== 'TBD') assertSafeLocalRoot(localRoot, logical);
-  }
-  return { map, extrasMap };
-}
-
-/**
- * Yield every surviving `{ logical, localRoot, dirname }` extras target after
- * the per-project and per-dirname skip filters, mutating `counts` as it goes
- * (`unmapped++` for a project with no host path / `'TBD'`, then skip it;
- * `skipped++` for a dirname outside `SUPPORTED_EXTRAS`). Shared by push, pull,
- * and the divergence check so all three walk identical skip/count semantics;
- * the caller builds src/dst from the yielded triple.
- *
- * @param quiet - Suppress the per-skip `log()` lines (the read-only divergence
- *   check skips silently; push/pull narrate). Counts increment either way.
- */
-function* eachExtrasTarget(
-  v: ValidatedExtras,
-  counts: ExtrasCounts,
-  quiet = false,
-): Generator<{ logical: string; localRoot: string; dirname: string }> {
-  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
-  for (const [logical, dirnames] of Object.entries(v.extrasMap)) {
-    const localRoot = v.map.projects[logical]?.[HOST];
-    if (!localRoot || localRoot === 'TBD') {
-      counts.unmapped++;
-      if (!quiet) log(`skip ${logical}: no path for ${HOST}`);
-      continue;
-    }
-    for (const dirname of dirnames) {
-      if (!whitelist.includes(dirname)) {
-        counts.skipped++;
-        if (!quiet) log(`skip ${dirname} for ${logical}: not in SUPPORTED_EXTRAS`);
-        continue;
-      }
-      yield { logical, localRoot, dirname };
-    }
-  }
-}
-
-/**
- * Recursive mirror copy: `rmSync` then `cpSync` so dst-only entries are
- * removed (true mirror, not just overwrite). Passes `verbatimSymlinks: true`
- * to keep relative symlink targets unrewritten across hosts (Pitfall 1;
- * nodejs/node issue 41693). Exported so the test file can call it directly;
- * `remapExtrasPush` and `remapExtrasPull` are the primary public API.
- */
-export function copyExtras(src: string, dst: string): void {
-  rmSync(dst, { recursive: true, force: true });
-  cpSync(src, dst, { recursive: true, force: true, verbatimSymlinks: true });
-}
+import {
+  copyExtras,
+  eachExtrasTarget,
+  loadValidatedExtras,
+  type ExtrasCounts,
+  type ValidatedExtras,
+} from './extras-sync.core.ts';
+import { assertSafeLogical } from './extras-sync.guards.ts';
+import { warn } from './utils.ts';
+import { encodePath } from './utils.json.ts';
+
+// Re-export the shared primitives so existing import sites that pull them from
+// `./extras-sync.ts` (tests call `copyExtras` directly) keep working unchanged.
+export { copyExtras, eachExtrasTarget, loadValidatedExtras };
+export type { ExtrasCounts, ValidatedExtras };
+
+// The two public remap ops live in the sibling module to hold the soft
+// line-cap; re-exported here so `./extras-sync.ts` stays the public surface.
+export { remapExtrasPull, remapExtrasPush } from './extras-sync.remap.ts';
 
 /**
  * Repo-relative `shared/extras/<logical>/<dirname>` paths for every (logical,
@@ -125,77 +50,6 @@ export function whitelistedExtrasPaths(map: PathMap): string[] {
   return [...paths].sort((a, b) => a.localeCompare(b));
 }
 
-/**
- * Push: copy whitelisted extras directories under each project's localRoot
- * into the repo at `shared/extras/<logical>/<dirname>/`. Returns
- * `{ unmapped, skipped }` with intentionally asymmetric granularity (see
- * `eachExtrasTarget`): `unmapped` per-project, `skipped` per-dirname; both feed
- * `emitSummary`. `opts.dryRun` logs `would push extras:` lines without writing,
- * with identical count semantics. Legacy `path-map.json` without an `extras`
- * key returns `{ unmapped: 0, skipped: 0 }` cleanly.
- */
-export function remapExtrasPush(ts: string, opts: { dryRun?: boolean } = {}): ExtrasCounts {
-  const dryRun = opts.dryRun === true;
-  const counts: ExtrasCounts = { unmapped: 0, skipped: 0 };
-  const v = loadValidatedExtras({ missingMsg: 'no path-map.json; skipping extras push' });
-  if (v === null) return counts;
-
-  const repoExtras = join(REPO_HOME, 'shared', 'extras');
-  if (!dryRun) mkdirSync(repoExtras, { recursive: true });
-
-  for (const { logical, localRoot, dirname } of eachExtrasTarget(v, counts)) {
-    const src = join(localRoot, dirname);
-    if (!existsSync(src)) continue;
-    const dst = join(repoExtras, logical, dirname);
-    if (dryRun) {
-      log(`would push extras: ${src} -> ${dst}`);
-      continue;
-    }
-    backupRepoWrite(dst, ts, REPO_HOME);
-    copyExtras(src, dst);
-    log(`pushed extras ${logical}/${dirname} -> shared/extras/${logical}/${dirname}`);
-  }
-  return counts;
-}
-
-/**
- * Pull: copy whitelisted extras from `shared/extras/<logical>/<dirname>/`
- * back into each project's localRoot on this host. Returns `{ unmapped,
- * skipped }` with the same asymmetric granularity as `remapExtrasPush`.
- * `opts.dryRun` logs `would overwrite extras:` lines without writing. Uses
- * `backupExtrasWrite` (not `backupBeforeWrite`) because `<localRoot>/<dirname>`
- * lives outside `CLAUDE_HOME` and the standard helper's relative-path guard
- * would no-op and lose prior content. Legacy `path-map.json` without an
- * `extras` key, or a missing `shared/extras/`, both produce a clean no-op.
- */
-export function remapExtrasPull(ts: string, opts: { dryRun?: boolean } = {}): ExtrasCounts {
-  const dryRun = opts.dryRun === true;
-  const counts: ExtrasCounts = { unmapped: 0, skipped: 0 };
-  const v = loadValidatedExtras({
-    requireRepoExtras: true,
-    missingMsg: 'no path-map or repo extras dir; skipping extras remap',
-  });
-  if (v === null) return counts;
-
-  const repoExtras = join(REPO_HOME, 'shared', 'extras');
-
-  for (const { logical, localRoot, dirname } of eachExtrasTarget(v, counts)) {
-    const src = join(repoExtras, logical, dirname);
-    if (!existsSync(src)) continue;
-    const dst = join(localRoot, dirname);
-    if (dryRun) {
-      log(`would overwrite extras: ${dst} (from ${src})`);
-      continue;
-    }
-    // Snapshot the host-side dst BEFORE copyExtras clobbers it. Anchor
-    // on localRoot so the backup tree mirrors the project layout.
-    backupExtrasWrite(dst, ts, localRoot);
-    copyExtras(src, dst);
-    log(`pulled extras ${logical}/${dirname} -> ${dst}`);
-  }
-  return counts;
-}
-
 /**
  * Read-only pre-pull check: compare local `<localRoot>/<dirname>/` against
  * the just-pulled `shared/extras/<logical>/<dirname>/` and emit a WARN per
@@ -214,7 +68,7 @@ export function divergenceCheckExtras(ts: string): void {
 
   const counts: ExtrasCounts = { unmapped: 0, skipped: 0 };
   const backupRoot = join(HOME, '.cache', 'claude-nomad', 'backup', ts, 'extras');
-  for (const { logical, localRoot, dirname } of eachExtrasTarget(v, counts, true)) {
+  for (const { logical, localRoot, dirname } of eachExtrasTarget(v, counts)) {
     const local = join(localRoot, dirname);
     const repo = join(REPO_HOME, 'shared', 'extras', logical, dirname);
     if (!existsSync(local) || !existsSync(repo)) continue;

package/src/links.ts

@@ -64,8 +64,19 @@ export function applySharedLinks(ts: string, opts: { dryRun?: boolean } = {}): v
  * would produce. The unified textual diff of the would-be-written content
  * is produced by `computePreview` in `src/preview.ts`, not here, to keep
  * this function's contract simple (mutation or log-only).
+ *
+ * Returns `{ label }` where `label` is the override-source tag
+ * (`'<HOST>.json'` when a host override exists, else `'no host overrides'`).
+ * The WET path no longer logs `wrote settings.json (base + <label>)` inline;
+ * `cmdPull` consumes the returned label to render the Settings row of its
+ * grouped tree. The dry-run `would write settings.json ...` log and the
+ * drift WARN are unchanged (the WET success log is the only thing that moved).
+ *
+ * @param ts - backup timestamp namespace for `backupBeforeWrite`.
+ * @param opts.dryRun - when `true`, log the would-write line and skip mutation.
+ * @returns `{ label }` describing the override source for the Settings row.
  */
-export function regenerateSettings(ts: string, opts: { dryRun?: boolean } = {}): void {
+export function regenerateSettings(ts: string, opts: { dryRun?: boolean } = {}): { label: string } {
   const dryRun = opts.dryRun === true;
   const basePath = join(REPO_HOME, 'shared', 'settings.base.json');
   const hostPath = join(REPO_HOME, 'hosts', `${HOST}.json`);
@@ -107,10 +118,10 @@ export function regenerateSettings(ts: string, opts: { dryRun?: boolean } = {}):
 
   if (dryRun) {
     log(`would write settings.json (base + ${overrideLabel})`);
-    return;
+    return { label: overrideLabel };
   }
 
   backupBeforeWrite(settingsPath, ts);
   writeJsonAtomic(settingsPath, merged);
-  log(`wrote settings.json (base + ${overrideLabel})`);
+  return { label: overrideLabel };
 }

package/src/nomad.help.ts

@@ -49,6 +49,8 @@ export const DEFAULT_HELP = [
   cont('gitleaks, gitlinks).'),
   row('       --check-shared', 'Preflight gitleaks scan of the session transcripts a'),
   cont('`nomad push` would stage (a temp copy, never the live dir).'),
+  row('       --check-schema', 'Flag settings.json keys absent from the live published'),
+  cont('Claude Code settings schema (needs network; degrades offline).'),
   row('       --resume-cmd <id>', 'Print `cd <abspath> && claude --resume <id>` for a session id'),
   cont('from ~/.claude/projects/.'),
   '',

package/src/nomad.ts

@@ -131,13 +131,16 @@ try {
       // 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.
+      // scan of the transcripts a push would stage; `doctor --check-schema`
+      // (no positional) appends the live settings-schema check. Bare `doctor`
+      // runs the plain read-only health check. Any other shape (unknown flag,
+      // extra positional, a scan flag 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] === '--check-schema' && process.argv.length === 4) {
+        cmdDoctor({ checkSchema: true });
       } else if (process.argv[3] === '--resume-cmd') {
         const id = process.argv[4];
         if (process.argv.length !== 5 || typeof id !== 'string' || id.length === 0) {
@@ -146,7 +149,9 @@ try {
         }
         resumeCmd(id);
       } else {
-        console.error('usage: nomad doctor [--check-shared | --resume-cmd <session-id>]');
+        console.error(
+          'usage: nomad doctor [--check-shared | --check-schema | --resume-cmd <session-id>]',
+        );
         process.exit(1);
       }
       break;

package/src/output-tree.ts

@@ -0,0 +1,91 @@
+import { failGlyph, red } from './color.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 shared by `cmdDoctor`, `cmdPush`, and `cmdPull`.
+ * Callers build an ordered list of `DoctorSection`s, push pre-rendered
+ * plain-text items into the relevant section, then call `renderTree`
+ * (aliased `renderDoctor` for doctor's call site) 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);
+}
+
+/**
+ * True when any item in the section contains the FAIL glyph.
+ * Color-wrapped failGlyph (`[31m✗[39m`) 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));
+}
+
+/**
+ * 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]}`);
+  }
+}
+
+/**
+ * Emit the full grouped tree. 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.
+ */
+export function renderTree(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]);
+  }
+}
+
+/**
+ * Back-compat alias for `renderTree`. Doctor's call site imports
+ * `renderDoctor`; push/pull import `renderTree`. Both point at the same
+ * implementation so doctor output stays byte-identical.
+ */
+export const renderDoctor = renderTree;