claude-nomad 0.17.0

package/src/resume.ts

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
+import { fail, readJson } from './utils.ts';
+
+type TranscriptLine = { type?: string; cwd?: string };
+
+/**
+ * Read-only sidecar that resolves a session ID to a host-local
+ * `cd <abspath> && claude --resume <id>` line, printed to stdout for `eval`.
+ *
+ * Flow: locate `<id>.jsonl` under `~/.claude/projects/<encoded>/`, extract
+ * the first non-file-history-snapshot line's `cwd`, reverse-lookup the
+ * logical project name in `path-map.json`, then look up the current host's
+ * abspath for that logical project.
+ *
+ * Does NOT acquire the nomad lock (read-only paths stay race-tolerant) and
+ * does NOT mutate any `.jsonl` byte (preserves the transcript byte-equality
+ * invariant validated in the end-to-end sync phase). All errors go to stderr
+ * prefixed with the red `✗` fail glyph; success goes to stdout as a bare
+ * shell line (no glyph) so `eval "$(...)"` works.
+ */
+export function resumeCmd(sessionId: string): void {
+  if (!/^[A-Za-z0-9_-]+$/.test(sessionId) || sessionId.length > 128) {
+    fail(`invalid session id: ${sessionId}`);
+    process.exit(1);
+  }
+
+  const projectsRoot = join(CLAUDE_HOME, 'projects');
+  if (!existsSync(projectsRoot)) {
+    fail(`${projectsRoot} does not exist`);
+    process.exit(1);
+  }
+
+  const jsonlPath = findTranscriptPath(projectsRoot, sessionId);
+  if (jsonlPath === null) {
+    fail(`session ${sessionId} not found in any ~/.claude/projects/<encoded>/`);
+    process.exit(1);
+  }
+  const recordedCwd = extractRecordedCwd(jsonlPath);
+  if (recordedCwd === null) {
+    fail(`no cwd field found in ${jsonlPath}`);
+    process.exit(1);
+  }
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  if (!existsSync(mapPath)) {
+    fail('path-map.json missing');
+    process.exit(1);
+  }
+  const map = readJson<unknown>(mapPath);
+  const schemaError = validatePathMap(map);
+  if (schemaError !== null) {
+    fail(schemaError);
+    process.exit(1);
+  }
+  const hit = lookupLocalPath(map as PathMap, recordedCwd);
+  if (hit === null) {
+    fail(`cwd ${recordedCwd} from session ${sessionId} not found in path-map.json`);
+    process.exit(1);
+  }
+  if (hit.localPath === undefined) {
+    fail(`session ${sessionId} not mapped on this host; add the logical to path-map.json`);
+    process.exit(1);
+  }
+
+  // Single-quote both interpolations so paths with spaces (or any shell
+  // metachar in sessionId) survive `eval` and the cd ends up at the
+  // intended directory rather than splitting on whitespace. Success line
+  // has NO glyph prefix; meant to be `eval`'d by the user.
+  console.log(`cd ${shQuote(hit.localPath)} && claude --resume ${shQuote(sessionId)}`);
+}
+
+/** Walks `<projectsRoot>/<dir>/<sessionId>.jsonl` and returns the first existing path, or null. */
+function findTranscriptPath(projectsRoot: string, sessionId: string): string | null {
+  for (const dir of readdirSync(projectsRoot)) {
+    const candidate = join(projectsRoot, dir, `${sessionId}.jsonl`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** Returns the first non-file-history-snapshot line's `cwd` from the transcript, or null. */
+function extractRecordedCwd(jsonlPath: string): string | null {
+  for (const line of readFileSync(jsonlPath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const obj = JSON.parse(line) as TranscriptLine;
+      if (obj.type === 'file-history-snapshot') continue;
+      if (typeof obj.cwd === 'string' && obj.cwd.length > 0) return obj.cwd;
+    } catch {
+      // Skip non-JSON or partial lines; transcripts can be appended mid-write.
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate that `raw` parses as `{ projects: { [logical]: { [host]: string } } }`
+ * deeply enough that downstream iteration cannot throw. Returns `null` on
+ * success or a human-readable reason on failure. Type-narrow callers must
+ * cast to `PathMap` after a `null` return; the cast is sound because every
+ * branch the consumers walk is verified here.
+ */
+function validatePathMap(raw: unknown): string | null {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return 'path-map.json invalid schema: top-level value must be an object';
+  }
+  const projects: unknown = (raw as { projects?: unknown }).projects;
+  if (projects === null || typeof projects !== 'object' || Array.isArray(projects)) {
+    return 'path-map.json invalid schema: "projects" must be an object';
+  }
+  for (const [name, hosts] of Object.entries(projects as Record<string, unknown>)) {
+    if (hosts === null || typeof hosts !== 'object' || Array.isArray(hosts)) {
+      return `path-map.json invalid schema: project "${name}" hosts must be an object`;
+    }
+    for (const [host, value] of Object.entries(hosts as Record<string, unknown>)) {
+      if (typeof value !== 'string') {
+        return `path-map.json invalid schema: project "${name}" host "${host}" path must be a string`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Reverse-lookups the logical project from `recordedCwd`. Matches when
+ * `recordedCwd` equals a mapped abspath OR is a descendant of one (a session
+ * started inside a subdirectory of a mapped project still resolves). The
+ * descendant test uses `startsWith(${root}/)` so `/orig/foo` does not match
+ * the project mapped at `/orig/foo-other`. Returns `{ logical, localPath }`
+ * (localPath undefined when host missing or 'TBD') or null on no match.
+ */
+function lookupLocalPath(
+  map: PathMap,
+  recordedCwd: string,
+): { logical: string; localPath: string | undefined } | null {
+  for (const [logical, hosts] of Object.entries(map.projects)) {
+    const isUnderMappedPath = Object.values(hosts).some(
+      (p) => recordedCwd === p || recordedCwd.startsWith(`${p}/`),
+    );
+    if (isUnderMappedPath) {
+      const localPath = hosts[HOST];
+      return { logical, localPath: localPath === 'TBD' ? undefined : localPath };
+    }
+  }
+  return null;
+}
+
+/**
+ * POSIX single-quote escape: wraps `s` in `'...'` and rewrites each interior
+ * `'` as `'\''`. Safe for `eval` and `bash -c`. Used to keep shell
+ * metacharacters in the resume output from being interpreted by the user's
+ * shell when they pipe the output through `eval`.
+ */
+function shQuote(s: string): string {
+  const escaped = s.replaceAll("'", String.raw`'\''`);
+  return `'${escaped}'`;
+}

package/src/summary.ts

@@ -0,0 +1,43 @@
+import { ok, warn } from './utils.ts';
+
+/**
+ * Emit the single end-of-run summary line shared by cmdPull, cmdPush, and
+ * cmdDiff. Canonical phrasing:
+ *   - `summary: clean` when nothing was unmapped (and, for push, no
+ *     collisions). Always printed so users see a consistent terminator
+ *     and can spot when behavior changes.
+ *   - `summary: <N> unmapped on pull (run nomad doctor to list)`
+ *   - `summary: <N> unmapped on diff (run nomad doctor to list)`
+ *   - `summary: <N> unmapped on push, <M> collisions (run nomad doctor to list)`
+ *
+ * Clean outcomes go through `ok()` (green `✓` glyph, stdout) and unmapped /
+ * collision outcomes go through `warn()` (yellow `⚠︎` glyph, stderr). The
+ * status glyph carries the success/warn semantics; users see e.g.
+ * `✓ summary: clean` or `⚠︎ summary: 3 unmapped on pull (...)`. Note: clean
+ * still goes to stdout so it survives backgrounded shell-rc invocations
+ * like `nomad pull 2>/dev/null &`. `collisions` is meaningful only for
+ * `'push'`; for `'pull'` / `'diff'` it is ignored and defaults to 0. This
+ * module is the SINGLE source of truth for the phrasing, eliminating drift
+ * risk across the three callers by construction.
+ */
+export function emitSummary(
+  verb: 'pull' | 'push' | 'diff',
+  unmapped: number,
+  collisions = 0,
+): void {
+  if (verb === 'push') {
+    if (unmapped === 0 && collisions === 0) {
+      ok('summary: clean');
+      return;
+    }
+    warn(
+      `summary: ${unmapped} unmapped on push, ${collisions} collisions (run nomad doctor to list)`,
+    );
+    return;
+  }
+  if (unmapped === 0) {
+    ok('summary: clean');
+    return;
+  }
+  warn(`summary: ${unmapped} unmapped on ${verb} (run nomad doctor to list)`);
+}

package/src/update.topology.ts

@@ -0,0 +1,118 @@
+import { execFileSync } from 'node:child_process';
+
+import { REPO_HOME, UPSTREAM_REPO_SLUG } from './config.ts';
+import { NomadFatal } from './utils.ts';
+
+/**
+ * Topology label resolved by `detectTopology`. `vanilla` is a single `origin`
+ * remote pointing at the public repo (read-only consumer). `fork` is the
+ * private-config layout: `upstream` is the public repo and `origin` is the
+ * user's private mirror. `unknown` is anything else: no `upstream`, an
+ * `origin` that does not match the public repo, etc. Unknown topologies
+ * surface a fatal so the user can run the two-command manual fallback
+ * without nomad guessing at intent.
+ */
+export type Topology = 'vanilla' | 'fork' | 'unknown';
+
+/** Escape regex metacharacters so a config value with `.` or `+` interpolated
+ * into a `new RegExp(...)` does not silently broaden the match. The current
+ * slug has no metachars, but this keeps the call defensible if it changes. */
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+/**
+ * Strict patterns matching the public repo's SSH and HTTPS remote URL forms,
+ * with and without a `.git` suffix. Both `git remote add upstream ...` styles
+ * (set-url ssh, gh-clone https) must round-trip through `detectTopology`.
+ */
+const SLUG_RE = escapeRe(UPSTREAM_REPO_SLUG);
+const SSH_REGEX = new RegExp(String.raw`^git@github\.com:${SLUG_RE}(\.git)?$`);
+const HTTPS_REGEX = new RegExp(String.raw`^https://github\.com/${SLUG_RE}(\.git)?$`);
+
+/**
+ * Determines whether a remote URL matches the canonical upstream repository forms (SSH or HTTPS).
+ *
+ * @param url - The remote URL to test
+ * @returns `true` if `url` matches the canonical upstream SSH or HTTPS form, `false` otherwise.
+ */
+function matchesUpstream(url: string): boolean {
+  return SSH_REGEX.test(url) || HTTPS_REGEX.test(url);
+}
+
+/**
+ * Parse the output of `git remote -v` into a mapping of remote names to their fetch URLs.
+ *
+ * Ignores `(push)` entries because topology detection drives the
+ * `git pull`/`fetch`/`merge` invocations, which all use the fetch URL.
+ * Lines that do not match the expected `<name> <url> (fetch)` format are
+ * skipped.
+ *
+ * @param out - Raw stdout from `git remote -v`
+ * @returns A record mapping each remote name to its fetch URL
+ */
+export function parseRemotes(out: string): Record<string, string> {
+  const remotes: Record<string, string> = {};
+  for (const line of out.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    const match = /^(\S+)\s+(\S+)\s+\(fetch\)$/.exec(trimmed);
+    if (match === null) continue;
+    remotes[match[1]] = match[2];
+  }
+  return remotes;
+}
+
+/**
+ * Classify a parsed `{ name: fetchUrl }` remote map into a topology label.
+ *
+ * Classification rules:
+ * - `vanilla` — exactly one remote named `origin` matching the public repo.
+ * - `fork` — an `upstream` matching the public repo and a separate `origin`
+ *   (any URL).
+ * - `unknown` — anything else (no `upstream`, an `origin` that does not
+ *   match the public repo, etc.).
+ *
+ * Pure and side-effect-free; tests drive it directly with hand-built maps.
+ *
+ * @param remotes - Map of remote name -> fetch URL produced by `parseRemotes`.
+ * @returns The resolved `Topology` label.
+ */
+export function detectTopology(remotes: Record<string, string>): Topology {
+  const origin = remotes.origin;
+  const upstream = remotes.upstream;
+  if (typeof upstream === 'string' && matchesUpstream(upstream) && typeof origin === 'string') {
+    return 'fork';
+  }
+  const names = Object.keys(remotes);
+  if (names.length === 1 && names[0] === 'origin' && matchesUpstream(origin ?? '')) {
+    return 'vanilla';
+  }
+  return 'unknown';
+}
+
+/**
+ * Detect the repository remote topology by running `git remote -v` in REPO_HOME
+ * and routing the output through `parseRemotes` + `detectTopology`.
+ *
+ * `git remote -v` is read-only so failures here are unexpected; we still
+ * route through `NomadFatal` so the dispatcher prints ``✗ ...``
+ * rather than dumping a stack trace.
+ *
+ * @returns The detected topology label: `'vanilla'`, `'fork'`, or `'unknown'`.
+ * @throws NomadFatal when `git remote -v` fails; any captured git stderr is written to `process.stderr` before the error is thrown.
+ */
+export function loadTopology(): Topology {
+  let out: string;
+  try {
+    out = execFileSync('git', ['remote', '-v'], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString();
+  } catch (err) {
+    const e = err as Error & { stderr?: Buffer };
+    if (e.stderr) process.stderr.write(e.stderr);
+    throw new NomadFatal('git remote -v failed');
+  }
+  return detectTopology(parseRemotes(out));
+}

package/src/utils.ts

@@ -0,0 +1,368 @@
+import { execFileSync } from 'node:child_process';
+import {
+  closeSync,
+  cpSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+
+import { dim, failGlyph, green, infoGlyph, okGlyph, red, warnGlyph, yellow } from './color.ts';
+import { CLAUDE_HOME, HOME } from './config.ts';
+
+const LOCK_PATH = join(HOME, '.cache', 'claude-nomad', 'nomad.lock');
+
+/** Opaque handle for an acquired lockfile. Pass to `releaseLock` in a `finally`. */
+export type LockHandle = { fd: number };
+
+/**
+ * Print an informational line prefixed with the dim `ℹ︎` glyph (U+2139+VS15)
+ * to stdout. Matches the doctor-style left-gutter glyph format so the whole
+ * CLI shares one visual vocabulary instead of the prior `[nomad]` text prefix
+ * coexisting with doctor's status glyphs.
+ */
+export const log = (msg: string): void => console.log(`${dim(infoGlyph)} ${msg}`);
+
+/**
+ * Print a success line prefixed with the green `✓` glyph to stdout. Use for
+ * positive terminators (e.g., `summary: clean`) where a status confirmation is
+ * load-bearing.
+ */
+export const ok = (msg: string): void => console.log(`${green(okGlyph)} ${msg}`);
+
+/**
+ * Print a warning line prefixed with the yellow `⚠︎` glyph to stderr. Use for
+ * non-fatal conditions the operator should notice (lock contention, partial
+ * sync outcomes, schema drift). Routes through `console.error` so both
+ * `console.error` spies and `process.stderr.write` spies in tests catch it.
+ */
+export const warn = (msg: string): void => {
+  console.error(`${yellow(warnGlyph)} ${msg}`);
+};
+
+/**
+ * Print a fatal-error line prefixed with the red `✗` glyph to stderr. Use for
+ * NomadFatal-equivalent failures surfaced to the user; the glyph carries the
+ * severity so callers do not need a redundant `FATAL:` text token. Routes
+ * through `console.error` so both `console.error` spies and
+ * `process.stderr.write` spies in tests catch it.
+ */
+export const fail = (msg: string): void => {
+  console.error(`${red(failGlyph)} ${msg}`);
+};
+
+/**
+ * Sentinel error class for fatal nomad failures. Thrown by `die()` and caught
+ * by top-level command wrappers (cmdPull, cmdPush, nomad.ts dispatcher) so a
+ * `finally` block can release locks before the process exits. Avoids the
+ * pre-fix bug where `process.exit()` skipped pending `finally` clauses and
+ * leaked the lockfile.
+ */
+export class NomadFatal extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NomadFatal';
+  }
+}
+
+/**
+ * Throw a `NomadFatal` with the given message. Callers should `catch` it in
+ * the cmdPull/cmdPush try/finally so the lock is released before exit.
+ */
+export const die = (msg: string): never => {
+  throw new NomadFatal(msg);
+};
+
+/**
+ * Shell-free, untrimmed `git status --porcelain=v1 -z` reader. Untrimmed
+ * because porcelain v1 -z records start with a 2-char status plus 1 space,
+ * and the first record's leading space is part of the format (e.g.
+ * `" M path\0"` for unstaged-modified). Going through `sh` would strip that
+ * space and shift the fixed-offset parse in `parsePorcelainZ`.
+ */
+export const gitStatusPorcelainZ = (cwd?: string): string =>
+  execFileSync('git', ['status', '--porcelain=v1', '-z'], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).toString();
+
+/**
+ * Run `git <args>` in `cwd`, forwarding stderr and converting non-zero exits
+ * to `NomadFatal`. Without this wrap, an ExecException would bubble past the
+ * cmdPull/cmdPush NomadFatal-only catch blocks and surface as a stack trace;
+ * the finally still releases the lock, but the user UX degrades.
+ */
+export function gitOrFatal(args: readonly string[], context: string, cwd?: string): void {
+  try {
+    execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    const e = err as Error & { stderr?: Buffer };
+    if (e.stderr) process.stderr.write(e.stderr);
+    throw new NomadFatal(`${context} failed`);
+  }
+}
+
+/** Read and JSON-parse `path`. Throws `SyntaxError` on malformed content. */
+export function readJson<T>(path: string): T {
+  const data: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  return data as T;
+}
+
+/** Write `data` as pretty-printed JSON (2-space indent, trailing newline). Non-atomic. */
+export function writeJson(path: string, data: unknown): void {
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Atomic write: temp + fsync + rename + parent-dir fsync. Survives
+ * interrupted pulls. Preserves the destination file's existing mode when it
+ * exists, defaults to 0o600 otherwise so credentials in `settings.json` are
+ * not widened by the process umask on every regenerate.
+ */
+export function writeJsonAtomic(path: string, data: unknown): void {
+  const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
+  const tmp = `${path}.tmp.${process.pid}`;
+  const fd = openSync(tmp, 'w', mode);
+  try {
+    writeFileSync(fd, JSON.stringify(data, null, 2) + '\n');
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, path);
+  // Fsync the parent directory so the rename itself is durable across a crash;
+  // otherwise the file contents are persisted but the directory entry can be
+  // lost. Linux/macOS support this on a read-only fd to the dir.
+  const dirFd = openSync(dirname(path), 'r');
+  try {
+    fsyncSync(dirFd);
+  } finally {
+    closeSync(dirFd);
+  }
+}
+
+/** Deep merge: source overrides target. Arrays replace, objects merge recursively. */
+export function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T {
+  const out: Record<string, unknown> = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    const existing = out[key];
+    const bothObjects =
+      value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      existing !== null &&
+      typeof existing === 'object' &&
+      !Array.isArray(existing);
+    out[key] = bothObjects
+      ? deepMerge(existing as Record<string, unknown>, value as Record<string, unknown>)
+      : value;
+  }
+  return out as T;
+}
+
+/** Claude Code encodes absolute project paths by replacing `/` with `-`. */
+export const encodePath = (absPath: string): string => absPath.replaceAll('/', '-');
+
+/** Local-time YYYYMMDD-HHMMSS timestamp; lexicographically sortable. Pure. */
+export function nowTimestamp(): string {
+  const d = new Date();
+  const pad = (n: number): string => n.toString().padStart(2, '0');
+  return (
+    d.getFullYear().toString() +
+    pad(d.getMonth() + 1) +
+    pad(d.getDate()) +
+    '-' +
+    pad(d.getHours()) +
+    pad(d.getMinutes()) +
+    pad(d.getSeconds())
+  );
+}
+
+/**
+ * Collision-resistant backup timestamp. `nowTimestamp()` is second-resolution,
+ * so two pulls in the same wall-clock second would share `ts`, and the
+ * second's `backupBeforeWrite` calls (which use `cpSync` with `force:false`)
+ * would silently no-op against the existing first snapshot. Append a `-N`
+ * suffix until the backup dir is unique.
+ */
+export function freshBackupTs(backupRoot: string): string {
+  const base = nowTimestamp();
+  if (!existsSync(join(backupRoot, base))) return base;
+  let n = 1;
+  while (existsSync(join(backupRoot, `${base}-${n}`))) n++;
+  return `${base}-${n}`;
+}
+
+/**
+ * Create a symlink at `linkPath` pointing to `target`, idempotently. No-op if
+ * a symlink already exists at `linkPath`; dies if a non-symlink exists there
+ * (caller should pre-scan and back up first; see `applySharedLinks`).
+ */
+export function ensureSymlink(linkPath: string, target: string): void {
+  if (existsSync(linkPath)) {
+    if (lstatSync(linkPath).isSymbolicLink()) return;
+    die(`${linkPath} exists and is not a symlink. Move it aside first.`);
+  }
+  mkdirSync(dirname(linkPath), { recursive: true });
+  symlinkSync(target, linkPath);
+  log(`linked ${linkPath} -> ${target}`);
+}
+
+/**
+ * Snapshot `absPath` into `~/.cache/claude-nomad/backup/<ts>/<rel>` before destructive write.
+ * No-op if source missing or outside CLAUDE_HOME. Recursive for directories.
+ */
+export function backupBeforeWrite(absPath: string, ts: string): void {
+  if (!existsSync(absPath)) return;
+  const rel = relative(CLAUDE_HOME, absPath);
+  if (rel.startsWith('..') || rel === '') return;
+  const backupRoot = join(HOME, '.cache', 'claude-nomad', 'backup', ts);
+  const dst = join(backupRoot, rel);
+  mkdirSync(dirname(dst), { recursive: true });
+  cpSync(absPath, dst, { recursive: true, force: false, preserveTimestamps: true });
+}
+
+/**
+ * Parallel of `backupBeforeWrite`, but scoped to `REPO_HOME` instead of
+ * `CLAUDE_HOME`. Used by `remapPush` to snapshot repo-side encoded-dir
+ * state before `copyDir` clobbers it. Backup root is repo-prefixed so the
+ * dump is distinguishable from `CLAUDE_HOME` backups in the same `ts` dir.
+ */
+export function backupRepoWrite(absPath: string, ts: string, repoHome: string): void {
+  if (!existsSync(absPath)) return;
+  const rel = relative(repoHome, absPath);
+  if (rel.startsWith('..') || rel === '') return;
+  const backupRoot = join(HOME, '.cache', 'claude-nomad', 'backup', ts, 'repo');
+  const dst = join(backupRoot, rel);
+  mkdirSync(dirname(dst), { recursive: true });
+  cpSync(absPath, dst, { recursive: true, force: false, preserveTimestamps: true });
+}
+
+/**
+ * Acquire the exclusive nomad lockfile so two pulls/pushes cannot mutate
+ * `~/.claude/` concurrently. Returns the handle on success, or `null` on
+ * contention (caller should `process.exit(0)`; skip-on-contention is the
+ * intended UX for backgrounded shell-rc invocations). Detects stale locks by
+ * probing the recorded pid with `kill(pid, 0)` and recovers via
+ * `unlinkIfSamePid` + `retryOnce`. `verb` is `'pull'` or `'push'`; surfaces
+ * in the contention-skip message.
+ */
+export function acquireLock(verb: string): LockHandle | null {
+  mkdirSync(dirname(LOCK_PATH), { recursive: true });
+  try {
+    const fd = openSync(LOCK_PATH, 'wx');
+    writeFileSync(fd, String(process.pid));
+    return { fd };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'EEXIST') throw err;
+    return checkStaleAndRetry(verb);
+  }
+}
+
+/**
+ * Release a previously-acquired lock handle. No-op when `handle` is null
+ * (matches `acquireLock`'s contention return). Tolerates the lockfile having
+ * already been unlinked. MUST be called from a `finally` so it runs even when
+ * the wrapped command throws.
+ */
+export function releaseLock(handle: LockHandle | null): void {
+  if (handle === null) return;
+  try {
+    closeSync(handle.fd);
+  } catch {
+    /* already closed; ignore */
+  }
+  try {
+    unlinkSync(LOCK_PATH);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+}
+
+/**
+ * Compare-and-delete helper that closes most of the TOCTOU window between
+ * reading a stale lock's pid and removing it: another process could
+ * legitimately acquire the lock between those steps, and a naive unlink
+ * would clobber it. Re-reads the file and only unlinks if the contents
+ * still equal `expectedPidStr`. Returns `true` if the lock was unlinked,
+ * `false` if the content drifted or the file already vanished. A microsecond
+ * window between the re-read and the unlink remains; the residual race is
+ * documented as a backlog item rather than fully closed here.
+ */
+function unlinkIfSamePid(expectedPidStr: string): boolean {
+  let current: string;
+  try {
+    current = readFileSync(LOCK_PATH, 'utf8').trim();
+  } catch {
+    return false;
+  }
+  if (current !== expectedPidStr) return false;
+  try {
+    unlinkSync(LOCK_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * EEXIST recovery path for `acquireLock`. Reads the lockfile pid, probes
+ * liveness with `kill(pid, 0)`, and tries one retry only when the pid is
+ * dead AND the compare-and-delete in `unlinkIfSamePid` confirms the file
+ * has not been replaced under us. Returns `null` (contention skip) in any
+ * other case.
+ */
+function checkStaleAndRetry(verb: string): LockHandle | null {
+  let pidStr: string;
+  try {
+    pidStr = readFileSync(LOCK_PATH, 'utf8').trim();
+  } catch {
+    pidStr = '';
+  }
+  const pid = Number.parseInt(pidStr, 10);
+  if (!Number.isFinite(pid) || pid <= 0) {
+    if (unlinkIfSamePid(pidStr)) return retryOnce(verb);
+    warn(`another nomad ${verb} running, skipping`);
+    return null;
+  }
+  try {
+    process.kill(pid, 0);
+    warn(`another nomad ${verb} running, skipping`);
+    return null;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ESRCH') {
+      if (unlinkIfSamePid(pidStr)) return retryOnce(verb);
+      warn(`another nomad ${verb} running, skipping`);
+      return null;
+    }
+    warn(`another nomad ${verb} running, skipping`);
+    return null;
+  }
+}
+
+/**
+ * Single retry of `openSync(..., 'wx')` after `unlinkIfSamePid` cleared a
+ * confirmed-stale lock. Bounded to one attempt to avoid spin loops if the
+ * lock is being rapidly recreated by another live process.
+ */
+function retryOnce(verb: string): LockHandle | null {
+  try {
+    const fd = openSync(LOCK_PATH, 'wx');
+    writeFileSync(fd, String(process.pid));
+    return { fd };
+  } catch {
+    warn(`another nomad ${verb} running, skipping`);
+    return null;
+  }
+}