claude-nomad 0.26.2 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.28.0](https://github.com/funkadelic/claude-nomad/compare/v0.27.0...v0.28.0) (2026-05-28)
+
+
+### Added
+
+* **doctor:** settings schema drift tooling (auto-sync PR + --check-schema) ([#168](https://github.com/funkadelic/claude-nomad/issues/168)) ([ac4ac21](https://github.com/funkadelic/claude-nomad/commit/ac4ac21f90148d7261b0b907bfdad43b3758f9fd))
+
+
+### Fixed
+
+* **doctor:** resync KNOWN_SETTINGS_KEYS with official settings schema ([#166](https://github.com/funkadelic/claude-nomad/issues/166)) ([2b453e1](https://github.com/funkadelic/claude-nomad/commit/2b453e18c18520dd0a4df035ace3825709097bc1))
+* drop-session scrub hint and README rendering/layout fixes ([#165](https://github.com/funkadelic/claude-nomad/issues/165)) ([0840ab4](https://github.com/funkadelic/claude-nomad/commit/0840ab408b72174b23532a0ea32c27df522cfe39))
+
+## [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

@@ -67,7 +67,7 @@ box, a personal rig and a work machine. [Get started in three steps.](#quickstar
 ## Quickstart
 
 If you already have a private **claude-nomad** mirror (see [Setup](#setup) for the one-time
-bootstrap), adding a new host is three steps:
+bootstrap), adding a new host is two one-time steps, then the everyday loop:
 
 ```bash
 $ npm i -g claude-nomad
@@ -157,16 +157,28 @@ so a clobbered dotfile variable does not break the CLI.
 
 ## What gets synced vs. not
 
-| Category               | Items                                                                                                                                                                                                                                     | Behavior                                                                                                                                                                                                        |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Synced**             | `CLAUDE.md`, `agents/`, `skills/`, `commands/`, `rules/`, `my-statusline.cjs`                                                                                                                                                             | Symlinked into `~/.claude/` from `shared/` (see `SHARED_LINKS` in `src/config.ts`).                                                                                                                             |
-| **Generated**          | `settings.json`                                                                                                                                                                                                                           | Deep-merge of `settings.base.json` with `hosts/<hostname>.json`. Rewritten on every pull.                                                                                                                       |
-| **Remapped**           | `projects/` session transcripts                                                                                                                                                                                                           | Copied with path translation per `path-map.json`.                                                                                                                                                               |
-| **Per-project extras** | `<localRoot>/.planning/` and other directories, or a single root file like `CLAUDE.md`, whitelisted by `SUPPORTED_EXTRAS` in `src/config.ts`                                                                                              | Opt-in via the `extras` field in `path-map.json`. Mirrored to/from `shared/extras/<logical>/<name>` (directory subtree or single file). Pre-pull divergence WARN flags local edits before they get overwritten. |
-| **Never synced**       | `~/.claude.json` (OAuth, MCP state), `history.jsonl`, `settings.local.json` (per-host overrides), `stats-cache.json`, `todos/`, `shell-snapshots/`, `debug/`, `file-history/`, `plans/`, `session-env/`, `statsig/`, `telemetry/`, `ide/` | Per-host ephemeral state.                                                                                                                                                                                       |
-| **Auto-rehydrated**    | `~/.claude/plugins/cache/<plugin>/...`                                                                                                                                                                                                    | Plugin payloads not synced. Claude Code re-downloads them on first use from the `enabledPlugins` list in the regenerated `settings.json`; no manual `claude plugins install ...` per host.                      |
-
-> [!NOTE] Plugins that depend on host-specific state (external binaries, API keys in env, MCP server
+| Category               | Items                                                                         | Behavior                                                                                       |
+| ---------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| **Synced**             | `CLAUDE.md`, `agents/`, `skills/`, `commands/`, `rules/`, `my-statusline.cjs` | Symlinked into `~/.claude/` from `shared/`.                                                    |
+| **Generated**          | `settings.json`                                                               | Deep-merge of `settings.base.json` with `hosts/<hostname>.json`; rewritten every pull.         |
+| **Remapped**           | `projects/` session transcripts                                               | Copied with path translation per `path-map.json`.                                              |
+| **Per-project extras** | Whitelisted dirs like `.planning/`, or a root file like `CLAUDE.md`           | Opt-in via the `extras` field in `path-map.json`; mirrored to/from `shared/extras/<logical>/`. |
+| **Never synced**       | OAuth and MCP state, shell history, per-host overrides, caches, scratch dirs  | Per-host ephemeral state; left untouched in both directions.                                   |
+| **Auto-rehydrated**    | `~/.claude/plugins/cache/<plugin>/...`                                        | Re-downloaded by Claude Code from the `enabledPlugins` list; no per-host install.              |
+
+Pointers and specifics:
+
+- **Synced** link names live in `SHARED_LINKS`, **whitelisted extras** names in `SUPPORTED_EXTRAS`,
+  and the full **never-synced** set in `NEVER_SYNC` (all in `src/config.ts`).
+- **Never synced**, in full: `~/.claude.json` (OAuth, MCP state), `history.jsonl`,
+  `settings.local.json` (per-host overrides), `stats-cache.json`, `todos/`, `shell-snapshots/`,
+  `debug/`, `file-history/`, `plans/`, `session-env/`, `statsig/`, `telemetry/`, `ide/`.
+- **Per-project extras** run a pre-pull divergence WARN that flags local edits before they get
+  overwritten.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> Plugins that depend on host-specific state (external binaries, API keys in env, MCP server
 > URLs) still need that side set up on each host. Put them in `hosts/<host>.json` or the plugin's
 > own per-host config.
 
@@ -197,7 +209,9 @@ block opts a project into syncing whitelisted directories (or a single root file
 }
 ```
 
-> [!IMPORTANT] The host-label keys must match whatever you set `NOMAD_HOST=` to on each host (see
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> The host-label keys must match whatever you set `NOMAD_HOST=` to on each host (see
 > [Setup](#setup)). Mismatched labels silently skip remap, so sessions land in the wrong host's
 > encoded dir.
 
@@ -249,17 +263,25 @@ host-only model overrides).
 
 ```json
 {
-  "model": "claude-opus-4-7",
+  "model": "claude-opus-4-8",
   "env": { "OLLAMA_HOST": "http://localhost:11434" }
 }
 ```
 
-Results on `your-other-host`: opus 4.7, the local Ollama env var, plus the shared permissions array.
+Results on `your-other-host`: opus 4.8, the local Ollama env var, plus the shared permissions array.
 
-> [!CAUTION] Never hand-edit `~/.claude/settings.json` on a synced host. It's regenerated on every
+<!-- prettier-ignore -->
+> [!CAUTION]
+> Never hand-edit `~/.claude/settings.json` on a synced host. It's regenerated on every
 > `nomad pull` from base + host, so your edits will be clobbered. Edit the base or host file in the
 > repo instead.
 
+`nomad doctor` warns when `settings.json` carries a top-level key it does not recognize (a cue that
+Claude Code added a setting). The recognized set is kept current against Claude Code's published
+settings schema by a weekly automated PR in the public repo, so a periodic `nomad update` is what
+keeps that warning quiet on your hosts. To check your own `settings.json` against the live schema on
+demand, run `nomad doctor --check-schema`.
+
 ## What does NOT sync (deliberate trade-offs)
 
 Read these before adopting so you opt in with eyes open.
@@ -300,9 +322,9 @@ Read these before adopting so you opt in with eyes open.
 - `gh` ([GitHub CLI](https://cli.github.com/)), used only by `nomad init` to auto-disable Actions on
   the private repo; if it is missing or unauthenticated, init prints a manual fallback tip and
   continues
-- [curl](https://curl.se/), used only by the version/update check (the `nomad doctor` latest-release
-  line and the post-`nomad update` check); it degrades silently when curl is absent or offline, so
-  the rest of the CLI works without it
+- [curl](https://curl.se/), used by the version/update check (the `nomad doctor` latest-release line
+  and the post-`nomad update` check) and by `nomad doctor --check-schema`; it degrades silently when
+  curl is absent or offline, so the rest of the CLI works without it
 
 ## Setup
 
@@ -330,7 +352,9 @@ automatically:
 Pass `--keep-actions` to either form of init to skip step 2 (for example, when your org already
 enforces an Actions policy upstream).
 
-> [!WARNING] If you ever flip the mirror to public, both protections evaporate: CI starts firing on
+<!-- prettier-ignore -->
+> [!WARNING]
+> If you ever flip the mirror to public, both protections evaporate: CI starts firing on
 > every `nomad push` against `main`, and your session transcripts (which include conversation
 > content) become world-readable. **Keep it private.**
 
@@ -525,12 +549,13 @@ 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.                                    |
 | `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 doctor --check-schema`    | Read-only: fetches the live Claude Code settings schema and lists any `~/.claude/settings.json` key absent from it (candidates for the hand-maintained `APP_ONLY_KEYS` list). Non-fatal and offline-tolerant: skips with a `⚠︎` when curl is missing or the schema is unreachable.                                                                        |
 | `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 ``⚠︎ claude-nomad: <local> -> <latest> (run `nomad update`)`` when the local
@@ -547,20 +572,83 @@ 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](#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
 
@@ -600,12 +688,25 @@ REQUIRED for durability, not optional housekeeping: `remapPush` (in `src/remap.t
 local content into the staged tree on the next push, so a drop without a local scrub re-stages the
 same secret.
 
+A successful drop prints this reminder inline, pointing at the live transcript that still needs
+scrubbing (the exact path when `path-map.json` maps the project to the current host, a generic
+`~/.claude/projects/<encoded>/<id>.jsonl` template otherwise). This is why a
+`nomad doctor --check-shared` run still reports the session after a drop: that scan reads the live
+`~/.claude/projects/` source, not the staged tree, so it keeps flagging the secret until the local
+transcript is scrubbed.
+
 ### 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.28.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-schema.ts

@@ -0,0 +1,72 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { dim, green, infoGlyph, okGlyph, warnGlyph, yellow } from './color.ts';
+import { addItem, readJsonSafe, type DoctorSection } from './commands.doctor.format.ts';
+import { CLAUDE_HOME, SETTINGS_SCHEMA_URL } from './config.ts';
+
+/**
+ * Opt-in `nomad doctor --check-schema` reporter. Fetches the live Claude Code
+ * settings JSON schema and lists any top-level key in this host's
+ * `~/.claude/settings.json` that the published schema does not define, i.e.
+ * candidates for the hand-maintained `APP_ONLY_KEYS` list. Offline-tolerant by
+ * design (mirrors the release version check): curl missing, a network failure,
+ * or a malformed schema all degrade to a single `⚠︎` skip line. Never sets
+ * `process.exitCode`; this is informational discovery, not a gate.
+ */
+
+/**
+ * Fetch the live settings schema via curl and return its top-level property
+ * names. curl is optional (matches the version check): a missing binary,
+ * non-2xx response, or malformed payload all surface as `null` so the caller
+ * skips cleanly. 3s timeout, fail-fast (`-f`), silent (`-s`), follow redirects.
+ */
+function fetchSchemaKeys(): string[] | null {
+  try {
+    const raw = execFileSync('curl', ['-fsSL', '-m', '3', SETTINGS_SCHEMA_URL], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString();
+    const parsed = JSON.parse(raw) as { properties?: Record<string, unknown> };
+    if (typeof parsed.properties !== 'object' || parsed.properties === null) return null;
+    return Object.keys(parsed.properties);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Append the `--check-schema` result to the supplied section: an info line when
+ * there is no local settings.json, a `⚠︎` skip when the schema cannot be
+ * fetched, an OK line when every key is in the schema, or a `⚠︎` line naming the
+ * keys absent from it (APP_ONLY_KEYS candidates).
+ */
+export function reportCheckSchema(section: DoctorSection): void {
+  const settingsPath = join(CLAUDE_HOME, 'settings.json');
+  if (!existsSync(settingsPath)) {
+    addItem(section, `${dim(infoGlyph)} no ~/.claude/settings.json to check`);
+    return;
+  }
+  const settings = readJsonSafe<Record<string, unknown>>(settingsPath, settingsPath, section);
+  if (settings === null) return;
+
+  const liveKeys = fetchSchemaKeys();
+  if (liveKeys === null) {
+    addItem(
+      section,
+      `${yellow(warnGlyph)} schema check skipped (offline, curl missing, or schema unreachable)`,
+    );
+    return;
+  }
+
+  const liveSet = new Set(liveKeys);
+  const candidates = Object.keys(settings).filter((k) => !liveSet.has(k));
+  if (candidates.length === 0) {
+    addItem(section, `${green(okGlyph)} settings.json keys all present in the published schema`);
+  } else {
+    addItem(
+      section,
+      `${yellow(warnGlyph)} settings.json keys absent from published schema (APP_ONLY_KEYS candidates): ${candidates.join(', ')}`,
+    );
+  }
+}

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.doctor.ts

@@ -15,6 +15,7 @@ import {
   reportRebaseClean,
   reportRemote,
 } from './commands.doctor.checks.repository.ts';
+import { reportCheckSchema } from './commands.doctor.check-schema.ts';
 import { reportCheckShared } from './commands.doctor.check-shared.ts';
 import { reportNodeEngineCheck } from './commands.doctor.engine.ts';
 import { renderDoctor, section } from './commands.doctor.format.ts';
@@ -35,8 +36,12 @@ import { reportVersionCheck } from './commands.doctor.version.ts';
  * 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).
+ *
+ * `opts.checkSchema` (the `--check-schema` sub-flag) appends a "Schema scan"
+ * section that fetches the live settings schema and flags local settings.json
+ * keys absent from it. Also OFF by default (it needs the network).
  */
-export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
+export function cmdDoctor(opts: { checkShared?: boolean; checkSchema?: boolean } = {}): void {
   const host = section('Host');
   reportHostAndPaths(host);
   reportRepoState(host);
@@ -74,5 +79,18 @@ export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
   // drift check above spawns `gitleaks version` separately, by design.)
   if (opts.checkShared === true) reportCheckShared(sharedScan, gitleaksReady);
 
-  renderDoctor([version, host, links, settings, pathMap, neverSync, repository, sharedScan]);
+  const schemaScan = section('Schema scan');
+  if (opts.checkSchema === true) reportCheckSchema(schemaScan);
+
+  renderDoctor([
+    version,
+    host,
+    links,
+    settings,
+    pathMap,
+    neverSync,
+    repository,
+    sharedScan,
+    schemaScan,
+  ]);
 }

package/src/commands.drop-session.scrub-hint.ts

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
+import { log } from './utils.ts';
+import { encodePath, readJson } from './utils.json.ts';
+
+/**
+ * Repo-relative session-match shape `shared/projects/<logical>/...`; the single
+ * capture group is the `<logical>` segment fed to the path-map reverse lookup.
+ */
+const SHARED_PROJECT_LOGICAL = /^shared\/projects\/([^/]+)\//;
+
+/**
+ * After a successful drop, remind the operator that the unstage is per-push
+ * only: the leaked secret still lives in the local transcript, so the next
+ * `nomad push` re-copies it (via `remapPush`) and `nomad doctor --check-shared`
+ * keeps reporting it (it scans the live `~/.claude/projects/` source, not the
+ * repo index). Points at the exact live transcript when it resolves for this
+ * host, or a generic `~/.claude/projects/<encoded>/<id>.jsonl` template
+ * otherwise. Advisory output only; never mutates state.
+ *
+ * @param id Already-validated session id.
+ * @param matches Repo-relative paths collected by `collectMatches`.
+ */
+export function reportScrubHint(id: string, matches: string[]): void {
+  const live = resolveLiveTranscript(id, matches);
+  const target = live ?? `~/.claude/projects/<encoded>/${id}.jsonl`;
+  log(
+    'note: this only un-stages the session from the next push. The leaked secret\n' +
+      '  is still in your local transcript, so nomad push re-stages it and nomad\n' +
+      '  doctor --check-shared keeps reporting it. To remediate, rotate the\n' +
+      `  credential, then scrub ${target}`,
+  );
+}
+
+/**
+ * Reverse-map a dropped session to its live transcript
+ * `~/.claude/projects/<encoded>/<id>.jsonl` on THIS host via `path-map.json`
+ * (`<logical>` -> `hosts[HOST]` -> `encodePath`). Best-effort: returns the path
+ * only when it resolves AND exists on disk; null when `path-map.json` is
+ * absent or malformed, no match maps to this host, or the live file is already
+ * gone. A `'TBD'` host placeholder also yields null (its bogus path never
+ * exists). The whole body is wrapped so a malformed map (parse error, `null`
+ * projects) degrades to the generic hint instead of crashing the drop.
+ *
+ * @param id Already-validated session id.
+ * @param matches Repo-relative paths collected by `collectMatches`.
+ * @returns Absolute live transcript path, or null when unresolvable.
+ */
+function resolveLiveTranscript(id: string, matches: string[]): string | null {
+  try {
+    const mapPath = join(REPO_HOME, 'path-map.json');
+    if (!existsSync(mapPath)) return null;
+    const projects = readJson<PathMap>(mapPath).projects;
+    for (const rel of matches) {
+      const logical = SHARED_PROJECT_LOGICAL.exec(rel)?.[1];
+      /* c8 ignore next -- defensive: every collectMatches path is rooted at shared/projects/<logical>/ */
+      if (logical === undefined) continue;
+      const abs = projects[logical]?.[HOST];
+      // A 'TBD' host placeholder needs no special case: encodePath('TBD') yields
+      // a directory that cannot exist among the absolute-path-encoded dirs, so
+      // the existsSync guard below rejects it and falls through to the generic.
+      if (abs === undefined) continue;
+      const live = join(CLAUDE_HOME, 'projects', encodePath(abs), `${id}.jsonl`);
+      if (existsSync(live)) return live;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/commands.drop-session.ts

@@ -4,6 +4,7 @@ import { join, relative } from 'node:path';
 
 import { REPO_HOME } from './config.ts';
 import { expandStagedDir, isInIndex, isTrackedInHead } from './commands.drop-session.git.ts';
+import { reportScrubHint } from './commands.drop-session.scrub-hint.ts';
 import { die, fail, log, NomadFatal } from './utils.ts';
 import { acquireLock, releaseLock } from './utils.lockfile.ts';
 
@@ -13,7 +14,9 @@ import { acquireLock, releaseLock } from './utils.lockfile.ts';
  * lock, collects every staged path matching the flat `<id>.jsonl` and the
  * sibling subagent directory `<id>/` (via `collectMatches`), then unstages
  * each (via `unstageOne`). This closes the leak where a "dropped" session
- * still shipped its subagent transcripts.
+ * still shipped its subagent transcripts. A successful drop ends with
+ * `reportScrubHint`, which reminds the operator that the unstage is per-push
+ * only and points at the live transcript that still needs scrubbing.
  *
  * Idempotent: entries not in the index are skipped silently. Exits 0 on
  * any drop (including an idempotent re-run); exits 1 with `✗ no staged
@@ -53,6 +56,7 @@ export function cmdDropSession(id: string): void {
       throw new NomadFatal(`no staged session matches ${id}`);
     }
     for (const rel of matches) unstageOne(rel);
+    reportScrubHint(id, matches);
   } catch (err) {
     // Defensive escape hatch: only fires if a non-NomadFatal error escapes
     // the try block. All execFileSync mutation failures are wrapped in