claude-nomad 0.23.0 → 0.25.0

package/src/commands.doctor.checks.ts

@@ -272,13 +272,19 @@ export function reportNeverSync(section: DoctorSection): void {
   addItem(section, `${dim(infoGlyph)} never-sync items: ${[...NEVER_SYNC].join(', ')}`);
 }
 
-/** Probes for gitleaks on PATH; emits okGlyph with version, or failGlyph with ENOENT vs other-error distinction (sets exitCode=1). */
-export function reportGitleaksProbe(section: DoctorSection): void {
+/**
+ * Probes for gitleaks on PATH; emits okGlyph with version, or failGlyph with
+ * ENOENT vs other-error distinction (sets exitCode=1). Returns `true` when a
+ * usable binary was found so the caller can skip a redundant second `version`
+ * probe (e.g. the `--check-shared` Shared scan section).
+ */
+export function reportGitleaksProbe(section: DoctorSection): boolean {
   try {
     const v = execFileSync('gitleaks', ['version'], { stdio: ['ignore', 'pipe', 'pipe'] })
       .toString()
       .trim();
     addItem(section, `${green(okGlyph)} gitleaks: ${dim(v)}`);
+    return true;
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
       addItem(section, `${red(failGlyph)} gitleaks: not on PATH (required for nomad push)`);
@@ -286,6 +292,7 @@ export function reportGitleaksProbe(section: DoctorSection): void {
       addItem(section, `${red(failGlyph)} gitleaks: probe failed: ${(err as Error).message}`);
     }
     process.exitCode = 1;
+    return false;
   }
 }
 

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

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

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

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

package/src/commands.doctor.ts

@@ -12,8 +12,11 @@ import {
   reportRepoState,
   reportSharedLinks,
 } from './commands.doctor.checks.ts';
+import { reportCheckShared } from './commands.doctor.check-shared.ts';
 import { reportNodeEngineCheck } from './commands.doctor.engine.ts';
 import { renderDoctor, section } from './commands.doctor.format.ts';
+import { reportGitleaksVersionCheck } from './commands.doctor.gitleaks-version.ts';
+import { reportMirrorActions } from './commands.doctor.mirror-actions.ts';
 import { reportVersionCheck } from './commands.doctor.version.ts';
 
 /**
@@ -24,8 +27,13 @@ import { reportVersionCheck } from './commands.doctor.version.ts';
  * inside the individual reporters, so a piped
  * `nomad doctor 2>/dev/null` still exposes failures to scripts. Differs from
  * `cmdPull` / `cmdPush` / `resumeCmd`, where FATAL is on stderr.
+ *
+ * `opts.checkShared` (the `--check-shared` sub-flag) appends a "Shared scan"
+ * section that runs the gitleaks preflight over the session transcripts a
+ * `nomad push` would stage. It is OFF by default so plain `nomad doctor`
+ * stays the fast read-only smoke test (no scan, no temp tree).
  */
-export function cmdDoctor(): void {
+export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
   const host = section('Host');
   reportHostAndPaths(host);
   reportRepoState(host);
@@ -45,14 +53,23 @@ export function cmdDoctor(): void {
   reportNeverSync(neverSync);
 
   const repository = section('Repository');
-  reportGitleaksProbe(repository);
+  const gitleaksReady = reportGitleaksProbe(repository);
   reportGitlinks(repository);
   reportRemote(repository);
   reportRebaseClean(repository);
+  reportMirrorActions(repository);
 
   const version = section('Version');
   reportVersionCheck(version);
   reportNodeEngineCheck(version);
+  reportGitleaksVersionCheck(version);
 
-  renderDoctor([version, host, links, settings, pathMap, neverSync, repository]);
+  const sharedScan = section('Shared scan');
+  // Reuse the Repository-section readiness probe so reportCheckShared does not
+  // re-spawn gitleaks for its own readiness on a --check-shared run; it still
+  // probes standalone when called without a prior result. (The Version-section
+  // drift check above spawns `gitleaks version` separately, by design.)
+  if (opts.checkShared === true) reportCheckShared(sharedScan, gitleaksReady);
+
+  renderDoctor([version, host, links, settings, pathMap, neverSync, repository, sharedScan]);
 }

package/src/commands.drop-session.ts

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

package/src/commands.push.ts

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

package/src/commands.update.ts

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

package/src/config.ts

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

package/src/extras-sync.ts

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