claude-nomad 0.30.0 → 0.31.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,18 @@
 # Changelog
 
+## [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)
@@ -610,7 +612,11 @@ 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 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 +768,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 +830,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 +844,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.31.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.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;
+}

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

@@ -0,0 +1,113 @@
+/**
+ * The Redact action for the push-time recovery menu. `applyRedact` resolves a
+ * finding's local transcript, refuses live sessions, re-scans the local file
+ * WITHOUT `--redact` to recover real secret values, rewrites it in place, and
+ * copies the cleaned file back to the staged tree.
+ *
+ * Split from `commands.push.recovery.actions.ts` to keep both modules under the
+ * ~220-line cap. Depends only on lower-level helpers (no import of the actions
+ * module), so the dependency direction stays acyclic: actions -> redact.
+ */
+
+import { cpSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
+
+import type { PathMap } from './config.ts';
+import { CLAUDE_HOME, HOST, REPO_HOME } from './config.ts';
+import { applyRedactions, isRecentlyModified, resolveLiveTranscript } from './commands.redact.ts';
+import type { Finding } from './push-gitleaks.scan.ts';
+import { scanFile } from './push-gitleaks.scan.ts';
+import { backupBeforeWrite } from './utils.fs.ts';
+import { encodePath } from './utils.json.ts';
+import { log } from './utils.ts';
+import { sessionIdFromFinding } from './commands.push.recovery.seams.ts';
+
+/**
+ * Apply the Redact action for one finding. Resolves the local transcript,
+ * checks the live-session guard, re-scans the local file (without `--redact`)
+ * to obtain real secret values, backs up, rewrites in place (same inode), and
+ * surgically copies the file back to the staged tree. Returns true on success,
+ * false when the session is active, unresolvable, or the local re-scan fails.
+ *
+ * The push-verdict findings (`f`, `allFindings`) drive which sessions to act on
+ * and provide session-id extraction, but their `Match` fields come from a
+ * `--redact` scan and are masked. The local re-scan (via `scan`) runs WITHOUT
+ * `--redact` so `applyRedactions` receives the real secret values.
+ *
+ * @param f Trigger finding (used for session-id extraction).
+ * @param allFindings Full finding set for this run (used for session-id
+ *   matching; values are masked and not used for redaction).
+ * @param ts Backup timestamp for `backupBeforeWrite`.
+ * @param map Parsed path-map for staged-tree path resolution.
+ * @param nowMs Injectable clock for the live-session mtime check.
+ * @param scan Injectable scan function for local re-scan (default: `scanFile`).
+ * @returns True when the redaction was applied; false when refused or failed.
+ */
+export function applyRedact(
+  f: Finding,
+  allFindings: Finding[],
+  ts: string,
+  map: PathMap,
+  nowMs: () => number,
+  scan: (p: string) => Finding[] | null = scanFile,
+): boolean {
+  /** Emit a refusal message and return false. */
+  const refuse = (msg: string): false => {
+    log(msg);
+    return false;
+  };
+
+  const sid = sessionIdFromFinding(f);
+  if (sid === null) {
+    return refuse(
+      `could not locate the local transcript for this finding; choose Skip or Drop session.`,
+    );
+  }
+  const localPath = resolveLiveTranscript(sid);
+  if (localPath === null) {
+    return refuse(
+      `could not locate the local transcript for session ${sid}; choose Skip or Drop session.`,
+    );
+  }
+  if (isRecentlyModified(statSync(localPath).mtimeMs, nowMs())) {
+    return refuse(
+      `session ${sid} looks active (modified within the last 5 minutes); refusing to redact, no changes made.\n` +
+        `  End the session and choose Redact again, or choose Drop session (holds this session back` +
+        ` from the push, local copy kept) or Skip.`,
+    );
+  }
+
+  // Re-scan without --redact to get real secret values for value-based redaction.
+  // Push-verdict findings have masked Match fields and cannot be used directly.
+  const realFindings = scan(localPath);
+  if (realFindings === null) {
+    return refuse(`re-scan of the transcript failed; choose Skip or Drop session.`);
+  }
+  if (realFindings.length === 0) {
+    return refuse(
+      `nothing to redact in the local transcript for session ${sid}; choose Skip or Drop session.`,
+    );
+  }
+
+  backupBeforeWrite(localPath, ts);
+  writeFileSync(localPath, applyRedactions(readFileSync(localPath, 'utf8'), realFindings), 'utf8');
+
+  let copied = false;
+  for (const [logical, hostMap] of Object.entries(map.projects)) {
+    const abs = hostMap[HOST];
+    if (abs === undefined) continue;
+    if (localPath.startsWith(join(CLAUDE_HOME, 'projects', encodePath(abs)) + sep)) {
+      cpSync(localPath, join(REPO_HOME, 'shared', 'projects', logical, `${sid}.jsonl`), {
+        force: true,
+      });
+      copied = true;
+      break;
+    }
+  }
+  if (!copied) {
+    return refuse(
+      `could not map the local transcript for session ${sid} to a staged copy; choose Drop session or Skip.`,
+    );
+  }
+  return true;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Pure, side-effect-free seams for the push-time recovery menu: key
+ * derivation, session-id extraction, and prompt-answer parsing. Extracted from
+ * `commands.push.recovery.actions.ts` so both modules stay under the 220-line
+ * advisory cap.
+ */
+
+import type { Finding } from './push-gitleaks.scan.ts';
+import { SESSION_PATH } from './push-gitleaks.ts';
+
+/** Action a user can assign to one finding in the recovery menu. */
+export type FindingAction = 'redact' | 'allow' | 'drop' | 'skip';
+
+/** Prompt function: asks one question and returns the answer. */
+export type PromptFn = (prompt: string) => Promise<string>;
+
+/**
+ * Build a stable key for a finding used as the actions-map key. Includes the
+ * rule id so two findings at the same file/line/column but different rules
+ * produce distinct keys and do not collide in the actions map.
+ *
+ * @param f The gitleaks finding.
+ * @returns A colon-delimited key combining file, start line, start column, and rule id.
+ */
+export function findingKey(f: Finding): string {
+  return `${f.File}:${f.StartLine}:${f.StartColumn}:${f.RuleID}`;
+}
+
+/** Valid session id charset: alphanumeric, hyphen, underscore (same as cmdDropSession/cmdRedact). */
+const VALID_SID = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Extract the session id from a finding's File path. Handles both the flat
+ * `shared/projects/<logical>/<sid>.jsonl` form (SESSION_PATH) and the deeper
+ * subagent form `shared/projects/<logical>/<sid>/...`. The extracted id is
+ * validated against `/^[A-Za-z0-9_-]+$/` before being returned; path-traversal
+ * segments (e.g. `..`) are rejected and cause a null return.
+ *
+ * @param f The gitleaks finding.
+ * @returns The session id, or null when the path matches neither pattern or the
+ *   extracted id contains characters outside `[A-Za-z0-9_-]`.
+ */
+export function sessionIdFromFinding(f: Finding): string | null {
+  // Try the flat `<sid>.jsonl` form first, then the deeper subagent form. Both
+  // patterns capture the session id at group 1; a matched capture group is
+  // always a string, so no nullish guard on `m[1]` is needed.
+  const m = SESSION_PATH.exec(f.File) ?? /^shared\/projects\/[^/]+\/([^/]+)\//.exec(f.File);
+  if (m === null) return null;
+  const sid = m[1];
+  return VALID_SID.test(sid) ? sid : null;
+}
+
+/**
+ * Parse a raw prompt answer into a `FindingAction`. Returns `'skip'` for
+ * empty, blank, or unrecognized input (D-02 default).
+ *
+ * @param raw The untrimmed string returned by the prompt.
+ * @returns The corresponding action, defaulting to `'skip'`.
+ */
+export function parseAction(raw: string): FindingAction {
+  const t = raw.trim().toLowerCase();
+  if (t === 'r' || t === 'redact') return 'redact';
+  if (t === 'a' || t === 'allow') return 'allow';
+  if (t === 'd' || t === 'drop') return 'drop';
+  return 'skip';
+}