claude-nomad 0.30.0 → 0.31.0

package/src/commands.push.recovery.ts

@@ -0,0 +1,198 @@
+/**
+ * Push-time interactive recovery menu for gitleaks findings. When `nomad push`
+ * detects secrets in the staged tree and the process is running on a real TTY,
+ * `resolveLeakFindings` presents a per-finding Redact / Allow / Drop / Skip
+ * menu (default Skip), applies each resolved action, then re-stages and
+ * re-scans. The push proceeds only when zero findings remain unresolved.
+ *
+ * Non-TTY contexts (CI, piped input) keep the existing `buildSessionAwareFatal`
+ * abort unchanged: the function throws a `NomadFatal` carrying the existing
+ * recovery body verbatim (D-01: zero CI behavior change).
+ *
+ * `--redact-all` bypasses the prompt and redacts every real finding in batch
+ * without requiring a TTY.
+ *
+ * Action helpers and per-finding dispatch live in
+ * `commands.push.recovery.actions.ts` to keep both modules under the 220-line
+ * advisory cap.
+ */
+
+import { createInterface } from 'node:readline/promises';
+
+import type { PathMap } from './config.ts';
+import { REPO_HOME } from './config.ts';
+import {
+  type FindingAction,
+  type PromptFn,
+  collectActions,
+  dispatchActions,
+  findingKey,
+  redactAllFindings,
+} from './commands.push.recovery.actions.ts';
+import type { Finding } from './push-gitleaks.scan.ts';
+import { scanFile } from './push-gitleaks.scan.ts';
+import { buildSessionAwareFatal, partitionFindings } from './push-gitleaks.ts';
+import type { LeakVerdict } from './push-leak-verdict.ts';
+import { NomadFatal, gitOrFatal } from './utils.ts';
+
+export type { FindingAction };
+
+/**
+ * Dependency injection object for `resolveLeakFindings`. Provides seams for
+ * the prompt loop, the re-scan, the clock, and the TTY check so tests can
+ * drive the interactive flow without a real terminal.
+ */
+export type RecoveryDeps = {
+  /** Override TTY detection (default: `isTTY()`). */
+  isTTYCheck?: () => boolean;
+  /** Override `scanPushVerdict` for the post-action re-scan. */
+  scanVerdict?: () => LeakVerdict;
+  /** Injectable clock for live-session detection (default: `Date.now`). */
+  nowMs?: () => number;
+  /** When true, redact all findings without prompting; no TTY required. */
+  redactAll?: boolean;
+  /** Injectable prompt factory for tests (default: real readline). */
+  makePrompt?: () => PromptFn;
+  /** Injectable single-file scan for redaction (default: `scanFile`). */
+  scan?: (p: string) => Finding[] | null;
+  /** Injectable legend printer for tests (default: `printRecoveryLegend`). */
+  printLegend?: () => void;
+};
+
+/**
+ * True when both stdin and stdout are interactive TTYs. Accepts injectable
+ * stream objects so tests can drive the branch without a real TTY.
+ *
+ * @param stdin Readable with optional `isTTY` flag (default: `process.stdin`).
+ * @param stdout Writable with optional `isTTY` flag (default: `process.stdout`).
+ * @returns True iff both streams report `isTTY === true`.
+ */
+export function isTTY(
+  stdin: { isTTY?: boolean } = process.stdin,
+  stdout: { isTTY?: boolean } = process.stdout,
+): boolean {
+  return stdin.isTTY === true && stdout.isTTY === true;
+}
+
+/**
+ * True when any value in the actions map is `'skip'`, meaning at least one
+ * finding was left unresolved. Pure, no I/O.
+ *
+ * @param actions Per-finding action map keyed by `findingKey`.
+ * @returns True when at least one action is `'skip'`.
+ */
+export function hasUnresolved(actions: Map<string, FindingAction>): boolean {
+  for (const action of actions.values()) {
+    if (action === 'skip') return true;
+  }
+  return false;
+}
+
+/**
+ * Print a one-time action legend to stdout before the interactive menu loop.
+ * Called exactly once on the TTY path; never called on non-TTY or --redact-all.
+ *
+ * @param print Output sink (default: `console.log`). Injectable for tests.
+ */
+export function printRecoveryLegend(print: (line: string) => void = console.log): void {
+  print('');
+  print('Recovery actions:');
+  print('  Redact       - scrub the secret from the local transcript, push the cleaned copy');
+  print('  Allow        - mark as false positive (adds a .gitleaksignore fingerprint), push as-is');
+  print('  Drop session - exclude this session from this push (local transcript kept, running');
+  print('                 session is not stopped)');
+  print('  Skip         - leave unresolved (the push aborts)');
+  print('');
+}
+
+/** Build the real-TTY readline-based prompt function (one interface per call). */
+function makeRealPrompt(): PromptFn {
+  return async (prompt: string) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true,
+    });
+    try {
+      return await rl.question(prompt);
+    } finally {
+      rl.close();
+    }
+  };
+}
+
+/**
+ * Resolve the gitleaks findings from `verdict` interactively (TTY path) or
+ * via `--redact-all` (non-interactive batch path). On a non-TTY context with
+ * no `--redact-all` flag, throws `NomadFatal` carrying the existing recovery
+ * body verbatim (D-01: zero CI behavior change).
+ *
+ * TTY flow (D-02, D-03): prompts once per finding with R/A/D/S (default Skip
+ * on empty input), collects all actions, dispatches them, then re-stages via
+ * `git add -A` and re-scans. If the re-scan still has findings the menu loops
+ * on the new set. If any finding remains Skipped after triage, throws the
+ * session-aware FATAL so the push aborts with the same non-zero exit.
+ *
+ * @param verdict The current leak verdict from `scanPushVerdict`.
+ * @param ts Backup timestamp created at the start of this push run.
+ * @param map Parsed `path-map.json` for session path resolution.
+ * @param deps Optional dependency overrides for testing.
+ * @returns The final clean `LeakVerdict` after all findings are resolved.
+ */
+export async function resolveLeakFindings(
+  verdict: LeakVerdict,
+  ts: string,
+  map: PathMap,
+  deps: RecoveryDeps = {},
+): Promise<LeakVerdict> {
+  const {
+    isTTYCheck = isTTY,
+    nowMs = Date.now,
+    redactAll = false,
+    makePrompt: makePromptFn = makeRealPrompt,
+    scan = scanFile,
+    printLegend = printRecoveryLegend,
+  } = deps;
+
+  const scanVerdict = deps.scanVerdict ?? (await import('./push-leak-verdict.ts')).scanPushVerdict;
+
+  let current = verdict;
+
+  if (redactAll) {
+    redactAllFindings(current.findings, ts, map, nowMs, scan);
+    gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
+    const next = scanVerdict();
+    if (next.leak) {
+      const { bySession, other } = partitionFindings(next.findings);
+      throw new NomadFatal(buildSessionAwareFatal(bySession, other));
+    }
+    return next;
+  }
+
+  if (!isTTYCheck()) {
+    // Every leak:true verdict has a non-null recovery body. The fallback covers
+    // the defensive unreachable case (scan-crash with leak=true).
+    /* c8 ignore next */
+    throw new NomadFatal(current.recovery ?? 'gitleaks detected secrets');
+  }
+
+  const prompt = makePromptFn();
+  printLegend();
+
+  while (current.leak && current.findings.length > 0) {
+    const actions = await collectActions(current.findings, prompt);
+
+    if (hasUnresolved(actions)) {
+      // collectActions populates an entry for every finding, so `get` never
+      // returns undefined here; an explicit `=== 'skip'` needs no default.
+      const unresolved = current.findings.filter((f) => actions.get(findingKey(f)) === 'skip');
+      const { bySession, other } = partitionFindings(unresolved);
+      throw new NomadFatal(buildSessionAwareFatal(bySession, other));
+    }
+
+    dispatchActions(current.findings, actions, ts, map, nowMs, scan);
+    gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
+    current = scanVerdict();
+  }
+  return current;
+}

