claude-nomad 0.56.2 → 0.57.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.57.0](https://github.com/funkadelic/claude-nomad/compare/v0.56.2...v0.57.0) (2026-07-03)
+
+
+### Added
+
+* **docs-site:** add starlight-llms-txt plugin ([#378](https://github.com/funkadelic/claude-nomad/issues/378)) ([0604327](https://github.com/funkadelic/claude-nomad/commit/0604327ffa69abbee0b70183a49416ec14a3306c))
+* **sync:** add unified nomad sync command ([#380](https://github.com/funkadelic/claude-nomad/issues/380)) ([e60a05e](https://github.com/funkadelic/claude-nomad/commit/e60a05e62179751652d70e54ba3deb8b6b7c4859))
+
+
+### Fixed
+
+* **plugin:** tolerate a user-supplied --dry-run in push and sync wrappers ([#381](https://github.com/funkadelic/claude-nomad/issues/381)) ([7ce0a99](https://github.com/funkadelic/claude-nomad/commit/7ce0a99ae53cd8737b5e03bb0f5f730447b1108d))
+
+
+### Changed
+
+* remove vestigial private-repo guards from workflows ([#383](https://github.com/funkadelic/claude-nomad/issues/383)) ([31e52b8](https://github.com/funkadelic/claude-nomad/commit/31e52b834ca55204dac29fcec6ceee35605f818b))
+* scrub internal planning IDs from source and test comments ([#382](https://github.com/funkadelic/claude-nomad/issues/382)) ([b024b7b](https://github.com/funkadelic/claude-nomad/commit/b024b7b1b877af347db7ca1754751ede73b5879f))
+
 ## [0.56.2](https://github.com/funkadelic/claude-nomad/compare/v0.56.1...v0.56.2) (2026-07-01)
 
 

package/README.md

@@ -13,8 +13,9 @@
 
 Open Claude Code on a second machine and it is a blank slate: none of your custom skills, slash
 commands, tuned settings, or past conversations. **claude-nomad** keeps all of it in sync through a
-private Git repo you control. `nomad push` on one machine, `nomad pull` on the next, and everything
-is there, conversations included.
+private Git repo you control. Run `nomad sync` on any machine and everything is there, conversations
+included; it pulls in your latest config first, then publishes your local changes, so you never have
+to remember which one to run first.
 
 Not dotfiles, not rsync. **claude-nomad** understands Claude Code's state, so your session history
 survives different file paths and your secrets never ride along.
@@ -117,14 +118,19 @@ Everyday loop on any host:
 
 ```bash
 $ nomad doctor   # confirm setup
-$ nomad pull     # apply config to ~/.claude/
-$ nomad push     # publish local changes (sessions, settings)
+$ nomad sync     # pull config, then publish local changes, in one step
 ```
 
-Pull before you push whenever both machines may have changed. Sync is last-write-wins, so pushing
-stale local state over newer remote state silently overwrites it. The
-[FAQ](https://funkadelic.github.io/claude-nomad/faq/) covers the full push/pull order when both
-sides have changed.
+`nomad sync` is the command to reach for day to day: it always pulls first (so changes from your
+other machines land before anything is pushed, and work that exists only on this machine is kept,
+not deleted) and then pushes, under one lock, so there is no ordering to remember. `nomad pull` and
+`nomad push` are still available as lower-level commands for cases `sync` does not cover: recovering
+a wedged repo with `nomad pull --force-remote`, or resolving a detected secret without the
+interactive menu via `nomad push --redact-all` / `--allow` / `--allow-all` (see
+[Changing settings](#changing-settings) and
+[Recovery flows](https://funkadelic.github.io/claude-nomad/recovery/)). The
+[FAQ](https://funkadelic.github.io/claude-nomad/faq/) covers what `sync` does under the hood and the
+push/pull order it enforces.
 
 ### Make your sessions follow you
 
@@ -216,10 +222,10 @@ first (minimum version `>= 0.35.0`), then add the plugin.
 /plugin install nomad@claude-nomad
 ```
 
-It adds `/nomad:pull`, `/nomad:diff`, `/nomad:push` (preview only), `/nomad:doctor`, and
-`/nomad:clean`, plus a session-start drift check. The plugin versions independently from the CLI,
-but requires nomad `>= 0.35.0` because it calls recent subcommands (`nomad diff`,
-`nomad clean --backups`) and reads the doctor command's status output. See the
+It adds `/nomad:sync` (preview only), `/nomad:pull`, `/nomad:diff`, `/nomad:push` (preview only),
+`/nomad:doctor`, and `/nomad:clean`, plus a session-start drift check. The plugin versions
+independently from the CLI, but requires nomad `>= 0.35.0` because it calls recent subcommands
+(`nomad diff`, `nomad clean --backups`) and reads the doctor command's status output. See the
 [plugin guide](https://funkadelic.github.io/claude-nomad/plugin/) for details.
 
 ## Requirements

package/dist/nomad.mjs

@@ -214,12 +214,13 @@ function gitOrFatal(args, context, cwd) {
     throw new NomadFatal(`${context} failed`);
   }
 }
-var log, warn, fail, item, NomadFatal, die, gitStatusPorcelainZ;
+var log, ok, warn, fail, item, NomadFatal, die, gitStatusPorcelainZ;
 var init_utils = __esm({
   "src/utils.ts"() {
     "use strict";
     init_color();
     log = (msg) => console.log(`${dim(infoGlyph)} ${msg}`);
+    ok = (msg) => console.log(`${green(okGlyph)} ${msg}`);
     warn = (msg) => {
       console.error(`${yellow(warnGlyph)} ${msg}`);
     };
@@ -468,7 +469,7 @@ var init_config = __esm({
       "hosts/",
       "path-map.json",
       ".gitleaksignore",
-      // written by nomad push Allow action (D-04)
+      // written by nomad push Allow action
       ".gitleaks.overlay.toml"
       // user-owned gitleaks allowlist overlay layered on the bundled base
     ];
@@ -5804,7 +5805,7 @@ function remapExtrasPush(ts, opts = {}) {
     //     Repo-only files survive; local edits propagate (overlay overwrites).
     //     The filter prevents ALWAYS_NEVER_SYNC files from landing in the repo
     //     working tree before the allow-list gate fires, eliminating the
-    //     "residue wedges repeat push" regression (WR-02). The allow-list gate
+    //     "residue wedges repeat push" regression. The allow-list gate
     //     (enforceAllowList / blockSetFor in commands.push.allowlist.ts)
     //     remains the hard security boundary.
     //   All others: copyExtrasFiltered with per-extra denylist.
@@ -5871,16 +5872,18 @@ function divergenceWarnLine(o) {
 }
 function divergenceCheckExtras(ts, prePostHeads) {
   const v = loadValidatedExtras({});
-  if (v === null) return;
+  if (v === null) return 0;
   const counts = { unmapped: 0, skipped: 0 };
   const backupRoot = join43(backupBase(), ts, "extras");
   const repo = repoHome();
+  let divergedCount = 0;
   for (const { logical, localRoot, dirname: dirname10 } of eachExtrasTarget(v, counts)) {
     const local = join43(localRoot, dirname10);
     const repoEntry = join43(repo, "shared", "extras", logical, dirname10);
     if (!existsSync36(local) || !existsSync36(repoEntry)) continue;
     const modified = listDivergingModified(local, repoEntry);
     if (modified.length === 0) continue;
+    divergedCount += modified.length;
     const projectBackupRoot = join43(backupRoot, encodePath(localRoot));
     warn(
       divergenceWarnLine({
@@ -5898,6 +5901,7 @@ function divergenceCheckExtras(ts, prePostHeads) {
       warn(keptDeleteWarnLine(logical, relToLocal));
     }
   }
+  return divergedCount;
 }
 
 // src/skills-sync.ts
@@ -6458,7 +6462,7 @@ function capturePrePostHeads(repo, rebase) {
   if (pre === void 0 || post === void 0) return void 0;
   return { pre, post };
 }
-function applyWetPull(ts, map, prePostHeads) {
+function buildWetPullSections(ts, map, prePostHeads) {
   applySharedLinks(ts, map);
   const { label } = regenerateSettings(ts);
   syncSkillsPull(ts);
@@ -6476,12 +6480,15 @@ function applyWetPull(ts, map, prePostHeads) {
       localOnly
     )
   );
-  renderTree([
-    buildSettingsSection(label),
-    buildSessionsSection(remapResult.pulled, remapResult.unmapped, localOnly),
-    buildExtrasSection(extrasResult.pulled, extrasResult.skipped),
-    summary
-  ]);
+  return {
+    sections: [
+      buildSettingsSection(label),
+      buildSessionsSection(remapResult.pulled, remapResult.unmapped, localOnly),
+      buildExtrasSection(extrasResult.pulled, extrasResult.skipped),
+      summary
+    ],
+    localOnly
+  };
 }
 function handleWedge(repo, forceRemote) {
   const wedge = classifyWedge(repo);
@@ -6501,11 +6508,40 @@ function handleWedge(repo, forceRemote) {
   const state = wedge === "rebase" ? "mid-rebase" : "mid-merge";
   die(wedgeMarkerRunbookText(state));
 }
-function cmdPull(opts = {}) {
+function runPullCore(opts = {}) {
   const dryRun = opts.dryRun === true;
   const forceRemote = opts.forceRemote === true;
   const repo = repoHome();
   const backup = backupBase();
+  const ts = freshBackupTs(backup);
+  handleWedge(repo, forceRemote);
+  if (!dryRun) {
+    const backupRoot = join46(backup, ts);
+    try {
+      mkdirSync10(backupRoot, { recursive: true });
+    } catch (err) {
+      die(`could not create backup dir: ${err.message}`);
+    }
+  }
+  log(
+    dryRun ? `pulling on host=${HOST} (backup=${ts}; dry-run)` : `pull on host=${HOST} (backup=${ts})`
+  );
+  const prePostHeads = capturePrePostHeads(repo, () => {
+    gitOrFatal(["pull", "--rebase", "--autostash"], "git pull --rebase", repo);
+  });
+  const mapPath = join46(repo, "path-map.json");
+  const map = existsSync39(mapPath) ? readPathMap(mapPath) : { projects: {} };
+  const divergedKeptLocal = divergenceCheckExtras(ts, dryRun ? prePostHeads : void 0);
+  if (dryRun) {
+    computePreview(ts, map, "pull");
+    log("dry-run complete; no mutation");
+    return { tag: "dry" };
+  }
+  const { sections, localOnly } = buildWetPullSections(ts, map, prePostHeads);
+  return { tag: "wet", sections, localOnly, divergedKeptLocal };
+}
+function cmdPull(opts = {}) {
+  const repo = repoHome();
   if (!existsSync39(repo)) die(`repo not cloned at ${repo}`);
   if (!existsSync39(join46(repo, "shared", "settings.base.json"))) {
     die("repo not initialized; run 'nomad init' to scaffold");
@@ -6513,31 +6549,8 @@ function cmdPull(opts = {}) {
   const handle = acquireLock("pull");
   if (handle === null) process.exit(0);
   try {
-    const ts = freshBackupTs(backup);
-    handleWedge(repo, forceRemote);
-    if (!dryRun) {
-      const backupRoot = join46(backup, ts);
-      try {
-        mkdirSync10(backupRoot, { recursive: true });
-      } catch (err) {
-        die(`could not create backup dir: ${err.message}`);
-      }
-    }
-    log(
-      dryRun ? `pulling on host=${HOST} (backup=${ts}; dry-run)` : `pull on host=${HOST} (backup=${ts})`
-    );
-    const prePostHeads = capturePrePostHeads(repo, () => {
-      gitOrFatal(["pull", "--rebase", "--autostash"], "git pull --rebase", repo);
-    });
-    const mapPath = join46(repo, "path-map.json");
-    const map = existsSync39(mapPath) ? readPathMap(mapPath) : { projects: {} };
-    divergenceCheckExtras(ts, dryRun ? prePostHeads : void 0);
-    if (dryRun) {
-      computePreview(ts, map, "pull");
-      log("dry-run complete; no mutation");
-    } else {
-      applyWetPull(ts, map, prePostHeads);
-    }
+    const result = runPullCore(opts);
+    if (result.tag === "wet") renderTree(result.sections);
   } catch (err) {
     if (err instanceof NomadFatal) {
       fail(err.message);
@@ -6962,7 +6975,7 @@ async function commitAndPush(st, ts, map, resolution, repo, newManifest) {
   if (staged.length === toDrop.length) {
     log("nothing to commit");
     renderNoScanTree(st);
-    return;
+    return "nothing";
   }
   st.globalConfig = collectGlobalConfigChanges(repo, HOST, { staged: true });
   let verdict = withSpinner("Scanning for secrets", () => scanPushVerdict(repo));
@@ -6978,6 +6991,7 @@ async function commitAndPush(st, ts, map, resolution, repo, newManifest) {
     warn(`could not write push manifest (next push will full-rescan): ${String(err)}`);
   }
   renderPushTree(st, verdict);
+  return "pushed";
 }
 function runDryRunPreview(st, map, repo, selection) {
   st.globalConfig = collectGlobalConfigChanges(repo, HOST, { staged: false });
@@ -6994,55 +7008,181 @@ function runDryRunPreview(st, map, repo, selection) {
 init_push_checks();
 init_utils();
 init_utils_fs();
-async function cmdPush(opts = {}) {
+async function runPushCore(opts = {}) {
   const dryRun = opts.dryRun === true;
   const redactAll = opts.redactAll === true;
   const allowAll = opts.allowAll === true;
   const allowRule = opts.allowRule;
   const fullScan = opts.fullScan === true;
-  guardResolutionModeConflicts(dryRun, redactAll, allowAll, allowRule);
   const repo = repoHome();
   const backup = backupBase();
+  console.log(dryRun ? `push on host=${HOST} (dry-run)` : `push on host=${HOST}`);
+  reportSettingsAheadDrift(repo);
+  const scannerVersion = probeGitleaks();
+  const configHash = computeConfigHash();
+  const old = readManifest(manifestPath());
+  const mapPath = join51(repo, "path-map.json");
+  const { map, selection, newManifest } = loadSelectionForPush(
+    mapPath,
+    old,
+    scannerVersion,
+    configHash,
+    fullScan
+  );
+  withSpinner("Rebasing onto origin", () => rebaseBeforePush(repo));
+  const ts = freshBackupTs(backup);
+  const remap = withSpinner("Syncing sessions", () => remapPush(ts, { dryRun, selection }));
+  const extras = withSpinner("Syncing extras", () => remapExtrasPush(ts, { dryRun }));
+  if (!dryRun) {
+    syncSkillsPush();
+    stripGsdHooksFromBase(repo, backup);
+  }
+  const st = { dryRun, remap, extras, globalConfig: [] };
+  guardGitlinks(repo);
+  const status = gitStatusPorcelainZ(repo, { untrackedAll: true });
+  if (!dryRun && !status) {
+    log("nothing to commit");
+    renderNoScanTree(st);
+    return { tag: "nothing" };
+  }
+  if (map === null) {
+    if (dryRun) {
+      runDryRunPreview(st, null, repo, selection);
+      return { tag: "dry" };
+    }
+    return die("path-map.json missing, cannot enforce push allow-list");
+  }
+  if (status) enforceAllowList(status, map);
+  if (dryRun) {
+    runDryRunPreview(st, map, repo, selection);
+    return { tag: "dry" };
+  }
+  const outcome = await commitAndPush(
+    st,
+    ts,
+    map,
+    { redactAll, allowAll, allowRule },
+    repo,
+    newManifest
+  );
+  return outcome === "nothing" ? { tag: "nothing" } : { tag: "pushed" };
+}
+async function cmdPush(opts = {}) {
+  const dryRun = opts.dryRun === true;
+  const redactAll = opts.redactAll === true;
+  const allowAll = opts.allowAll === true;
+  const allowRule = opts.allowRule;
+  guardResolutionModeConflicts(dryRun, redactAll, allowAll, allowRule);
+  const repo = repoHome();
   if (!existsSync43(repo)) die(`repo not cloned at ${repo}`);
   const handle = acquireLock("push");
   if (handle === null) process.exit(0);
   try {
-    console.log(dryRun ? `push on host=${HOST} (dry-run)` : `push on host=${HOST}`);
-    reportSettingsAheadDrift(repo);
-    const scannerVersion = probeGitleaks();
-    const configHash = computeConfigHash();
-    const old = readManifest(manifestPath());
-    const mapPath = join51(repo, "path-map.json");
-    const { map, selection, newManifest } = loadSelectionForPush(
-      mapPath,
-      old,
-      scannerVersion,
-      configHash,
-      fullScan
-    );
-    withSpinner("Rebasing onto origin", () => rebaseBeforePush(repo));
-    const ts = freshBackupTs(backup);
-    const remap = withSpinner("Syncing sessions", () => remapPush(ts, { dryRun, selection }));
-    const extras = withSpinner("Syncing extras", () => remapExtrasPush(ts, { dryRun }));
-    if (!dryRun) {
-      syncSkillsPush();
-      stripGsdHooksFromBase(repo, backup);
-    }
-    const st = { dryRun, remap, extras, globalConfig: [] };
-    guardGitlinks(repo);
-    const status = gitStatusPorcelainZ(repo, { untrackedAll: true });
-    if (!dryRun && !status) {
-      log("nothing to commit");
-      renderNoScanTree(st);
-      return;
+    await runPushCore(opts);
+  } catch (err) {
+    if (err instanceof NomadFatal) {
+      fail(err.message);
+      process.exitCode = 1;
+    } else {
+      throw err;
     }
-    if (map === null) {
-      if (dryRun) return runDryRunPreview(st, null, repo, selection);
-      return die("path-map.json missing, cannot enforce push allow-list");
+  } finally {
+    releaseLock(handle);
+  }
+}
+
+// src/commands.sync.ts
+import { existsSync as existsSync44 } from "node:fs";
+import { join as join52 } from "node:path";
+init_config();
+init_utils();
+init_utils_fs();
+init_utils_json();
+function pullHasNoSyncedItems(sections) {
+  return sections.every(
+    (s) => s.header === "Settings" || s.header === "Summary" || s.items.length === 0
+  );
+}
+function isNoopSync(pull, pushOutcome) {
+  if (!pushOutcome.ok) return false;
+  if (pull.localOnly !== 0 || pull.divergedKeptLocal !== 0) return false;
+  if (pushOutcome.result.tag !== "nothing") return false;
+  return pullHasNoSyncedItems(pull.sections);
+}
+function pullPhrase(pull) {
+  const summary = pull.sections.find((s) => s.header === "Summary");
+  return summary?.items[0] ?? "applied";
+}
+function reconciledNotes(pull) {
+  const notes = [];
+  if (pull.divergedKeptLocal > 0) {
+    notes.push(`${pull.divergedKeptLocal} diverged files kept local and pushed`);
+  }
+  if (pull.localOnly > 0) {
+    notes.push(`${pull.localOnly} local-only sessions pushed`);
+  }
+  return notes;
+}
+function buildSyncSummarySection(pull, pushOutcome) {
+  const s = section("Summary");
+  if (!pushOutcome.ok) {
+    addItem(s, `pull: applied, push: failed (${pushOutcome.message})`);
+    return s;
+  }
+  addItem(s, `pull: ${pullPhrase(pull)}`);
+  addItem(s, `push: ${pushOutcome.result.tag === "pushed" ? "pushed" : "nothing to push"}`);
+  for (const note of reconciledNotes(pull)) addItem(s, note);
+  return s;
+}
+function renderWetSync(pull, pushOutcome) {
+  if (isNoopSync(pull, pushOutcome)) {
+    ok("already in sync");
+    return;
+  }
+  renderTree(pull.sections);
+  renderTree([buildSyncSummarySection(pull, pushOutcome)]);
+}
+async function runSyncPushHalf() {
+  try {
+    const result = await runPushCore();
+    return { ok: true, result };
+  } catch (err) {
+    if (err instanceof NomadFatal) {
+      process.exitCode = 1;
+      return { ok: false, message: err.message };
+    }
+    throw err;
+  }
+}
+async function runSyncWet() {
+  const pull = runPullCore();
+  const pushOutcome = await runSyncPushHalf();
+  renderWetSync(pull, pushOutcome);
+}
+async function runSyncDryRun(repo, backup) {
+  const ts = freshBackupTs(backup);
+  const mapPath = join52(repo, "path-map.json");
+  const map = existsSync44(mapPath) ? readPathMap(mapPath) : { projects: {} };
+  computePreview(ts, map, "pull");
+  log("push preview below is computed against pre-pull state (a real sync pushes after pull)");
+  await runPushCore({ dryRun: true });
+}
+async function cmdSync(opts = {}) {
+  const dryRun = opts.dryRun === true;
+  const repo = repoHome();
+  const backup = backupBase();
+  if (!existsSync44(repo)) die(`repo not cloned at ${repo}`);
+  if (!existsSync44(join52(repo, "shared", "settings.base.json"))) {
+    die("repo not initialized; run 'nomad init' to scaffold");
+  }
+  const handle = acquireLock("sync");
+  if (handle === null) process.exit(0);
+  try {
+    if (dryRun) {
+      await runSyncDryRun(repo, backup);
+    } else {
+      await runSyncWet();
     }
-    if (status) enforceAllowList(status, map);
-    if (dryRun) return runDryRunPreview(st, map, repo, selection);
-    await commitAndPush(st, ts, map, { redactAll, allowAll, allowRule }, repo, newManifest);
   } catch (err) {
     if (err instanceof NomadFatal) {
       fail(err.message);
@@ -7099,18 +7239,18 @@ init_config();
 
 // src/diff.ts
 init_config();
-import { existsSync as existsSync44 } from "node:fs";
-import { join as join52 } from "node:path";
+import { existsSync as existsSync45 } from "node:fs";
+import { join as join53 } from "node:path";
 init_utils();
 init_utils_fs();
 init_utils_json();
 function cmdDiff() {
   try {
     const repo = repoHome();
-    if (!existsSync44(repo)) die(`repo not cloned at ${repo}`);
+    if (!existsSync45(repo)) die(`repo not cloned at ${repo}`);
     const ts = freshBackupTs(backupBase());
-    const mapPath = join52(repo, "path-map.json");
-    const map = existsSync44(mapPath) ? readPathMap(mapPath) : { projects: {} };
+    const mapPath = join53(repo, "path-map.json");
+    const map = existsSync45(mapPath) ? readPathMap(mapPath) : { projects: {} };
     divergenceCheckExtras(ts);
     computePreview(ts, map, "diff");
   } catch (err) {
@@ -7125,8 +7265,8 @@ function cmdDiff() {
 
 // src/init.ts
 init_config();
-import { existsSync as existsSync46, mkdirSync as mkdirSync12, writeFileSync as writeFileSync6 } from "node:fs";
-import { join as join54 } from "node:path";
+import { existsSync as existsSync47, mkdirSync as mkdirSync12, writeFileSync as writeFileSync6 } from "node:fs";
+import { join as join55 } from "node:path";
 
 // src/init.gh-onboard.ts
 init_config();
@@ -7208,33 +7348,33 @@ init_config();
 init_utils();
 init_utils_fs();
 init_utils_json();
-import { copyFileSync as copyFileSync2, cpSync as cpSync7, existsSync as existsSync45, rmSync as rmSync15, statSync as statSync12 } from "node:fs";
-import { join as join53 } from "node:path";
+import { copyFileSync as copyFileSync2, cpSync as cpSync7, existsSync as existsSync46, rmSync as rmSync15, statSync as statSync12 } from "node:fs";
+import { join as join54 } from "node:path";
 function snapshotIntoShared(map) {
   const repo = repoHome();
   const claude = claudeHome();
   for (const name of allSharedLinks(map)) {
-    const src = join53(claude, name);
-    if (!existsSync45(src)) continue;
-    const dst = join53(repo, "shared", name);
+    const src = join54(claude, name);
+    if (!existsSync46(src)) continue;
+    const dst = join54(repo, "shared", name);
     if (statSync12(src).isDirectory()) {
-      const gk = join53(dst, ".gitkeep");
-      if (existsSync45(gk)) rmSync15(gk);
+      const gk = join54(dst, ".gitkeep");
+      if (existsSync46(gk)) rmSync15(gk);
       cpSync7(src, dst, { recursive: true, force: false, errorOnExist: true });
     } else {
       copyFileSync2(src, dst);
     }
     log(`snapshotted shared/${name} from ${src}`);
   }
-  const userSettings = join53(claude, "settings.json");
-  if (existsSync45(userSettings)) {
+  const userSettings = join54(claude, "settings.json");
+  if (existsSync46(userSettings)) {
     let parsed;
     try {
       parsed = readJson(userSettings);
     } catch (err) {
       return die(`malformed ${userSettings}: ${err.message}`);
     }
-    const hostFile = join53(repo, "hosts", `${HOST}.json`);
+    const hostFile = join54(repo, "hosts", `${HOST}.json`);
     writeJsonAtomic(hostFile, parsed);
     log(`snapshotted hosts/${HOST}.json from ${userSettings}`);
   }
@@ -7247,14 +7387,14 @@ var SHARED_CLAUDE_MD = "<!-- claude-nomad shared CLAUDE.md; symlinked into ~/.cl
 var SHARED_KEEP_DIRS = ["agents", "skills", "commands", "rules", "hooks"];
 function preflightConflict(repoHome2) {
   const candidates = [
-    join54(repoHome2, "shared", "settings.base.json"),
-    join54(repoHome2, "shared", "CLAUDE.md"),
-    join54(repoHome2, "path-map.json"),
-    join54(repoHome2, "hosts"),
-    join54(repoHome2, "shared")
+    join55(repoHome2, "shared", "settings.base.json"),
+    join55(repoHome2, "shared", "CLAUDE.md"),
+    join55(repoHome2, "path-map.json"),
+    join55(repoHome2, "hosts"),
+    join55(repoHome2, "shared")
   ];
   for (const c of candidates) {
-    if (existsSync46(c)) return c;
+    if (existsSync47(c)) return c;
   }
   return null;
 }
@@ -7272,25 +7412,25 @@ function cmdInit(opts = {}) {
     die(`already initialized; refusing to clobber ${conflict}`);
   }
   ensureOriginRepo(opts.repoName ?? DEFAULT_REPO_NAME, opts.run);
-  mkdirSync12(join54(repo, "shared"), { recursive: true });
-  mkdirSync12(join54(repo, "hosts"), { recursive: true });
+  mkdirSync12(join55(repo, "shared"), { recursive: true });
+  mkdirSync12(join55(repo, "hosts"), { recursive: true });
   for (const name of SHARED_KEEP_DIRS) {
-    mkdirSync12(join54(repo, "shared", name), { recursive: true });
+    mkdirSync12(join55(repo, "shared", name), { recursive: true });
   }
-  const userClaudeMd = join54(claude, "CLAUDE.md");
-  if (!snapshot || !existsSync46(userClaudeMd)) {
-    writeFileSync6(join54(repo, "shared", "CLAUDE.md"), SHARED_CLAUDE_MD);
+  const userClaudeMd = join55(claude, "CLAUDE.md");
+  if (!snapshot || !existsSync47(userClaudeMd)) {
+    writeFileSync6(join55(repo, "shared", "CLAUDE.md"), SHARED_CLAUDE_MD);
     item("created shared/CLAUDE.md");
   }
   for (const name of SHARED_KEEP_DIRS) {
-    writeFileSync6(join54(repo, "shared", name, ".gitkeep"), "");
+    writeFileSync6(join55(repo, "shared", name, ".gitkeep"), "");
     item(`created shared/${name}/.gitkeep`);
   }
-  writeFileSync6(join54(repo, "hosts", ".gitkeep"), "");
+  writeFileSync6(join55(repo, "hosts", ".gitkeep"), "");
   item("created hosts/.gitkeep");
-  writeJsonAtomic(join54(repo, "shared", "settings.base.json"), {});
+  writeJsonAtomic(join55(repo, "shared", "settings.base.json"), {});
   item("created shared/settings.base.json");
-  writeJsonAtomic(join54(repo, "path-map.json"), { projects: {} });
+  writeJsonAtomic(join55(repo, "path-map.json"), { projects: {} });
   item("created path-map.json");
   if (snapshot) {
     snapshotIntoShared({ projects: {} });
@@ -7356,11 +7496,11 @@ function maybeDisableRepoActions(repoHome2, run) {
 // src/init.prompt.ts
 init_config();
 init_utils();
-import { existsSync as existsSync47, readdirSync as readdirSync17, statSync as statSync13 } from "node:fs";
-import { join as join55 } from "node:path";
+import { existsSync as existsSync48, readdirSync as readdirSync17, statSync as statSync13 } from "node:fs";
+import { join as join56 } from "node:path";
 import { createInterface as createInterface3 } from "node:readline/promises";
 function nonEmptyExists(path) {
-  if (!existsSync47(path)) return false;
+  if (!existsSync48(path)) return false;
   try {
     if (statSync13(path).isDirectory()) return readdirSync17(path).length > 0;
     return true;
@@ -7369,8 +7509,8 @@ function nonEmptyExists(path) {
   }
 }
 function hasExistingClaudeConfig(claudeHome2) {
-  if (existsSync47(join55(claudeHome2, "settings.json"))) return true;
-  return SHARED_LINKS.some((name) => nonEmptyExists(join55(claudeHome2, name)));
+  if (existsSync48(join56(claudeHome2, "settings.json"))) return true;
+  return SHARED_LINKS.some((name) => nonEmptyExists(join56(claudeHome2, name)));
 }
 async function confirmSnapshotDefault(claudeHome2) {
   if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
@@ -7654,10 +7794,27 @@ function parsePushArgs(argv) {
   };
 }
 
+// src/nomad.dispatch.sync.ts
+function parseSyncArgs(argv) {
+  let dryRun = false;
+  let i = 3;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (token === "--dry-run") {
+      if (dryRun) return null;
+      dryRun = true;
+    } else {
+      return null;
+    }
+    i++;
+  }
+  return { dryRun };
+}
+
 // package.json
 var package_default = {
   name: "claude-nomad",
-  version: "0.56.2",
+  version: "0.57.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: [
@@ -7786,6 +7943,12 @@ var DEFAULT_HELP = [
   cont("when no finding survives. No TTY required. Never skips the scan."),
   cont("Mutually exclusive with --redact-all/--allow. Cannot combine with --dry-run."),
   "",
+  row("  sync", "Pull (retain-merge), then push, under one lock. One-shot; hides ordering."),
+  row("       --dry-run", "Stack the pull preview then the push preview; mutates nothing."),
+  cont("Fails fast on a pull-half error; a wedged repo hints at nomad pull --force-remote"),
+  cont("(sync itself takes no --force-remote). Mid-push leak recovery behaves exactly"),
+  cont("like nomad push."),
+  "",
   row("  diff", "Offline preview of what `pull` would change against local repo state."),
   cont("No git pull, no lock acquired."),
   "",
@@ -7882,15 +8045,15 @@ var DEFAULT_HELP = [
 init_config();
 init_utils();
 init_utils_json();
-import { existsSync as existsSync48, readFileSync as readFileSync17, readdirSync as readdirSync18 } from "node:fs";
-import { join as join56 } from "node:path";
+import { existsSync as existsSync49, readFileSync as readFileSync17, readdirSync as readdirSync18 } from "node:fs";
+import { join as join57 } from "node:path";
 function resumeCmd(sessionId) {
   if (!/^[A-Za-z0-9_-]+$/.test(sessionId) || sessionId.length > 128) {
     fail(`invalid session id: ${sessionId}`);
     process.exit(1);
   }
-  const projectsRoot = join56(claudeHome(), "projects");
-  if (!existsSync48(projectsRoot)) {
+  const projectsRoot = join57(claudeHome(), "projects");
+  if (!existsSync49(projectsRoot)) {
     fail(`${projectsRoot} does not exist`);
     process.exit(1);
   }
@@ -7904,8 +8067,8 @@ function resumeCmd(sessionId) {
     fail(`no cwd field found in ${jsonlPath}`);
     process.exit(1);
   }
-  const mapPath = join56(repoHome(), "path-map.json");
-  if (!existsSync48(mapPath)) {
+  const mapPath = join57(repoHome(), "path-map.json");
+  if (!existsSync49(mapPath)) {
     fail("path-map.json missing");
     process.exit(1);
   }
@@ -7928,8 +8091,8 @@ function resumeCmd(sessionId) {
 }
 function findTranscriptPath(projectsRoot, sessionId) {
   for (const dir of readdirSync18(projectsRoot)) {
-    const candidate = join56(projectsRoot, dir, `${sessionId}.jsonl`);
-    if (existsSync48(candidate)) return candidate;
+    const candidate = join57(projectsRoot, dir, `${sessionId}.jsonl`);
+    if (existsSync49(candidate)) return candidate;
   }
   return null;
 }
@@ -8007,6 +8170,15 @@ try {
       });
       break;
     }
+    case "sync": {
+      const syncArgs = parseSyncArgs(process.argv);
+      if (syncArgs === null) {
+        console.error("usage: nomad sync [--dry-run]");
+        process.exit(1);
+      }
+      await cmdSync({ dryRun: syncArgs.dryRun });
+      break;
+    }
     case "init": {
       const initArgs = parseInitArgs(process.argv);
       if (initArgs === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.56.2",
+  "version": "0.57.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": [