claude-nomad 0.27.0 → 0.29.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.29.1](https://github.com/funkadelic/claude-nomad/compare/v0.29.0...v0.29.1) (2026-05-29)
+
+
+### Fixed
+
+* **doctor:** degrade gitleaks-absent probe to WARN, not FAIL ([#173](https://github.com/funkadelic/claude-nomad/issues/173)) ([320bb8a](https://github.com/funkadelic/claude-nomad/commit/320bb8a5d6f6c1f02207be8e186fe678f8e6f8bd))
+
+## [0.29.0](https://github.com/funkadelic/claude-nomad/compare/v0.28.0...v0.29.0) (2026-05-29)
+
+
+### Added
+
+* sync hook scripts and tool support dirs across hosts ([#171](https://github.com/funkadelic/claude-nomad/issues/171)) ([e340fd2](https://github.com/funkadelic/claude-nomad/commit/e340fd221882f9107f4e10c3a64ccd7be4061a14))
+
+## [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)
 
 

package/README.md

@@ -45,6 +45,7 @@ box, a personal rig and a work machine. [Get started in three steps.](#quickstar
   - [Repo layout](#repo-layout-what-claude-nomad-looks-like-on-a-configured-host)
   - [What gets synced vs. not](#what-gets-synced-vs-not)
   - [Path remapping](#path-remapping)
+  - [Shared support dirs (sharedDirs)](#shared-support-dirs-shareddirs)
   - [Per-host overrides](#per-host-overrides)
   - [What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs)
 - **Getting started**
@@ -67,7 +68,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
@@ -113,6 +114,7 @@ public funkadelic/claude-nomad          your private <your-username>/claude-noma
                                           │   ├── skills/
                                           │   ├── commands/
                                           │   ├── rules/
+                                          │   ├── hooks/
                                           │   ├── settings.base.json
                                           │   └── projects/
                                           ├── hosts/<hostname>.json
@@ -143,6 +145,7 @@ so a clobbered dotfile variable does not break the CLI.
 │   ├── skills/
 │   ├── commands/
 │   ├── rules/
+│   ├── hooks/                # hook scripts, symlinked into ~/.claude/hooks/
 │   ├── my-statusline.cjs     # any script you want symlinked into ~/.claude/
 │   ├── .gitignore            # defense-in-depth: blocks .claude.json, settings.local.json, *.token, *.key, *.pem, id_rsa, id_ed25519, .env, .env.*
 │   ├── projects/             # session transcripts under logical names
@@ -157,16 +160,35 @@ 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/`, `hooks/`, `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>/`.                                                                |
+| **Shared support dirs** | Opt-in global `~/.claude/` dirs like a tool's `get-shit-done/`                          | Opt-in via the `sharedDirs` field in `path-map.json`; symlinked into `~/.claude/` from `shared/`. See [Shared support dirs](#shared-support-dirs-shareddirs). |
+| **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` (and the optional `sharedDirs` field in
+  `path-map.json` -- see [Shared support dirs](#shared-support-dirs-shareddirs)), **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), `.credentials.json` (OAuth
+  credential store), `history.jsonl`, `settings.local.json` (per-host overrides),
+  `stats-cache.json`, `todos/`, `shell-snapshots/`, `debug/`, `file-history/`, `plans/`,
+  `session-env/`, `statsig/`, `telemetry/`, `ide/`, plus host-local caches and runtime state
+  (`cache/`, `backups/`, `paste-cache/`, `daemon/`, `jobs/`, `tasks/`, `security/`, `sessions/`).
+  This set is also the deny-list the `sharedDirs` opt-in is checked against, so one of these names
+  cannot be symlinked into the shared repo by mistake.
+- **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 +219,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.
 
@@ -225,6 +249,55 @@ copy and prints a per-file WARN naming anything that differs.
 Your existing local content is backed up under `~/.cache/claude-nomad/backup/<ts>/extras/` before
 the pull copy lands, so an unexpected overwrite is always recoverable.
 
+## Shared support dirs (sharedDirs)
+
+Some tools install a `hooks` block into `settings.json` whose commands point at scripts under
+`~/.claude/hooks/` (and sometimes a support directory such as `~/.claude/get-shit-done/`). Because
+`settings.json` is regenerated on every pull, that hook configuration travels to every host, but the
+scripts it points at did not, so hooks broke on a freshly configured host. `~/.claude/hooks/` is now
+a built-in synced link (it rides the same symlink model as `skills/` and `agents/`), so hook scripts
+travel automatically.
+
+For any other global `~/.claude/` support directory a tool needs, the optional top-level
+`sharedDirs` field in `path-map.json` opts it into the same symlink sync:
+
+```json
+{
+  "projects": {
+    "my-example-repo": {
+      "<your-mac>": "/Users/you/code/my-example-repo"
+    }
+  },
+  "sharedDirs": ["get-shit-done"]
+}
+```
+
+What this means for you: each listed name is symlinked from `shared/<name>` into `~/.claude/<name>`
+(the same model as the built-in synced links, not a copy), so editing it on any host updates the one
+shared copy. The field is additive and back-compatible: a `path-map.json` without it behaves exactly
+as before.
+
+Entries are validated before anything is linked. A name is accepted only if it is a single path
+segment (no `/`, no `..`), is not one of the never-synced names, and does not collide with a
+reserved `shared/` name (`settings.base.json`, the built-in synced links, `hooks`, `hosts`,
+`path-map.json`). An invalid entry is dropped with a warning rather than aborting the run. The
+contents still go through the same gitleaks scan as everything else on push, so do not point
+`sharedDirs` at a directory that holds credentials.
+
+First-time setup on an already-configured repo: a symlink can only form once the directory exists
+under `shared/`. On a fresh repo `nomad init --snapshot` handles this for you. To add `hooks/` (or a
+new `sharedDirs` entry) to a repo that is already set up, move it into `shared/` once on the host
+that has it, then let the normal flow take over:
+
+```bash
+$ mv ~/.claude/hooks ~/claude-nomad/shared/hooks   # one-time, on the source host
+$ nomad pull                                        # re-creates ~/.claude/hooks as a symlink
+$ nomad push                                        # shares it with your other hosts
+```
+
+`nomad pull` never writes back to the remote, so it will not seed `shared/` for you; the one-time
+move is deliberate.
+
 ## Per-host overrides
 
 `settings.base.json` holds portable defaults (model, permissions, plugins).
@@ -249,17 +322,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 +381,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 +411,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.**
 
@@ -516,27 +599,35 @@ point under your npm prefix's `bin/`), then delete the alias line from your shel
 
 ## Commands
 
-| Command                          | Description                                                                                                                                                                                                                                                                                                                                              |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nomad init`                     | Scaffold empty `shared/`, `hosts/`, `path-map.json` on a fresh clone. Refuses to clobber existing scaffold. Auto-disables Actions on a detected private GitHub mirror (see [Privacy by default](#privacy-by-default)).                                                                                                                                   |
-| `nomad init --snapshot`          | Overlay current host's `~/.claude/` into `shared/` and write `~/.claude/settings.json` verbatim into `hosts/<NOMAD_HOST>.json`. Originals not modified. Same auto-disable behavior as `nomad init`.                                                                                                                                                      |
-| `nomad init --keep-actions`      | Skip the auto-disable. Combinable with `--snapshot`. Use when an upstream org policy already governs Actions, or you intentionally want CI on the private mirror.                                                                                                                                                                                        |
-| `nomad pull`                     | `git pull --rebase --autostash`, apply symlinks, regenerate `settings.json`, remap session paths, and pull opted-in per-project extras. Errors out if scaffold missing.                                                                                                                                                                                  |
-| `nomad pull --dry-run`           | Network-aware preview: acquire lock + `git pull --rebase`, print planned changes (symlink moves, `settings.json` diff, transcript overwrites), exit without writing.                                                                                                                                                                                     |
-| `nomad diff`                     | Offline, lockless twin of `pull --dry-run`. No network, no lock. Works against the current local repo state.                                                                                                                                                                                                                                             |
-| `nomad push`                     | Export local sessions and opted-in per-project extras to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                                                                                                                                                  |
-| `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list) 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 --version`                | Print the installed CLI version as bare semver to stdout; exits 0. Used by the npm-publish smoke test and useful for ad-hoc upgrade checks.                                                                                                                                                                                                              |
+| Command                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nomad init`                     | Scaffold empty `shared/`, `hosts/`, `path-map.json` on a fresh clone. Refuses to clobber existing scaffold. Auto-disables Actions on a detected private GitHub mirror (see [Privacy by default](#privacy-by-default)).                                                                                                                                                                                                                                                       |
+| `nomad init --snapshot`          | Overlay current host's `~/.claude/` into `shared/` and write `~/.claude/settings.json` verbatim into `hosts/<NOMAD_HOST>.json`. Originals not modified. Same auto-disable behavior as `nomad init`.                                                                                                                                                                                                                                                                          |
+| `nomad init --keep-actions`      | Skip the auto-disable. Combinable with `--snapshot`. Use when an upstream org policy already governs Actions, or you intentionally want CI on the private mirror.                                                                                                                                                                                                                                                                                                            |
+| `nomad pull`                     | `git pull --rebase --autostash`, apply symlinks, regenerate `settings.json`, remap session paths, and pull opted-in per-project extras. Errors out if scaffold missing.                                                                                                                                                                                                                                                                                                      |
+| `nomad pull --dry-run`           | Network-aware preview: acquire lock + `git pull --rebase`, print planned changes (symlink moves, `settings.json` diff, transcript overwrites), exit without writing.                                                                                                                                                                                                                                                                                                         |
+| `nomad diff`                     | Offline, lockless twin of `pull --dry-run`. No network, no lock. Works against the current local repo state.                                                                                                                                                                                                                                                                                                                                                                 |
+| `nomad push`                     | Export local sessions and opted-in per-project extras to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                                                                                                                                                                                                                                                                      |
+| `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list) 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, a Hook targets check that fails (`✗`, exit 1) when `settings.json` references a hook command whose script under `~/.claude/` is missing on this host, 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
 install is behind the latest upstream release, and `✓ claude-nomad: <local> (latest)` when current.
 It silently skips on network failures.
 
+The Hook targets check reads the live `~/.claude/settings.json` `hooks` block and fails (`✗`, exit
+
+1. when a hook command points at a script under `~/.claude/` that is missing on this host (the
+   freshly-configured-host symptom that motivated syncing `hooks/`). It deliberately skips any
+   command it cannot resolve to a `~/.claude/` path (bare binaries like `jq`, unresolved env vars),
+   so it never false-fails on a command that does not reference a local script.
+
 Two further `⚠︎`-only drift checks run in `nomad doctor`. The gitleaks version-drift line
 `⚠︎ gitleaks: <local> -> <pinned> (...)` fires when the local gitleaks major.minor differs from the
 CI-pinned `GITLEAKS_PINNED_VERSION` (gitleaks rule and allowlist behavior tracks the minor line, so
@@ -614,8 +705,9 @@ synced, or a `⚠︎` warning naming the counts when something was skipped:
 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
+`✗` 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.
 
@@ -662,6 +754,13 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.27.0",
+  "version": "0.29.1",
   "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.check-shared.scan.ts

@@ -83,10 +83,10 @@ function reportRemediation(
     const logical = logicalBySession.get(sid);
     /* c8 ignore next -- false branch is defensive; every bySession sid is keyed in logicalBySession */
     if (logical !== undefined) {
-      addItem(
-        section,
-        `  ${dim(`- rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`)}`,
+      const rotateLine = dim(
+        `- rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`,
       );
+      addItem(section, `  ${rotateLine}`);
     }
   }
   addItem(section, `  ${dim('- false positive? add a pattern to .gitleaks.toml')}`);
@@ -147,7 +147,8 @@ function emitDescriptionLegend(section: DoctorSection, findings: Finding[]): voi
   addItem(section, '');
   addItem(section, bold('Finding types'));
   for (const [rule, desc] of descByRule) {
-    addItem(section, `  ${red(`- [${rule}]`)}: ${dim(desc)}`);
+    const ruleLabel = red(`- [${rule}]`);
+    addItem(section, `  ${ruleLabel}: ${dim(desc)}`);
   }
 }
 

package/src/commands.doctor.checks.hooks.ts

@@ -0,0 +1,176 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { dim, failGlyph, green, infoGlyph, okGlyph, red } from './color.ts';
+import { addItem, readJsonSafe, type DoctorSection } from './commands.doctor.format.ts';
+import { CLAUDE_HOME, HOME } from './config.ts';
+
+/**
+ * Always-on `nomad doctor` reporter. Reads `~/.claude/settings.json`, walks
+ * every `{ type: "command", command }` entry in the `hooks` block, and FAILs
+ * with `process.exitCode = 1` for each command token that confidently resolves
+ * to a path under `~/.claude` but is missing on disk. Commands with no
+ * resolvable `~/.claude` path (bare binaries, unresolved env vars) are silently
+ * skipped per D-09: the check only surfaces the issue-#170 case of synced hook
+ * config pointing at unsynced local scripts.
+ */
+
+/**
+ * Expand a leading `~`, `$HOME`, or `${HOME}` to the resolved HOME directory so
+ * the resulting path can be passed to `existsSync` and compared against the
+ * absolute `~/.claude` location. A token with no home-relative prefix (a bare
+ * binary, an already-absolute path) is returned unchanged.
+ *
+ * @param token - A raw path token extracted from a hook command string.
+ * @returns The path with any leading home-relative syntax resolved to HOME.
+ */
+function expandHome(token: string): string {
+  return token
+    .replace(/^\$\{HOME\}/, HOME)
+    .replace(/^\$HOME/, HOME)
+    .replace(/^~/, HOME);
+}
+
+/**
+ * Strip shell quoting and trailing control punctuation from a raw command
+ * token so a real path is not mistaken for a missing one. Without this, a
+ * quoted compound command like `bash -c 'a.sh; ~/.claude/hooks/run.sh'` yields
+ * the token `~/.claude/hooks/run.sh'` (trailing quote), and `existsSync` would
+ * FAIL on a script that is actually present (a D-09 false-FAIL). Removes
+ * leading quotes and any trailing run of `'"`;)|&>` characters. A genuine path
+ * never carries these on its boundary, so stripping them is safe.
+ *
+ * @param token - A raw whitespace-delimited token from a command segment.
+ * @returns The token with boundary shell punctuation removed.
+ */
+function stripShellPunctuation(token: string): string {
+  return token.replace(/^['"]+/, '').replace(/['"`;)|&>]+$/, '');
+}
+
+/**
+ * Yield every command token that resolves to a path under `~/.claude`. Each
+ * `&&`-, `||`-, `;`-, or `|`-separated sub-command is scanned token by token
+ * (not just its leading word), so wrappers like `bash ~/.claude/hooks/run.sh`
+ * are caught and not just `~/.claude/hooks/run.sh` on its own. Every token is
+ * stripped of shell quoting and home-expanded before comparison, so the
+ * literal `~`, `$HOME`, and `${HOME}` forms collapse to one check. Tokens that
+ * do not resolve under `~/.claude` (bare binaries, flags, unresolved env vars)
+ * are skipped per D-09, so the check only ever FAILs on a real `~/.claude`
+ * target.
+ *
+ * @param command - The raw `command` string from a hook entry.
+ * @returns Iterable of absolute resolved paths under `~/.claude`.
+ */
+function* claudePathsIn(command: string): Iterable<string> {
+  const claudePrefix = `${CLAUDE_HOME}/`;
+  for (const segment of command.split(/&&|\|\||;|\|/)) {
+    for (const raw of segment.trim().split(/\s+/).filter(Boolean)) {
+      const expanded = expandHome(stripShellPunctuation(raw));
+      if (expanded.startsWith(claudePrefix)) yield expanded;
+    }
+  }
+}
+
+/**
+ * A hook entry in flat format: `{ type: "command"; command: string }`.
+ * Used internally by `commandsFromFlat` to narrow the parsed JSON shape.
+ */
+type FlatEntry = { type: unknown; command?: unknown };
+
+/**
+ * Yield command strings from a flat-format entry list (each element is
+ * directly `{ type: "command", command: string }`). Skips non-object and
+ * non-command entries silently (T-25-07 defence).
+ *
+ * @param entries - Array of flat hook entries to walk.
+ */
+function* commandsFromFlat(entries: unknown[]): Iterable<string> {
+  for (const entry of entries) {
+    if (typeof entry !== 'object' || entry === null) continue;
+    const e = entry as FlatEntry;
+    if (e.type === 'command' && typeof e.command === 'string') yield e.command;
+  }
+}
+
+/**
+ * Yield every `{ type: "command"; command: string }` entry from a single
+ * hook group, which may be a flat array entry or a grouped object with a
+ * nested `hooks` array. Non-object / non-command entries are silently skipped
+ * (D-09 / T-25-07 defence: malformed input degrades to skips, never throws).
+ *
+ * @param group - One element of a hooks event array.
+ * @returns Iterable of command strings from command-type entries.
+ */
+function* commandsFromGroup(group: unknown): Iterable<string> {
+  if (typeof group !== 'object' || group === null) return;
+  const g = group as Record<string, unknown>;
+  // Grouped shape: { matcher?, hooks: HookEntry[] }
+  if (Array.isArray(g.hooks)) {
+    yield* commandsFromFlat(g.hooks);
+    return;
+  }
+  // Flat shape: the group itself is { type: "command", command: string }
+  if (g.type === 'command' && typeof g.command === 'string') yield g.command;
+}
+
+/**
+ * Walk all hook groups for a single event and emit FAIL items for every
+ * resolved-but-missing `~/.claude` target. Returns true when at least one
+ * FAIL was emitted (used by the caller to suppress the OK summary line).
+ *
+ * @param section - Doctor section to append items to.
+ * @param event - Hook event name (e.g. `PostToolUse`).
+ * @param groups - Array of hook groups for this event.
+ * @returns True when any missing target was found.
+ */
+function checkEventGroups(section: DoctorSection, event: string, groups: unknown[]): boolean {
+  let anyFail = false;
+  for (const group of groups) {
+    for (const cmd of commandsFromGroup(group)) {
+      for (const resolved of claudePathsIn(cmd)) {
+        if (existsSync(resolved)) continue;
+        addItem(section, `${red(failGlyph)} hooks/${event}: command target missing: ${resolved}`);
+        process.exitCode = 1;
+        anyFail = true;
+      }
+    }
+  }
+  return anyFail;
+}
+
+/**
+ * Append the Hook-targets check result to the supplied section. Reads
+ * `~/.claude/settings.json`, walks every command entry in the `hooks` block,
+ * and emits a `✗` FAIL for each `~/.claude` target that is absent on disk.
+ * Commands with no resolvable local path are silently skipped (D-09).
+ * Emits a `✓` OK line when all resolvable targets exist (or none were found).
+ * Emits a `ℹ︎` info skip when `settings.json` is absent.
+ *
+ * @param section - The doctor section to append items to.
+ */
+export function reportHooksTargetCheck(section: DoctorSection): void {
+  const settingsPath = join(CLAUDE_HOME, 'settings.json');
+  if (!existsSync(settingsPath)) {
+    addItem(section, `${dim(infoGlyph)} no ~/.claude/settings.json; skipping hook target check`);
+    return;
+  }
+
+  const settings = readJsonSafe<Record<string, unknown>>(settingsPath, settingsPath, section);
+  if (settings === null) return;
+
+  const hooks = settings.hooks;
+  if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
+    addItem(section, `${green(okGlyph)} hooks: all command targets present`);
+    return;
+  }
+
+  let anyFail = false;
+  for (const [event, groups] of Object.entries(hooks as Record<string, unknown>)) {
+    if (!Array.isArray(groups)) continue;
+    if (checkEventGroups(section, event, groups)) anyFail = true;
+  }
+
+  if (!anyFail) {
+    addItem(section, `${green(okGlyph)} hooks: all command targets present`);
+  }
+}