package/src/commands.push.ts

@@ -3,6 +3,7 @@ import { join, relative } from 'node:path';
 
 import { HOME, HOST, type PathMap, REPO_HOME } from './config.ts';
 import { enforceAllowList } from './commands.push.allowlist.ts';
+import { resolveLeakFindings } from './commands.push.recovery.ts';
 import { type PushState, renderNoScanTree, renderPushTree } from './commands.push.sections.ts';
 import { remapExtrasPush } from './extras-sync.ts';
 import { scanPushVerdict } from './push-leak-verdict.ts';
@@ -35,27 +36,27 @@ function guardGitlinks(): void {
 }
 
 /**
- * The staged-tree leak gate + commit/push for the REAL push path. Runs
- * `scanPushVerdict` AFTER `git add -A` (sees what would push) but BEFORE commit
- * (a detection unwinds cleanly with no commit to revert). On a leak it renders
- * the tree (with the ✗ Leak scan row + Summary) so the tree precedes the
- * recovery block, then throws the recovery body as a `NomadFatal` (the catch
- * prints it and sets a non-zero exit). On a clean scan it commits, pushes, and
- * renders the tree with the `✓ no leaks` row.
+ * Staged-tree leak gate + commit/push. Stages with `git add -A`, scans, and
+ * on a leak renders the ✗ tree row then delegates to `resolveLeakFindings`
+ * (TTY interactive menu or non-TTY FATAL throw, D-01 preserved). On a clean
+ * scan commits, pushes, and renders the `✓ no leaks` row.
  *
- * @param st - The collected push state for the final tree render.
+ * @param st - Push state for the tree render.
+ * @param ts - Backup timestamp passed to the recovery flow.
+ * @param map - Parsed path-map for session path resolution.
+ * @param redactAll - When true, redact all findings non-interactively.
  */
