claude-nomad 0.25.4 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.25.4",
+  "version": "0.26.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": [
@@ -42,6 +42,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "lint:md": "markdownlint-cli2",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "prepublishOnly": "npm run lint && npm run typecheck && npm run test && node scripts/verify-tarball.cjs",
@@ -52,7 +53,11 @@
       "eslint --fix",
       "prettier --write"
     ],
-    "*.{js,mjs,cjs,json,md}": [
+    "*.{js,mjs,cjs,json}": [
+      "prettier --write"
+    ],
+    "*.md": [
+      "markdownlint-cli2 --fix",
       "prettier --write"
     ]
   },
@@ -64,9 +69,11 @@
     "@vitest/coverage-v8": "^4.1.6",
     "eslint": "^10.4.0",
     "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-sonarjs": "^4.0.3",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.5",
+    "markdownlint-cli2": "^0.22.1",
     "prettier": "^3.8.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.4",

package/src/commands.doctor.check-shared.scan.ts

@@ -14,7 +14,7 @@
 
 import { join } from 'node:path';
 
-import { green, red, okGlyph, failGlyph } from './color.ts';
+import { green, red, dim, okGlyph, failGlyph } from './color.ts';
 import { addItem, type DoctorSection } from './commands.doctor.format.ts';
 import { CLAUDE_HOME } from './config.ts';
 import { type Finding, partitionFindings, scanStagedTree } from './push-gitleaks.ts';
@@ -47,16 +47,16 @@ function reportSessionFindings(
 ): void {
   for (const [sid, counts] of bySession) {
     const summary = [...counts.entries()].map(([rule, n]) => `${rule} (${n})`).join(', ');
-    addItem(section, `${red(failGlyph)} session ${sid}: ${summary}`);
+    addItem(section, `${red(failGlyph)} ${red(summary)} in session ${sid}`);
     const logical = logicalBySession.get(sid);
     /* c8 ignore next -- false branch is defensive; every bySession sid is keyed in logicalBySession */
     if (logical !== undefined) {
       addItem(
         section,
-        `  rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`,
+        `  ${dim(`rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`)}`,
       );
     }
-    addItem(section, `  false positive? add a pattern to .gitleaks.toml`);
+    addItem(section, `  ${dim('false positive? add a pattern to .gitleaks.toml')}`);
   }
   process.exitCode = 1;
 }
