claude-nomad 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.25.0](https://github.com/funkadelic/claude-nomad/compare/v0.24.0...v0.25.0) (2026-05-25)
+
+
+### Added
+
+* **doctor:** add gitleaks version and mirror-Actions drift checks ([#125](https://github.com/funkadelic/claude-nomad/issues/125)) ([8a16e0c](https://github.com/funkadelic/claude-nomad/commit/8a16e0c274bb7b961c6fd2df9912874c572023ee))
+* **extras:** support a single root file as an extras entry ([#132](https://github.com/funkadelic/claude-nomad/issues/132)) ([6303b62](https://github.com/funkadelic/claude-nomad/commit/6303b62de84406da6a7fa2b7eb7af28a0473d0aa))
+
+
+### Fixed
+
+* **drop-session:** cascade unstage into subagent transcript directory ([#120](https://github.com/funkadelic/claude-nomad/issues/120)) ([7f10d51](https://github.com/funkadelic/claude-nomad/commit/7f10d5135a7eaa9b6e74fb1aa863506a7b914a09))
+* **push,update:** handle untracked extras in allow-list and fork merge ([#122](https://github.com/funkadelic/claude-nomad/issues/122)) ([e710a48](https://github.com/funkadelic/claude-nomad/commit/e710a48973a7c4e7479a9671d5891458a182dac7))
+* **update:** skip push prompt when fork merge is a no-op ([#123](https://github.com/funkadelic/claude-nomad/issues/123)) ([77fdb20](https://github.com/funkadelic/claude-nomad/commit/77fdb20244a096e44a1fecd0a283e3401a78972d))
+
+
+### Changed
+
+* pin workflow actions to SHAs and drop persisted CI credentials ([#130](https://github.com/funkadelic/claude-nomad/issues/130)) ([b60109c](https://github.com/funkadelic/claude-nomad/commit/b60109c0cbb5dff1b13c4155cc12c3d98ce1b141))
+
+
+### Documentation
+
+* add CONTRIBUTING, PR template, and SECURITY policy ([#131](https://github.com/funkadelic/claude-nomad/issues/131)) ([774eb58](https://github.com/funkadelic/claude-nomad/commit/774eb58a36af032f7d1cd109d59f313c4ff6affa))
+* lead README with a benefit-first pitch ([#133](https://github.com/funkadelic/claude-nomad/issues/133)) ([289e299](https://github.com/funkadelic/claude-nomad/commit/289e2994fd7dffb10818fe02aad64b193ad800b6))
+* **readme:** foreground secret-safety in the intro ([#126](https://github.com/funkadelic/claude-nomad/issues/126)) ([e661e9f](https://github.com/funkadelic/claude-nomad/commit/e661e9f02247fc30630fd90d5facc65aa7b4f2a0))
+
+
+### Dependencies
+
+* bump SonarSource/sonarqube-scan-action from 8.0.0 to 8.1.0 ([#127](https://github.com/funkadelic/claude-nomad/issues/127)) ([603f20d](https://github.com/funkadelic/claude-nomad/commit/603f20d9a22528c8df19d328c91a02012690836c))
+* bump the dev-dependencies group across 1 directory with 2 updates ([#128](https://github.com/funkadelic/claude-nomad/issues/128)) ([50b1b87](https://github.com/funkadelic/claude-nomad/commit/50b1b87b7288eed60280843504e6ccc2598f10b0))
+* bump tsx from 4.22.2 to 4.22.3 in the prod-dependencies group ([#129](https://github.com/funkadelic/claude-nomad/issues/129)) ([a7ada00](https://github.com/funkadelic/claude-nomad/commit/a7ada000ec2d3dbee132c7b61dc207012e53c1c3))
+
 ## [0.24.0](https://github.com/funkadelic/claude-nomad/compare/v0.23.0...v0.24.0) (2026-05-24)
 
 

package/README.md

@@ -6,17 +6,17 @@
 
 ![claude-nomad - Sync your Claude Code setup. Same environment. Any machine.](docs/hero.svg)
 
-Claude Code's state is per-machine. Your `CLAUDE.md`, custom agents, skills, slash commands, settings, and session history live in `~/.claude/` and don't follow you to your laptop, your work machine, or your homelab box.
+**Your entire Claude Code setup, on every machine. History included, secrets excluded.**
 
-claude-nomad keeps all of it in sync through a private Git repo you control. `nomad push` on one machine, `nomad pull` on another, and your full setup is there, including past sessions you can resume.
+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.
 
-**Who this is 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, or any combination. If you've ever felt the friction of starting fresh on a second machine or copying files around by hand, this is for you.
+- **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.
+- **Private by default.** Your `~/.claude/` also holds OAuth tokens, MCP credentials, and the full text of every conversation. Every push is secret-scanned before it leaves your machine, credentials and ephemeral state never sync, and `nomad init` disables CI on your private mirror by default, so transcripts can't leak through Actions 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.
 
-Three things it does that ad-hoc dotfiles syncing can't:
+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.
 
-- **Session history survives path differences.** The same project at `/Users/norm/code/foo` on your Mac and `/home/norm/foo` on Linux gets remapped automatically, so `claude --resume` finds your past conversations on whichever machine you're on.
-- **Per-host settings via deep merge.** Shared defaults live in one file; machine-specific overrides (model choice, MCP server URLs, env vars, hooks) live in a per-host file. They're merged on every pull instead of overwriting each other.
-- **Per-project content rides along, opt-in.** Whitelisted directories at a project's root (declared via `path-map.json`'s `extras` field) sync alongside session transcripts, so project-attached state like `.planning/` follows you across hosts. Off by default; projects without an `extras` entry behave exactly as before.
+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
 
@@ -114,7 +114,7 @@ By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config
 │   ├── commands/
 │   ├── rules/
 │   ├── my-statusline.cjs     # any script you want symlinked into ~/.claude/
-│   ├── .gitignore            # defense-in-depth: blocks .claude.json, settings.local.json, *.token, *.key, .env
+│   ├── .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
 │   └── extras/               # opt-in per-project content (materializes when path-map.json declares extras)
 ├── hosts/
@@ -127,14 +127,14 @@ By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config
 
 ## 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 whitelisted by `SUPPORTED_EXTRAS` in `src/config.ts`                                                                                                                                       | Opt-in via the `extras` field in `path-map.json`. Mirrored to/from `shared/extras/<logical>/<dirname>/`. 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. |
+| 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 URLs) still need that side set up on each host. Put them in `hosts/<host>.json` or the plugin's own per-host config.
@@ -145,7 +145,7 @@ For the rationale behind these choices, see [What does NOT sync (deliberate trad
 
 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 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
 {
@@ -157,7 +157,7 @@ The hard problem: Claude Code stores sessions in `~/.claude/projects/<encoded-pa
     }
   },
   "extras": {
-    "ha-acwd": [".planning"]
+    "ha-acwd": [".planning", "CLAUDE.md"]
   }
 }
 ```
@@ -169,7 +169,7 @@ Use the literal string `"TBD"` for hosts you haven't onboarded yet; `remapPull`
 
 On `push`, sessions in `~/.claude/projects/-Users-you-code-ha-acwd/` get copied to `shared/projects/ha-acwd/`. 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).
 
-The `extras` block is additive and back-compatible: legacy `path-map.json` files without it continue to work unchanged. Each value is an array of directory names validated against `SUPPORTED_EXTRAS` in `src/config.ts`; values outside the whitelist are skipped with a log line so an unrecognized name cannot widen the sync surface. On `push`, opted-in directories at `<localRoot>/<dirname>/` are copied to `shared/extras/<logical>/<dirname>/` and inherit the staged-tree gitleaks scan. On `pull`, the reverse copy runs after `git pull --rebase`; just before it overwrites your working tree, a divergence check compares the incoming content against your local copy and emits a per-file WARN naming the diverging files. The existing local content is backed up to `~/.cache/claude-nomad/backup/<ts>/extras/<encoded-localRoot>/<rel>/` before the pull copy lands (`<encoded-localRoot>` is the `localRoot` with `/` rewritten as `-`, so two opted-in projects with the same relative extras path do not collide in one backup run).
+The `extras` block is additive and back-compatible: legacy `path-map.json` files without it continue to work unchanged. Each value is an array of directory or root-file names (e.g. `.planning`, `CLAUDE.md`) validated against `SUPPORTED_EXTRAS` in `src/config.ts`; values outside the whitelist are 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 inherits the staged-tree gitleaks scan. On `pull`, the reverse copy runs after `git pull --rebase`; just before it overwrites your working tree, a divergence check compares the incoming content against your local copy and emits a per-file WARN naming the diverging files. The existing local content is backed up to `~/.cache/claude-nomad/backup/<ts>/extras/<encoded-localRoot>/<rel>/` before the pull copy lands (`<encoded-localRoot>` is the `localRoot` with `/` rewritten as `-`, so two opted-in projects with the same relative extras path do not collide in one backup run).
 
 ## Per-host overrides
 
@@ -206,7 +206,7 @@ Read these before adopting so you opt in with eyes open.
 - **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. Dirnames 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) FATAL before any filesystem mutation via `assertSafeLogical` / `assertSafeLocalRoot` in `src/extras-sync.ts`.
+- **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) FATAL before any filesystem mutation via `assertSafeLogical` / `assertSafeLocalRoot` in `src/extras-sync.ts`.
 - **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.
 
@@ -334,9 +334,9 @@ nomad update
 `nomad update` (see `cmdUpdate` in `src/commands.update.ts`) 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`, `git merge upstream/main`, then prompt before pushing the merge to `origin/main`. Pass `--push-origin` to skip the prompt.
+- **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, topology resolves to `vanilla` or `fork`, current branch is `main`, working tree is clean per `git status --porcelain -z` (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, 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.
+Pre-flight checks run before any mutation: `REPO_HOME` exists, topology resolves to `vanilla` or `fork`, current branch is `main`, working tree is clean per `git status --porcelain -z` (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:
 
@@ -369,15 +369,17 @@ If you installed an earlier version via `./install.sh` and a shell alias (the pr
 | `nomad diff`                     | Offline, lockless twin of `pull --dry-run`. No network, no lock. Works against the current local repo state.                                                                                                                                                                                                                                             |
 | `nomad push`                     | Export local sessions and opted-in per-project extras to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                                                                                                                                                  |
 | `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list); skip stage, scan, commit, and push.                                                                                                                                                                                                                        |
-| `nomad drop-session <id>`        | Surgically unstage every `shared/projects/*/<id>.jsonl` from the staged tree of `~/claude-nomad/`. Idempotent; the local `~/.claude/projects/<encoded>/<id>.jsonl` is preserved. See [Recovery flows](#recovery-flows).                                                                                                                                  |
+| `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.                                                                                                                                               |
+| `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.                                                                                                                                                                                                              |
 
 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.
 
+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:
 
 ```text
@@ -392,7 +394,7 @@ Every `nomad pull`, `nomad push`, and `nomad diff` run ends with a single `summa
 
 ### `nomad drop-session <id>`
 
-Surgically unstages every `shared/projects/*/<id>.jsonl` from the staged tree of `~/claude-nomad/`. The local `~/.claude/projects/<encoded>/<id>.jsonl` is 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>
@@ -400,14 +402,14 @@ 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.
 
-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. Idempotent: a second run on the same id sees no matching staged file 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 no `shared/projects/*/<id>.jsonl` 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. The local copy is preserved for `claude --resume`, grep recovery, or whatever the user wants. If the underlying secret is real, scrub the local file separately.
+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, scrub the local files separately.
 
 ### Recovery flow: gitleaks FATAL on a session JSONL
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "description": "Sync Claude Code config (~/.claude/) across machines via a private Git repo, with path remapping and per-host settings overrides.",
   "keywords": [

package/src/commands.doctor.gitleaks-version.ts

@@ -0,0 +1,132 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { green, okGlyph, warnGlyph, yellow } from './color.ts';
+import { addItem, type DoctorSection } from './commands.doctor.format.ts';
+import { GITLEAKS_PINNED_VERSION, REPO_HOME } from './config.ts';
+import type { SpawnSyncFn } from './gh-actions.ts';
+
+/**
+ * Soft gitleaks version-drift check appended to the Version section of
+ * `nomad doctor`. Parses `gitleaks version` stdout and compares its
+ * major.minor against `GITLEAKS_PINNED_VERSION` (the value CI installs),
+ * emitting one of:
+ *   - `✓ gitleaks: X.Y.Z (matches pinned A.B)` when major.minor agree
+ *   - `⚠︎ gitleaks: <local> -> <pin> (CI pins this; local drift may change scan results)`
+ *     when major.minor diverge
+ * Only major.minor is compared: a patch-only difference is treated as OK,
+ * because gitleaks rule/allowlist behavior tracks the minor line, not the
+ * patch. Every failure path (gitleaks absent, subprocess error, unparseable
+ * or two-segment output) is a SILENT skip; this module never sets
+ * `process.exitCode` and never writes to stderr, mirroring the sibling
+ * release-version and node-engine checks.
+ */
+
+/** Strict three-segment matcher capturing major and minor. Anchored on both
+ * ends so a two-segment string like `8.30` does not parse (feeding such a
+ * value to a triple-segment comparator would be undecidable). */
+const SEMVER_MAJOR_MINOR = /^(\d+)\.(\d+)\.\d+$/;
+
+/** Hard cap on the `gitleaks version` subprocess (matching the gh-actions
+ * primitives' `GH_TIMEOUT_MS` convention) so a wedged binary cannot hang the
+ * synchronous doctor run; the timeout throws and is swallowed as a silent skip. */
+const GITLEAKS_TIMEOUT_MS = 5_000;
+
+/**
+ * Capture the `[major, minor]` pair from a strict `X.Y.Z` semver string.
+ * Returns `null` when the input does not match a three-segment semver (e.g. a
+ * two-segment `8.30`, or non-numeric noise), which the caller treats as a
+ * silent skip.
+ *
+ * @param value - Candidate version string (already trimmed).
+ * @returns A `[major, minor]` tuple of bare numeric strings, or `null`.
+ */
+function majorMinorOf(value: string): [string, string] | null {
+  const m = SEMVER_MAJOR_MINOR.exec(value);
+  return m === null ? null : [m[1], m[2]];
+}
+
+/**
+ * Run `gitleaks version` via the injected runner and return the trimmed
+ * stdout, or `null` on any throw (missing binary, subprocess failure). Mirrors
+ * the `probeGitleaks` invocation form in `push-checks.ts`: argv-array
+ * `execFileSync` (no shell), piped stdio, and a conditional
+ * `--config <REPO_HOME>/.gitleaks.toml` when that allowlist exists at call
+ * time, plus a `GITLEAKS_TIMEOUT_MS` cap so a wedged binary cannot hang the
+ * synchronous doctor run. Swallowing the error here is what makes both the
+ * absent-gitleaks case and a timeout a silent skip rather than a doctor failure.
+ *
+ * @param run - Injectable subprocess runner; defaults to `execFileSync`.
+ * @param tomlExists - Injectable allowlist-file existence check; defaults to
+ *   `existsSync`. Injected in tests so the `--config` branch is exercised
+ *   independent of the host filesystem (REPO_HOME varies per host and in CI).
+ * @returns The trimmed `gitleaks version` output, or `null` on any failure.
+ */
+function readGitleaksVersion(
+  run: SpawnSyncFn,
+  tomlExists: (path: string) => boolean,
+): string | null {
+  const tomlPath = join(REPO_HOME, '.gitleaks.toml');
+  const args: string[] = ['version'];
+  if (tomlExists(tomlPath)) args.push('--config', tomlPath);
+  try {
+    return run('gitleaks', args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: GITLEAKS_TIMEOUT_MS,
+    })
+      .toString()
+      .trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Emit a single, non-fatal gitleaks version-drift diagnostic for
+ * `nomad doctor` by comparing the host's `gitleaks version` major.minor to
+ * `GITLEAKS_PINNED_VERSION`.
+ *
+ * Logs one of:
+ * - `✓ gitleaks: X.Y.Z (matches pinned A.B)` when the major.minor agree
+ *   (including a patch-only difference from the pin)
+ * - `⚠︎ gitleaks: <local> -> <pin> (...)` when the major.minor diverge
+ *
+ * A missing gitleaks binary, a subprocess error, or output that does not match
+ * a strict `X.Y.Z` semver results in no output and does not change
+ * `process.exitCode`.
+ *
+ * @param section - The Version section to append the diagnostic line to.
+ * @param run - Injectable subprocess runner; defaults to `execFileSync`.
+ * @param tomlExists - Injectable allowlist-file existence check; defaults to
+ *   `existsSync`. Mirrors the `run` seam so tests cover the `--config` branch
+ *   deterministically.
+ */
+export function reportGitleaksVersionCheck(
+  section: DoctorSection,
+  run: SpawnSyncFn = execFileSync,
+  tomlExists: (path: string) => boolean = existsSync,
+): void {
+  const raw = readGitleaksVersion(run, tomlExists);
+  if (raw === null) return;
+  const local = majorMinorOf(raw);
+  if (local === null) return;
+  const pin = majorMinorOf(GITLEAKS_PINNED_VERSION);
+  // Defensive: GITLEAKS_PINNED_VERSION is a hardcoded strict semver, so this
+  // never fires in practice; skip silently rather than risk a false WARN if a
+  // future edit ever malforms the constant.
+  /* c8 ignore next */
+  if (pin === null) return;
+  // Compare major.minor ONLY (D-02). Inline numeric compare on the captured
+  // segments; do NOT feed a two-segment string to compareSemver (its
+  // triple-segment contract returns an undecidable 0).
+  const sameMajorMinor = local[0] === pin[0] && local[1] === pin[1];
+  if (sameMajorMinor) {
+    addItem(section, `${green(okGlyph)} gitleaks: ${raw} (matches pinned ${pin[0]}.${pin[1]})`);
+    return;
+  }
+  addItem(
+    section,
+    `${yellow(warnGlyph)} gitleaks: ${raw} -> ${GITLEAKS_PINNED_VERSION} (CI pins this; local drift may change scan results)`,
+  );
+}

package/src/commands.doctor.mirror-actions.ts

@@ -0,0 +1,83 @@
+import { execFileSync } from 'node:child_process';
+
+import { warnGlyph, yellow } from './color.ts';
+import { addItem, type DoctorSection } from './commands.doctor.format.ts';
+import { REPO_HOME } from './config.ts';
+import {
+  ghAuthStatus,
+  isActionsEnabled,
+  isRepoPrivate,
+  parseGitHubRemote,
+  readOriginRemote,
+  type SpawnSyncFn,
+} from './gh-actions.ts';
+
+/**
+ * Drift check appended to the Repository section of `nomad doctor`. WARNs (never
+ * FAILs, never sets `process.exitCode`) when the origin remote is a private
+ * GitHub mirror that is gh-authed with Actions re-enabled, the quiet failure
+ * mode where Actions get turned back on after `nomad init` auto-disabled them
+ * (via the GitHub web UI or a stray `gh` call) and the mirror starts firing its
+ * workflows on every push again.
+ *
+ * Reuses the five `gh-actions.ts` primitives unchanged (no new gh wrapper) and
+ * clones the `cmdInit` auto-disable gate ORDER, but strips every tip-log and
+ * the `disableActions` call: doctor is read-only and SILENT on every miss where
+ * init is chatty. The gate chain returns with no output when any of these hold:
+ *   gate 1 - the origin remote cannot be read (not a git repo / no origin)
+ *   gate 2 - the origin is not a GitHub URL (`parseGitHubRemote` null)
+ *   gate 3 - `gh` is not installed or not authed
+ *   gate 4 - the repo is public, or the privacy probe throws
+ *   gate 5 - Actions are already disabled, or the Actions probe throws
+ * Only when all five gates pass does it emit the single yellow WARN line with a
+ * `gh api -X PUT ... -F enabled=false` remediation hint (the exact shape
+ * `disableActions` would run). The three gh probes (gates 3-5) carry the shared
+ * `GH_TIMEOUT_MS` internally; gates 1-2 are local (a `git remote get-url` config
+ * read and a regex parse), so no network and no timeout needed. No new doctor
+ * section; no opt-out flag.
+ *
+ * @param section - The Repository section to append the WARN line to.
+ * @param run - Injectable subprocess runner; defaults to `execFileSync`.
+ */
+export function reportMirrorActions(section: DoctorSection, run: SpawnSyncFn = execFileSync): void {
+  // Gate 1: origin remote. Throws on no remote / non-repo -> silent skip.
+  let remote: string;
+  try {
+    remote = readOriginRemote(REPO_HOME, run);
+  } catch {
+    return;
+  }
+
+  // Gate 2: GitHub remote. Non-GitHub URL parses to null -> silent skip.
+  const ref = parseGitHubRemote(remote);
+  if (ref === null) return;
+
+  // Gate 3: gh available and authed. Doctor stays silent on both miss reasons
+  // (init prints a tip here; doctor does not, per the read-only contract).
+  if (ghAuthStatus(run) !== null) return;
+
+  // Gate 4: private mirror. A public repo, or a probe that throws, is a skip.
+  let isPrivate: boolean;
+  try {
+    isPrivate = isRepoPrivate(ref, run);
+  } catch {
+    return;
+  }
+  if (!isPrivate) return;
+
+  // Gate 5: Actions enabled. Already-disabled, or a probe that throws, is a skip.
+  let enabled: boolean;
+  try {
+    enabled = isActionsEnabled(ref, run);
+  } catch {
+    return;
+  }
+  if (!enabled) return;
+
+  // All gates passed: the private mirror has Actions re-enabled. Emit the
+  // single yellow WARN with the exact disable command as the remediation hint.
+  addItem(
+    section,
+    `${yellow(warnGlyph)} mirror Actions: enabled on private mirror ${ref.owner}/${ref.repo} (re-disable with 'gh api -X PUT repos/${ref.owner}/${ref.repo}/actions/permissions -F enabled=false')`,
+  );
+}

package/src/commands.doctor.ts

@@ -15,6 +15,8 @@ import {
 import { reportCheckShared } from './commands.doctor.check-shared.ts';
 import { reportNodeEngineCheck } from './commands.doctor.engine.ts';
 import { renderDoctor, section } from './commands.doctor.format.ts';
+import { reportGitleaksVersionCheck } from './commands.doctor.gitleaks-version.ts';
+import { reportMirrorActions } from './commands.doctor.mirror-actions.ts';
 import { reportVersionCheck } from './commands.doctor.version.ts';
 
 /**
@@ -55,15 +57,18 @@ export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
   reportGitlinks(repository);
   reportRemote(repository);
   reportRebaseClean(repository);
+  reportMirrorActions(repository);
 
   const version = section('Version');
   reportVersionCheck(version);
   reportNodeEngineCheck(version);
+  reportGitleaksVersionCheck(version);
 
   const sharedScan = section('Shared scan');
-  // Pass the Repository-section probe result so gitleaks `version` is not
-  // invoked a second time on a --check-shared run; reportCheckShared still
-  // probes for itself when called standalone.
+  // Reuse the Repository-section readiness probe so reportCheckShared does not
+  // re-spawn gitleaks for its own readiness on a --check-shared run; it still
+  // probes standalone when called without a prior result. (The Version-section
+  // drift check above spawns `gitleaks version` separately, by design.)
   if (opts.checkShared === true) reportCheckShared(sharedScan, gitleaksReady);
 
   renderDoctor([version, host, links, settings, pathMap, neverSync, repository, sharedScan]);

package/src/commands.drop-session.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 
 import { REPO_HOME } from './config.ts';
@@ -7,27 +7,32 @@ import { acquireLock, die, fail, log, NomadFatal, releaseLock } from './utils.ts
 
 /**
  * Surgical removal of a contaminated session from the staged tree of
- * `~/claude-nomad/`. Walks `shared/projects/<logical>/<id>.jsonl` at the
- * top level only, classifies each match via `git ls-files --error-unmatch`,
- * and unstages with the appropriate primitive:
+ * `~/claude-nomad/`. For each `shared/projects/<logical>/` child this
+ * matches both the flat `<id>.jsonl` AND the sibling subagent directory
+ * `<id>/` (whose nested transcripts are keyed by the same session id),
+ * classifies each staged entry via `git ls-files --error-unmatch`, and
+ * unstages with the appropriate primitive:
  *
  *   - tracked-in-HEAD  -> `git restore --staged --worktree -- <rel>`
  *   - newly-staged     -> `git rm --cached -f -- <rel>`
  *
- * Idempotent: files that are not in the index at all are skipped silently
- * rather than treated as errors. Exits 0 on any drop, including an
- * idempotent re-run that finds the matches already absent. Exits 1 with
- * `✗ no staged session matches <id>` (red `✗` fail glyph) only when no
- * `shared/projects/<logical>/<id>.jsonl` exists at all in the shared tree.
+ * The directory tree is expanded into its staged entries via
+ * `git ls-files -z -- <dir-rel>` so every nested file flows through the
+ * same per-entry classification loop as the flat jsonl; this closes the
+ * leak where a "dropped" session still shipped its subagent transcripts.
+ *
+ * Idempotent: entries not in the index are skipped silently. Exits 0 on
+ * any drop (including an idempotent re-run); exits 1 with `✗ no staged
+ * session matches <id>` only when neither a flat `<id>.jsonl` nor a
+ * `<id>/` directory with staged entries exists anywhere in the tree.
  *
  * Defense-in-depth: the id is validated against the same allowlist regex
  * used in `src/resume.ts` before any path composition. argv-array form
  * for every git invocation.
  *
- * NEVER touches `~/.claude/projects/<encoded>/<id>.jsonl`. The local file
- * is preserved so it can race-safely coexist with active Claude Code
- * writers; rotate-and-scrub of the local copy is the user's
- * responsibility.
+ * NEVER touches `~/.claude/projects/<encoded>/<id>.jsonl` or the local
+ * `<id>/` tree; the local copies are preserved so they race-safely
+ * coexist with active Claude Code writers.
  *
  * @param id Session id (filename minus `.jsonl`). Must match `[A-Za-z0-9_-]+`
  *           with length 1..128.
@@ -49,21 +54,32 @@ export function cmdDropSession(id: string): void {
     if (!existsSync(repoProjects)) {
       throw new NomadFatal(`no staged session matches ${id}`);
     }
-    // Top-level walk only: for each `shared/projects/<logical>/` child,
-    // check whether `<id>.jsonl` exists. No descent into
-    // subagents/memory/tool-results subdirectories.
+    // For each `shared/projects/<logical>/` child, match the flat
+    // `<id>.jsonl` plus the sibling subagent directory `<id>/`. The
+    // directory is expanded into its staged entries so every nested file
+    // flows through the same per-entry unstage loop as the flat jsonl.
     const matches: string[] = [];
     for (const logical of readdirSync(repoProjects)) {
       const candidate = join(repoProjects, logical, `${id}.jsonl`);
       if (existsSync(candidate)) {
-        matches.push(candidate);
+        matches.push(relative(REPO_HOME, candidate));
+      }
+      const dir = join(repoProjects, logical, id);
+      if (existsSync(dir) && statSync(dir).isDirectory()) {
+        const dirRel = relative(REPO_HOME, dir);
+        const staged = expandStagedDir(dirRel);
+        // A dir present on disk but absent from the index is an already-dropped
+        // rerun: push the dir path itself so the per-entry isInIndex() guard
+        // logs it as "already absent" rather than letting an empty match set
+        // escalate to the no-match fatal (idempotency for dir-only sessions).
+        if (staged.length > 0) matches.push(...staged);
+        else matches.push(dirRel);
       }
     }
     if (matches.length === 0) {
       throw new NomadFatal(`no staged session matches ${id}`);
     }
-    for (const m of matches) {
-      const rel = relative(REPO_HOME, m);
+    for (const rel of matches) {
       // Pitfall 7: skip files that are not in the index at all (the
       // load-bearing guard for the idempotent second-run case, where the
       // first drop already removed the entry from the index but left the
@@ -120,6 +136,31 @@ export function cmdDropSession(id: string): void {
   }
 }
 
+/**
+ * Expand a repo-relative directory into its staged entries via
+ * `git ls-files -z -- <dirRel>` (argv-array form, NUL-split for path
+ * safety). Returns repo-relative POSIX paths for every staged file under
+ * the directory, or an empty array when none are staged or `git` fails
+ * (missing/corrupt index); the caller then falls through to the existing
+ * per-entry idempotency guard rather than escalating to a FATAL.
+ *
+ * @param dirRel Repo-relative directory path (`shared/projects/<logical>/<id>`).
+ */
+function expandStagedDir(dirRel: string): string[] {
+  try {
+    const out = execFileSync('git', ['ls-files', '-z', '--', dirRel], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return out
+      .toString()
+      .split('\0')
+      .filter((p) => p !== '');
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Is `rel` (repo-relative path) present in the HEAD tree? Wraps
  * `git cat-file -e HEAD:<rel>`: exit 0 means tracked in HEAD,

package/src/commands.push.ts

@@ -85,22 +85,28 @@ export function parsePorcelainZ(statusPorcelain: string): string[] {
  * Reject any staged path that is not on the push allow-list or that matches a
  * `NEVER_SYNC` entry. Builds the runtime allow-list by combining
  * `PUSH_ALLOWED_STATIC` with one `shared/projects/<logical>/` prefix per entry
- * in `path-map.json` AND one `shared/extras/<logical>/<dirname>/` prefix per
- * (logical, whitelisted dirname) pair in `map.extras ?? {}` (Pitfall 4 closed:
- * data-driven, no hand-rolled bypass). The dirname filter (`SUPPORTED_EXTRAS`)
- * is the same one `remapExtrasPush` honors, so manually staged content under a
- * non-whitelisted dirname surfaces as a FATAL instead of riding through on the
- * logical-only prefix. Logs every violation as a FATAL line so the user sees
- * the full set (not just the first), then throws `NomadFatal` to unwind the
- * caller's try/finally and release the push lock.
+ * in `path-map.json` AND, per (logical, whitelisted name) pair in
+ * `map.extras ?? {}`, an exact `shared/extras/<logical>/<name>` entry plus a
+ * `shared/extras/<logical>/<name>/` prefix entry (Pitfall 4 closed:
+ * data-driven, no hand-rolled bypass). The exact entry permits the declared
+ * name when it is a single root file (e.g. `CLAUDE.md`); the prefix entry
+ * permits the declared name's subtree when it is a directory. Neither widens
+ * to a logical-only prefix, so an arbitrary sibling file under the same
+ * logical stays rejected. The name filter (`SUPPORTED_EXTRAS`) is the same one
+ * `remapExtrasPush` honors, so manually staged content under a non-whitelisted
+ * name surfaces as a FATAL instead of riding through. Logs every violation as
+ * a FATAL line so the user sees the full set (not just the first), then throws
+ * `NomadFatal` to unwind the caller's try/finally and release the push lock.
  */
 export function enforceAllowList(statusPorcelain: string, map: PathMap): void {
   const extrasWhitelist: readonly string[] = SUPPORTED_EXTRAS;
   const allowed = [
     ...PUSH_ALLOWED_STATIC,
     ...Object.keys(map.projects).map((l) => `shared/projects/${l}/`),
-    ...Object.entries(map.extras ?? {}).flatMap(([l, dirnames]) =>
-      dirnames.filter((d) => extrasWhitelist.includes(d)).map((d) => `shared/extras/${l}/${d}/`),
+    ...Object.entries(map.extras ?? {}).flatMap(([l, names]) =>
+      names
+        .filter((n) => extrasWhitelist.includes(n))
+        .flatMap((n) => [`shared/extras/${l}/${n}`, `shared/extras/${l}/${n}/`]),
     ),
   ];
   const neverSyncHits: string[] = [];
@@ -193,7 +199,13 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     }
     // Routed through the shell-free, untrimmed helper because `sh` would .trim()
     // the leading status-space and shift parsePorcelainZ's offsets.
-    const status = gitStatusPorcelainZ(REPO_HOME);
+    // `untrackedAll` (issue #111): the allow-list runs on this snapshot BEFORE
+    // `git add -A`. Without it, a fresh host whose entire `shared/extras/`
+    // subtree is untracked yields a single collapsed `?? shared/extras/`
+    // record that the `shared/extras/<logical>/<dirname>/` child prefix cannot
+    // match, so the first extras push is rejected. Expanding to per-file paths
+    // lets the existing allow-list accept them while keeping the gate order.
+    const status = gitStatusPorcelainZ(REPO_HOME, { untrackedAll: true });
     if (!status) {
       log('nothing to commit');
       // Combine session-unmapped and extras-unmapped into one user-visible

package/src/commands.update.ts

@@ -3,6 +3,7 @@ import { closeSync, existsSync, openSync, readSync } from 'node:fs';
 
 import { cmdDoctor } from './commands.doctor.ts';
 import { REPO_HOME } from './config.ts';
+import { commitRegeneratedLockfile, precommitForkExtras } from './update.fork-extras.ts';
 import { loadTopology } from './update.topology.ts';
 import { die, gitOrFatal, gitStatusPorcelainZ, log, NomadFatal, warn } from './utils.ts';
 
@@ -277,12 +278,21 @@ function tryAutoResolveMergeConflict(opts: CmdUpdateOpts): boolean {
  * pushes when the answer is `y` or `yes` (case-insensitive). Non-affirmative
  * answers skip the push and log a "run later" hint.
  *
+ * When the merge (and any extras precommit) leaves `HEAD` unchanged from
+ * `beforeSha`, there is nothing new to push: the function logs a one-line
+ * "already in sync" and returns without pushing or prompting (issue #66). An
+ * auto-resolved conflict always advances `HEAD` via its merge commit, so that
+ * path is never mistaken for a no-op.
+ *
  * @param opts - Update options; respected fields are:
  *   - `dryRun`: when true, log actions instead of executing them
  *   - `pushOrigin`: when true, push to `origin/main` without prompting
  *   - `prompt`: optional prompt function used for interactive confirmation
+ * @param beforeSha - `HEAD` SHA captured before the fork update began; the
+ *   post-merge `HEAD` is compared against it to detect a no-op. When omitted
+ *   (dry-run preview) the no-op short-circuit is skipped.
  */
-function runFork(opts: CmdUpdateOpts): boolean {
+function runFork(opts: CmdUpdateOpts, beforeSha?: string): boolean {
   const promptFn = opts.prompt ?? defaultPrompt;
   if (opts.dryRun === true) {
     log('DRY-RUN: would run `git fetch upstream`');
@@ -295,6 +305,10 @@ function runFork(opts: CmdUpdateOpts): boolean {
     return false;
   }
   gitOrFatal(['fetch', 'upstream'], 'git fetch upstream', REPO_HOME);
+  // Pre-commit whitelisted extras (issue #112): otherwise untracked
+  // shared/extras/ content that upstream also adds makes the merge abort
+  // pre-merge with no UU state, so the lone-lockfile auto-resolve never fires.
+  precommitForkExtras();
   let autoResolved = false;
   try {
     gitOrFatal(['merge', 'upstream/main'], 'git merge upstream/main', REPO_HOME);
@@ -302,6 +316,13 @@ function runFork(opts: CmdUpdateOpts): boolean {
     if (!tryAutoResolveMergeConflict(opts)) throw err;
     autoResolved = true;
   }
+  // No-op merge (and no extras precommit): HEAD never moved, so there is
+  // nothing new to push. A `beforeSha` of undefined (dry-run never reaches
+  // here) can never equal a real SHA, so the comparison is self-guarding.
+  if (headSha() === beforeSha) {
+    log('already in sync with origin/main, nothing to push');
+    return autoResolved;
+  }
   if (opts.pushOrigin === true) {
     gitOrFatal(['push', 'origin', 'main'], 'git push origin main', REPO_HOME);
     return autoResolved;
@@ -376,8 +397,12 @@ export function cmdUpdate(opts: CmdUpdateOpts = {}): void {
   }
 
   const beforeSha = headSha();
-  const installAlreadyRan = topology === 'vanilla' ? runVanilla(opts) : runFork(opts);
+  const installAlreadyRan = topology === 'vanilla' ? runVanilla(opts) : runFork(opts, beforeSha);
 
   if (!installAlreadyRan) reinstallIfNeeded(beforeSha);
+  // Secondary item of issue #112: a post-merge `npm install` that regenerated
+  // package-lock.json leaves uncommitted drift the trailing doctor flags.
+  // Commit just the lockfile (fork topology only) so the repo is clean.
+  if (topology === 'fork') commitRegeneratedLockfile();
   cmdDoctor();
 }

package/src/config.ts

@@ -36,6 +36,17 @@ export const REPO_HOME = process.env.NOMAD_REPO || resolve(HOME, 'claude-nomad')
  */
 export const UPSTREAM_REPO_SLUG = 'funkadelic/claude-nomad';
 
+/**
+ * Pinned gitleaks version. Single source of truth for the gitleaks pin used by
+ * `nomad doctor`'s version-drift check (`reportGitleaksVersionCheck`), which
+ * WARNs when the host's installed gitleaks major.minor diverges from this
+ * value. Mirrors the `GITLEAKS_VERSION` env in both `.github/workflows/tests.yml`
+ * and `.github/workflows/gitleaks.yml`; `config.gitleaks-pin.test.ts` asserts
+ * all three stay in lockstep so a CI bump that misses this constant (or vice
+ * versa) fails the suite. Bump here and in both workflow YAMLs together.
+ */
+export const GITLEAKS_PINNED_VERSION = '8.30.1';
+
 /**
  * Resolved host identity used to pick `hosts/<HOST>.json` and key entries in
  * `path-map.json`. Reads `NOMAD_HOST` first, falls back to `hostname()`, then
@@ -58,16 +69,18 @@ export const SHARED_LINKS = [
 ] as const;
 
 /**
- * Whitelist of directory names allowed in `path-map.json`'s top-level
- * `extras` field. Gates the named-extras opt-in mechanism: only entries
- * appearing in this list are eligible for sync. Initial set contains
- * `.planning` only; widening to include `.notes`, `.scratch`, etc. is a
- * one-line edit here with no schema migration required (the field is
- * additive on the consumer side). Mirrors `SHARED_LINKS` in shape and
+ * Whitelist of names allowed in `path-map.json`'s top-level `extras` field.
+ * Each entry is either a directory name (e.g. `.planning`) OR a single
+ * root-level file name (e.g. `CLAUDE.md`); both are validated the same way
+ * and copied verbatim under `shared/extras/<logical>/<name>`. Gates the
+ * named-extras opt-in mechanism: only entries appearing in this list are
+ * eligible for sync. Widening to include `.notes`, `.scratch`, `AGENTS.md`,
+ * etc. is a one-line edit here with no schema migration required (the field
+ * is additive on the consumer side). Mirrors `SHARED_LINKS` in shape and
  * intent: a short, append-only `as const` tuple that downstream callers
  * narrow against.
  */
-export const SUPPORTED_EXTRAS = ['.planning'] as const;
+export const SUPPORTED_EXTRAS = ['.planning', 'CLAUDE.md'] as const;
 
 /**
  * Path segments that must never cross the sync boundary in either direction.
@@ -159,9 +172,9 @@ export const PUSH_ALLOWED_STATIC = [
  * the literal string `'TBD'` as a placeholder while a host has not yet cloned
  * the project; `remapPull` / `remapPush` skip `'TBD'` entries.
  *
- * Optional `extras` field (additive, top-level): opt-in per-project
- * named-directory sync. Keyed by the same logical project name used in
- * `projects`; values are arrays of directory names validated by downstream
+ * Optional `extras` field (additive, top-level): opt-in per-project sync of
+ * named content. Keyed by the same logical project name used in `projects`;
+ * values are arrays of directory or root-file names validated by downstream
  * consumers against `SUPPORTED_EXTRAS`. Absence of the field is equivalent
  * to no extras for any project; legacy `path-map.json` files without an
  * `extras` block continue to work unchanged (no migration required).

package/src/extras-sync.ts

@@ -2,7 +2,7 @@ import { execFileSync } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, rmSync } from 'node:fs';
 import { isAbsolute, join, normalize } from 'node:path';
 
-import { HOME, HOST, REPO_HOME, SUPPORTED_EXTRAS } from './config.ts';
+import { HOME, HOST, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
 // prettier-ignore
 import { backupExtrasWrite, backupRepoWrite, encodePath, log, NomadFatal, readPathMap, warn } from './utils.ts';
 
@@ -61,6 +61,35 @@ export function copyExtras(src: string, dst: string): void {
   cpSync(src, dst, { recursive: true, force: true, verbatimSymlinks: true });
 }
 
+/**
+ * Repo-relative `shared/extras/<logical>/<dirname>` paths for every
+ * (logical, whitelisted dirname) pair declared in `map.extras`. This is the
+ * same prefix set the push allow-list permits (minus the trailing slash, so
+ * the values are usable directly as `git add` arguments). Used by the fork
+ * update path (issue #112) to pre-commit overlapping extras before
+ * `git merge upstream/main`, turning an untracked-overwrite abort into a
+ * tracked-file merge. Non-whitelisted dirnames are filtered out so manually
+ * staged content under a non-supported dirname is never auto-committed.
+ * Logical names are validated for path-traversal safety first, matching the
+ * `remapExtras*` contract.
+ *
+ * @param map - Parsed `path-map.json`. A missing `extras` key yields `[]`.
+ * @returns Sorted, de-duplicated repo-relative extras paths (no trailing slash).
+ */
+export function whitelistedExtrasPaths(map: PathMap): string[] {
+  const extrasMap = map.extras ?? {};
+  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
+  const paths = new Set<string>();
+  for (const [logical, dirnames] of Object.entries(extrasMap)) {
+    assertSafeLogical(logical);
+    for (const dirname of dirnames) {
+      if (!whitelist.includes(dirname)) continue;
+      paths.add(`shared/extras/${logical}/${dirname}`);
+    }
+  }
+  return [...paths].sort((a, b) => a.localeCompare(b));
+}
+
 /**
  * Push: copy whitelisted extras directories under each project's localRoot
  * into the repo at `shared/extras/<logical>/<dirname>/`. Returns

package/src/push-gitleaks.ts

@@ -93,7 +93,10 @@ export function partitionFindings(findings: Finding[]): {
  * transcript(s).` header, one block per affected session with a
  * `Recover with: nomad drop-session <id>` line, an optional `Also found:`
  * block for non-session paths, and a trailing `After recovery, re-run
- * nomad push.` line. Pure.
+ * nomad push.` line. The header carries a single clarifying note that the
+ * drop also clears any sibling subagent transcript directory for the
+ * session, since those nested paths route to the `other` bucket and are
+ * not listed per-session. Pure.
  */
 export function buildSessionAwareFatal(
   bySession: Map<string, Map<string, number>>,
@@ -101,24 +104,23 @@ export function buildSessionAwareFatal(
 ): string {
   if (bySession.size === 0) return LEGACY_FATAL;
   const lines: string[] = [];
-  lines.push(`gitleaks detected secrets in ${bySession.size} session transcript(s).`);
+  lines.push(
+    `gitleaks detected secrets in ${bySession.size} session transcript(s).`,
+    "nomad drop-session also clears each session's sibling subagent transcript directory.",
+  );
   for (const [sid, counts] of bySession) {
     const summary = [...counts.entries()].map(([rule, n]) => `${rule} (${n})`).join(', ');
-    lines.push('');
-    lines.push(`Session ${sid}:`);
-    lines.push(`  ${summary}`);
-    lines.push(`  Recover with: nomad drop-session ${sid}`);
+    lines.push('', `Session ${sid}:`, `  ${summary}`, `  Recover with: nomad drop-session ${sid}`);
   }
   if (other.length > 0) {
-    lines.push('');
-    lines.push('Also found:');
-    for (const f of other) {
-      lines.push(`  ${f.File}  ${f.RuleID}`);
-    }
-    lines.push('  Review with: git diff --cached, then unstage manually.');
+    lines.push(
+      '',
+      'Also found:',
+      ...other.map((f) => `  ${f.File}  ${f.RuleID}`),
+      '  Review with: git diff --cached, then unstage manually.',
+    );
   }
-  lines.push('');
-  lines.push('After recovery, re-run nomad push.');
+  lines.push('', 'After recovery, re-run nomad push.');
   return lines.join('\n');
 }
 

package/src/update.fork-extras.ts

@@ -0,0 +1,101 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { REPO_HOME } from './config.ts';
+import { whitelistedExtrasPaths } from './extras-sync.ts';
+import { gitOrFatal, log, readPathMap } from './utils.ts';
+
+/**
+ * Pre-commit whitelisted extras before a fork merge so an untracked-overwrite
+ * abort becomes a tracked-file merge (issue #112).
+ *
+ * When a fork host has untracked `shared/extras/<logical>/<dirname>/` content
+ * that `upstream/main` also introduces, `git merge upstream/main` aborts
+ * before creating any merge state ("untracked working tree files would be
+ * overwritten by merge"). No `UU` is recorded, so the lone-lockfile
+ * auto-resolve never fires and the merge surfaces as an opaque failure.
+ * Staging alone is insufficient (git still refuses to overwrite staged-but-
+ * uncommitted local changes); the overlap must be a committed tracked path so
+ * the merge engine treats it as a content merge. After this commit, identical
+ * extras merge cleanly (the normal sync case, leaving the lone `UU
+ * package-lock.json` the existing auto-resolve handles) and divergent extras
+ * surface a real, resolvable conflict instead of the abort.
+ *
+ * Scoped strictly to the whitelisted `shared/extras/` paths declared in
+ * `path-map.json`; never a blanket `git add -A`. No-op when there is no
+ * `path-map.json`, no declared extras, or none of the declared extras paths
+ * exist on disk, and when staging produces no index change (nothing dirty).
+ */
+export function precommitForkExtras(): void {
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  if (!existsSync(mapPath)) return;
+  const map = readPathMap(mapPath);
+  const candidates = whitelistedExtrasPaths(map).filter((p) => existsSync(join(REPO_HOME, p)));
+  if (candidates.length === 0) return;
+
+  gitOrFatal(['add', '--', ...candidates], 'git add extras', REPO_HOME);
+  // Only commit when staging actually changed the index. The probe and commit
+  // are BOTH path-scoped to the extras candidates so an unrelated staged change
+  // present before update neither flips the dirty probe nor rides along in the
+  // commit. `git diff --cached --quiet -- <candidates>` exits 0 when those paths
+  // match HEAD (nothing to commit), 1 when they differ; avoids an empty-commit
+  // failure when the extras were already tracked and unmodified.
+  let dirty = false;
+  try {
+    execFileSync('git', ['diff', '--cached', '--quiet', '--', ...candidates], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch {
+    dirty = true;
+  }
+  if (!dirty) return;
+  gitOrFatal(
+    ['commit', '-m', 'chore: stage local extras before upstream merge', '--', ...candidates],
+    'git commit extras',
+    REPO_HOME,
+  );
+  log(`staged local extras before merge: ${candidates.join(', ')}`);
+}
+
+/**
+ * After a successful fork merge, commit a `package-lock.json` that `npm
+ * install` regenerated and left uncommitted (secondary item of issue #112).
+ *
+ * The post-merge reinstall (`reinstallIfNeeded`) can rewrite the lockfile
+ * when the merge changed dependencies, leaving working-tree drift that the
+ * trailing `nomad doctor` reports as "uncommitted changes". This stages and
+ * commits ONLY `package-lock.json` so the repo is clean after update. No-op
+ * when the lockfile is absent or unchanged (the `git diff --quiet` probe
+ * exits 0). Tightly scoped: never touches any other path.
+ */
+export function commitRegeneratedLockfile(): void {
+  const lockfile = join(REPO_HOME, 'package-lock.json');
+  if (!existsSync(lockfile)) return;
+  // `git diff --quiet -- package-lock.json` exits 0 when the working tree
+  // matches HEAD (no drift to commit), 1 when it differs.
+  let drifted = false;
+  try {
+    execFileSync('git', ['diff', '--quiet', '--', 'package-lock.json'], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch {
+    drifted = true;
+  }
+  if (!drifted) return;
+  gitOrFatal(['add', '--', 'package-lock.json'], 'git add package-lock.json', REPO_HOME);
+  gitOrFatal(
+    [
+      'commit',
+      '-m',
+      'chore: commit regenerated package-lock.json after update',
+      '--',
+      'package-lock.json',
+    ],
+    'git commit package-lock.json',
+    REPO_HOME,
+  );
+  log('committed regenerated package-lock.json after update');
+}

package/src/utils.ts

@@ -88,12 +88,32 @@ export const die = (msg: string): never => {
  * and the first record's leading space is part of the format (e.g.
  * `" M path\0"` for unstaged-modified). Going through `sh` would strip that
  * space and shift the fixed-offset parse in `parsePorcelainZ`.
+ *
+ * `opts.untrackedAll` (default `false`): when `true`, passes
+ * `--untracked-files=all` so git emits one record per untracked file instead
+ * of collapsing a fully-untracked subtree to its highest all-untracked parent
+ * directory (`?? shared/extras/`). The push allow-list (issue #111) needs the
+ * per-file paths so its `shared/extras/<logical>/<dirname>/` child prefix
+ * matches; the working-tree-clean checks in `cmdUpdate` and `cmdDoctor` only
+ * care whether output is empty, so they keep the cheaper default-collapse
+ * behavior. Opt-in rather than a global default so those consumers do not
+ * pay for the deeper walk.
+ *
+ * @param cwd - Working directory for the git invocation; defaults to the process cwd.
+ * @param opts - Reader options. `untrackedAll` expands collapsed untracked directory records into per-file paths.
+ * @returns The raw NUL-delimited porcelain v1 output as a string.
  */
-export const gitStatusPorcelainZ = (cwd?: string): string =>
-  execFileSync('git', ['status', '--porcelain=v1', '-z'], {
+export const gitStatusPorcelainZ = (
+  cwd?: string,
+  opts: { untrackedAll?: boolean } = {},
+): string => {
+  const args = ['status', '--porcelain=v1', '-z'];
+  if (opts.untrackedAll === true) args.push('--untracked-files=all');
+  return execFileSync('git', args, {
     cwd,
     stdio: ['ignore', 'pipe', 'pipe'],
   }).toString();
+};
 
 /**
  * Run `git <args>` in `cwd`, forwarding stderr and converting non-zero exits