-function commitAndPush(st: PushState): void {
-  // gitOrFatal uses execFileSync (no shell) so NOMAD_HOST cannot escape quoting.
+async function commitAndPush(
+  st: PushState,
+  ts: string,
+  map: PathMap,
+  redactAll: boolean,
+): Promise<void> {
   gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
-  const verdict = scanPushVerdict();
+  let verdict = scanPushVerdict();
   if (verdict.leak) {
     renderPushTree(st, verdict);
-    // Every `leak: true` branch of scanPushVerdict sets a non-null recovery
-    // body, so the `?? fallback` is defensively unreachable (excluded from
-    // coverage rather than contorting a test to fake an impossible state).
-    /* c8 ignore next */
-    throw new NomadFatal(verdict.recovery ?? 'gitleaks detected secrets');
+    verdict = await resolveLeakFindings(verdict, ts, map, { redactAll });
   }
   gitOrFatal(['commit', '-m', `chore: sync from ${HOST}`], 'git commit', REPO_HOME);
   gitOrFatal(['push'], 'git push', REPO_HOME);
@@ -144,8 +145,9 @@ function runDryRunPreview(st: PushState, map: PathMap | null): void {
  * pre-existing violation surfaces; an empty status has nothing to classify.
  * Mirrors `cmdPull`'s `dryRun` contract.
  */
-export function cmdPush(opts: { dryRun?: boolean } = {}): void {
+export async function cmdPush(opts: { dryRun?: boolean; redactAll?: boolean } = {}): Promise<void> {
   const dryRun = opts.dryRun === true;
+  const redactAll = opts.redactAll === true;
   if (!existsSync(REPO_HOME)) die(`repo not cloned at ${REPO_HOME}`);
   const handle = acquireLock('push');
   if (handle === null) process.exit(0);
@@ -202,7 +204,7 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     // dryRun skips git add / commit / push: run the read-only leak preview,
     // which prints any recovery below the rendered tree.
     if (dryRun) return runDryRunPreview(st, map);
-    commitAndPush(st);
+    await commitAndPush(st, ts, map, redactAll);
   } catch (err) {
     if (err instanceof NomadFatal) {
       fail(err.message);

package/src/commands.redact.core.ts

@@ -0,0 +1,94 @@
+import { appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { REPO_HOME } from './config.ts';
+
+/**
+ * Replace every occurrence of a literal secret value in a raw line. Uses
+ * split/join to avoid regex escaping and to replace all occurrences. Pure,
+ * no I/O.
+ *
+ * The replacement token `[REDACTED:<ruleId>]` contains no JSON-special
+ * characters, so the result remains valid JSON when the value sits inside a
+ * JSON string token.
+ *
+ * @param line Raw JSONL line text.
+ * @param match Literal secret value to replace (empty string is a no-op).
+ * @param ruleId Gitleaks rule identifier included in the replacement token.
+ * @returns Line with all occurrences of `match` replaced by `[REDACTED:<ruleId>]`.
+ */
+export function redactValue(line: string, match: string, ruleId: string): string {
+  if (match === '') return line;
+  return line.split(match).join(`[REDACTED:${ruleId}]`);
+}
+
+/** Minimal finding shape consumed by `applyRedactions`. */
+export type RedactFinding = {
+  StartLine: number;
+  Match: string;
+  RuleID: string;
+};
+
+/**
+ * Apply all findings for one file in memory. Replaces each finding's `Match`
+ * value globally across the whole content string (split/join, no column
+ * arithmetic). To avoid a shorter secret being a substring of a longer one
+ * causing a partial match, findings are sorted by `Match.length` descending so
+ * the longer secret is replaced first. Findings with an empty `Match` are
+ * silently skipped (a defensive guard: an empty match would otherwise inject
+ * the token between every character). Pure, no I/O.
+ *
+ * @param content Full file content as a single string.
+ * @param findings Array of finding descriptors.
+ * @returns Redacted file content.
+ */
+export function applyRedactions(content: string, findings: readonly RedactFinding[]): string {
+  const sorted = [...findings].sort((a, b) => b.Match.length - a.Match.length);
+  let result = content;
+  for (const f of sorted) {
+    if (f.Match === '') continue;
+    result = result.split(f.Match).join(`[REDACTED:${f.RuleID}]`);
+  }
+  return result;
+}
+
+/**
+ * Format a gitleaks fingerprint for appending to `.gitleaksignore`. Strips any
+ * embedded `\r` or `\n` characters (a newline in a fingerprint must not inject
+ * extra ignore lines) and appends exactly one trailing newline. Pure.
+ *
+ * @param fingerprint Raw fingerprint string from `Finding.Fingerprint`.
+ * @returns Sanitized fingerprint with a single trailing newline.
+ */
+export function formatFingerprint(fingerprint: string): string {
+  return fingerprint.replace(/[\r\n]/g, '') + '\n';
+}
+
+/**
+ * True if the file mtime is within `thresholdMs` of `nowMs` (heuristic for a
+ * live session that Claude Code may still be writing). Pure, injectable for
+ * tests.
+ *
+ * @param mtimeMs File modification time in milliseconds.
+ * @param nowMs Current epoch time in milliseconds.
+ * @param thresholdMs Threshold window in milliseconds (default 5 minutes).
+ * @returns True when the file was modified within the threshold.
+ */
+export function isRecentlyModified(
+  mtimeMs: number,
+  nowMs: number,
+  thresholdMs = 5 * 60 * 1000,
+): boolean {
+  return nowMs - mtimeMs < thresholdMs;
+}
+
+/**
+ * Append one sanitized fingerprint line to `REPO_HOME/.gitleaksignore`. The
+ * fingerprint is passed through `formatFingerprint` to strip embedded newlines
+ * before the append.
+ *
+ * @param fingerprint Raw fingerprint from `Finding.Fingerprint`.
+ */
+export function appendGitleaksIgnore(fingerprint: string): void {
+  appendFileSync(join(REPO_HOME, '.gitleaksignore'), formatFingerprint(fingerprint), 'utf8');
+}

package/src/commands.redact.ts

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CLAUDE_HOME, HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
+import { applyRedactions, isRecentlyModified } from './commands.redact.core.ts';
+import { type Finding, scanFile } from './push-gitleaks.scan.ts';
+import { backupBeforeWrite, freshBackupTs } from './utils.fs.ts';
+import { encodePath, readJson } from './utils.json.ts';
+import { die, fail, log, NomadFatal } from './utils.ts';
+import { acquireLock, releaseLock } from './utils.lockfile.ts';
+
+export type { RedactFinding } from './commands.redact.core.ts';
+export {
+  applyRedactions,
+  appendGitleaksIgnore,
+  formatFingerprint,
+  isRecentlyModified,
+  redactValue,
+} from './commands.redact.core.ts';
+
+/**
+ * Resolve a session id to the live local transcript path on this host via
+ * `path-map.json`. Returns the absolute path when it exists on disk, or `null`
+ * when the path-map is absent, the session is unmapped on this host, or the
+ * local file is already gone. Mirrors `resolveLiveTranscript` from
+ * `commands.drop-session.scrub-hint.ts`.
+ *
+ * @param id Already-validated session id.
+ * @returns Absolute live transcript path, or null when unresolvable.
+ */
+export function resolveLiveTranscript(id: string): string | null {
+  try {
+    const mapPath = join(REPO_HOME, 'path-map.json');
+    if (!existsSync(mapPath)) return null;
+    const projects = readJson<PathMap>(mapPath).projects;
+    for (const hostMap of Object.values(projects)) {
+      const abs = hostMap[HOST];
+      if (abs === undefined) continue;
+      const live = join(CLAUDE_HOME, 'projects', encodePath(abs), `${id}.jsonl`);
+      if (existsSync(live)) return live;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Options for the `nomad redact` subcommand. */
+export type RedactOpts = {
+  /** Session id (validated against `[A-Za-z0-9_-]+`, length 1..128). */
+  id: string;
+  /** Limit redaction to findings of this gitleaks rule id only. */
+  rule?: string;
+  /** When true, print the plan and write nothing. */
+  dryRun?: boolean;
+  /**
+   * Findings to redact. When provided (push-time recovery flow), used directly
+   * after applying the optional `rule` filter. When omitted (standalone
+   * `nomad redact`), `cmdRedact` scans the local transcript with `gitleaks
+   * detect --no-git` and uses the resulting findings. A scan error (gitleaks
+   * absent or crashed) is reported as a distinct failure, not silently treated
+   * as "no findings".
+   */
+  findings?: readonly {
+    StartLine: number;
+    Match: string;
+    RuleID: string;
+  }[];
+};
+
+/**
+ * Resolve the findings list for a redact operation. When `rawFindings` is
+ * provided (push-time recovery), returns them filtered by `rule`. When
+ * `rawFindings` is undefined (standalone `nomad redact`), calls `scan` on the
+ * local transcript and returns the findings filtered by `rule`, or `null` when
+ * the scan itself fails (gitleaks absent or crashed).
+ *
+ * @param localPath Absolute path to the local transcript.
+ * @param rawFindings Pre-supplied findings or undefined to trigger a scan.
+ * @param rule Optional rule-id filter applied after findings are resolved.
+ * @param scan Injectable scan function (default: `scanFile`).
+ * @returns Filtered findings array, or `null` when scan fails.
+ */
+function resolveRedactFindings(
+  localPath: string,
+  rawFindings: RedactOpts['findings'],
+  rule: string | undefined,
+  scan: (p: string) => Finding[] | null,
+): readonly { StartLine: number; Match: string; RuleID: string }[] | null {
+  const source = rawFindings ?? scan(localPath);
+  if (source === null) return null;
+  return source.filter((f) => rule === undefined || f.RuleID === rule);
+}
+
+/**
+ * Non-interactive redaction of a session transcript's secret spans. Rewrites
+ * the LOCAL source transcript at `~/.claude/projects/<encoded>/<id>.jsonl` in
+ * place (same inode) after backing it up via `backupBeforeWrite`. Refuses to
+ * touch a transcript whose mtime is within the live-session threshold (D-06).
+ *
+ * When `opts.findings` is provided, uses it directly (push-time recovery flow).
+ * When `opts.findings` is omitted, scans the local transcript with gitleaks
+ * detect via the injected `scan` function. A scan failure (null return) is
+ * reported as a distinct error rather than silently treated as "no findings".
+ *
+ * Validates `id` before any path resolution or lock acquisition. Uses
+ * `acquireLock('redact')` with the standard `try/catch(NomadFatal)/finally
+ * releaseLock` shape.
+ *
+ * @param opts Redact options: session id, optional rule filter, optional dry-run, optional findings.
+ * @param nowMs Injectable clock for live-session detection (tests inject a fixed value).
+ * @param scan Injectable single-file scan function (tests inject a fake; default: `scanFile`).
+ */
+export function cmdRedact(
+  opts: RedactOpts,
+  nowMs: () => number = Date.now,
+  scan: (p: string) => Finding[] | null = scanFile,
+): void {
+  const { id, rule, dryRun = false, findings: rawFindings } = opts;
+
+  if (id.length === 0 || id.length > 128 || !/^[A-Za-z0-9_-]+$/.test(id)) {
+    fail(`invalid session id: ${id}`);
+    process.exit(1);
+  }
+  if (!existsSync(REPO_HOME)) die(`repo not cloned at ${REPO_HOME}`);
+
+  const handle = acquireLock('redact');
+  if (handle === null) process.exit(0);
+  try {
+    const localPath = resolveLiveTranscript(id);
+    if (localPath === null || !existsSync(localPath)) {
+      fail(`could not resolve local transcript for session ${id} on this host`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const mtimeMs = statSync(localPath).mtimeMs;
+    if (isRecentlyModified(mtimeMs, nowMs())) {
+      log(
+        `session ${id} was modified recently and may be active.\n` +
+          '  Refusing to rewrite a potentially live transcript.\n' +
+          '  To proceed: wait for the session to end, then re-run nomad redact.\n' +
+          `  Or drop from the staged tree: nomad drop-session ${id}\n` +
+          '  Or skip this finding during nomad push.',
+      );
+      return;
+    }
+
+    const findings = resolveRedactFindings(localPath, rawFindings, rule, scan);
+    if (findings === null) {
+      fail(`gitleaks scan failed for session ${id} (is gitleaks installed?)`);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (findings.length === 0) {
+      log(`no findings${rule !== undefined ? ` for rule ${rule}` : ''} in session ${id}`);
+      return;
+    }
+
+    if (dryRun) {
+      log(
+        `dry-run: would redact ${findings.length} finding(s) in ${localPath}\n` +
+          findings.map((f) => `  line ${f.StartLine} [${f.RuleID}]`).join('\n'),
+      );
+      return;
+    }
+
+    const backupBase = join(HOME, '.cache', 'claude-nomad', 'backup');
+    const ts = freshBackupTs(backupBase);
+    backupBeforeWrite(localPath, ts);
+
+    const original = readFileSync(localPath, 'utf8');
+    const redacted = applyRedactions(original, findings);
+    writeFileSync(localPath, redacted, 'utf8');
+    log(`redacted ${findings.length} finding(s) in ${localPath} (backup: ${ts})`);
+  } catch (err) {
+    /* c8 ignore next 3 */
+    if (!(err instanceof NomadFatal)) {
+      throw err;
+    }
+    fail(err.message);
+    process.exitCode = 1;
+  } finally {
+    releaseLock(handle);
+  }
+}

package/src/config.ts

@@ -180,6 +180,7 @@ export const PUSH_ALLOWED_STATIC = [
   'shared/hooks/',
   'hosts/',
   'path-map.json',
+  '.gitleaksignore', // written by nomad push Allow action (D-04)
 ] as const;
 
 /**

package/src/nomad.dispatch.ts

@@ -23,3 +23,60 @@ export function parseFlags(argv: string[], known: Set<string>): Set<string> | nu
   }
   return seen;
 }
+
+/** Parsed result from {@link parseRedactArgs}. */
+export type RedactArgs = {
+  /** Validated session id. */
+  id: string;
+  /** Optional gitleaks rule id filter passed via `--rule <id>`. */
+  rule: string | undefined;
+  /** True when `--dry-run` was present. */
+  dryRun: boolean;
+};
+
+/**
+ * Argv parser for `nomad redact <session-id> [--rule <rule-id>] [--dry-run]`.
+ *
+ * Handles a required positional id at argv[3], an optional boolean
+ * `--dry-run`, and an optional `--rule <value>` that consumes the next token.
+ * Returns `null` on any parse error: missing id, id failing the validation
+ * regex, unknown flag, `--rule` with no value or a value that looks like
+ * another flag, or a repeated flag.
+ *
+ * The id regex (`/^\w[\w-]{0,127}$/`) mirrors the `drop-session` arm: the
+ * leading `\w` prevents leading-dash ids so `nomad redact --bogus` shows
+ * usage rather than passing an invalid id to `cmdRedact`.
+ *
+ * @param argv The full process argv array (parsing starts at index 3).
+ * @returns Parsed redact arguments, or `null` on any parse error.
+ */
+export function parseRedactArgs(argv: string[]): RedactArgs | null {
+  const id = argv[3];
+  if (typeof id !== 'string' || !/^\w[\w-]{0,127}$/.test(id)) {
+    return null;
+  }
+  let rule: string | undefined;
+  let dryRun = false;
+  let sawRule = false;
+  let sawDryRun = false;
+  let i = 4;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (token === '--dry-run') {
+      if (sawDryRun) return null;
+      sawDryRun = true;
+      dryRun = true;
+      i++;
+    } else if (token === '--rule') {
+      if (sawRule) return null;
+      sawRule = true;
+      const val = argv[i + 1];
+      if (val === undefined || val.startsWith('--')) return null;
+      rule = val;
+      i += 2;
+    } else {
+      return null;
+    }
+  }
+  return { id, rule, dryRun };
+}

package/src/nomad.help.ts

@@ -37,6 +37,8 @@ export const DEFAULT_HELP = [
   row('  push', 'Rebase, run safety checks (gitleaks, gitlinks, allow-list), commit, push.'),
   row('       --dry-run', 'Run pre-checks (rebase, gitleaks probe, gitlink scan) and preview'),
   cont('remap, without staging or pushing.'),
+  row('       --redact-all', 'Redact all findings non-interactively (backup, no prompt); no TTY'),
+  cont('required. Does not auto-Allow.'),
   '',
   row('  diff', 'Offline preview of what `pull` would change against local repo state.'),
   cont('No git pull, no lock acquired.'),
@@ -59,6 +61,14 @@ export const DEFAULT_HELP = [
     'Unstage shared/projects/<logical>/<id>.jsonl from the staged tree (local ~/.claude/projects is never touched).',
   ),
   '',
+  row(
+    '  redact <session-id>',
+    'Rewrite the secret span in the local source transcript for a session,',
+  ),
+  cont('backed up to ~/.cache/claude-nomad/backup/. Safe to re-run.'),
+  row('       --rule <id>', 'Limit redaction to one gitleaks rule id.'),
+  row('       --dry-run', 'Show what would change without writing.'),
+  '',
   row('  update', 'Topology-aware upgrade of ~/claude-nomad/ to the latest upstream.'),
   row('       --dry-run', 'Detect topology + pre-flight, print would-be git commands only.'),
   row('       --force', 'Proceed even when the working tree is not clean.'),