@@ -70,7 +70,7 @@ function reportSessionFindings(
  */
 function reportOtherFindings(section: DoctorSection, other: Finding[]): void {
   for (const f of other) {
-    addItem(section, `${red(failGlyph)} leak in ${f.File}: ${f.RuleID}`);
+    addItem(section, `${red(failGlyph)} ${red(f.RuleID)} leak in ${f.File}`);
   }
   process.exitCode = 1;
 }
@@ -111,6 +111,29 @@ function buildLogicalBySession(findings: Finding[]): Map<string, string> {
   return logicalBySession;
 }
 
+/**
+ * Emit a deduplicated description legend in the footer: one `[rule-id]:
+ * description` row per distinct RuleID across all findings, set off by a blank
+ * line before and after. Sourced from the `Description` gitleaks bakes into
+ * each finding, so it needs no network; rules whose description is absent
+ * (older gitleaks, custom rules) are skipped, and the whole block (including
+ * the surrounding blanks) is omitted when no descriptions are available. The
+ * legend lives in the footer so a rule hit across many files or sessions
+ * (e.g. `sonar-api-token`) is explained once, not per occurrence.
+ */
+function emitDescriptionLegend(section: DoctorSection, findings: Finding[]): void {
+  const descByRule = new Map<string, string>();
+  for (const f of findings) {
+    if (f.Description && !descByRule.has(f.RuleID)) descByRule.set(f.RuleID, f.Description);
+  }
+  if (descByRule.size === 0) return;
+  addItem(section, '');
+  for (const [rule, desc] of descByRule) {
+    addItem(section, `  ${red(`[${rule}]`)}: ${dim(desc)}`);
+  }
+  addItem(section, '');
+}
+
 /**
  * Scan the staged temp tree through the shared `scanStagedTree` and emit the
  * result rows. Isolates the deepest nesting from `reportCheckShared`: the scan
@@ -155,4 +178,5 @@ export function scanAndReport(
   if (bySession.size > 0) {
     reportSessionFindings(section, bySession, buildLogicalBySession(findings), logicalToEncoded);
   }
+  emitDescriptionLegend(section, findings);
 }

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

@@ -13,7 +13,7 @@ import { encodePath } from './utils.json.ts';
  * `process.exitCode = 1`. Read-only: FAIL lines stay on stdout.
  */
 
-/** Emits the mapped-projects header for the current host and one line per mapped project. */
+/** Emits the mapped-projects header for the current host and one indented child line per mapped project. */
 function reportMappedProjects(section: DoctorSection, map: PathMap): void {
   const mapped = Object.entries(map.projects).filter(([, hosts]) => hosts[HOST]);
   addItem(
@@ -21,7 +21,7 @@ function reportMappedProjects(section: DoctorSection, map: PathMap): void {
     `${dim(infoGlyph)} mapped projects for ${cyan(HOST)}: ${dim(String(mapped.length))}`,
   );
   for (const [name, hosts] of mapped) {
-    addItem(section, `${dim(infoGlyph)} ${name} -> ${blue(hosts[HOST])}`);
+    addItem(section, `      ${name} -> ${blue(hosts[HOST])}`);
   }
 }
 

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

@@ -43,7 +43,7 @@ export function isOverrideActive(): boolean {
  * Pushes the host identity (info) and the two key path lines (repo and
  * claude-home) with gutter glyphs. Path presence is reported via warnGlyph
  * (not failGlyph) so an absent CLAUDE_HOME does not flip sectionFailed to
- * decorate the Host header with `✘`. The authoritative empty-repo FAIL is
+ * decorate the Host header with a fail glyph. The authoritative empty-repo FAIL is
  * owned by reportRepoState; these two lines remain informational and do
  * NOT mutate process.exitCode.
  */
@@ -83,51 +83,96 @@ export function reportRepoState(section: DoctorSection): void {
   }
 }
 
+/**
+ * True when the repo has a `shared/<name>` source for this link. `applySharedLinks`
+ * only creates a symlink when this source exists, so when it does NOT, an absent
+ * or dangling link in `~/.claude/` is expected (nothing to sync), not a problem to
+ * fix. Doctor uses this to downgrade those rows from a warn to an info note.
+ */
+function repoHasSharedSource(name: string): boolean {
+  return existsSync(join(REPO_HOME, 'shared', name));
+}
+
+/**
+ * Resolve the display item and optional exit-code side-effect for a single
+ * shared-link path. Returns `{ line, fail }` where `fail` true means the
+ * caller should set `process.exitCode = 1`.
+ *
+ * Extracted from `reportSharedLinks` to reduce cognitive complexity: the lstat
+ * try/catch and the inner symlink-target try/catch each count against the
+ * parent function's score.
+ */
+function classifySharedLink(name: string, p: string): { line: string; fail: boolean } {
+  let stat;
+  try {
+    stat = lstatSync(p);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return repoHasSharedSource(name)
+        ? {
+            line: `${yellow(warnGlyph)} ${name}: missing (run \`nomad pull\` to restore)`,
+            fail: false,
+          }
+        : { line: `${dim(infoGlyph)} ${name}: not synced (nothing in shared/)`, fail: false };
+    }
+    return { line: `${red(failGlyph)} ${name}: could not stat (${String(code)})`, fail: true };
+  }
+  if (!stat.isSymbolicLink()) {
+    return { line: `${red(failGlyph)} ${name}: NOT a symlink (blocks sync)`, fail: true };
+  }
+  return classifySymlinkTarget(name, p);
+}
+
+/**
+ * Resolve the display item for a path already confirmed to be a symlink.
+ * Follows the link via statSync; a throw means the target is missing or
+ * unreadable. Never FAILs (`fail: false`): a dangling link whose source still
+ * lives in the repo is a WARN with a `nomad pull` hint, a dangling link whose
+ * source is gone from the repo is an info note (stale, safe to remove), and a
+ * non-ENOENT stat error is a WARN naming the code.
+ */
+function classifySymlinkTarget(name: string, p: string): { line: string; fail: boolean } {
+  try {
+    statSync(p);
+    return { line: `${green(okGlyph)} ${name}: symlink`, fail: false };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return repoHasSharedSource(name)
+        ? {
+            line: `${yellow(warnGlyph)} ${name}: broken symlink (target missing, run \`nomad pull\`)`,
+            fail: false,
+          }
+        : {
+            line: `${dim(infoGlyph)} ${name}: stale symlink (no longer in shared/, safe to remove)`,
+            fail: false,
+          };
+    }
+    return {
+      line: `${yellow(warnGlyph)} ${name}: symlink target unreadable (${String(code)})`,
+      fail: false,
+    };
+  }
+}
+
 /**
  * Emits a per-entry status line for each name in SHARED_LINKS
- * (okGlyph/warnGlyph/failGlyph). A non-symlink blocks sync and FAILs via
- * process.exitCode. TOCTOU-safe: lstatSync is wrapped in try/catch so a path
+ * (okGlyph/warnGlyph/infoGlyph/failGlyph). A non-symlink blocks sync and FAILs
+ * via process.exitCode. TOCTOU-safe: lstatSync is wrapped in try/catch so a path
  * that vanishes or becomes unreadable between the probe and the stat yields a
- * row instead of an unhandled throw that aborts the whole doctor run. A symlink
- * whose target cannot be resolved is a WARN (broken-symlink for a missing
- * target, target-unreadable otherwise), never a healthy OK, so a dangling or
- * unreadable link is not masked.
+ * row instead of an unhandled throw that aborts the whole doctor run. Severity
+ * keys off whether the repo still has a `shared/<name>` source: an absent or
+ * dangling link is a WARN with a `nomad pull` hint when the source exists (a
+ * real out-of-sync state), and a calm info note when it does not (nothing to
+ * sync). A symlink whose target cannot be resolved is never a healthy OK, so a
+ * dangling or unreadable link is not masked.
  */
 export function reportSharedLinks(section: DoctorSection): void {
   for (const name of SHARED_LINKS) {
     const p = join(CLAUDE_HOME, name);
-    let stat;
-    try {
-      stat = lstatSync(p);
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === 'ENOENT') {
-        addItem(section, `${yellow(warnGlyph)} ${name}: missing`);
-      } else {
-        addItem(section, `${red(failGlyph)} ${name}: could not stat (${String(code)})`);
-        process.exitCode = 1;
-      }
-      continue;
-    }
-    if (stat.isSymbolicLink()) {
-      try {
-        // statSync follows the link; a throw means the target does not resolve.
-        statSync(p);
-        addItem(section, `${green(okGlyph)} ${name}: symlink`);
-      } catch (err) {
-        const code = (err as NodeJS.ErrnoException).code;
-        if (code === 'ENOENT') {
-          addItem(section, `${yellow(warnGlyph)} ${name}: broken symlink (target missing)`);
-        } else {
-          addItem(
-            section,
-            `${yellow(warnGlyph)} ${name}: symlink target unreadable (${String(code)})`,
-          );
-        }
-      }
-    } else {
-      addItem(section, `${red(failGlyph)} ${name}: NOT a symlink (blocks sync)`);
-      process.exitCode = 1;
-    }
+    const { line, fail } = classifySharedLink(name, p);
+    addItem(section, line);
+    if (fail) process.exitCode = 1;
   }
 }

