claude-nomad 0.25.4 → 0.26.0

package/README.md

@@ -1,22 +1,41 @@
 # claude-nomad
 
 [![tests](https://img.shields.io/github/actions/workflow/status/funkadelic/claude-nomad/tests.yml?branch=main&label=tests)](https://github.com/funkadelic/claude-nomad/actions/workflows/tests.yml)
-[![release](https://img.shields.io/github/v/release/funkadelic/claude-nomad?label=release&sort=semver)](https://github.com/funkadelic/claude-nomad/releases)
-[![coverage](https://img.shields.io/codecov/c/github/funkadelic/claude-nomad/main?label=coverage)](https://codecov.io/gh/funkadelic/claude-nomad)
+[![codeql](https://img.shields.io/github/actions/workflow/status/funkadelic/claude-nomad/codeql.yml?branch=main&label=codeql)](https://github.com/funkadelic/claude-nomad/actions/workflows/codeql.yml)
+[![codecov](https://codecov.io/gh/funkadelic/claude-nomad/graph/badge.svg?token=5NML626POS)](https://codecov.io/gh/funkadelic/claude-nomad)
+[![NPM Version](https://img.shields.io/npm/v/claude-nomad?logo=npm)](https://www.npmjs.com/package/claude-nomad)
+[![node](https://img.shields.io/node/v/claude-nomad?logo=nodedotjs)](https://www.npmjs.com/package/claude-nomad)
+[![license](https://img.shields.io/npm/l/claude-nomad)](LICENSE)
 
 ![claude-nomad - Sync your Claude Code setup. Same environment. Any machine.](docs/hero.svg)
 
 **Your entire Claude Code setup, on every machine. History included, every push secret-scanned.**
 
-Open Claude Code on a second machine and it is a blank slate: none of your custom agents, slash commands, tuned settings, or past conversations. claude-nomad keeps all of it in sync through a private Git repo you control. `nomad push` on one machine, `nomad pull` on the next, and everything is there, conversations included.
-
-- **Resume your sessions on any machine.** Start a conversation on your desktop and pick it up on your laptop. claude-nomad remaps the file paths Claude Code embeds in every transcript, so your history follows you instead of getting stranded on the box where it started.
-- **Secret-scanned, private by default.** Your `~/.claude/` also holds OAuth tokens, MCP credentials, and the full text of every conversation, so claude-nomad is deliberate about what leaves your machine: credentials and ephemeral state never sync, only an explicit allow-list of paths is pushed, and everything that does go up is scanned by [gitleaks](https://github.com/gitleaks/gitleaks) before it leaves your machine; the push aborts on any hit. `nomad init` also disables Actions on your private mirror by default, so transcripts can't leak through CI logs.
-- **One setup, every machine.** Your agents, skills, slash commands, and settings live in one place and follow you everywhere. Per-machine tweaks like model choice, MCP URLs, and env vars merge on top instead of clobbering your shared defaults.
-
-Not dotfiles, not rsync. claude-nomad understands Claude Code's state, so your session history survives different file paths and your secrets never ride along.
-
-For anyone running Claude Code on more than one machine: a laptop and a desktop, a Mac and a WSL box, a personal rig and a work machine. [Get started in three steps.](#quickstart)
+Open Claude Code on a second machine and it is a blank slate: none of your custom agents, slash
+commands, tuned settings, or past conversations. **claude-nomad** keeps all of it in sync through a
+private Git repo you control. `nomad push` on one machine, `nomad pull` on the next, and everything
+is there, conversations included.
+
+- **Resume your Claude Code [sessions](https://code.claude.com/docs/en/agent-sdk/sessions) on any
+  machine.** Start a conversation on your desktop and pick it up on your laptop. **claude-nomad**
+  remaps the file paths Claude Code embeds in every transcript, so your history follows you instead
+  of getting stranded on the box where it started.
+- **Secret-scanned, private by default.** Your `~/.claude/` also holds OAuth tokens, MCP
+  credentials, and the full text of every conversation, so **claude-nomad** is deliberate about what
+  leaves your machine: credentials and ephemeral state never sync, only an explicit allow-list of
+  paths is pushed, and everything that does go up is scanned by
+  [gitleaks](https://github.com/gitleaks/gitleaks) before it leaves your machine; the push aborts on
+  any hit. `nomad init` also disables Actions on your private mirror by default, so transcripts
+  can't leak through CI logs.
+- **One setup, every machine.** Your agents, skills, slash commands, and settings live in one place
+  and follow you everywhere. Per-machine tweaks like model choice, MCP URLs, and env vars merge on
+  top instead of clobbering your shared defaults.
+
+Not dotfiles, not rsync. **claude-nomad** understands Claude Code's state, so your session history
+survives different file paths and your secrets never ride along.
+
+For anyone running Claude Code on more than one machine: a laptop and a desktop, a Mac and a WSL
+box, a personal rig and a work machine. [Get started in three steps.](#quickstart)
 
 ## Table of contents
 
@@ -47,7 +66,8 @@ For anyone running Claude Code on more than one machine: a laptop and a desktop,
 
 ## 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:
+If you already have a private **claude-nomad** mirror (see [Setup](#setup) for the one-time
+bootstrap), adding a new host is three steps:
 
 ```bash
 $ npm i -g claude-nomad
@@ -73,13 +93,16 @@ $ nomad pull     # apply config to ~/.claude/
 $ nomad push     # publish local changes (sessions, settings)
 ```
 
-First-host bootstrap and the safe-migration sequence for a populated `~/.claude/` are in [Setup](#setup) and [Migrating an existing ~/.claude/](#migrating-an-existing-claude).
+First-host bootstrap and the safe-migration sequence for a populated `~/.claude/` are in
+[Setup](#setup) and [Migrating an existing ~/.claude/](#migrating-an-existing-claude).
 
 ## How it works (two-repo model)
 
-claude-nomad is a **tool**, not a config store. You maintain a separate **private** repo that holds your actual config (`CLAUDE.md`, agents, skills, settings overrides, session transcripts). The tool's source and your config end up coexisting in one working tree on each host.
+**claude-nomad** is a **tool**, not a config store. You maintain a separate **private** repo that
+holds your actual config (`CLAUDE.md`, agents, skills, settings overrides, session transcripts). The
+tool's source and your config end up coexisting in one working tree on each host.
 
-```
+```text
 public funkadelic/claude-nomad          your private <your-username>/claude-nomad
   ├── src/         (the CLI)              ├── src/         (copy of the CLI)
   ├── package.json                        ├── package.json
@@ -96,13 +119,20 @@ public funkadelic/claude-nomad          your private <your-username>/claude-noma
                                           └── path-map.json
 ```
 
-You bootstrap once by mirror-pushing this public tool repo into a fresh private repo of your own (see [Setup](#setup)), then layer your config on top. Every host afterward installs the CLI (`npm i -g claude-nomad`), clones your private repo to `~/claude-nomad/`, and runs `nomad pull` to sync.
+You bootstrap once by mirror-pushing this public tool repo into a fresh private repo of your own
+(see [Setup](#setup)), then layer your config on top. Every host afterward installs the CLI
+(`npm i -g claude-nomad`), clones your private repo to `~/claude-nomad/`, and runs `nomad pull` to
+sync.
 
-By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config.ts`). Developers working from an alternate checkout can `export NOMAD_REPO=/path/to/repo` to point the CLI at their working tree without symlink gymnastics; `nomad doctor` surfaces an active override via a trailing `(NOMAD_REPO)` annotation on the repo-state line. Empty `NOMAD_REPO` falls through to the default, so a clobbered dotfile variable does not break the CLI.
+By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config.ts`). Developers
+working from an alternate checkout can `export NOMAD_REPO=/path/to/repo` to point the CLI at their
+working tree without symlink gymnastics; `nomad doctor` surfaces an active override via a trailing
+`(NOMAD_REPO)` annotation on the repo-state line. Empty `NOMAD_REPO` falls through to the default,
+so a clobbered dotfile variable does not break the CLI.
 
 ## Repo layout (what `~/claude-nomad/` looks like on a configured host)
 
-```
+```text
 ~/claude-nomad/
 ├── src/                      # the CLI (came from the public tool repo)
 ├── scripts/                  # helper scripts you add
@@ -136,16 +166,21 @@ By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config
 | **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 URLs) still need that side set up on each host. Put them in `hosts/<host>.json` or the plugin's own per-host config.
+> [!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.
 
-For the rationale behind these choices, see [What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs).
+For the rationale behind these choices, see
+[What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs).
 
 ## Path remapping
 
-The hard problem: Claude Code stores sessions in `~/.claude/projects/<encoded-path>/` where the encoded path is the absolute path with `/` replaced by `-`. So the same logical project ends up in different directories on each host.
+The hard problem: Claude Code stores sessions in `~/.claude/projects/<encoded-path>/` where the
+encoded path is the absolute path with `/` replaced by `-`. So the same logical project ends up in
+different directories on each host.
 
-`path-map.json` defines logical names and where the repo lives on each host. The optional `extras` block opts a project into syncing whitelisted directories (or a single root file) at its root:
+`path-map.json` defines logical names and where the repo lives on each host. The optional `extras`
+block opts a project into syncing whitelisted directories (or a single root file) at its root:
 
 ```json
 {
@@ -162,22 +197,44 @@ The hard problem: Claude Code stores sessions in `~/.claude/projects/<encoded-pa
 }
 ```
 
-> [!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.
+> [!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.
 
-Use the literal string `"TBD"` for hosts you haven't onboarded yet; `remapPull` skips TBD entries cleanly instead of creating an orphan `~/.claude/projects/TBD/`. Replace each `"TBD"` with the real path when you bring up that host.
+Use the literal string `"TBD"` for hosts you haven't onboarded yet; `remapPull` skips TBD entries
+cleanly instead of creating an orphan `~/.claude/projects/TBD/`. Replace each `"TBD"` with the real
+path when you bring up that host.
 
-On `push`, sessions in `~/.claude/projects/-Users-you-code-my-example-repo/` get copied to `shared/projects/my-example-repo/`. On `pull` on another machine, they get copied to that host's encoded path. `claude --resume` then finds them (see [What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs) for the cross-OS cwd-binding gotcha).
+On `push`, sessions in `~/.claude/projects/-Users-you-code-my-example-repo/` get copied to
+`shared/projects/my-example-repo/`. On `nomad pull` on another machine, they get copied to that
+host's encoded path. `claude --resume` then finds them (see
+[What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs) for the
+cross-OS cwd-binding gotcha).
 
-The `extras` block is additive and back-compatible: legacy `path-map.json` files without it keep working unchanged. Each value is an array of directory or root-file names (e.g. `.planning`, `CLAUDE.md`) checked against `SUPPORTED_EXTRAS` in `src/config.ts`; anything outside that whitelist is skipped with a log line, so an unrecognized name cannot widen the sync surface.
+The `extras` block is additive and back-compatible: legacy `path-map.json` files without it keep
+working unchanged. Each value is an array of directory or root-file names (e.g. `.planning`,
+`CLAUDE.md`) checked against `SUPPORTED_EXTRAS` in `src/config.ts`; anything outside that whitelist
+is skipped with a log line, so an unrecognized name cannot widen the sync surface.
 
-On `push`, opted-in content at `<localRoot>/<name>` (a directory subtree or a single file) is copied to `shared/extras/<logical>/<name>` and goes through the same staged-tree gitleaks scan as everything else. On `pull`, the reverse copy runs after `git pull --rebase`, and just before it overwrites your working tree a divergence check compares the incoming content against your local copy and prints a per-file WARN naming anything that differs.
+On `nomad push`, opted-in content at `<localRoot>/<name>` (a directory subtree or a single file) is
+copied to `shared/extras/<logical>/<name>` and goes through the same staged-tree gitleaks scan as
+everything else. On `nomad pull`, the reverse copy runs after `git pull --rebase`, and just before
+it overwrites your working tree a divergence check compares the incoming content against your local
+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.
+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.
 
 ## Per-host overrides
 
-`settings.base.json` holds portable defaults (model, permissions, plugins). `hosts/<NOMAD_HOST>.json` holds machine-specific patches. They're deep-merged on every pull (scalars override, objects merge recursively, arrays replace). Keys that used to be force-marked per-host because they embedded absolute paths (`statusLine.command`, `hooks`) can live in base if you write the commands with `$HOME` (e.g. `"command": "node \"$HOME/.claude/my-statusline.cjs\""`); Claude Code runs them through a shell so shell expansion applies. Reserve per-host files for truly machine-specific values (env, MCP URLs, host-only model overrides).
+`settings.base.json` holds portable defaults (model, permissions, plugins).
+`hosts/<NOMAD_HOST>.json` holds machine-specific patches. They're deep-merged on every pull (scalars
+override, objects merge recursively, arrays replace). Keys that used to be force-marked per-host
+because they embedded absolute paths (`statusLine.command`, `hooks`) can live in
+`settings.base.json` if you write the commands with `$HOME` (e.g.
+`"command": "node \"$HOME/.claude/my-statusline.cjs\""`); Claude Code runs them through a shell so
+shell expansion applies. Reserve per-host files for truly machine-specific values (env, MCP URLs,
+host-only model overrides).
 
 `shared/settings.base.json`:
 
@@ -188,7 +245,7 @@ Your existing local content is backed up under `~/.cache/claude-nomad/backup/<ts
 }
 ```
 
-`hosts/<your-wsl-host>.json`:
+`hosts/<your-other-host>.json`:
 
 ```json
 {
@@ -197,10 +254,11 @@ Your existing local content is backed up under `~/.cache/claude-nomad/backup/<ts
 }
 ```
 
-Result on that host: opus model, the local Ollama env var, plus the shared permissions array.
+Results on `your-other-host`: opus 4.7, 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 `nomad pull` from base + host, so your edits will be clobbered. Edit the base or host file in the repo instead.
+> [!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.
 
 ## What does NOT sync (deliberate trade-offs)
 
@@ -209,39 +267,72 @@ Read these before adopting so you opt in with eyes open.
 - **Last-write-wins on conflicts.** Git surfaces them on merge; no field-level JSON merging.
 - **Manual push/pull.** No file watcher. Shell hooks recommended.
 - **OAuth doesn't sync.** You'll log in once per host. Intentional.
-- **Only sessions in `path-map.json` are remapped.** Drive-by sessions on un-mapped paths are left alone.
-- **Extras are opt-in and whitelisted.** Projects without an `extras` entry in `path-map.json` are unaffected. Names (a directory or a single root file) outside `SUPPORTED_EXTRAS` are skipped with a `skip ... not in SUPPORTED_EXTRAS` log line so an unrecognized name cannot widen the sync surface. Unsafe path-map values (path-traversal in `logical` keys, non-absolute or unnormalized `localRoot` values) abort the run before any file is touched, so a malformed entry fails loudly instead of corrupting state.
-- **Cross-OS `claude --resume` cwd binding.** Sessions embed the cwd where they were created, so the picker's `cd ... && claude --resume <id>` line fails on a different host. Use `nomad doctor --resume-cmd <id>` for a host-local equivalent (see [Cross-OS resume](#cross-os-resume)). The sidecar approach preserves transcript byte-equality.
-- **Empty directories don't survive sync.** Git doesn't track empty dirs; `nomad doctor` reports them as `missing` (benign). Drop a `.gitkeep` to force materialization.
+- **Only sessions in `path-map.json` are remapped.** Drive-by sessions on un-mapped paths are left
+  alone.
+- **Extras are opt-in and whitelisted.** Projects without an `extras` entry in `path-map.json` are
+  unaffected. Names (a directory or a single root file) outside `SUPPORTED_EXTRAS` are skipped with
+  a `skip ... not in SUPPORTED_EXTRAS` log line so an unrecognized name cannot widen the sync
+  surface. Unsafe path-map values (path-traversal in `logical` keys, non-absolute or unnormalized
+  `localRoot` values) abort the run before any file is touched, so a malformed entry fails loudly
+  instead of corrupting state.
+- **Cross-OS `claude --resume` cwd binding.** Sessions embed the cwd where they were created, so
+  Claude Code's picker's `cd ... && claude --resume <id>` line fails on a different host. Use
+  `nomad doctor --resume-cmd <id>` for a host-local equivalent (see
+  [Cross-OS resume](#cross-os-resume)). The sidecar approach preserves transcript byte-equality.
+- **Empty directories don't survive sync.** Git doesn't track empty dirs; `nomad doctor` reports
+  them as `missing` (benign). Drop a `.gitkeep` to force materialization.
 
 ## Requirements
 
-- Node.js 22.22.1 or newer (24 LTS recommended; the npm `engines` field declares the 22.22.1 floor and surfaces a warning on older runtimes - npm only blocks the install when `engine-strict=true` is configured)
-- `tsx` (ships as a runtime dependency of the published package; no separate global install required)
+- Node.js 22.22.1 or newer (24 LTS recommended; the npm `engines` field declares the 22.22.1 floor
+  and surfaces a warning on older runtimes - npm only blocks the install when `engine-strict=true`
+  is configured)
+- `tsx` (ships as a runtime dependency of the published package; no separate global install
+  required)
 - Git
-- [`gitleaks`](https://github.com/gitleaks/gitleaks) (required for `nomad push`, which exits with an error if it is not on PATH; `nomad doctor` also checks it against the pinned 8.30.x and warns when it is absent or mismatched)
+- [`gitleaks`](https://github.com/gitleaks/gitleaks) (required for `nomad push`, which exits with an
+  error if it is not on PATH; `nomad doctor` also checks it against the pinned 8.30.x and warns when
+  it is absent or mismatched)
 - A **private** GitHub repo (or any Git remote you control)
 
-**Optional:**
+**Optional, but recommended:**
 
-- `gh` (GitHub CLI), 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`, 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
+- `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
 
 ## Setup
 
-**Why not just fork?** GitHub doesn't let you flip a public fork to private, and your config (especially session transcripts) must stay private. So the bootstrap is a one-time mirror-push into a fresh private repo, not a fork.
+**Why not just fork?** GitHub doesn't let you flip a public fork to private, and your config
+(especially session transcripts) must stay private. So the bootstrap is a one-time mirror-push into
+a fresh private repo, not a fork.
 
 ### Privacy by default
 
-When you mirror-push the tool into your repo, you copy its automation along with its code: the `.github/workflows/` directory holds the public project's own CI (running its test suite, linting, secret and code scanning, release tagging, and npm publishing). That CI is meant for the public project, not your config; if it ran on your private mirror, a job could echo transcript contents into build logs. So your mirror gets two independent layers of defense against that, both applied automatically:
+When you mirror-push the tool into your repo, you copy its automation along with its code: the
+`.github/workflows/` directory holds the public project's own CI (running its test suite, linting,
+secret and code scanning, release tagging, and npm publishing). That CI is meant for the public
+project, not your config; if it ran on your private mirror, a job could echo transcript contents
+into build logs. So your mirror gets two independent layers of defense against that, both applied
+automatically:
 
-1. **The workflows are written to skip private repos.** Each one carries the run condition `${{ !github.event.repository.private }}` (in plain terms: "run only when this repo is NOT private"), so even with Actions enabled the jobs do not run on your mirror.
-2. **`nomad init` turns Actions off for the whole repo** on first run, via the GitHub API call `gh api -X PUT repos/<owner>/<repo>/actions/permissions -F enabled=false`. This needs the `gh` CLI installed and authed; if it is missing or unauthed, init logs a manual fallback tip and continues.
+1. **The workflows are written to skip private repos.** Each one carries the run condition
+   `${{ !github.event.repository.private }}` (in plain terms: "run only when this repo is NOT
+   private"), so even with Actions enabled the jobs do not run on your mirror.
+2. **`nomad init` turns Actions off for the whole repo** on first run, via the GitHub API call
+   `gh api -X PUT repos/<owner>/<repo>/actions/permissions -F enabled=false`. This needs the `gh`
+   CLI installed and authed; if it is missing or unauthed, init logs a manual fallback tip and
+   continues.
 
-Pass `--keep-actions` to either form of init to skip step 2 (for example, when your org already enforces an Actions policy upstream).
+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 every `nomad push` against `main`, and your session transcripts (which include conversation content) become world-readable. Keep it private.
+> [!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.**
 
 ### Bootstrap
 
@@ -254,10 +345,10 @@ $ gh repo create <your-username>/claude-nomad --private
 # 2. Copy the public tool into your private repo. A bare clone followed by a
 #    mirror push makes a complete, independent copy (every branch and tag) with
 #    no fork link back to upstream, which is what lets you keep it private. Once, ever.
-$ git clone --bare git@github.com:funkadelic/claude-nomad.git /tmp/cn.git # download a full copy
-$ cd /tmp/cn.git
+$ git clone --bare git@github.com:funkadelic/claude-nomad.git /tmp/claude-nomad.git # download a full copy
+$ cd /tmp/claude-nomad.git
 $ git push --mirror git@github.com:<your-username>/claude-nomad.git # upload it to your private repo
-$ cd .. && rm -rf /tmp/cn.git
+$ cd .. && rm -rf /tmp/claude-nomad.git
 
 # 3. Install the CLI globally and clone your private copy. Repeat on every host.
 $ npm i -g claude-nomad
@@ -267,15 +358,22 @@ $ git clone git@github.com:<your-username>/claude-nomad.git ~/claude-nomad
 export NOMAD_HOST=<your-host-label>      # any short, stable label; nomad reads this instead of os.hostname()
 ```
 
-`npm i -g claude-nomad` puts a `nomad` binary on your PATH. The bin shim is the existing `src/nomad.ts` entrypoint resolved through tsx (a runtime dependency); no compile step. (The Node version floor and the `engine-strict` caveat are in [Requirements](#requirements).)
+`npm i -g claude-nomad` puts a `nomad` binary on your PATH. The bin shim is the existing
+`src/nomad.ts` entrypoint resolved through tsx (a runtime dependency); no compile step. (The Node
+version floor and the `engine-strict` caveat are in [Requirements](#requirements).)
 
-On every additional host you repeat only steps 3-4; steps 1-2 are already done, since your private repo lives on the remote from step 2.
+On every additional host you repeat only steps 3-4; steps 1-2 are already done, since your private
+repo lives on the remote from step 2.
 
-`NOMAD_HOST` overrides `os.hostname()`, which returns noisy values like `WINDOWS-I5NT6OH` on WSL or `<name>.local` on macOS. Pick a clean label per machine (e.g., `wsl-laptop`, `macbook`, `homelab-nuc`). `nomad doctor` reports the resolved host so you can confirm.
+`NOMAD_HOST` overrides `os.hostname()`, which returns noisy values like `WINDOWS-I5NT6OH` on WSL or
+`<name>.local` on macOS. Pick a clean label per machine (e.g., `wsl-laptop`, `macbook`,
+`homelab-nuc`). `nomad doctor` reports the resolved host so you can confirm.
 
 ### Initialize the repo layout
 
-First host only; subsequent hosts just clone and `nomad pull`. Both forms below auto-disable Actions on a detected private GitHub mirror as described in [Privacy by default](#privacy-by-default). Pick one:
+First host only; subsequent hosts just clone and `nomad pull`. Both forms below auto-disable Actions
+on a detected private GitHub mirror as described in [Privacy by default](#privacy-by-default). Pick
+one:
 
 ```bash
 # Fresh start: scaffold an empty shared/, hosts/, path-map.json skeleton.
@@ -285,12 +383,12 @@ $ nomad init
 # starting point. Stages shared/ and writes hosts/<NOMAD_HOST>.json from
 # your current ~/.claude/settings.json. Does NOT touch the originals.
 $ nomad init --snapshot
-
-# Either form accepts --keep-actions to skip the auto-disable.
-$ nomad init --keep-actions
 ```
 
-`nomad init` refuses to clobber existing scaffold artifacts, so re-running on a populated repo is a safe no-op (it errors out naming the offender). `nomad pull` against an unscaffolded repo fails fast with `FATAL: repo not initialized; run 'nomad init' to scaffold` instead of silently leaving a half-state.
+`nomad init` refuses to clobber existing scaffold artifacts, so re-running on a populated repo is a
+safe no-op (it errors out naming the offender). `nomad pull` against an unscaffolded repo fails fast
+with `FATAL: repo not initialized; run 'nomad init' to scaffold` instead of silently leaving a
+half-state.
 
 Edit `path-map.json` to add your logical projects (see [Path remapping](#path-remapping)), then:
 
@@ -302,13 +400,19 @@ $ nomad push                  # send current state to the private remote
 $ nomad pull                  # apply on another host (or this one after a remote update)
 ```
 
-`nomad pull --dry-run` is the network-aware twin of `nomad diff`: it acquires the lock and runs `git pull` so you see what the next real pull would do given the latest remote, then exits without mutating.
+`nomad pull --dry-run` is the network-aware twin of `nomad diff`: it acquires the lock and runs
+`git pull` so you see what the next real pull would do given the latest remote, then exits without
+mutating.
 
-If the destination host already has populated `~/.claude/{CLAUDE.md, agents/, ...}`, the first `nomad pull` will refuse to overwrite real files. See [Migrating an existing ~/.claude/](#migrating-an-existing-claude) for the safe migration flow.
+If the destination host already has populated `~/.claude/{CLAUDE.md, agents/, ...}`, the first
+`nomad pull` will refuse to overwrite real files. See
+[Migrating an existing ~/.claude/](#migrating-an-existing-claude) for the safe migration flow.
 
 ## Migrating an existing ~/.claude/
 
-If a host already has real files at `~/.claude/{CLAUDE.md, agents/, skills/, ...}` and you want to bring them into the sync, the required sequence is `nomad init --snapshot` → `nomad push` → `nomad pull`:
+If a host already has real files at `~/.claude/{CLAUDE.md, agents/, skills/, ...}` and you want to
+bring them into the sync, the required sequence is `nomad init --snapshot` → `nomad push` →
+`nomad pull`:
 
 ```bash
 # From the host that has the canonical config (the originals are not modified):
@@ -319,22 +423,44 @@ $ nomad push              # publish the captured state to the private remote
 $ nomad pull              # materializes the symlinks
 ```
 
-`nomad pull` is what actually migrates the host. `applySharedLinks` runs a two-pass scan: any pre-existing non-symlink at a `SHARED_LINKS` path whose counterpart exists under `shared/` is renamed into `~/.cache/claude-nomad/backup/<ts>/` first, then the symlink is created. Your originals are preserved under that timestamped backup directory, not deleted. Paths whose `shared/<name>` is absent from the remote are left untouched, so a partial publish does not delete data on the destination host.
+`nomad pull` is what actually migrates the host. `applySharedLinks` runs a two-pass scan: any
+pre-existing non-symlink at a `SHARED_LINKS` path whose counterpart exists under `shared/` is
+renamed into `~/.cache/claude-nomad/backup/<ts>/` first, then the symlink is created. Your originals
+are preserved under that timestamped backup directory, not deleted. Paths whose `shared/<name>` is
+absent from the remote are left untouched, so a partial publish does not delete data on the
+destination host.
 
-If the remote has not been populated yet (you skipped `nomad init --snapshot` and `nomad push`), `nomad pull` is a no-op for SHARED_LINKS: there is nothing on the remote to symlink against, so your local `~/.claude/` files stay in place. The auto-move only triggers once the canonical state is published.
+If the remote has not been populated yet (you skipped `nomad init --snapshot` and `nomad push`),
+`nomad pull` is a no-op for SHARED_LINKS: there is nothing on the remote to symlink against, so your
+local `~/.claude/` files stay in place. The auto-move only triggers once the canonical state is
+published.
 
-Prefer an explicit tarball rollback and a confirmation prompt before any deletion? Write the equivalent under `scripts/`: tar the `SHARED_LINKS` entries under `~/.claude/` first, copy into `shared/`, prompt, then `nomad pull`. The auto-move path above is the recommended default.
+Prefer an explicit tarball rollback and a confirmation prompt before any deletion? Write the
+equivalent under `scripts/`: tar the `SHARED_LINKS` entries under `~/.claude/` first, copy into
+`shared/`, prompt, then `nomad pull`. The auto-move path above is the recommended default.
 
 ## Upgrading the tool
 
 Two different things can fall behind, and they update independently:
 
-- **The `nomad` CLI binary** (what runs when you type `nomad`). If you installed it with `npm i -g claude-nomad`, upgrade it with `npm update -g claude-nomad`. This refreshes only the binary on your PATH; it does not touch anything inside your private `~/claude-nomad/` repo.
-- **The synced tool files inside your private repo:** `src/`, `.gitleaks.toml` (the secret-scan allowlist), and the `.github/workflows/` privacy gating. These were copied from the public repo at bootstrap and then froze, so `npm update -g` does not refresh them. `nomad update`, run from `~/claude-nomad/`, is what pulls newer versions of these files in. Topology-aware: detects vanilla vs fork remotes, pulls or merges upstream, and re-runs `npm install` when `package-lock.json` shifted.
-
-Most people who followed the Quickstart need both: `npm update -g` for the binary, and an occasional `nomad update` for the repo files (notably to receive `.gitleaks.toml` allowlist changes and any update to the privacy gating itself). The mirror-push bootstrap leaves your repo with `origin` on your private mirror and no `upstream` remote; that becomes the "fork" topology `nomad update` expects once you add the upstream remote (the one-time `git remote add upstream ...` step is below).
-
-Your private repo is not a fork, so GitHub's "Sync fork" UI doesn't apply. The shortcut on a source-checkout host is:
+- **The `nomad` CLI binary** (what runs when you type `nomad`). If you installed it with
+  `npm i -g claude-nomad`, upgrade it with `npm update -g claude-nomad`. This refreshes only the
+  binary on your PATH; it does not touch anything inside your private `~/claude-nomad/` repo.
+- **The synced tool files inside your private repo:** `src/`, `.gitleaks.toml` (the secret-scan
+  allowlist), and the `.github/workflows/` privacy gating. These were copied from the public repo at
+  bootstrap and then froze, so `npm update -g` does not refresh them. `nomad update`, run from
+  `~/claude-nomad/`, is what pulls newer versions of these files in. Topology-aware: detects vanilla
+  vs fork remotes, pulls or merges upstream, and re-runs `npm install` when `package-lock.json`
+  shifted.
+
+Most people who followed the Quickstart need both: `npm update -g` for the binary, and an occasional
+`nomad update` for the repo files (notably to receive `.gitleaks.toml` allowlist changes and any
+update to the privacy gating itself). The mirror-push bootstrap leaves your repo with `origin` on
+your private mirror and no `upstream` remote; that becomes the "fork" topology `nomad update`
+expects once you add the upstream remote (the one-time `git remote add upstream ...` step is below).
+
+Your private repo is not a fork, so GitHub's "Sync fork" UI doesn't apply. The shortcut on a
+source-checkout host is:
 
 ```bash
 $ cd ~/claude-nomad
@@ -344,11 +470,23 @@ $ nomad update
 `nomad update` detects which layout your `~/claude-nomad/` uses and does the right thing:
 
 - **vanilla** (`origin` points at the public repo): `git pull --ff-only origin main`.
-- **fork** (`upstream` points at the public repo, `origin` points at your private mirror): `git fetch upstream`, then (before merging) commit any whitelisted `shared/extras/` content that is still untracked locally so an overlap with upstream becomes a normal file merge instead of an untracked-overwrite abort, `git merge upstream/main`, then prompt before pushing the merge to `origin/main`. Pass `--push-origin` to skip the prompt. When the merge is a no-op (HEAD unchanged, nothing new to push) the prompt is skipped entirely and `nomad update` logs `already in sync with origin/main`.
-
-Pre-flight checks run before any mutation: `REPO_HOME` exists, the topology resolves to `vanilla` or `fork`, the current branch is `main`, the working tree is clean (override with `--force`), and `--push-origin` is rejected on vanilla topology.
-
-After the merge or pull, `nomad update` re-runs `npm install` only when `package-lock.json` actually shifted, commits the regenerated `package-lock.json` (fork topology) if the reinstall changed it, then invokes `nomad doctor`. The trailing version-check is non-fatal: `✓` when local matches the latest release, `⚠︎` when behind, an informational `ℹ︎ ... ahead of latest release` line when ahead (e.g. a `-dev` build between releases), and silent on network failures.
+- **fork** (`upstream` points at the public repo, `origin` points at your private mirror):
+  `git fetch upstream`, then (before merging) commit any whitelisted `shared/extras/` content that
+  is still untracked locally so an overlap with upstream becomes a normal file merge instead of an
+  untracked-overwrite abort, `git merge upstream/main`, then prompt before pushing the merge to
+  `origin/main`. Pass `--push-origin` to skip the prompt. When the merge is a no-op (HEAD unchanged,
+  nothing new to push) the prompt is skipped entirely and `nomad update` logs
+  `already in sync with origin/main`.
+
+Pre-flight checks run before any mutation: `REPO_HOME` exists, the topology resolves to `vanilla` or
+`fork`, the current branch is `main`, the working tree is clean (override with `--force`), and
+`--push-origin` is rejected on vanilla topology.
+
+After the merge or pull, `nomad update` re-runs `npm install` only when `package-lock.json` actually
+shifted, commits the regenerated `package-lock.json` (fork topology) if the reinstall changed it,
+then invokes `nomad doctor`. The trailing version-check is non-fatal: `✓` when local matches the
+latest release, `⚠︎` when behind, an informational `ℹ︎ ... ahead of latest release` line when ahead
+(e.g. a `-dev` build between releases), and silent on network failures.
 
 Common cases:
 
@@ -365,9 +503,16 @@ One-time setup if you're running a fork layout and don't have the `upstream` rem
 $ git remote add upstream git@github.com:funkadelic/claude-nomad.git
 ```
 
-To pin to a specific release (`vX.Y.Z`, tagged by release-please) instead of tracking `main`, fetch tags from the public repo and check out the tag (detached HEAD). On vanilla topology that's `origin`; on fork topology that's `upstream` (the private mirror at `origin` does not accumulate upstream release tags). Example: `git fetch upstream --tags && git switch --detach vX.Y.Z` (substitute `origin` for vanilla; use `git checkout vX.Y.Z` on older Git).
+To pin to a specific release (`vX.Y.Z`, tagged by release-please) instead of tracking `main`, fetch
+tags from the public repo and check out the tag (detached HEAD). On vanilla topology that's
+`origin`; on fork topology that's `upstream` (the private mirror at `origin` does not accumulate
+upstream release tags). Example: `git fetch upstream --tags && git switch --detach vX.Y.Z`
+(substitute `origin` for vanilla; use `git checkout vX.Y.Z` on older Git).
 
-If you installed an earlier version via `./install.sh` and a shell alias (the pre-npm path), your existing alias keeps working unchanged. Run `npm i -g claude-nomad` whenever you're ready to switch to the global binary, confirm `nomad --version` resolves to the npm install (`which nomad` should point under your npm prefix's `bin/`), then delete the alias line from your shell rc.
+If you installed an earlier version via `./install.sh` and a shell alias (the pre-npm path), your
+existing alias keeps working unchanged. Run `npm i -g claude-nomad` whenever you're ready to switch
+to the global binary, confirm `nomad --version` resolves to the npm install (`which nomad` should
+point under your npm prefix's `bin/`), then delete the alias line from your shell rc.
 
 ## Commands
 
@@ -388,11 +533,23 @@ If you installed an earlier version via `./install.sh` and a shell alias (the pr
 | `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.                                                                                                                                                                                                              |
 
-The version-check emits ``⚠︎ version: <local> -> <latest> (run `nomad update`)`` when the local install is behind the latest upstream release, and `✓ version: <local> (latest)` when current. It silently skips on network failures.
+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.
 
-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 a patch-only difference stays `✓`), and is silent when gitleaks is not on PATH. The mirror-Actions line (carrying a `gh api -X PUT repos/<owner>/<repo>/actions/permissions -F enabled=false` remediation hint) fires when origin is a private GitHub mirror that is gh-authed with Actions 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).
+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
+a patch-only difference stays `✓`), and is silent when gitleaks is not on PATH. The mirror-Actions
+line (carrying a `gh api -X PUT repos/<owner>/<repo>/actions/permissions -F enabled=false`
+remediation hint) fires when origin is a private GitHub mirror that is gh-authed with Actions
+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:
+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:
 
 ```text
 ✓ summary: clean
@@ -400,32 +557,55 @@ Every `nomad pull`, `nomad push`, and `nomad diff` run ends with a single `summa
 ⚠︎ 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. 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.
 
 ## Recovery flows
 
 ### `nomad drop-session <id>`
 
-Surgically unstages every `shared/projects/*/<id>.jsonl` plus the sibling `shared/projects/*/<id>/` subagent directory (whose nested transcripts are keyed by the same session id) from the staged tree of `~/claude-nomad/`. The local `~/.claude/projects/<encoded>/<id>.jsonl` and the local `<id>/` tree are never touched.
+Surgically unstages every `shared/projects/*/<id>.jsonl` plus the sibling `shared/projects/*/<id>/`
+subagent directory (whose nested transcripts are keyed by the same session id) from the staged tree
+of `~/claude-nomad/`. The local `~/.claude/projects/<encoded>/<id>.jsonl` and the local `<id>/` tree
+are never touched.
 
 ```bash
 $ nomad drop-session <id>
 ```
 
-Single positional id (the session filename minus `.jsonl`). Anything else (missing id, leading dash, extra arg) exits 1 with a `usage:` line.
+Single positional id (the session filename minus `.jsonl`). Anything else (missing id, leading dash,
+extra arg) exits 1 with a `usage:` line.
 
-For each match in the staged tree, `cmdDropSession` (in `src/commands.drop-session.ts`) classifies the entry as tracked-in-HEAD vs newly-staged and unstages it via `git restore --staged --worktree --` or `git rm --cached -f --` respectively. The `<id>/` subagent directory is expanded into its staged entries via `git ls-files -z` so every nested transcript flows through the same per-entry classification; a session that has only a subagent directory (no flat `<id>.jsonl`) is still droppable. Idempotent: a second run on the same id sees no matching staged entries and exits 0.
+For each match in the staged tree, `cmdDropSession` (in `src/commands.drop-session.ts`) classifies
+the entry as tracked-in-HEAD vs newly-staged and unstages it via
+`git restore --staged --worktree --` or `git rm --cached -f --` respectively. The `<id>/` subagent
+directory is expanded into its staged entries via `git ls-files -z` so every nested transcript flows
+through the same per-entry classification; a session that has only a subagent directory (no flat
+`<id>.jsonl`) is still droppable. Idempotent: a second run on the same id sees no matching staged
+entries and exits 0.
 
 Exit codes:
 
 - `0` on any drop, including an idempotent re-run.
-- `1` with `✗ no staged session matches <id>` on stderr when neither a `shared/projects/*/<id>.jsonl` nor a `shared/projects/*/<id>/` directory with staged entries matches.
+- `1` with `✗ no staged session matches <id>` on stderr when neither a
+  `shared/projects/*/<id>.jsonl` nor a `shared/projects/*/<id>/` directory with staged entries
+  matches.
 
-What it does NOT do: touch the local `~/.claude/projects/<encoded>/<id>.jsonl` file or the local `<id>/` subagent tree. The local copies are preserved for `claude --resume`, grep recovery, or whatever the user wants. If the underlying secret is real, scrubbing or removing the local files is REQUIRED for durability, not optional housekeeping: `remapPush` (in `src/remap.ts`) re-mirrors the local content into the staged tree on the next push, so a drop without a local scrub re-stages the same secret.
+What it does NOT do: touch the local `~/.claude/projects/<encoded>/<id>.jsonl` file or the local
+`<id>/` subagent tree. The local copies are preserved for `claude --resume`, grep recovery, or
+whatever the user wants. If the underlying secret is real, scrubbing or removing the local files is
+REQUIRED for durability, not optional housekeeping: `remapPush` (in `src/remap.ts`) re-mirrors the
+local content into the staged tree on the next push, so a drop without a local scrub re-stages the
+same secret.
 
 ### Recovery flow: gitleaks FATAL on a session JSONL
 
-`nomad push` runs `gitleaks protect --staged` before commit. To catch the same findings before you push (and without mutating anything), run the read-only preflight `nomad doctor --check-shared`, which stages and scans the exact transcripts a push would publish. When findings live in a session transcript, the push aborts and names every affected session id and the recovery command:
+`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:
 
 ```text
 ✗ gitleaks detected secrets in 1 session transcript(s).
@@ -439,22 +619,38 @@ After recovery, re-run nomad push.
 
 Two branches from here:
 
-1. **Real secret.** Rotate the credential at its provider first (revoke in dashboard, issue replacement) before touching anything else. Running `nomad drop-session <sid-aaaa>` clears the contaminated copy from the current staged tree, but that alone is NOT durable: `remapPush` (in `src/remap.ts`) does a full rm-and-copy mirror of your LOCAL transcripts into `shared/projects/` on every push, so the next `nomad push` re-copies the un-scrubbed local file forward and re-stages the same secret. The durable fix is to rotate AND scrub or remove the local transcript at `~/.claude/projects/<encoded>/<sid-aaaa>.jsonl` (plus the sibling `<sid-aaaa>/` subagent directory under that encoded dir, if present) so the next `remapPush` carries clean content forward. Do not leave the local file un-scrubbed and expect the staged-tree drop to hold.
+1. **Real secret.** Rotate the credential at its provider first (revoke in dashboard, issue
+   replacement) before touching anything else. Running `nomad drop-session <sid-aaaa>` clears the
+   contaminated copy from the current staged tree, but that alone is NOT durable: `remapPush` (in
+   `src/remap.ts`) does a full rm-and-copy mirror of your LOCAL transcripts into `shared/projects/`
+   on every push, so the next `nomad push` re-copies the un-scrubbed local file forward and
+   re-stages the same secret. The durable fix is to rotate AND scrub or remove the local transcript
+   at `~/.claude/projects/<encoded>/<sid-aaaa>.jsonl` (plus the sibling `<sid-aaaa>/` subagent
+   directory under that encoded dir, if present) so the next `remapPush` carries clean content
+   forward. Do not leave the local file un-scrubbed and expect the staged-tree drop to hold.
 
-2. **False positive.** Add an allowlist regex to `.gitleaks.toml` at the repo root that matches the noise pattern but not real-secret formats, commit it, then re-run `nomad push`. The new allowlist propagates to deploy hosts via `nomad update`.
+2. **False positive.** Add an allowlist regex to `.gitleaks.toml` at the repo root that matches the
+   noise pattern but not real-secret formats, commit it, then re-run `nomad push`. The new allowlist
+   propagates to deploy hosts via `nomad update`.
 
-`nomad drop-session` only acts on the staged tree of `~/claude-nomad/`. Active Claude Code sessions writing to the local file are not disturbed.
+`nomad drop-session` only acts on the staged tree of `~/claude-nomad/`. Active Claude Code sessions
+writing to the local file are not disturbed.
 
 ### `.gitleaks.toml` allowlist policy
 
-`gitleaks protect` runs against the staged tree on every `nomad push` and can flag structurally-distinguishable tool-output noise as `generic-api-key`. The repo-root `.gitleaks.toml` pre-allows four such patterns so routine pushes are not blocked:
+`gitleaks protect` runs against the staged tree on every `nomad push` and can flag
+structurally-distinguishable tool-output noise as `generic-api-key`. The repo-root `.gitleaks.toml`
+pre-allows four such patterns so routine pushes are not blocked:
 
 - Sonar issue keys (`AY` prefix + 20+ url-safe chars).
 - gitleaks fingerprint format (`<context>:<rule>:<line>` emitted by gitleaks's own reports).
 - npm audit advisory hashes (anchored on the JSON shape `"id":"<40..64 hex>"`).
 - Coverage-report line-keys (`key=<hex> <path>:<line>`).
 
-The file extends the default gitleaks ruleset, so real high-entropy secrets like `ghp_*`, `sk_live_*`, `xoxb-*`, and `AKIA*` still fire. The allowlist patterns are structurally distinguishable from real-secret formats: a malformed credential cannot match an allowlist regex by accident.
+The file extends the default gitleaks ruleset, so real high-entropy secrets like `ghp_*`,
+`sk_live_*`, `xoxb-*`, and `AKIA*` still fire. The allowlist patterns are structurally
+distinguishable from real-secret formats: a malformed credential cannot match an allowlist regex by
+accident.
 
 ```toml
 [extend]
@@ -469,13 +665,23 @@ regexes = [
 ]
 ```
 
-File location: `.gitleaks.toml` at the public repo root (alongside `package.json`). At runtime both `probeGitleaks` (in `src/push-checks.ts`) and `runGitleaksScan` (in `src/push-gitleaks.ts`) conditionally pass `--config <REPO_HOME>/.gitleaks.toml` when the file exists. Hosts that have not yet run `nomad update` (or fresh clones predating the allowlist) fall back silently to the default gitleaks ruleset; there is no warning. Run `nomad update` to receive the latest allowlist.
+File location: `.gitleaks.toml` at the public repo root (alongside `package.json`). At runtime both
+`probeGitleaks` (in `src/push-checks.ts`) and `runGitleaksScan` (in `src/push-gitleaks.ts`)
+conditionally pass `--config <REPO_HOME>/.gitleaks.toml` when the file exists. Hosts that have not
+yet run `nomad update` (or fresh clones predating the allowlist) fall back silently to the default
+gitleaks ruleset; there is no warning. Run `nomad update` to receive the latest allowlist.
 
-Editing: amend `.gitleaks.toml` in this repo, open a PR, and merge to `main`. Use TOML literal strings (triple single quotes, `'''regex'''`) for new regex entries so backslashes do not need escaping. Verify the new pattern does not match real-secret formats (`ghp_<36>`, `sk_live_*`, `xoxb-*`, `AKIA[A-Z0-9]{16}`, etc.) before merging. The propagation path is the same as any other repo update: `nomad update` on each host pulls the new file in.
+Editing: amend `.gitleaks.toml` in this repo, open a PR, and merge to `main`. Use TOML literal
+strings (triple single quotes, `'''regex'''`) for new regex entries so backslashes do not need
+escaping. Verify the new pattern does not match real-secret formats (`ghp_<36>`, `sk_live_*`,
+`xoxb-*`, `AKIA[A-Z0-9]{16}`, etc.) before merging. The propagation path is the same as any other
+repo update: `nomad update` on each host pulls the new file in.
 
 ## Cross-OS resume
 
-Claude Code embeds the original `cwd` in each session transcript. When you resume on a different host where that path doesn't exist, the picker prints a `cd <orig-cwd> && claude --resume <id>` line that fails (the source-host path isn't there).
+Claude Code embeds the original `cwd` in each session transcript. When you resume on a different
+host where that path doesn't exist, the picker prints a `cd <orig-cwd> && claude --resume <id>` line
+that fails (the source-host path isn't there).
 
 Run this instead:
 
@@ -489,7 +695,10 @@ Or pipe through bash:
 $ nomad doctor --resume-cmd <session-id> | bash
 ```
 
-`nomad doctor --resume-cmd <id>` reads the `.jsonl`'s recorded `cwd`, reverse-looks up the logical project in `path-map.json`, finds your current host's abspath for that logical, and prints `cd <local-abspath> && claude --resume <id>` to stdout. The command is read-only: it never modifies any transcript byte.
+`nomad doctor --resume-cmd <id>` reads the `.jsonl`'s recorded `cwd`, reverse-looks up the logical
+project in `path-map.json`, finds your current host's abspath for that logical, and prints
+`cd <local-abspath> && claude --resume <id>` to stdout. The command is read-only: it never modifies
+any transcript byte.
 
 If the session isn't mapped on this host, you'll see:
 
@@ -497,7 +706,10 @@ If the session isn't mapped on this host, you'll see:
 ✗ session <id> not mapped on this host; add the logical to path-map.json
 ```
 
-Other fatal surfaces: missing `~/.claude/projects/`, session id absent from every encoded dir, no `cwd` field anywhere in the transcript, missing `path-map.json`, recorded cwd not present in any logical's host map. All errors go to stderr prefixed with the red `✗` fail glyph; the success line goes to stdout as a bare shell command (no glyph) so `eval` works.
+Other fatal surfaces: missing `~/.claude/projects/`, session id absent from every encoded dir, no
+`cwd` field anywhere in the transcript, missing `path-map.json`, recorded cwd not present in any
+logical's host map. All errors go to stderr prefixed with the red `✗` fail glyph; the success line
+goes to stdout as a bare shell command (no glyph) so `eval` works.
 
 ## Run tests