claude-nomad 0.30.0 → 0.32.0

package/.gitleaks.toml

@@ -38,3 +38,23 @@ paths = [
     '''^shared/projects/[^/]+/.*\.jsonl$''',
 ]
 condition = "AND"
+
+# Path-scoped: SonarCloud issue-listing tool output (`gh`/sonar API dumps of
+# the form `key: <20-char id>` immediately followed by `rule: <lang>:S<n>`)
+# lands in session transcripts during PR reviews. The issue key is an opaque
+# 20-char base64url identifier, not a credential, but it is shaped like a
+# generic API key and does not carry the `AY` prefix the noise allowlist
+# above keys on. Anchoring on the surrounding `key:`/`rule:` structure (via
+# regexTarget = "line") keeps this from whitelisting a bare token: a real API
+# key is never followed by `\n  rule: <lang>:S####`. `condition = "AND"` plus
+# the session-jsonl path scope double-locks it to synced transcripts.
+[[allowlists]]
+description = "claude-nomad: SonarCloud issue-listing output (key: <id> / rule: <lang>:S<n>) in synced session transcripts"
+regexTarget = "line"
+regexes = [
+    '''key:\s*[A-Za-z0-9_-]{19,24}\\n\s*rule:\s*\w+:S\d+''',
+]
+paths = [
+    '''^shared/projects/[^/]+/.*\.jsonl$''',
+]
+condition = "AND"

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.32.0](https://github.com/funkadelic/claude-nomad/compare/v0.31.0...v0.32.0) (2026-05-30)
+
+
+### Added
+
+* **adopt:** add nomad adopt for pre-existing local dirs ([#185](https://github.com/funkadelic/claude-nomad/issues/185)) ([251d5b7](https://github.com/funkadelic/claude-nomad/commit/251d5b71569315cbcf6ae073e29faecb4dbe5aa2))
+
+
+### Documentation
+
+* **readme:** note synced skills carry shims, not the tool engine ([#183](https://github.com/funkadelic/claude-nomad/issues/183)) ([695ba02](https://github.com/funkadelic/claude-nomad/commit/695ba029a92f397a1469ca1cf5f782e0b5bcecac))
+
+## [0.31.0](https://github.com/funkadelic/claude-nomad/compare/v0.30.0...v0.31.0) (2026-05-29)
+
+
+### Added
+
+* **push:** interactive secret recovery on push and nomad redact ([#181](https://github.com/funkadelic/claude-nomad/issues/181)) ([4931e27](https://github.com/funkadelic/claude-nomad/commit/4931e27ba30998a02b123c71edc1315069c9181a))
+
+
+### Changed
+
+* **gitleaks:** allowlist SonarCloud issue-key tool-output noise in synced transcripts ([#179](https://github.com/funkadelic/claude-nomad/issues/179)) ([0f7d816](https://github.com/funkadelic/claude-nomad/commit/0f7d8161d4de3379cd6a4db00482f560c8b3f280))
+* **settings-drift:** author PRs via app token and make regen idempotent ([#182](https://github.com/funkadelic/claude-nomad/issues/182)) ([062397c](https://github.com/funkadelic/claude-nomad/commit/062397c565926471eccc8e75f72d1ccf2e5cc8c0))
+
 ## [0.30.0](https://github.com/funkadelic/claude-nomad/compare/v0.29.1...v0.30.0) (2026-05-29)
 
 

package/README.md

@@ -60,7 +60,9 @@ box, a personal rig and a work machine. [Get started in three steps.](#quickstar
   - [Commands](#commands)
   - [Recovery flows](#recovery-flows)
     - [`nomad drop-session <id>`](#nomad-drop-session-id)
+    - [`nomad redact <session-id>`](#nomad-redact-session-id)
     - [Recovery flow: gitleaks FATAL on a session JSONL](#recovery-flow-gitleaks-fatal-on-a-session-jsonl)
+    - [Recovery flow: push-time interactive menu](#recovery-flow-push-time-interactive-menu)
     - [`.gitleaks.toml` allowlist policy](#gitleakstoml-allowlist-policy)
   - [Cross-OS resume](#cross-os-resume)
   - [Run tests](#run-tests)
@@ -192,6 +194,17 @@ Pointers and specifics:
 > URLs) still need that side set up on each host. Put them in `hosts/<host>.json` or the plugin's
 > own per-host config.
 
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> Syncing a tool's `skills/` or `commands/` files copies the command shims, not the engine behind
+> them. If a tool keeps a binary or runtime outside `~/.claude/` (installed with `npm i -g`, a setup
+> script, and so on), nomad does not carry that part, so the synced commands appear on a new host but
+> fail until the tool itself is installed there. Install such tools once per host. For example, if you
+> sync the GSD (`get-shit-done`) skills, run `npm i -g get-shit-done-cc` on each host, pinned to the
+> version that matches your committed skills. Claude Code marketplace plugins (such as superpowers)
+> are the exception: they are listed in `enabledPlugins`, synced via `settings.base.json`, and
+> re-downloaded by Claude Code automatically, so they need no manual install.
+
 For the rationale behind these choices, see
 [What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs).
 
@@ -610,7 +623,13 @@ point under your npm prefix's `bin/`), then delete the alias line from your shel
 | `nomad diff`                     | Offline, lockless twin of `pull --dry-run`. No network, no lock. Works against the current local repo state.                                                                                                                                                                                                                                                                                                                                                                 |
 | `nomad push`                     | Export local sessions and opted-in per-project extras to logical names, commit (`chore: sync from <NOMAD_HOST>`), push.                                                                                                                                                                                                                                                                                                                                                      |
 | `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list) and a read-only gitleaks leak preview over a throwaway temp copy of the sessions and extras this host would stage; skip stage, commit, and push. Exits 1 if a leak is found in the preview. Nothing is written to the sync repo.                                                                                                                                                |
+| `nomad push --redact-all`        | Redact all findings non-interactively (backup written first) without a TTY. Does not auto-Allow findings. After redaction re-stages and re-scans; aborts with the session-aware FATAL if any finding survives. Use this in scripts or when you are confident every finding is a real secret that should be scrubbed. See [Recovery flow: push-time interactive menu](#recovery-flow-push-time-interactive-menu).                                                             |
 | `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 adopt <name>`             | Back up, then move a pre-existing `~/.claude/<name>` directory into `shared/<name>`, recreate the symlink so this host keeps working, and stage the result for push. `<name>` must already be listed in `SHARED_LINKS` or in the `sharedDirs` field of `path-map.json`; adopt is a mover, not a config editor, so it never writes `path-map.json` itself.                                                                                                                    |
+| `nomad adopt <name> --dry-run`   | Preview the planned backup, move, and `git add` without touching the filesystem or the git index.                                                                                                                                                                                                                                                                                                                                                                            |
+| `nomad redact <session-id>`      | Rewrite the secret span in the local source transcript for a session, backed up to `~/.cache/claude-nomad/backup/`. Refuses to touch a session that was modified recently (potential active session). Safe to re-run. See [`nomad redact <session-id>`](#nomad-redact-session-id).                                                                                                                                                                                           |
+| `nomad redact --rule <id>`       | Limit redaction to findings of one gitleaks rule id only.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `nomad redact --dry-run`         | Show what `nomad redact` would change without writing anything.                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `nomad update`                   | Topology-aware upgrade to the latest upstream. Flags: `--dry-run`, `--force`, `--push-origin`. See [Upgrading the tool](#upgrading-the-tool).                                                                                                                                                                                                                                                                                                                                |
 | `nomad doctor`                   | Read-only health check. Each line carries a status glyph (`✓` pass, `✗` fail, `⚠︎` warn); any `✗` sets `process.exitCode = 1` (`⚠︎` does not). Includes an offline-tolerant release-version staleness check, a Hook targets check that fails (`✗`, exit 1) when `settings.json` references a hook command whose script under `~/.claude/` is missing on this host, plus two `⚠︎`-only drift checks: gitleaks version drift and, on a private GitHub mirror, re-enabled Actions. |
 | `nomad doctor --resume-cmd <id>` | Print a host-local `cd ... && claude --resume <id>` line for a session (see [Cross-OS resume](#cross-os-resume)).                                                                                                                                                                                                                                                                                                                                                            |
@@ -762,6 +781,38 @@ scrubbing (the exact path when `path-map.json` maps the project to the current h
 `~/.claude/projects/` source, not the staged tree, so it keeps flagging the secret until the local
 transcript is scrubbed.
 
+### `nomad redact <session-id>`
+
+Rewrites the secret span in the local source transcript at
+`~/.claude/projects/<encoded>/<session-id>.jsonl` in place, replacing each flagged span with
+`[REDACTED:<rule>]`. Before rewriting, the original transcript is backed up to
+`~/.cache/claude-nomad/backup/<timestamp>/`.
+
+```bash
+$ nomad redact <session-id>
+$ nomad redact <session-id> --rule github-pat   # one rule only
+$ nomad redact <session-id> --dry-run           # preview without writing
+```
+
+What it does: rewrites the LOCAL source transcript (not just the staged copy). This is the durable
+fix for a gitleaks finding: `nomad drop-session` only removes the staged copy, but `remapPush`
+re-copies from local on the next push, so the secret resurfaces. Redacting the local source means
+future pushes carry clean content.
+
+What it does NOT do: rotate credentials. Always rotate the secret at its provider first.
+
+Safety checks:
+
+- A session whose transcript was modified within the last 5 minutes is treated as potentially active
+  (Claude Code may still be writing to it). `nomad redact` refuses to touch it and suggests
+  `nomad drop-session` or waiting for the session to end.
+- Before every rewrite, a backup is written to `~/.cache/claude-nomad/backup/<timestamp>/`, so the
+  original content is recoverable.
+- `--dry-run` prints the planned redactions and writes nothing.
+
+This command is safe to re-run: if the span was already redacted (the replacement token is already
+present), the content is unchanged.
+
 ### Recovery flow: gitleaks FATAL on a session JSONL
 
 `nomad push` runs `gitleaks protect --staged` before commit. To catch the same findings before you
@@ -792,10 +843,12 @@ Two branches from here:
    contaminated copy from the current staged tree, but that alone is NOT durable: `remapPush` (in
    `src/remap.ts`) does a full rm-and-copy mirror of your LOCAL transcripts into `shared/projects/`
    on every push, so the next `nomad push` re-copies the un-scrubbed local file forward and
-   re-stages the same secret. The durable fix is to rotate AND scrub or remove the local transcript
-   at `~/.claude/projects/<encoded>/<sid-aaaa>.jsonl` (plus the sibling `<sid-aaaa>/` subagent
-   directory under that encoded dir, if present) so the next `remapPush` carries clean content
-   forward. Do not leave the local file un-scrubbed and expect the staged-tree drop to hold.
+   re-stages the same secret. The durable fix is to rotate AND scrub the local transcript. The
+   easiest way: `nomad redact <sid-aaaa>` (see [`nomad redact`](#nomad-redact-session-id)), which
+   rewrites the secret span in place with a backup. Alternatively, remove the local transcript at
+   `~/.claude/projects/<encoded>/<sid-aaaa>.jsonl` (plus the sibling `<sid-aaaa>/` subagent
+   directory, if present). Do not leave the local file un-scrubbed and expect the staged-tree drop
+   to hold.
 
 2. **False positive.** Add an allowlist regex to `.gitleaks.toml` at the repo root that matches the
    noise pattern but not real-secret formats, commit it, then re-run `nomad push`. The new allowlist
@@ -804,6 +857,49 @@ Two branches from here:
 `nomad drop-session` only acts on the staged tree of `~/claude-nomad/`. Active Claude Code sessions
 writing to the local file are not disturbed.
 
+### Recovery flow: push-time interactive menu
+
+When `nomad push` detects a secret and the process is running on an interactive TTY, it presents a
+per-finding menu instead of aborting immediately. Each finding is shown with its rule id, file, and
+line number (the secret value is never printed: the scan uses `--redact`).
+
+```text
+Finding: github-pat in shared/projects/my-proj/abc123.jsonl line 42 (session: abc123)
+  [R]edact  [A]llow  [D]rop session  [S]kip (default)
+>
+```
+
+What the actions do:
+
+- **Redact** rewrites the secret span in the LOCAL source transcript in place (same flow as
+  `nomad redact`), backs up first, then re-copies the file to the staged tree. Refuses if the
+  session was modified in the last 5 minutes (potential active session): choose Drop or Skip instead
+  and wait for the session to end.
+- **Allow** appends the finding's fingerprint to `.gitleaksignore` at the repo root. Use this for
+  confirmed false positives. The fingerprint format (`file:rule:line`) is tied to the current line,
+  so if the content moves gitleaks re-prompts rather than silently suppressing a new hit.
+- **Drop session** excludes this session from the current push by unstaging it from the repo's git
+  index (same as `nomad drop-session <id>`). The local `~/.claude/projects/.../` transcript is kept
+  intact and any running Claude session is not stopped. Not durable: the next push re-copies from
+  local unless you also redact or remove the local transcript.
+- **Skip** (default on bare Enter) leaves the finding unresolved for now.
+
+After you respond to every finding, the menu applies your choices. If any finding was Skipped, the
+push aborts with the session-aware FATAL (same exit as a non-interactive push with findings). If all
+findings were resolved, the staged tree is updated and re-scanned. A clean re-scan proceeds to
+commit and push. If new findings appear after the first round of actions, the menu loops on the new
+set.
+
+On a non-TTY (CI, piped input, or scripted `nomad push`), the menu never appears and the push aborts
+with the existing session-aware FATAL unchanged.
+
+**Batch redact without a TTY:** `nomad push --redact-all` redacts every finding non-interactively
+(backup written first) without prompting and without requiring a TTY. It does not auto-Allow. After
+redaction the staged tree is re-scanned; any surviving finding aborts with the FATAL. Use this in
+scripts or when every finding is a real secret that should be scrubbed. For a single session,
+`nomad redact <session-id>` (see [`nomad redact`](#nomad-redact-session-id)) gives you per-session
+control with `--rule` and `--dry-run` options.
+
 ### `.gitleaks.toml` allowlist policy
 
 `gitleaks protect` runs against the staged tree on every `nomad push` and can flag

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.30.0",
+  "version": "0.32.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.adopt.ts

@@ -0,0 +1,183 @@
+import { cpSync, existsSync, lstatSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CLAUDE_HOME, HOME, REPO_HOME, SHARED_LINKS, type PathMap } from './config.ts';
+import { isValidSharedDir } from './config.sharedDirs.guard.ts';
+import { fail, gitOrFatal, log, NomadFatal } from './utils.ts';
+import { backupBeforeWrite, ensureSymlink, freshBackupTs } from './utils.fs.ts';
+import { readPathMap } from './utils.json.ts';
+
+/**
+ * Follow-up hint printed after a successful adopt. Exported so Plan 02's
+ * doctor hint can reuse the exact literal without duplicating the string.
+ */
+export const ADOPT_PUSH_HINT = 'run `nomad push` to share with other hosts';
+
+/**
+ * lstat-based existence check that, unlike `existsSync`, does NOT follow
+ * symlinks: a dangling symlink at `p` returns true. Used for the clobber
+ * guard so an existing (even broken) `shared/<name>` link is refused rather
+ * than fed to `cpSync`, which would otherwise throw an opaque non-NomadFatal
+ * error on a dangling-symlink destination.
+ *
+ * @param p Absolute path to probe.
+ * @returns True when any entry (file, dir, or symlink) exists at `p`.
+ */
+function lexists(p: string): boolean {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read `path-map.json` if present; fall back to an empty map when absent.
+ * Adopt reads sharedDirs for membership only; it never writes path-map.json.
+ *
+ * @param repoHome Absolute path to the nomad repo root.
+ * @returns The parsed PathMap, or `{ projects: {} }` when path-map.json is absent.
+ */
+function readMapIfPresent(repoHome: string): PathMap {
+  const mapPath = join(repoHome, 'path-map.json');
+  return existsSync(mapPath) ? readPathMap(mapPath) : { projects: {} };
+}
+
+/**
+ * Return true when `name` is an already-configured shared target: either a
+ * static `SHARED_LINKS` member or a `sharedDirs` entry declared in
+ * `path-map.json`. This is a read-only membership check; adopt never writes
+ * `path-map.json` (D-03).
+ *
+ * @param name Candidate name.
+ * @param map Parsed path-map (sharedDirs membership source).
+ * @returns True when name is a configured shared target.
+ */
+function isConfiguredTarget(name: string, map: PathMap): boolean {
+  return (
+    (SHARED_LINKS as readonly string[]).includes(name) || (map.sharedDirs?.includes(name) ?? false)
+  );
+}
+
+/**
+ * Return true when `name` is safe to adopt. Static `SHARED_LINKS` members
+ * are pre-approved and bypass `isValidSharedDir` (which rejects RESERVED_SHARED,
+ * overlapping with SHARED_LINKS). Candidate `sharedDirs` names must pass
+ * `isValidSharedDir` to prevent path injection (D-00a).
+ *
+ * @param name Candidate name from the CLI argument.
+ * @returns True when the name is safe for adopt processing.
+ */
+function isValidAdoptName(name: string): boolean {
+  if ((SHARED_LINKS as readonly string[]).includes(name)) return true;
+  return isValidSharedDir(name);
+}
+
+/**
+ * Perform the actual backup -> copy -> remove -> relink -> stage sequence
+ * once all preconditions have passed. Extracts the mutation block so the
+ * top-level function stays under the cognitive-complexity threshold.
+ *
+ * @param name The validated, configured, real-directory name to adopt.
+ * @param linkPath Absolute path of the source directory (`CLAUDE_HOME/<name>`).
+ * @param sharedTarget Absolute path of the destination (`REPO_HOME/shared/<name>`).
+ */
+function performAdoptMove(name: string, linkPath: string, sharedTarget: string): void {
+  const backupBase = join(HOME, '.cache', 'claude-nomad', 'backup');
+  const ts = freshBackupTs(backupBase);
+
+  // D-00c: backup before any mutation
+  backupBeforeWrite(linkPath, ts);
+
+  // D-00e, V-07: copy fully into shared/ BEFORE removing the source so a
+  // mid-move crash cannot lose user content
+  cpSync(linkPath, sharedTarget, { recursive: true, force: true, preserveTimestamps: true });
+  rmSync(linkPath, { recursive: true, force: true });
+
+  // D-01: recreate the symlink immediately on this host
+  ensureSymlink(linkPath, sharedTarget);
+
+  // D-02: targeted stage of shared/<name> only; never git add -A
+  const rel = join('shared', name);
+  gitOrFatal(['add', '--', rel], `git add shared/${name}`, REPO_HOME);
+
+  log(`adopted ${name}; ${ADOPT_PUSH_HINT}`);
+}
+
+/**
+ * Bring a pre-existing `~/.claude/<name>` directory into the nomad shared set.
+ *
+ * Validates `name`, enforces the precondition matrix, then performs:
+ * backup -> copy-into-shared -> remove-source -> recreate-symlink ->
+ * targeted `git add` -> print follow-up hint. Stops there: no auto-commit,
+ * no push pipeline (D-02).
+ *
+ * Accepts only already-configured names: a static SHARED_LINKS member or a
+ * `sharedDirs` entry already declared in `path-map.json`. adopt is a mover,
+ * not a config editor; it never writes `path-map.json` (D-03).
+ *
+ * `--dry-run` reports the planned actions and performs zero filesystem or
+ * git changes (D-00d, V-08).
+ *
+ * @param name The `~/.claude/<name>` directory to adopt.
+ * @param opts.dryRun When true, log planned actions and return without mutation.
+ */
+export function cmdAdopt(name: string, opts: { dryRun?: boolean } = {}): void {
+  const dryRun = opts.dryRun === true;
+
+  // D-00a: validate name format (rejects path separators, NEVER_SYNC, and arbitrary
+  // names that are not in SHARED_LINKS; SHARED_LINKS statics bypass isValidSharedDir
+  // because RESERVED_SHARED overlaps with SHARED_LINKS by design)
+  if (!isValidAdoptName(name)) {
+    fail(`invalid name: ${JSON.stringify(name)}`);
+    process.exit(1);
+  }
+
+  // D-03: confirm name is an already-configured shared target
+  const map = readMapIfPresent(REPO_HOME);
+  if (!isConfiguredTarget(name, map)) {
+    fail(
+      `${name}: not a configured shared target. ` +
+        `Add it to sharedDirs in path-map.json first, then re-run adopt.`,
+    );
+    process.exit(1);
+  }
+
+  const linkPath = join(CLAUDE_HOME, name);
+  const sharedTarget = join(REPO_HOME, 'shared', name);
+
+  // D-00b precondition checks -- in order: absent, already symlink, would clobber
+  if (!existsSync(linkPath)) {
+    log(`${name}: nothing to adopt (not present in ~/.claude/)`);
+    return;
+  }
+  if (lstatSync(linkPath).isSymbolicLink()) {
+    log(`${name}: already adopted (already a symlink)`);
+    return;
+  }
+  if (lexists(sharedTarget)) {
+    fail(`${name}: shared/${name} already exists; would clobber. Remove it first.`);
+    process.exit(1);
+  }
+
+  // D-00d: dry-run preview -- branch before any mutation
+  if (dryRun) {
+    const backupBase = join(HOME, '.cache', 'claude-nomad', 'backup');
+    const ts = freshBackupTs(backupBase);
+    log(`would backup: ${linkPath} -> backup/${ts}/${name}`);
+    log(`would move: ${linkPath} -> shared/${name}`);
+    log(`would stage: shared/${name}`);
+    return;
+  }
+
+  /* c8 ignore start -- catch is defensive: performAdoptMove only throws on a git/fs fault */
+  try {
+    performAdoptMove(name, linkPath, sharedTarget);
+  } catch (err) {
+    if (!(err instanceof NomadFatal)) throw err;
+    fail(err.message);
+    process.exitCode = 1;
+  }
+  /* c8 ignore stop */
+}

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

@@ -119,7 +119,10 @@ function classifySharedLink(name: string, p: string): { line: string; fail: bool
     return { line: `${red(failGlyph)} ${name}: could not stat (${String(code)})`, fail: true };
   }
   if (!stat.isSymbolicLink()) {
-    return { line: `${red(failGlyph)} ${name}: NOT a symlink (blocks sync)`, fail: true };
+    return {
+      line: `${red(failGlyph)} ${name}: NOT a symlink (blocks sync); run \`nomad adopt ${name}\` to fix`,
+      fail: true,
+    };
   }
   return classifySymlinkTarget(name, p);
 }

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

@@ -13,12 +13,12 @@ const SHARED_PROJECT_LOGICAL = /^shared\/projects\/([^/]+)\//;
 
 /**
  * After a successful drop, remind the operator that the unstage is per-push
- * only: the leaked secret still lives in the local transcript, so the next
- * `nomad push` re-copies it (via `remapPush`) and `nomad doctor --check-shared`
- * keeps reporting it (it scans the live `~/.claude/projects/` source, not the
- * repo index). Points at the exact live transcript when it resolves for this
- * host, or a generic `~/.claude/projects/<encoded>/<id>.jsonl` template
- * otherwise. Advisory output only; never mutates state.
+ * only: the local source still contains the secret, so the next `nomad push`
+ * re-copies it (via `remapPush`) and `nomad doctor --check-shared` keeps
+ * reporting it (it scans the live `~/.claude/projects/` source, not the repo
+ * index). Full remediation requires rotating the credential, then running
+ * `nomad redact <id>` (or scrubbing the local transcript manually). Advisory
+ * output only; never mutates state.
  *
  * @param id Already-validated session id.
  * @param matches Repo-relative paths collected by `collectMatches`.
@@ -27,10 +27,12 @@ export function reportScrubHint(id: string, matches: string[]): void {
   const live = resolveLiveTranscript(id, matches);
   const target = live ?? `~/.claude/projects/<encoded>/${id}.jsonl`;
   log(
-    'note: this only un-stages the session from the next push. The leaked secret\n' +
-      '  is still in your local transcript, so nomad push re-stages it and nomad\n' +
-      '  doctor --check-shared keeps reporting it. To remediate, rotate the\n' +
-      `  credential, then scrub ${target}`,
+    'note: this only un-stages the session from the next push.\n' +
+      '  The local source still contains the secret, so nomad push re-stages it\n' +
+      '  on the next run and nomad doctor --check-shared keeps reporting it.\n' +
+      '  To fully remediate: rotate the credential, then run:\n' +
+      `    nomad redact ${id}\n` +
+      `  (or scrub ${target} manually)`,
   );
 }
 

package/src/commands.push.recovery.actions.ts

@@ -0,0 +1,165 @@
+/**
+ * I/O action dispatchers for the push-time recovery menu: `applyAllow`,
+ * `applyRedact`, `collectActions`, `dispatchActions`, `redactAllFindings`.
+ * Pure seams live in `commands.push.recovery.seams.ts`; lock-free drop
+ * helper in `commands.push.recovery.drop.ts`.
+ */
+
+import type { PathMap } from './config.ts';
+import { appendGitleaksIgnore } from './commands.redact.ts';
+import { applyRedact } from './commands.push.recovery.redact.ts';
+import { dropSessionFromStaged } from './commands.push.recovery.drop.ts';
+import type { Finding } from './push-gitleaks.scan.ts';
+import { scanFile } from './push-gitleaks.scan.ts';
+import { log } from './utils.ts';
+import {
+  type FindingAction,
+  type PromptFn,
+  findingKey,
+  parseAction,
+  sessionIdFromFinding,
+} from './commands.push.recovery.seams.ts';
+
+export type { FindingAction, PromptFn };
+export { dropSessionFromStaged, findingKey, parseAction, sessionIdFromFinding };
+
+/** Apply the Allow action: append the finding's fingerprint to .gitleaksignore. */
+export function applyAllow(f: Finding): void {
+  appendGitleaksIgnore(f.Fingerprint);
+}
+
+/**
+ * Walk all findings and prompt the user for one action each. Returns a map
+ * from `findingKey` to the chosen action, defaulting to `'skip'` on empty
+ * input.
+ *
+ * @param findings The findings to present.
+ * @param prompt An injectable prompt function (one question per call).
+ * @returns Populated actions map.
+ */
+export async function collectActions(
+  findings: Finding[],
+  prompt: PromptFn,
+): Promise<Map<string, FindingAction>> {
+  const actions = new Map<string, FindingAction>();
+  for (const f of findings) {
+    const sid = sessionIdFromFinding(f);
+    const header =
+      `\nFinding: ${f.RuleID} in ${f.File} line ${f.StartLine}` +
+      (sid !== null ? ` (session: ${sid})` : '') +
+      '\n  [R]edact  [A]llow  [D]rop session  [S]kip (default)\n';
+    actions.set(findingKey(f), parseAction(await prompt(header + '> ')));
+  }
+  return actions;
+}
+
+/**
+ * Apply one finding's triaged action against local state. Extracted from
+ * `dispatchActions` so each function stays under the cognitive-complexity gate.
+ * `redactedSids` and `droppedSids` are mutated in place so per-session
+ * de-duplication is maintained across the caller's loop. Drop wins: once a
+ * session id appears in `droppedSids`, subsequent redact or allow actions for
+ * findings in that session are skipped.
+ *
+ * @param f The finding to act on.
+ * @param findings Full findings list (passed to `applyRedact` for per-session redaction).
+ * @param actions The action map returned by `collectActions`.
+ * @param ts Backup timestamp.
+ * @param map Parsed path-map.
+ * @param nowMs Injectable clock.
+ * @param scan Injectable scan function for `applyRedact`.
+ * @param drop Injectable staged-copy remover for the Drop action.
+ * @param redactedSids Set of already-redacted session ids (mutated in place).
+ * @param droppedSids Set of already-dropped session ids (mutated in place).
+ */
+function dispatchOne(
+  f: Finding,
+  findings: Finding[],
+  actions: Map<string, FindingAction>,
+  ts: string,
+  map: PathMap,
+  nowMs: () => number,
+  scan: (p: string) => Finding[] | null,
+  drop: (sid: string, map: PathMap) => boolean,
+  redactedSids: Set<string>,
+  droppedSids: Set<string>,
+): void {
+  const action = actions.get(findingKey(f)) ?? 'skip';
+  if (action === 'skip') return;
+  if (action === 'allow') {
+    applyAllow(f);
+    return;
+  }
+  const sid = sessionIdFromFinding(f);
+  if (sid === null) return;
+  if (droppedSids.has(sid)) return;
+  if (action === 'drop') {
+    droppedSids.add(sid);
+    if (drop(sid, map)) {
+      log(
+        `dropped session ${sid} from this push (local transcript kept; the secret remains in your local copy)`,
+      );
+    }
+    return;
+  }
+  if (action === 'redact' && !redactedSids.has(sid)) {
+    if (applyRedact(f, findings, ts, map, nowMs, scan)) redactedSids.add(sid);
+  }
+}
+
+/**
+ * Dispatch all non-skip actions from the triage map against local state.
+ * Redacted sessions are de-duplicated: the first finding for a given session
+ * triggers the in-place rewrite; subsequent findings for the same session are
+ * skipped (the rewrite already covered all findings in one pass).
+ *
+ * @param findings Full findings list from the current verdict.
+ * @param actions The action map returned by `collectActions`.
+ * @param ts Backup timestamp.
+ * @param map Parsed path-map.
+ * @param nowMs Injectable clock.
+ * @param scan Injectable scan function for `applyRedact` (default: `scanFile`).
+ * @param drop Injectable staged-copy remover for the Drop action (default: `dropSessionFromStaged`).
+ */
+export function dispatchActions(
+  findings: Finding[],
+  actions: Map<string, FindingAction>,
+  ts: string,
+  map: PathMap,
+  nowMs: () => number,
+  scan: (p: string) => Finding[] | null = scanFile,
+  drop: (sid: string, map: PathMap) => boolean = dropSessionFromStaged,
+): void {
+  const redactedSids = new Set<string>();
+  const droppedSids = new Set<string>();
+  for (const f of findings) {
+    dispatchOne(f, findings, actions, ts, map, nowMs, scan, drop, redactedSids, droppedSids);
+  }
+}
+
+/**
+ * Batch-redact all findings non-interactively (the `--redact-all` path).
+ * Does not require a TTY. Findings with no resolvable session id are skipped.
+ * Sessions are de-duplicated: the first finding per session triggers the
+ * rewrite.
+ *
+ * @param findings All findings from the current verdict.
+ * @param ts Backup timestamp.
+ * @param map Parsed path-map.
+ * @param nowMs Injectable clock.
+ * @param scan Injectable scan function for `applyRedact` (default: `scanFile`).
+ */
+export function redactAllFindings(
+  findings: Finding[],
+  ts: string,
+  map: PathMap,
+  nowMs: () => number,
+  scan: (p: string) => Finding[] | null = scanFile,
+): void {
+  const redactedSids = new Set<string>();
+  for (const f of findings) {
+    const sid = sessionIdFromFinding(f);
+    if (sid === null || redactedSids.has(sid)) continue;
+    if (applyRedact(f, findings, ts, map, nowMs, scan)) redactedSids.add(sid);
+  }
+}

package/src/commands.push.recovery.drop.ts

@@ -0,0 +1,47 @@
+/**
+ * Lock-free session drop helper for the push-time recovery menu.
+ * `dropSessionFromStaged` removes a session's generated copies from the
+ * `REPO_HOME/shared/projects/` tree so the recovery loop's subsequent
+ * `git add -A` stages the deletion rather than re-staging the file.
+ *
+ * Kept separate from `commands.push.recovery.actions.ts` to respect the
+ * ~220-line module cap.
+ */
+
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { PathMap } from './config.ts';
+import { REPO_HOME } from './config.ts';
+
+/**
+ * Remove the session's generated copies from the staged tree under
+ * `REPO_HOME/shared/projects/<logical>/` so the subsequent `git add -A` in
+ * the recovery loop stages the deletion rather than re-staging the file.
+ *
+ * Removes both the flat `<sid>.jsonl` transcript and the sibling subagent
+ * directory `<sid>/` (if present) for every logical project in `map`. These
+ * are generated copies produced by `remapPush`; the originals under
+ * `~/.claude/projects/` are never touched.
+ *
+ * Lock-free by design: the caller (`dispatchActions`) runs inside a `push`
+ * that already holds the global nomad lock. Calling `cmdDropSession` here
+ * would deadlock on the lock it already owns.
+ *
+ * @param sid Session id to drop from the staged tree.
+ * @param map Parsed path-map; provides the logical project names.
+ * @returns True when `map.projects` has at least one logical entry (the
+ *   session copies were targeted for removal), false when the map is empty
+ *   and no paths were evaluated.
+ */
+export function dropSessionFromStaged(sid: string, map: PathMap): boolean {
+  const logicals = Object.keys(map.projects);
+  if (logicals.length === 0) return false;
+  for (const logical of logicals) {
+    const jsonl = join(REPO_HOME, 'shared', 'projects', logical, `${sid}.jsonl`);
+    const dir = join(REPO_HOME, 'shared', 'projects', logical, sid);
+    rmSync(jsonl, { force: true });
+    rmSync(dir, { recursive: true, force: true });
+  }
+  return true;
+}