package/src/commands.doctor.format.ts

@@ -70,17 +70,32 @@ function sectionFailed(s: DoctorSection): boolean {
  * headers with a red `✗ ` glyph (U+2717, same as the per-item FAIL glyph so
  * `grep -F '✗'` catches both row and header failures), and writes one blank
  * line between rendered sections (no leading or trailing blank).
+ *
+ * An empty-string item renders as a true blank line (no tree connector), which
+ * lets a reporter set off a footer block (e.g. the `--check-shared` description
+ * legend) with vertical whitespace. The `└` connector attaches to the last
+ * non-empty item rather than the last array slot so a trailing blank does not
+ * strand the elbow on an empty line.
+ */
+/**
+ * Render one section: a (possibly fail-glyph-prefixed) header followed by its
+ * items as a tree. Empty-string items print as true blank lines; the `└` elbow
+ * attaches to the last non-empty item so a trailing blank cannot strand it.
  */
+function renderSection(s: DoctorSection): void {
+  const header = sectionFailed(s) ? `${red(FAIL_GLYPH_BARE)} ${s.header}` : s.header;
+  console.log(header);
+  const lastContent = s.items.reduce((acc, item, j) => (item !== '' ? j : acc), -1);
+  for (let j = 0; j < s.items.length; j++) {
+    if (s.items[j] === '') console.log('');
+    else console.log(`${j === lastContent ? '  └ ' : '  ├ '}${s.items[j]}`);
+  }
+}
+
 export function renderDoctor(sections: DoctorSection[]): void {
   const visible = sections.filter((s) => s.items.length > 0);
   for (let i = 0; i < visible.length; i++) {
     if (i > 0) console.log('');
-    const s = visible[i];
-    const header = sectionFailed(s) ? `${red(FAIL_GLYPH_BARE)} ${s.header}` : s.header;
-    console.log(header);
-    for (let j = 0; j < s.items.length; j++) {
-      const isLast = j === s.items.length - 1;
-      console.log(`${isLast ? '  └ ' : '  ├ '}${s.items[j]}`);
-    }
+    renderSection(visible[i]);
   }
 }

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

@@ -52,9 +52,14 @@ export function reportMirrorActions(section: DoctorSection, run: SpawnSyncFn = e
   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 3: gh available and authed. A definitive gh-not-installed / gh-not-authed
+  // result is a silent skip (init prints a tip here; doctor does not, per the
+  // read-only contract). A gh-probe-error (the auth-status call timed out or
+  // hiccuped) is NOT definitive, so fall through: gates 4-5 run their own probes
+  // and silently skip if the network is genuinely down, but the drift WARN can
+  // still fire when only the auth-status call blipped on an authed host (#124).
+  const auth = ghAuthStatus(run);
+  if (auth === 'gh-not-installed' || auth === 'gh-not-authed') return;
 
   // Gate 4: private mirror. A public repo, or a probe that throws, is a skip.
   let isPrivate: boolean;

package/src/commands.doctor.ts

@@ -62,7 +62,7 @@ export function cmdDoctor(opts: { checkShared?: boolean } = {}): void {
   reportRebaseClean(repository);
   reportMirrorActions(repository);
 
-  const version = section('Version');
+  const version = section('Version Checks');
   reportVersionCheck(version);
   reportNodeEngineCheck(version);
   reportGitleaksVersionCheck(version);

package/src/commands.doctor.version.ts

@@ -11,9 +11,9 @@ import { HOME, UPSTREAM_REPO_SLUG } from './config.ts';
  * Soft, offline-tolerant release-version check appended to `cmdDoctor`. Reads
  * the local `package.json.version`, compares it to the latest release tag on
  * the upstream GitHub repo (cached 1h, 3s curl timeout), and emits one of:
- *   - `✓ version: <local> (latest)` when local == latest
- *   - `⚠︎ version: <local> -> <latest>` when local < latest
- *   - `ℹ︎ version: <local> (ahead of latest release <latest>)` when local > latest
+ *   - `✓ claude-nomad: <local> (latest)` when local == latest
+ *   - `⚠︎ claude-nomad: <local> -> <latest>` when local < latest
+ *   - `ℹ︎ claude-nomad: <local> (ahead of latest release <latest>)` when local > latest
  * Every failure path (offline, curl missing, non-2xx, malformed JSON, missing
  * `tag_name`, missing/unreadable package.json) is a SILENT skip; this module
  * never sets `process.exitCode` and never writes to stderr.
@@ -153,9 +153,9 @@ function fetchLatestTag(): string | null {
  * Emit a single, non-fatal version diagnostic for `nomad doctor` by comparing the local package.json version to the latest upstream release.
  *
  * Logs one of:
- * - `✓ version: <local> (latest)` when the versions match
- * - `⚠︎ version: <local> -> <latest> (run \`nomad update\`)` when the local version is behind
- * - `ℹ︎ version: <local> (ahead of latest release <latest>)` when the local version is ahead
+ * - `✓ claude-nomad: <local> (latest)` when the versions match
+ * - `⚠︎ claude-nomad: <local> -> <latest> (run \`nomad update\`)` when the local version is behind
+ * - `ℹ︎ claude-nomad: <local> (ahead of latest release <latest>)` when the local version is ahead
  *
  * Any failure to read the local version, retrieve or parse the latest release, or use the cache results in no output and does not change `process.exitCode`.
  */
@@ -181,10 +181,16 @@ export function reportVersionCheck(section: DoctorSection): void {
 
   const cmp = compareSemver(localPure, latest);
   if (cmp === 0) {
-    addItem(section, `${green(okGlyph)} version: ${local} (latest)`);
+    addItem(section, `${green(okGlyph)} claude-nomad: ${local} (latest)`);
   } else if (cmp === -1) {
-    addItem(section, `${yellow(warnGlyph)} version: ${local} -> ${latest} (run \`nomad update\`)`);
+    addItem(
+      section,
+      `${yellow(warnGlyph)} claude-nomad: ${local} -> ${latest} (run \`nomad update\`)`,
+    );
   } else {
-    addItem(section, `${dim(infoGlyph)} version: ${local} (ahead of latest release ${latest})`);
+    addItem(
+      section,
+      `${dim(infoGlyph)} claude-nomad: ${local} (ahead of latest release ${latest})`,
+    );
   }
 }

package/src/gh-actions.ts

@@ -7,10 +7,13 @@ import { execFileSync, type ExecFileSyncOptions } from 'node:child_process';
 export type GhRepoRef = { owner: string; repo: string };
 
 /**
- * Reason `ghAuthStatus` returned without success. Distinguishes the two
- * actionable failure modes so callers can print useful tips.
+ * Reason `ghAuthStatus` returned without success. Distinguishes three
+ * actionable failure modes so callers decide how to treat each:
+ * `gh-not-installed` (the binary is missing), `gh-not-authed` (gh ran and
+ * reported no authentication), and `gh-probe-error` (the probe itself failed,
+ * e.g. a timeout or transient spawn error, so the auth state is unknown).
  */
-export type GhUnavailableReason = 'gh-not-installed' | 'gh-not-authed';
+export type GhUnavailableReason = 'gh-not-installed' | 'gh-not-authed' | 'gh-probe-error';
 
 /**
  * Injectable subprocess runner so tests can mock without `vi.doMock` and
@@ -47,8 +50,16 @@ export function parseGitHubRemote(remoteUrl: string): GhRepoRef | null {
 /**
  * Check `gh` CLI availability and auth status in one call. Returns null on
  * success or a structured reason string. `gh auth status` exits 0 when the
- * user is authed against github.com and non-zero otherwise; ENOENT signals
- * the binary itself is missing.
+ * user is authed against github.com and non-zero otherwise.
+ *
+ * The catch separates a definitive answer from an indeterminate one so callers
+ * are not forced to treat a transient probe failure as "not authed":
+ * - `ENOENT`: the binary is missing, so `gh-not-installed`.
+ * - the child ran and exited with a numeric code (`typeof status === 'number'`,
+ *   which by spawnSync semantics means it was not signal-killed): the only
+ *   definitive unauthenticated answer, so `gh-not-authed`.
+ * - anything else (a timeout SIGTERM-kills the child so `status` is null, an
+ *   `ETIMEDOUT`, a spawn hiccup): the probe itself failed, so `gh-probe-error`.
  */
 export function ghAuthStatus(run: SpawnSyncFn = execFileSync): GhUnavailableReason | null {
   try {
@@ -58,9 +69,10 @@ export function ghAuthStatus(run: SpawnSyncFn = execFileSync): GhUnavailableReas
     });
     return null;
   } catch (err) {
-    const e = err as { code?: string };
+    const e = err as { code?: string; status?: number | null };
     if (e.code === 'ENOENT') return 'gh-not-installed';
-    return 'gh-not-authed';
+    if (typeof e.status === 'number') return 'gh-not-authed';
+    return 'gh-probe-error';
   }
 }
 

package/src/init.ts

@@ -159,6 +159,11 @@ function maybeDisableMirrorActions(repoHome: string, run?: SpawnSyncFn): void {
     );
     return;
   }
+  // A gh-probe-error (auth-status timed out or hiccuped) is deliberately left to
+  // fall through: auth state is unknown, so the privacy probe below tries
+  // optimistically with its own catch + tip. This avoids the misleading
+  // 'gh auth login' tip a transient failure used to trigger when the user may
+  // in fact be authed (#124).
 
   let isPrivate: boolean;
   try {

package/src/nomad.help.ts

@@ -5,37 +5,67 @@
  * cold invocation of `nomad` is self-describing without forcing the user
  * into the README. Channel is stderr, exit code is 1.
  */
+
+/**
+ * Column (0-indexed) at which every command and flag description starts. Sized
+ * to clear the longest label (`--resume-cmd <id>`, which ends at column 24)
+ * with a two-space gutter. A single constant is what keeps every row aligned;
+ * padding lines by hand is how a description drifts out of column.
+ */
+const DESC_COL = 26;
+
+/**
+ * Render a `label` + `desc` help row, padding the label out to DESC_COL so the
+ * description lands in the shared column. `padEnd` is a no-op when a label is
+ * already at or past the column, so no row can throw or fall out of alignment.
+ */
+const row = (label: string, desc: string): string => label.padEnd(DESC_COL) + desc;
+
+/**
+ * Indent a continuation line (wrapped description text with no label of its
+ * own) to DESC_COL so it sits directly under the description column.
+ */
+const cont = (text: string): string => ' '.repeat(DESC_COL) + text;
+
 export const DEFAULT_HELP = [
   'usage: nomad <command> [flags]',
   '',
   'Commands:',
-  '  pull             Sync ~/.claude/ from the shared repo (settings, symlinks, sessions).',
-  '       --dry-run   Run lock + git pull, then preview every mutation without writing.',
+  row('  pull', 'Sync ~/.claude/ from the shared repo (settings, symlinks, sessions).'),
+  row('       --dry-run', 'Run lock + git pull, then preview every mutation without writing.'),
+  '',
+  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.'),
   '',
-  '  push             Rebase, run safety checks (gitleaks, gitlinks, allow-list), commit, push.',
-  '       --dry-run   Run pre-checks (rebase, gitleaks probe, gitlink scan) and preview',
-  '                   remap, without staging or pushing.',
+  row('  diff', 'Offline preview of what `pull` would change against local repo state.'),
+  cont('No git pull, no lock acquired.'),
   '',
-  '  diff             Offline preview of what `pull` would change against local repo state.',
-  '                   No git pull, no lock acquired.',
+  row('  init', 'Scaffold an empty ~/claude-nomad/ repo (shared/, hosts/, path-map).'),
+  row('       --snapshot', 'Overlay the current ~/.claude/ into shared/ as the initial seed.'),
+  row('       --keep-actions', 'Skip auto-disabling GitHub Actions on the private mirror.'),
   '',
-  '  init             Scaffold an empty ~/claude-nomad/ repo (shared/, hosts/, path-map).',
-  '       --snapshot      Overlay the current ~/.claude/ into shared/ as the initial seed.',
-  '       --keep-actions  Skip auto-disabling GitHub Actions on the private mirror.',
+  row('  doctor', 'Read-only health check (symlinks, host file, path-map,'),
+  cont('gitleaks, gitlinks).'),
+  row('       --check-shared', 'Preflight gitleaks scan of the session transcripts a'),
+  cont('`nomad push` would stage (a temp copy, never the live dir).'),
+  row('       --resume-cmd <id>', 'Print `cd <abspath> && claude --resume <id>` for a session id'),
+  cont('from ~/.claude/projects/.'),
   '',
-  '  doctor                  Read-only health check (symlinks, host file, path-map,',
-  '                          gitleaks, gitlinks).',
-  '       --check-shared     Preflight gitleaks scan of the session transcripts a',
-  '                          `nomad push` would stage (a temp copy, never the live dir).',
-  '       --resume-cmd <id>  Print `cd <abspath> && claude --resume <id>` for a session id',
-  '                          from ~/.claude/projects/.',
+  row(
+    '  drop-session <id>',
+    'Unstage shared/projects/<logical>/<id>.jsonl from the staged tree (local ~/.claude/projects is never touched).',
+  ),
   '',
-  '  drop-session <id>   Unstage shared/projects/<logical>/<id>.jsonl from the staged tree (local ~/.claude/projects is never touched).',
+  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.'),
+  row(
+    '       --push-origin',
+    'Fork topology only: push the merge to origin/main without prompting.',
+  ),
   '',
-  '  update              Topology-aware upgrade of ~/claude-nomad/ to the latest upstream.',
-  '       --dry-run      Detect topology + pre-flight, print would-be git commands only.',
-  '       --force        Proceed even when the working tree is not clean.',
-  '       --push-origin  Fork topology only: push the merge to origin/main without prompting.',
+  row('  --version', 'Print the installed CLI version as bare semver to stdout; exits 0.'),
   '',
   'Run `nomad doctor` to validate your setup. Edit shared/ or hosts/<HOST>.json',
   'in the repo, never ~/.claude/settings.json directly (it is regenerated on',

package/src/nomad.ts

@@ -154,15 +154,11 @@ try {
       // Single positional argv; cmdDropSession revalidates id at entry as
       // defense-in-depth (the function may be called from non-argv paths
       // in tests). The argv regex mirrors the function-entry allowlist
-      // (`[A-Za-z0-9_-]`) but additionally rejects ids starting with `-`
+      // (`[\w-]`) but additionally rejects ids starting with `-`
       // so a typo like `nomad drop-session --bogus` shows the usage line,
       // not a FATAL. The length bound matches cmdDropSession.
       const id = process.argv[3];
-      if (
-        process.argv.length !== 4 ||
-        typeof id !== 'string' ||
-        !/^[A-Za-z0-9_][A-Za-z0-9_-]{0,127}$/.test(id)
-      ) {
+      if (process.argv.length !== 4 || typeof id !== 'string' || !/^\w[\w-]{0,127}$/.test(id)) {
         console.error('usage: nomad drop-session <id>');
         process.exit(1);
       }