claude-nomad 0.21.0 → 0.22.1

package/.gitleaks.toml

@@ -6,7 +6,7 @@
 [extend]
 useDefault = true
 
-[allowlist]
+[[allowlists]]
 description = "claude-nomad: structurally-distinguishable tool-output noise"
 regexes = [
     '''AY[A-Za-z0-9_-]{20,}''',
@@ -14,3 +14,22 @@ regexes = [
     '''"id"\s*:\s*"[a-f0-9]{40,64}"''',
     '''key=[a-f0-9]{8,} [\w./-]+\.\w+:\d+''',
 ]
+
+# Path-scoped: the documented test-fixture github-pat literal accumulates
+# in Claude Code session transcripts whenever a conversation touches the
+# Pitfall 4 docs or this allowlist itself. Live sessions cannot be
+# safely sed-scrubbed (sed -i renames out from under the running CLI's
+# open file descriptor and silently drops post-rename writes), so the
+# only sustainable false-positive handler is a narrow allowlist scoped
+# to synced session paths. `condition = "AND"` requires BOTH the literal
+# AND a `shared/projects/<logical>/.../*.jsonl` path; a real PAT in the
+# same file (different 36-char body) still fires.
+[[allowlists]]
+description = "claude-nomad: documented test-fixture github-pat literal in synced session transcripts"
+regexes = [
+    '''ghp_xJZbT3qfV2nLpKR8mYwH4dGtCsW9aE1uF6oA''',
+]
+paths = [
+    '''^shared/projects/[^/]+/.*\.jsonl$''',
+]
+condition = "AND"

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.22.1](https://github.com/funkadelic/claude-nomad/compare/v0.22.0...v0.22.1) (2026-05-23)
+
+
+### Fixed
+
+* **gitignore:** anchor .planning/ to source repo root ([#105](https://github.com/funkadelic/claude-nomad/issues/105)) ([50c403d](https://github.com/funkadelic/claude-nomad/commit/50c403d7223f79f30fa28b99ce6e5b2dcc350356))
+
+## [0.22.0](https://github.com/funkadelic/claude-nomad/compare/v0.21.0...v0.22.0) (2026-05-23)
+
+
+### Added
+
+* **extras-sync:** sync per-project .planning/ directories across hosts ([#103](https://github.com/funkadelic/claude-nomad/issues/103)) ([4563fe3](https://github.com/funkadelic/claude-nomad/commit/4563fe32a143dd9a2450baab8ec94a902800c2b3))
+
 ## [0.21.0](https://github.com/funkadelic/claude-nomad/compare/v0.20.0...v0.21.0) (2026-05-22)
 
 

package/README.md

@@ -12,10 +12,11 @@ claude-nomad keeps all of it in sync through a private Git repo you control. `no
 
 **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.
 
-Two things it does that ad-hoc dotfiles syncing can't:
+Three things it does that ad-hoc dotfiles syncing can't:
 
 - **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.
 
 ## Table of contents
 
@@ -114,7 +115,8 @@ By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config
 │   ├── rules/
 │   ├── my-statusline.cjs     # any script you want symlinked into ~/.claude/
 │   ├── .gitignore            # defense-in-depth: blocks .claude.json, settings.local.json, *.token, *.key, .env
-│   └── projects/             # session transcripts under logical names
+│   ├── projects/             # session transcripts under logical names
+│   └── extras/               # opt-in per-project content (materializes when path-map.json declares extras)
 ├── hosts/
 │   ├── <your-mac>.json       # patches merged over settings.base.json
 │   ├── <your-wsl-host>.json
@@ -125,13 +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`.                                                                                                                                          |
-| **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 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. |
 
 > [!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.
@@ -142,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:
+`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:
 
 ```json
 {
@@ -152,6 +155,9 @@ The hard problem: Claude Code stores sessions in `~/.claude/projects/<encoded-pa
       "<your-wsl-host>": "/home/you/code/ha-acwd",
       "<your-nuc>": "TBD"
     }
+  },
+  "extras": {
+    "ha-acwd": [".planning"]
   }
 }
 ```
@@ -163,6 +169,8 @@ 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).
+
 ## 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).
@@ -198,12 +206,13 @@ 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`.
 - **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.
 
 ## 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)
+- 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
 - A **private** GitHub repo (or any Git remote you control)
@@ -354,10 +363,10 @@ If you installed an earlier version via `./install.sh` and a shell alias (the pr
 | `nomad init`                     | Scaffold empty `shared/`, `hosts/`, `path-map.json` on a fresh clone. Refuses to clobber existing scaffold. Auto-disables Actions on a detected private GitHub mirror (see [Privacy by default](#privacy-by-default)).  |
 | `nomad init --snapshot`          | Overlay current host's `~/.claude/` into `shared/` and write `~/.claude/settings.json` verbatim into `hosts/<NOMAD_HOST>.json`. Originals not modified. Same auto-disable behavior as `nomad init`.                     |
 | `nomad init --keep-actions`      | Skip the auto-disable. Combinable with `--snapshot`. Use when an upstream org policy already governs Actions, or you intentionally want CI on the private mirror.                                                       |
-| `nomad pull`                     | `git pull --rebase --autostash`, apply symlinks, regenerate `settings.json`, remap session paths. FATAL if scaffold missing.                                                                                            |
+| `nomad pull`                     | `git pull --rebase --autostash`, apply symlinks, regenerate `settings.json`, remap session paths, and pull opted-in per-project extras. FATAL if scaffold missing.                                                      |
 | `nomad pull --dry-run`           | Network-aware preview: acquire lock + `git pull --rebase`, print planned changes (symlink moves, `settings.json` diff, transcript overwrites), exit without writing.                                                    |
 | `nomad diff`                     | Offline, lockless twin of `pull --dry-run`. No network, no lock. Works against the current local repo state.                                                                                                            |
-| `nomad push`                     | Export local sessions to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                                                 |
+| `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 update`                   | Topology-aware upgrade to the latest upstream. Flags: `--dry-run`, `--force`, `--push-origin`. See [Upgrading the tool](#upgrading-the-tool).                                                                           |
@@ -435,7 +444,7 @@ The file extends the default gitleaks ruleset, so real high-entropy secrets like
 [extend]
 useDefault = true
 
-[allowlist]
+[[allowlists]]
 description = "claude-nomad: structurally-distinguishable tool-output noise"
 regexes = [
     '''AY[A-Za-z0-9_-]{20,}''',

package/package.json

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

package/src/commands.pull.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { HOME, HOST, REPO_HOME } from './config.ts';
+import { divergenceCheckExtras, remapExtrasPull } from './extras-sync.ts';
 import { applySharedLinks, regenerateSettings } from './links.ts';
 import { computePreview } from './preview.ts';
 import { remapPull } from './remap.ts';
@@ -12,18 +13,23 @@ import { acquireLock, die, fail, freshBackupTs, gitOrFatal, log, NomadFatal, rel
 /**
  * `nomad pull` command. Acquires the push/pull lock, takes a backup
  * timestamp, runs `git pull --rebase --autostash` in `REPO_HOME`, then
- * applies the three side-effecting sync steps in order:
- *   1. `applySharedLinks` (symlink shared/* into ~/.claude/)
- *   2. `regenerateSettings` (deep-merge base + host-override into settings.json)
- *   3. `remapPull` (copy repo-side session transcripts into host-encoded dirs)
+ * applies the side-effecting sync steps in order:
+ *   1. `divergenceCheckExtras` (read-only WARN naming local files that
+ *      diverge from origin; fires in BOTH wet and dry modes per D-08)
+ *   2. `applySharedLinks` (symlink shared/* into ~/.claude/)
+ *   3. `regenerateSettings` (deep-merge base + host-override into settings.json)
+ *   4. `remapPull` (copy repo-side session transcripts into host-encoded dirs)
+ *   5. `remapExtrasPull` (copy `shared/extras/<logical>/<dirname>/` back
+ *      into each project's localRoot; SKIPPED under dryRun)
  *
  * `opts.dryRun` (default `false`): when `true`, the lock IS still acquired
  * and `git pull --rebase` still runs (so concurrent invocations cannot race
- * and so the user sees the same network round-trip behavior they would on a
- * real pull). Then `computePreview` runs in place of the three mutating
- * steps. The per-run backup directory under
- * `~/.cache/claude-nomad/backup/<ts>/` is intentionally NOT created (no
- * backups are written under dryRun and an empty dir would pollute the cache).
+ * and the user sees the same network round-trip as a real pull).
+ * `divergenceCheckExtras` still fires (read-only by design). Then
+ * `computePreview` runs in place of the four mutating steps. The per-run
+ * backup directory under `~/.cache/claude-nomad/backup/<ts>/` is
+ * intentionally NOT created (no backups are written under dryRun and an
+ * empty dir would pollute the cache).
  *
  * Any `NomadFatal` thrown along the way is caught here so the `finally` block
  * releases the lock before exit (a raw `process.exit()` would skip `finally`
@@ -62,16 +68,28 @@ export function cmdPull(opts: { dryRun?: boolean } = {}): void {
     }
     log(`pulling on host=${HOST} (backup=${ts}${dryRun ? '; dry-run' : ''})`);
     gitOrFatal(['pull', '--rebase', '--autostash'], 'git pull --rebase', REPO_HOME);
+    // Read-only pre-pull check: fires in BOTH wet and dry modes (D-08).
+    // Runs AFTER the rebase (so origin content is fetched) and BEFORE any
+    // mutation (so local state is intact for byte-level comparison). The
+    // function itself silently skips when no `extras` key is declared.
+    divergenceCheckExtras(ts);
     if (dryRun) {
       const previewResult = computePreview(ts);
+      // dryRun deliberately omits remapExtrasPull to preserve the
+      // zero-mutation contract; users still see the divergence WARN above.
       log('dry-run complete; no mutation');
       emitSummary('pull', previewResult.unmapped);
     } else {
       applySharedLinks(ts);
       regenerateSettings(ts);
       const remapResult = remapPull(ts);
+      const extrasResult = remapExtrasPull(ts);
       log('pull complete');
-      emitSummary('pull', remapResult.unmapped);
+      // Combine session-unmapped and extras-unmapped into one user-visible
+      // count; from the operator's perspective both mean "couldn't sync this
+      // for the host". extras-skipped (non-whitelisted dirname) stays
+      // separate because it signals config misuse, not a host-config gap.
+      emitSummary('pull', remapResult.unmapped + extrasResult.unmapped, 0, extrasResult.skipped);
     }
   } catch (err) {
     // Catch fatal errors here so the finally block runs and releases the

package/src/commands.push.ts

@@ -2,13 +2,14 @@ import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 
 // prettier-ignore
-import { HOME, HOST, NEVER_SYNC, PUSH_ALLOWED_STATIC, REPO_HOME, type PathMap } from './config.ts';
+import { HOME, HOST, NEVER_SYNC, PUSH_ALLOWED_STATIC, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { remapExtrasPush } from './extras-sync.ts';
 import { findGitlinks, probeGitleaks, rebaseBeforePush } from './push-checks.ts';
 import { runGitleaksScan } from './push-gitleaks.ts';
 import { remapPush } from './remap.ts';
 import { emitSummary } from './summary.ts';
 // prettier-ignore
-import { acquireLock, die, fail, freshBackupTs, gitOrFatal, gitStatusPorcelainZ, log, NomadFatal, readJson, releaseLock } from './utils.ts';
+import { acquireLock, die, fail, freshBackupTs, gitOrFatal, gitStatusPorcelainZ, log, NomadFatal, readPathMap, releaseLock } from './utils.ts';
 
 /**
  * Match `path` against an entry in the push allow-list. Exact match for
@@ -29,8 +30,16 @@ function isAllowed(path: string, allowed: readonly string[]): boolean {
   return false;
 }
 
-/** True when any path segment matches a `NEVER_SYNC` entry (hard-block list). */
+/**
+ * True when any path segment matches a `NEVER_SYNC` entry (hard-block list).
+ * Scope exception (Pitfall 6): paths beginning with `shared/extras/` are
+ * exempt. The segment list was authored against `~/.claude/` semantics for
+ * ephemeral Claude Code state (`todos/`, `shell-snapshots/`, etc.); inside
+ * the extras tree, `.planning/todos/` is a meaningful GSD-managed path. The
+ * narrowed scope preserves the original hard-block for all other surface.
+ */
 function isNeverSync(path: string): boolean {
+  if (path.startsWith('shared/extras/')) return false;
   for (const segment of path.split('/')) {
     if (NEVER_SYNC.has(segment)) return true;
   }
@@ -76,14 +85,23 @@ 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`. Logs every violation as a FATAL line so the user sees
+ * 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.
  */
 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}/`),
+    ),
   ];
   const neverSyncHits: string[] = [];
   const violations: string[] = [];
@@ -111,11 +129,13 @@ export function enforceAllowList(statusPorcelain: string, map: PathMap): void {
  *   2. `rebaseBeforePush` (surface remote conflicts against committed state,
  *      not against in-flight `remapPush` copies)
  *   3. `remapPush` (copy host-encoded session dirs into shared logical names)
- *   4. `findGitlinks` walk of `shared/` (refuse to push nested .git entries;
- *      runs AFTER `remapPush` so it catches .git dirs copied in from the host)
- *   5. allow-list enforcement on the resulting `git status` (refuse any path
- *      not on `PUSH_ALLOWED_STATIC` or matching `NEVER_SYNC`)
- *   6. `git add -A` -> `runGitleaksScan` on staged tree -> `git commit` -> `git push`
+ *   4. `remapExtrasPush` (copy whitelisted per-project extras under
+ *      `shared/extras/<logical>/<dirname>/`, between `remapPush` and the
+ *      gitlink walk so produced paths reach both the walk and the allow-list)
+ *   5. `findGitlinks` walk of `shared/` (refuse to push nested .git entries)
+ *   6. allow-list enforcement on the resulting `git status` (runtime
+ *      `shared/extras/<logical>/` prefix per declared logical added)
+ *   7. `git add -A` -> `runGitleaksScan` on staged tree -> `git commit` -> `git push`
  *
  * The gitleaks scan runs AFTER staging so it sees what would actually be
  * pushed, but BEFORE commit so a detection unwinds cleanly without leaving a
@@ -149,6 +169,11 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     // remapPush runs BEFORE the empty-status check: it produces the diffs status
     // observes, so swapping the order would short-circuit before anything is staged.
     const remapResult = remapPush(ts, { dryRun });
+    // remapExtrasPush lands between remapPush and findGitlinks so the
+    // produced `shared/extras/<logical>/<dirname>/` paths are visible to
+    // both the gitlink walk and the downstream allow-list classification.
+    // dryRun is forwarded so a preview push reports the same skipped count.
+    const extrasResult = remapExtrasPush(ts, { dryRun });
     // Gitlink walk of shared/ AFTER remapPush so it inspects the post-copy tree.
     // A nested .git copied in from a host's encoded session dir would slip past a
     // pre-remap scan and reach the remote via the shared/projects/<logical>/ prefix.
@@ -171,25 +196,34 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     const status = gitStatusPorcelainZ(REPO_HOME);
     if (!status) {
       log('nothing to commit');
-      emitSummary('push', remapResult.unmapped, remapResult.collisions);
+      // Combine session-unmapped and extras-unmapped into one user-visible
+      // count; both mean "couldn't sync this for the host". extras-skipped
+      // (non-whitelisted dirname) stays separate because it signals config
+      // misuse, not a host-config gap.
+      emitSummary(
+        'push',
+        remapResult.unmapped + extrasResult.unmapped,
+        remapResult.collisions,
+        extrasResult.skipped,
+      );
       return;
     }
     const mapPath = join(REPO_HOME, 'path-map.json');
     if (!existsSync(mapPath)) die('path-map.json missing, cannot enforce push allow-list');
-    // Route a malformed path-map.json through NomadFatal so finally releases the lock.
-    let map: PathMap;
-    try {
-      map = readJson<PathMap>(mapPath);
-    } catch (err) {
-      throw new NomadFatal(`could not parse path-map.json: ${(err as Error).message}`);
-    }
+    // readPathMap routes parse failures through NomadFatal so finally releases the lock.
+    const map = readPathMap(mapPath);
     enforceAllowList(status, map);
     if (dryRun) {
       // Skip the staging quartet so no commit lands and nothing is pushed.
       // The user has already seen probeGitleaks pass, the rebase result, the
       // remap preview, the gitlink scan, and the allow-list classification.
       log('push: dry-run; skipping git add, gitleaks scan, commit, and push');
-      emitSummary('push', remapResult.unmapped, remapResult.collisions);
+      emitSummary(
+        'push',
+        remapResult.unmapped + extrasResult.unmapped,
+        remapResult.collisions,
+        extrasResult.skipped,
+      );
       return;
     }
     // gitOrFatal uses execFileSync (no shell) so NOMAD_HOST cannot escape quoting.
@@ -201,7 +235,12 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     gitOrFatal(['commit', '-m', `chore: sync from ${HOST}`], 'git commit', REPO_HOME);
     gitOrFatal(['push'], 'git push', REPO_HOME);
     log('push complete');
-    emitSummary('push', remapResult.unmapped, remapResult.collisions);
+    emitSummary(
+      'push',
+      remapResult.unmapped + extrasResult.unmapped,
+      remapResult.collisions,
+      extrasResult.skipped,
+    );
   } catch (err) {
     if (err instanceof NomadFatal) {
       fail(err.message);

package/src/config.ts

@@ -57,6 +57,18 @@ export const SHARED_LINKS = [
   'my-statusline.cjs',
 ] 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
+ * intent: a short, append-only `as const` tuple that downstream callers
+ * narrow against.
+ */
+export const SUPPORTED_EXTRAS = ['.planning'] as const;
+
 /**
  * Path segments that must never cross the sync boundary in either direction.
  * Defense-in-depth pair with `PUSH_ALLOWED_STATIC`: even if the allow-list
@@ -146,5 +158,15 @@ export const PUSH_ALLOWED_STATIC = [
  * against `HOST`) to the absolute path the project lives at on that host. Use
  * 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
+ * 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).
  */
-export type PathMap = { projects: Record<string, Record<string, string>> };
+export type PathMap = {
+  projects: Record<string, Record<string, string>>;
+  extras?: Record<string, string[]>;
+};

package/src/extras-sync.ts

@@ -0,0 +1,290 @@
+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';
+// prettier-ignore
+import { backupExtrasWrite, backupRepoWrite, encodePath, log, NomadFatal, readPathMap, warn } from './utils.ts';
+
+/**
+ * `logical` keys in `path-map.json` are project identifiers (e.g. `ha-acwd`,
+ * `foo`), never path fragments. A crafted key like `../escape` or `foo/bar`
+ * would escape `shared/extras/` via `join()` (which normalizes `..`) and land
+ * content somewhere unexpected on the filesystem. The push allow-list catches
+ * such commits at the `git add` boundary, but the filesystem mutation has
+ * already happened by then. This check fails fast before any write. The
+ * pattern matches what every reasonable project name looks like and rejects
+ * everything else; tighten only if a real project needs broader characters.
+ */
+const SAFE_LOGICAL = /^[A-Za-z0-9._-]+$/;
+function assertSafeLogical(logical: string): void {
+  if (!SAFE_LOGICAL.test(logical) || logical === '.' || logical === '..') {
+    throw new NomadFatal(
+      `invalid logical name in path-map.json extras: ${JSON.stringify(logical)} (must match [A-Za-z0-9._-]+; no path separators or '..')`,
+    );
+  }
+}
+
+/**
+ * Reject `localRoot` values that contain unnormalized segments (`..`,
+ * redundant `/.`, trailing slashes that don't survive `normalize`). A
+ * poisoned `path-map.json` with `host: '/tmp/x/../escape'` would silently
+ * land writes at `/tmp/escape/.planning/` because `path.join` normalizes
+ * `..` before `cpSync` sees the destination. The user thinks they declared
+ * one path and got another. Requiring `localRoot === normalize(localRoot)`
+ * (and an absolute path on top) catches the obvious traversal trick and
+ * forces poisoned-map writes to surface as a FATAL before any filesystem
+ * mutation. Same defense-in-depth shape as `assertSafeLogical`.
+ */
+function assertSafeLocalRoot(localRoot: string, logical: string): void {
+  if (!isAbsolute(localRoot)) {
+    throw new NomadFatal(
+      `invalid localRoot for ${logical} in path-map.json: ${JSON.stringify(localRoot)} (must be absolute)`,
+    );
+  }
+  if (localRoot !== normalize(localRoot)) {
+    throw new NomadFatal(
+      `invalid localRoot for ${logical} in path-map.json: ${JSON.stringify(localRoot)} (must be already-normalized; no '..' or redundant segments)`,
+    );
+  }
+}
+
+/**
+ * Recursive mirror copy: `rmSync` then `cpSync` so dst-only entries are
+ * removed (true mirror, not just overwrite). Passes `verbatimSymlinks: true`
+ * to keep relative symlink targets unrewritten across hosts (Pitfall 1;
+ * nodejs/node issue 41693). Exported so the test file can call it directly;
+ * `remapExtrasPush` and `remapExtrasPull` are the primary public API.
+ */
+export function copyExtras(src: string, dst: string): void {
+  rmSync(dst, { recursive: true, force: true });
+  cpSync(src, dst, { recursive: true, force: true, verbatimSymlinks: true });
+}
+
+/**
+ * Push: copy whitelisted extras directories under each project's localRoot
+ * into the repo at `shared/extras/<logical>/<dirname>/`. Returns
+ * `{ unmapped, skipped }` with intentionally asymmetric granularity:
+ * `unmapped` is per-project (one increment per `logical` with no host path,
+ * which short-circuits before its dirnames are visited) and `skipped` is
+ * per-dirname (one increment per non-whitelisted entry inside an otherwise
+ * mapped project). Both counts feed `emitSummary`; the asymmetry mirrors
+ * the underlying skip-loop control flow (outer per-logical, inner
+ * per-dirname) and matches what an operator wants to see in the summary
+ * line. `opts.dryRun` logs `would push extras:` lines without writing,
+ * with identical count semantics. Legacy `path-map.json` without an
+ * `extras` key returns `{ unmapped: 0, skipped: 0 }` cleanly.
+ */
+export function remapExtrasPush(
+  ts: string,
+  opts: { dryRun?: boolean } = {},
+): { unmapped: number; skipped: number } {
+  const dryRun = opts.dryRun === true;
+  let unmapped = 0;
+  let skipped = 0;
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  if (!existsSync(mapPath)) {
+    log('no path-map.json; skipping extras push');
+    return { unmapped: 0, skipped: 0 };
+  }
+
+  const map = readPathMap(mapPath);
+  const extrasMap = map.extras ?? {};
+  if (Object.keys(extrasMap).length === 0) return { unmapped: 0, skipped: 0 };
+
+  // Validation pass: FATAL on any poisoned logical or unnormalized
+  // localRoot before any filesystem mutation. Runs over the entire extras
+  // map up-front so the documented "FATAL before any filesystem mutation"
+  // contract holds even when a clean entry sits ahead of a poisoned one in
+  // the iteration order (otherwise `mkdirSync(shared/extras/)` and the
+  // first cpSync would already have landed before the FATAL fired).
+  for (const logical of Object.keys(extrasMap)) {
+    assertSafeLogical(logical);
+    const localRoot = map.projects[logical]?.[HOST];
+    if (localRoot && localRoot !== 'TBD') assertSafeLocalRoot(localRoot, logical);
+  }
+
+  const repoExtras = join(REPO_HOME, 'shared', 'extras');
+  if (!dryRun) mkdirSync(repoExtras, { recursive: true });
+
+  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
+
+  for (const [logical, dirnames] of Object.entries(extrasMap)) {
+    const localRoot = map.projects[logical]?.[HOST];
+    if (!localRoot || localRoot === 'TBD') {
+      unmapped++;
+      log(`skip ${logical}: no path for ${HOST}`);
+      continue;
+    }
+    for (const dirname of dirnames) {
+      if (!whitelist.includes(dirname)) {
+        skipped++;
+        log(`skip ${dirname} for ${logical}: not in SUPPORTED_EXTRAS`);
+        continue;
+      }
+      const src = join(localRoot, dirname);
+      if (!existsSync(src)) continue;
+      const dst = join(repoExtras, logical, dirname);
+      if (dryRun) {
+        log(`would push extras: ${src} -> ${dst}`);
+        continue;
+      }
+      backupRepoWrite(dst, ts, REPO_HOME);
+      copyExtras(src, dst);
+      log(`pushed extras ${logical}/${dirname} -> shared/extras/${logical}/${dirname}`);
+    }
+  }
+  return { unmapped, skipped };
+}
+
+/**
+ * Pull: copy whitelisted extras from `shared/extras/<logical>/<dirname>/`
+ * back into each project's localRoot on this host. Returns `{ unmapped,
+ * skipped }` with the same asymmetric granularity as `remapExtrasPush`:
+ * `unmapped` per-project, `skipped` per-dirname. `opts.dryRun` logs `would
+ * overwrite extras:` lines without writing. Uses `backupExtrasWrite` (not
+ * `backupBeforeWrite`) because `<localRoot>/<dirname>` lives outside
+ * `CLAUDE_HOME` and the standard helper's relative-path guard would no-op
+ * and lose prior content. Legacy `path-map.json` without an `extras` key,
+ * or a missing `shared/extras/`, both produce a clean no-op.
+ */
+export function remapExtrasPull(
+  ts: string,
+  opts: { dryRun?: boolean } = {},
+): { unmapped: number; skipped: number } {
+  const dryRun = opts.dryRun === true;
+  let unmapped = 0;
+  let skipped = 0;
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  const repoExtras = join(REPO_HOME, 'shared', 'extras');
+  if (!existsSync(mapPath) || !existsSync(repoExtras)) {
+    log('no path-map or repo extras dir; skipping extras remap');
+    return { unmapped: 0, skipped: 0 };
+  }
+
+  const map = readPathMap(mapPath);
+  const extrasMap = map.extras ?? {};
+  if (Object.keys(extrasMap).length === 0) return { unmapped: 0, skipped: 0 };
+
+  // Validation pass: FATAL on any poisoned logical or unnormalized
+  // localRoot before any host-side `backupExtrasWrite` or `copyExtras`
+  // runs. Symmetric with `remapExtrasPush`: a poisoned entry anywhere in
+  // the map must fail the whole pull up-front, otherwise a clean entry
+  // earlier in iteration order would already have clobbered the host
+  // before the FATAL fired (partial host-side mutation breaks the
+  // documented "fail before mutation" contract).
+  for (const logical of Object.keys(extrasMap)) {
+    assertSafeLogical(logical);
+    const localRoot = map.projects[logical]?.[HOST];
+    if (localRoot && localRoot !== 'TBD') assertSafeLocalRoot(localRoot, logical);
+  }
+
+  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
+
+  for (const [logical, dirnames] of Object.entries(extrasMap)) {
+    const localRoot = map.projects[logical]?.[HOST];
+    if (!localRoot || localRoot === 'TBD') {
+      unmapped++;
+      log(`skip ${logical}: no path for ${HOST}`);
+      continue;
+    }
+    for (const dirname of dirnames) {
+      if (!whitelist.includes(dirname)) {
+        skipped++;
+        log(`skip ${dirname} for ${logical}: not in SUPPORTED_EXTRAS`);
+        continue;
+      }
+      const src = join(repoExtras, logical, dirname);
+      if (!existsSync(src)) continue;
+      const dst = join(localRoot, dirname);
+
+      if (dryRun) {
+        log(`would overwrite extras: ${dst} (from ${src})`);
+        continue;
+      }
+      // Snapshot the host-side dst BEFORE copyExtras clobbers it. Anchor
+      // on localRoot so the backup tree mirrors the project layout.
+      backupExtrasWrite(dst, ts, localRoot);
+      copyExtras(src, dst);
+      log(`pulled extras ${logical}/${dirname} -> ${dst}`);
+    }
+  }
+  return { unmapped, skipped };
+}
+
+/**
+ * List files that differ between two paths via `git diff --no-index
+ * --name-only`. Exit 0 = identical, exit 1 = differences exist (not an
+ * error: read names from `e.stdout`). Other failures are surfaced via WARN
+ * so the operator can tell the difference between "no diff" (silent),
+ * "git not on PATH" (WARN), and other git failures (WARN) instead of all
+ * three paths collapsing to a silent empty list and defeating D-08's
+ * loud-doctor contract. Argv-array `execFileSync` (no shell) so paths
+ * cannot inject.
+ */
+function listDivergingFiles(a: string, b: string): string[] {
+  try {
+    const stdout = execFileSync('git', ['diff', '--no-index', '--name-only', a, b], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString();
+    return stdout.split('\n').filter((line) => line.length > 0);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { status?: number; stdout?: Buffer };
+    if (e.status === 1 && e.stdout !== undefined) {
+      return e.stdout
+        .toString()
+        .split('\n')
+        .filter((line) => line.length > 0);
+    }
+    if (e.code === 'ENOENT') {
+      warn(`git not on PATH; divergence check skipped for ${a}`);
+      return [];
+    }
+    warn(`divergence check failed for ${a}: ${e.message ?? String(err)}`);
+    return [];
+  }
+}
+
+/**
+ * Read-only pre-pull check: compare local `<localRoot>/<dirname>/` against
+ * the just-pulled `shared/extras/<logical>/<dirname>/` and emit a WARN per
+ * diverging file plus a count summary. Runs AFTER `git pull --rebase` and
+ * BEFORE `remapExtrasPull` (so local state is intact for comparison).
+ * Non-blocking per the inherited LWW model; the WARN message names the
+ * per-project `~/.cache/claude-nomad/backup/<ts>/extras/<encoded-localRoot>/`
+ * path that `remapExtrasPull` will write to so users can recover the
+ * overwritten content. The `<encoded-localRoot>` namespace mirrors
+ * `backupExtrasWrite`'s layout so two opted-in projects with the same
+ * relative extras path do not collide. Silent skip on missing path-map, no
+ * `extras` key, missing or `'TBD'` host path, non-whitelisted dirname, or
+ * either side absent.
+ */
+export function divergenceCheckExtras(ts: string): void {
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  if (!existsSync(mapPath)) return;
+
+  const map = readPathMap(mapPath);
+  const extrasMap = map.extras ?? {};
+  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
+  const backupRoot = join(HOME, '.cache', 'claude-nomad', 'backup', ts, 'extras');
+  for (const [logical, dirnames] of Object.entries(extrasMap)) {
+    assertSafeLogical(logical);
+    const localRoot = map.projects[logical]?.[HOST];
+    if (!localRoot || localRoot === 'TBD') continue;
+    assertSafeLocalRoot(localRoot, logical);
+    const projectBackupRoot = join(backupRoot, encodePath(localRoot));
+    for (const dirname of dirnames) {
+      if (!whitelist.includes(dirname)) continue;
+      const local = join(localRoot, dirname);
+      const repo = join(REPO_HOME, 'shared', 'extras', logical, dirname);
+      if (!existsSync(local) || !existsSync(repo)) continue;
+      const diff = listDivergingFiles(local, repo);
+      if (diff.length > 0) {
+        warn(
+          `local ${dirname} for ${logical} diverges from origin in ${diff.length} file(s); next remapExtrasPull will overwrite them (backups at ${projectBackupRoot}/)`,
+        );
+        for (const f of diff) warn(`  ${f}`);
+      }
+    }
+  }
+}

package/src/summary.ts

@@ -4,40 +4,48 @@ import { ok, warn } from './utils.ts';
  * Emit the single end-of-run summary line shared by cmdPull, cmdPush, and
  * cmdDiff. Canonical phrasing:
  *   - `summary: clean` when nothing was unmapped (and, for push, no
- *     collisions). Always printed so users see a consistent terminator
- *     and can spot when behavior changes.
+ *     collisions or extras skipped). Always printed so users see a consistent
+ *     terminator and can spot when behavior changes.
  *   - `summary: <N> unmapped on pull (run nomad doctor to list)`
+ *   - `summary: <N> unmapped on pull, <X> extras skipped (run nomad doctor to list)`
  *   - `summary: <N> unmapped on diff (run nomad doctor to list)`
  *   - `summary: <N> unmapped on push, <M> collisions (run nomad doctor to list)`
+ *   - `summary: <N> unmapped on push, <M> collisions, <X> extras skipped (run nomad doctor to list)`
  *
  * Clean outcomes go through `ok()` (green `✓` glyph, stdout) and unmapped /
- * collision outcomes go through `warn()` (yellow `⚠︎` glyph, stderr). The
- * status glyph carries the success/warn semantics; users see e.g.
+ * collision / extras-skipped outcomes go through `warn()` (yellow `⚠︎` glyph,
+ * stderr). The status glyph carries the success/warn semantics; users see e.g.
  * `✓ summary: clean` or `⚠︎ summary: 3 unmapped on pull (...)`. Note: clean
  * still goes to stdout so it survives backgrounded shell-rc invocations
  * like `nomad pull 2>/dev/null &`. `collisions` is meaningful only for
- * `'push'`; for `'pull'` / `'diff'` it is ignored and defaults to 0. This
- * module is the SINGLE source of truth for the phrasing, eliminating drift
- * risk across the three callers by construction.
+ * `'push'`; for `'pull'` / `'diff'` it is ignored and defaults to 0.
+ * `extrasSkipped` counts dirnames that the per-project whitelist
+ * (`SUPPORTED_EXTRAS`) declined to sync; surfaces from `remapExtrasPush`
+ * and `remapExtrasPull`. The fourth positional parameter defaults to 0 so
+ * legacy three-arg call sites continue to work unchanged (D-03 additive
+ * contract). This module is the SINGLE source of truth for the phrasing,
+ * eliminating drift risk across the three callers by construction.
  */
 export function emitSummary(
   verb: 'pull' | 'push' | 'diff',
   unmapped: number,
   collisions = 0,
+  extrasSkipped = 0,
 ): void {
   if (verb === 'push') {
-    if (unmapped === 0 && collisions === 0) {
+    if (unmapped === 0 && collisions === 0 && extrasSkipped === 0) {
       ok('summary: clean');
       return;
     }
-    warn(
-      `summary: ${unmapped} unmapped on push, ${collisions} collisions (run nomad doctor to list)`,
-    );
+    const base = `summary: ${unmapped} unmapped on push, ${collisions} collisions`;
+    const extras = extrasSkipped > 0 ? `, ${extrasSkipped} extras skipped` : '';
+    warn(`${base}${extras} (run nomad doctor to list)`);
     return;
   }
-  if (unmapped === 0) {
+  if (unmapped === 0 && extrasSkipped === 0) {
     ok('summary: clean');
     return;
   }
-  warn(`summary: ${unmapped} unmapped on ${verb} (run nomad doctor to list)`);
+  const extras = extrasSkipped > 0 ? `, ${extrasSkipped} extras skipped` : '';
+  warn(`summary: ${unmapped} unmapped on ${verb}${extras} (run nomad doctor to list)`);
 }

package/src/utils.ts

@@ -17,7 +17,7 @@ import {
 import { dirname, join, relative } from 'node:path';
 
 import { dim, failGlyph, green, infoGlyph, okGlyph, red, warnGlyph, yellow } from './color.ts';
-import { CLAUDE_HOME, HOME } from './config.ts';
+import { CLAUDE_HOME, HOME, type PathMap } from './config.ts';
 
 const LOCK_PATH = join(HOME, '.cache', 'claude-nomad', 'nomad.lock');
 
@@ -117,6 +117,29 @@ export function readJson<T>(path: string): T {
   return data as T;
 }
 
+/**
+ * Read `path-map.json` and wrap failures as `NomadFatal` so callers route the
+ * failure through their `try/finally` lock-release path instead of exposing a
+ * raw `SyntaxError` (or `ENOENT`/`EACCES`) past `NomadFatal`-only catch
+ * blocks. Equivalent to the inline `try { readJson } catch { throw NomadFatal }`
+ * pattern in `cmdPush`; use this helper at every other read site so the
+ * lock-release contract holds uniformly across the pipeline.
+ *
+ * Error verb is conditioned on the cause so ops can distinguish parse
+ * failures (malformed JSON) from IO failures (permission denied, file
+ * removed mid-run) without scraping the wrapped message. Callers gate on
+ * `existsSync(mapPath)` first in the happy path, so an `ENOENT` here means
+ * a TOCTOU race rather than the expected absent-file case.
+ */
+export function readPathMap(mapPath: string): PathMap {
+  try {
+    return readJson<PathMap>(mapPath);
+  } catch (err) {
+    const verb = err instanceof SyntaxError ? 'parse' : 'read';
+    throw new NomadFatal(`could not ${verb} path-map.json: ${(err as Error).message}`);
+  }
+}
+
 /**
  * Atomic write: temp + fsync + rename + parent-dir fsync. Survives
  * interrupted pulls. Preserves the destination file's existing mode when it
@@ -242,6 +265,37 @@ export function backupRepoWrite(absPath: string, ts: string, repoHome: string):
   cpSync(absPath, dst, { recursive: true, force: false, preserveTimestamps: true });
 }
 
+/**
+ * Parallel of `backupBeforeWrite` and `backupRepoWrite`, scoped to an
+ * explicit `projectRoot` instead of `CLAUDE_HOME` or `REPO_HOME`. Used by
+ * `remapExtrasPull` to snapshot host-side extras content (e.g.
+ * `<localRoot>/.planning/`) before `copyExtras` clobbers it. The existing
+ * helpers cannot serve this case: their `relative(CLAUDE_HOME, absPath)` and
+ * `relative(repoHome, absPath)` guards return a `..`-prefixed string for any
+ * path outside their anchor and silently no-op, so a pull-side
+ * `<localRoot>/.planning/` would never be backed up.
+ *
+ * Backup root is `extras/`-prefixed inside the same `<ts>` dir so the
+ * snapshot is distinguishable from `CLAUDE_HOME` dumps (no prefix) and
+ * `repo/` dumps. Layout:
+ * `~/.cache/claude-nomad/backup/<ts>/extras/<encoded-projectRoot>/<rel>/`
+ * where `<rel>` is `relative(projectRoot, absPath)` and
+ * `<encoded-projectRoot>` is `encodePath(projectRoot)`. The encoded prefix
+ * namespaces snapshots by project so two opted-in projects with the same
+ * relative extras path (e.g. both with `.planning/PLAN.md`) cannot collide
+ * inside the same `<ts>` directory (`cpSync` runs with `force: false`, so a
+ * collision would silently drop the second snapshot).
+ */
+export function backupExtrasWrite(absPath: string, ts: string, projectRoot: string): void {
+  if (!existsSync(absPath)) return;
+  const rel = relative(projectRoot, absPath);
+  if (rel.startsWith('..') || rel === '') return;
+  const backupRoot = join(HOME, '.cache', 'claude-nomad', 'backup', ts, 'extras');
+  const dst = join(backupRoot, encodePath(projectRoot), rel);
+  mkdirSync(dirname(dst), { recursive: true });
+  cpSync(absPath, dst, { recursive: true, force: false, preserveTimestamps: true });
+}
+
 /**
  * Acquire the exclusive nomad lockfile so two pulls/pushes cannot mutate
  * `~/.claude/` concurrently. Returns the handle on success, or `null` on