moshcode 0.39.0 → 0.40.0

package/README.md

@@ -43,6 +43,8 @@ or miss one that does. A test fails the build when it drifts.
 | `moshcode login` | account | authenticate with app.moshcode.sh |
 | `moshcode whoami` | account | show the logged-in account |
 | `moshcode logout` | account | clear the logged-in account |
+| `moshcode save` | account | save this machine's pit settings to your account |
+| `moshcode load` | account | bring your saved pit settings onto this machine |
 | `moshcode console` | account | serve or connect to the browser terminal |
 | `moshcode dns` | hosting | resolve Moshpit names on this machine |
 | `moshcode doh` | hosting | run the DNS-over-HTTPS resolver |
@@ -579,6 +581,52 @@ event, and publishes it to the displayed relays. Both flows leave the final
 confirmation in the browser. If the pit is remote or headless, `/post` prints
 the composer URL instead.
 
+## Settings sync (`/save` and `/load`)
+
+Your pit becomes yours by accretion — a dozen aliases, herd rules you tuned until
+the roster stopped lying to you. All of it lives in `~/.moshcode` on one machine,
+which is why every new laptop, container and droplet used to feel like someone
+else's prompt.
+
+`/save` pushes that configuration to your `app.moshcode.sh` account. `/load`
+brings it down onto any machine you have run `/login` on.
+
+```sh
+moshcode save                 # push this machine's settings (pit: /save)
+moshcode save --dry-run       # what would go up, and stop
+
+# on the new box
+moshcode login
+moshcode load                 # pull them down (pit: /load)
+moshcode load --dry-run       # the per-file plan, changing nothing
+```
+
+What syncs is an allowlist, not a directory walk:
+
+| file | what it is |
+|---|---|
+| `~/.moshcode/aliases.json` | your pit aliases (`/alias`) |
+| `~/.moshcode/herd/rules.json` | herd state-detection overrides |
+
+What never syncs, by name: `credentials.json` (the account token this very
+feature authenticates with), `herd/sessions.json` (live state pinned to one tmux
+server), `sync.json`, and the `pkg/` binary cache. Engine configuration
+(`~/.claude.json` and friends) is deliberately left alone — those files carry
+provider API keys.
+
+Nothing is overwritten quietly:
+
+- Each save is a numbered **revision**. `/save` sends the revision it last agreed
+  on, and the app refuses the write if another machine has saved since — you get
+  told, with `/load` and `/save --force` as the two ways out.
+- `/load` refuses to replace a settings file you edited since this machine last
+  synced, and names it. `--force` overrides.
+- The last ten revisions are kept. See them, and which machine each came from, at
+  [app.moshcode.sh/settings/sync](https://app.moshcode.sh/settings/sync) — where
+  you can also promote an older revision or delete the lot.
+
+Both verbs take `--json`, so a provisioning script can act on the result.
+
 ## Browser terminal (`moshcode console`)
 
 A real terminal in the browser — arrow keys, history, full-screen TUIs — because

package/bin/moshcode.mjs

@@ -26,6 +26,7 @@ import { canOpenBrowser, openBrowser } from "../src/open-url.mjs";
 import { locate, tilde } from "../src/pwd.mjs";
 import { createPrd, listPrds, authoringPrompt } from "../src/prd.mjs";
 import { loginAuto, whoami, logout } from "../src/auth.mjs";
+import { loadCommand, saveCommand } from "../src/settings-sync.mjs";
 import { tui } from "../src/tui.mjs";
 import { consoleCommand } from "../src/console.mjs";
 import { herdCommand, herdStart, splitDetachArgs } from "../src/herd-cli.mjs";
@@ -609,6 +610,8 @@ async function main() {
     return;
   }
   if (cmd === "logout") { logout(); return; }
+  if (cmd === "save") { process.exitCode = await saveCommand(rest); return; }
+  if (cmd === "load") { process.exitCode = await loadCommand(rest); return; }
   if (cmd === "run") {
     let max = 3, dryRun = false;
     let optionsEnded = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "type": "module",
   "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {

package/prd/0010-cloud-settings-sync.md

@@ -0,0 +1,132 @@
+---
+openprd: "0.2"
+id: "0010"
+title: "Sync the pit's settings to your moshcode.sh account"
+status: Draft
+authors:
+  - anthony@profullstack.com
+created: 2026-08-11
+updated: 2026-08-11
+repo: https://github.com/moshcoder/moshcode
+discussion:
+implementation: src/settings-sync.mjs · apps/pwa/src/routes/settings-sync.mjs
+tags: account, settings, sync
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+A pit becomes yours by accretion. You add `/alias set gs "git status"`, then a
+dozen more; you tune the herd's rules until it stops calling a working agent
+blocked. None of it is in a repo, none of it is in a dotfile anyone syncs, and
+all of it lives in `~/.moshcode` on exactly one machine.
+
+So the second machine is a stranger. A new laptop, a fresh container, a droplet
+you SSH into to babysit an agent, a reinstall after a disk swap — each one starts
+from nothing, and the muscle memory built at the first prompt does not work at
+the second. People already log in to `app.moshcode.sh` (`/login`) for approvals,
+notifications and the session mirror, so the account that could hold this
+configuration is already there and already paired with every machine.
+
+## Goals
+
+- Moving to a new machine costs `/login` and `/load`, not an afternoon of
+  remembering what you had.
+- A person can see what is stored on their account, and delete it, from the web.
+- Nobody is ever surprised by a settings overwrite — not from another machine,
+  and not over their own uncommitted edits.
+- No credential, key or token is ever part of what syncs, and that fact is
+  enforced by a test rather than by care.
+
+## Non-Goals
+
+- Continuous or background sync. Settings are edited by a person at a moment they
+  can name; a daemon that pushes silently is a daemon that overwrites silently.
+- Syncing engine configuration (`~/.claude.json`, `~/.codex`, MCP registrations).
+  Those files carry provider API keys and are owned by other tools' schemas.
+- Syncing machine state: live herd sessions, the package cache, shell history.
+  None of it means anything on a different box.
+- Merging. Two divergent settings files are resolved by a person choosing one,
+  not by a three-way merge of someone's aliases.
+
+## Users
+
+- **The multi-machine moshcoder** — laptop, desktop, a dev box, and a container
+  per project. Wants the same prompt everywhere.
+- **The reinstaller** — new OS, same person. Wants their aliases back.
+- **The team lead** — one account, several machines, and a strong preference for
+  never explaining to a colleague why their aliases disappeared.
+
+## Requirements
+
+- R1 [P0] `/save` (and `moshcode save`) uploads this machine's pit settings to the
+  logged-in account. `/load` (`moshcode load`) brings them back down.
+- R2 [P0] What syncs is an allowlist, not a directory walk: `aliases.json` and
+  `herd/rules.json` today. `credentials.json`, `herd/sessions.json`, `sync.json`
+  and `pkg/` are named as never-synced and asserted in tests.
+- R3 [P0] Each save is a numbered revision. `/save` sends the revision it last
+  agreed on and the app refuses the write if the account has moved past it, so
+  two machines cannot silently erase one another.
+- R4 [P0] `/load` refuses to overwrite a settings file that changed locally since
+  the last sync, and names the file. `--force` overrides; `--dry-run` shows the
+  per-file plan and writes nothing.
+- R5 [P0] Every path in a downloaded snapshot is re-checked against the allowlist
+  before anything is written. A snapshot is data from the network, and an
+  unchecked path in it makes `/load` a remote write primitive.
+- R6 [P1] The app keeps the last ten revisions, shows them at
+  `/settings/sync` with the machine and time each came from, and can promote an
+  older one to current.
+- R7 [P1] `--json` on both verbs, so a provisioning script can act on the result.
+- R8 [P1] A snapshot records which engines and tools the source machine had
+  installed. `/load` names the missing ones as a suggestion; it never installs.
+- R9 [P2] Not logged in, session expired, nothing saved yet, conflict: each is a
+  sentence naming the command that resolves it (`/login`, `/save`, `/load`,
+  `--force`).
+
+## UX Notes
+
+```
+mosh ▸ /save
+  ✓ saved 2 files to you@example.com (revision 3)
+     aliases.json  pit aliases
+     herd/rules.json  herd state rules
+     on another machine: `/login` then `/load`
+
+mosh ▸ /load                       # on the new box
+  loaded revision 3 from dev — 2 files written
+     added    aliases.json
+     added    herd/rules.json
+     that machine also had codex, gh — `/install <name>` to match it
+
+mosh ▸ /load                       # after editing aliases locally
+  1 local file changed since this machine last synced:
+     aliases.json
+     `/save` to keep them, `/load --force` to replace them, `/load --dry-run` to see the difference
+```
+
+The pit never blocks on this: both verbs are one request and some printing, so
+readline keeps the prompt. `~/.moshcode/sync.json` remembers the revision and a
+per-file digest — that digest is what separates "someone else saved" from "you
+edited this five minutes ago", which want opposite answers.
+
+## Success Metrics
+
+- A fresh machine reaches a familiar prompt in two commands (`/login`, `/load`).
+- Zero settings-loss reports: every destructive path is either refused or
+  recoverable from `/settings/sync`.
+- No credential ever appears in a stored snapshot (asserted, not audited).
+
+## Risks & Open Questions
+
+- **Scope creep into secrets.** The most-requested next file will be an engine
+  config that holds an API key. Holding the line — settings, never credentials —
+  is what keeps `/load` safe to run on a machine you share.
+- **Ten revisions is a guess.** Cheap to raise; it exists so a bad `/save` from
+  the wrong machine is recoverable at all.
+- **A snapshot version bump.** Handled by refusing to read a newer snapshot and
+  naming `moshcode upgrade`, rather than by guessing at a shape this build has
+  never seen.
+- **Should `/load` be able to pick a revision?** The app stores ten and the web
+  page can promote one, which covers recovery without adding a flag that takes a
+  number. Open if people ask for `--revision`.

package/prd/README.md

@@ -25,4 +25,5 @@ Start one with `moshcode prd "<idea>"` (TUI: `/prd`).
 | [0007](0007-profullstack-site-init.md) | Generate batteries-included Profullstack sites for Moshpit names | Draft |
 | [0008](0008-ticker-research-and-plugin-marketplace.md) | Bring equity research into the pit, and ship the pit's slash commands as a plugin | Draft |
 | [0009](0009-persistent-agent-runtime.md) | Keep the herd alive — a persistent runtime, semantic agent state, and one control surface for humans and agents | Accepted |
+| [0010](0010-cloud-settings-sync.md) | Sync the pit's settings to your moshcode.sh account | Draft |
 <!-- PRD-INDEX:END -->

package/src/cli-schema.mjs

@@ -278,6 +278,43 @@ export const CORE_CLI_COMMANDS = [
     synopsis: [["moshcode logout", ""]],
     seeAlso: ["login"],
   },
+  {
+    name: "save",
+    group: "account",
+    description: "save this machine's pit settings to your account",
+    synopsis: [["moshcode save [--dry-run] [--force] [--json]", ""]],
+    flags: [
+      ["--dry-run", "list what would be saved and stop", ""],
+      ["--force", "save even if another machine saved after this one last synced", ""],
+      ["--json", "machine-readable result", ""],
+    ],
+    examples: [
+      ["moshcode save", "push aliases + herd rules to app.moshcode.sh"],
+      ["moshcode save --dry-run", "what would go up"],
+    ],
+    seeAlso: ["load", "login", "alias"],
+    note: "aliases (~/.moshcode/aliases.json) and herd rules (~/.moshcode/herd/rules.json). "
+      + "credentials, live herd state and the package cache are never included. "
+      + "each save is a numbered revision; the last ten are kept at app.moshcode.sh/settings/sync.",
+  },
+  {
+    name: "load",
+    group: "account",
+    description: "bring your saved pit settings onto this machine",
+    synopsis: [["moshcode load [--dry-run] [--force] [--json]", ""]],
+    flags: [
+      ["--dry-run", "show the per-file plan and change nothing", ""],
+      ["--force", "overwrite local settings that changed since the last sync", ""],
+      ["--json", "machine-readable result", ""],
+    ],
+    examples: [
+      ["moshcode load", "on a new machine, right after moshcode login"],
+      ["moshcode load --dry-run", "which files would change"],
+    ],
+    seeAlso: ["save", "login", "alias"],
+    note: "refuses rather than overwriting a local file you edited since the last sync — "
+      + "`moshcode save` to keep it, or --force to replace it.",
+  },
   {
     name: "console",
     group: "account",
@@ -891,6 +928,10 @@ export const PIT_COMMANDS = [
   { name: "whoami", cli: "whoami", description: "who this machine is logged in as" },
   // Dispatched since forever and missing from /help until now.
   { name: "logout", cli: "logout", description: "clear the logged-in account" },
+  { name: "save", args: "[--dry-run] [--force]", cli: "save",
+    description: "save this pit's settings to your moshcode.sh account" },
+  { name: "load", args: "[--dry-run] [--force]", cli: "load",
+    description: "bring your saved settings onto this machine" },
   { name: "pwd", aliases: ["where"], cli: "pwd",
     description: "show the current dir + git repo/branch/origin" },
   { name: "shell", aliases: ["sh"], args: "[cmd]", pitOnly: true,

package/src/dns-system.mjs

@@ -274,7 +274,8 @@ export function requiredPort(platform, preferred = 5354) {
 /* ------------------------------------------------------- running the plan */
 
 import { spawn } from "node:child_process";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import dgram from "node:dgram";
+import { mkdir, open, readFile, rm, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir, tmpdir } from "node:os";
@@ -367,17 +368,132 @@ export async function daemonStatus(path = pidfilePath()) {
 }
 
 /**
- * Start the bridge detached, so the shell that launched it can exit.
+ * Where a daemon that died on startup left its reason.
  *
- * Not a systemd unit / launchd job / Windows service yet, which means it does
+ * Next to the pidfile, because the two answer halves of the same question and
+ * a person debugging one wants the other in the same directory.
+ */
+export function daemonLogPath(path = pidfilePath()) {
+  return join(dirname(path), "moshpit-dns.log");
+}
+
+/**
+ * How long to wait for the bridge to answer before reporting it unproven.
+ *
+ * Generous on purpose, and it costs nothing in the case that matters: a daemon
+ * that dies resolves the race on its `exit` event immediately, so this bounds
+ * only the "alive but has not answered yet" case. The bridge binds *after* it
+ * fetches the ending list, which against the live registry is ~3s on a fast
+ * link — a tighter deadline would print a warning about healthy bridges on
+ * every slow connection.
+ */
+export const READY_TIMEOUT_MS = 8000;
+const POLL_MS = 150;
+const LOG_TAIL_LINES = 20;
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** A minimal A query. Only the reply matters here, never what it says. */
+function encodeQuery(name, id) {
+  const labels = String(name).split(".").filter(Boolean);
+  const head = Buffer.alloc(12);
+  head.writeUInt16BE(id, 0);
+  head.writeUInt16BE(0x0100, 2); // standard query, recursion desired
+  head.writeUInt16BE(1, 4); // one question
+  const tail = Buffer.alloc(4);
+  tail.writeUInt16BE(1, 0); // A
+  tail.writeUInt16BE(1, 2); // IN
+  return Buffer.concat([
+    head,
+    ...labels.map((label) => {
+      const bytes = Buffer.from(label, "ascii");
+      return Buffer.concat([Buffer.from([bytes.length]), bytes]);
+    }),
+    Buffer.from([0]),
+    tail,
+  ]);
+}
+
+/**
+ * Is something serving DNS on this port?
+ *
+ * Any well-formed reply counts, including NXDOMAIN and SERVFAIL. The question
+ * is whether the resolver is up, and a bridge whose upstreams are unreachable
+ * is still a bridge that started — conflating the two would turn a bad network
+ * into a failed start.
+ */
+export function probeResolver({ host = "127.0.0.1", port, name = "a.eggs", timeoutMs = 500 } = {}) {
+  return new Promise((resolve) => {
+    const socket = dgram.createSocket("udp4");
+    const id = Math.floor(Math.random() * 65536);
+    let done = false;
+    const finish = (answered) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try {
+        socket.close();
+      } catch {
+        // Already closed by the error that brought us here.
+      }
+      resolve(answered);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    socket.once("error", () => finish(false));
+    socket.on("message", (msg) => finish(msg.length >= 2 && msg.readUInt16BE(0) === id));
+    socket.send(encodeQuery(name, id), port, host, (err) => {
+      if (err) finish(false);
+    });
+  });
+}
+
+async function readLogTail(path, lines = LOG_TAIL_LINES) {
+  const text = await readFile(path, "utf8").catch(() => "");
+  const trimmed = text.trimEnd();
+  return trimmed ? trimmed.split("\n").slice(-lines).join("\n") : "";
+}
+
+/**
+ * Start the bridge detached, so the shell that launched it can exit — and do
+ * not claim it started until it has proved it is there.
+ *
+ * The old version spawned with `stdio: "ignore"`, wrote the pidfile from
+ * `child.pid`, and returned `started: true` in the same tick. Both halves of
+ * that were wrong on any machine where the daemon dies on startup. `enable`
+ * printed `ok bridge started (pid N)` for a process that was already gone, then
+ * installed catch-all routing — `Domains=~.` — pointing every lookup on the box
+ * at a port with nothing behind it. The failure took the machine's whole
+ * resolver down and left no way to find out why, because the one stream the
+ * daemon wrote its reason to had been routed to /dev/null. A node that is not
+ * on root's PATH, a port it cannot bind, a half-written install: all of them
+ * arrived as the same confident success line.
+ *
+ * So: stdout and stderr go to a file, an early exit is a failed start that
+ * reports what the daemon said, and the pidfile is written only once the
+ * process is still there — never for one that is not, which is what made
+ * `daemonStatus` report a stale pid as a crash that had never happened.
+ *
+ * Still not a systemd unit / launchd job / Windows service, which means it does
  * not survive a reboot. `moshcode dns status` says so plainly rather than
  * letting someone discover it when their names stop resolving.
  */
-export async function startDaemon({ port, registryBase, path = pidfilePath(), entry, proxy = null }) {
+export async function startDaemon({
+  port,
+  registryBase,
+  path = pidfilePath(),
+  entry,
+  proxy = null,
+  host = "127.0.0.1",
+  logPath = null,
+  readyTimeoutMs = READY_TIMEOUT_MS,
+  probe = probeResolver,
+  sleep = defaultSleep,
+}) {
   const existing = await daemonStatus(path);
   if (existing.running) return { started: false, pid: existing.pid, alreadyRunning: true };
 
   await mkdir(dirname(path), { recursive: true });
+  const log = logPath || daemonLogPath(path);
   const args = [entry, "dns", "start", "--port", String(port)];
   if (registryBase) args.push("--registry", registryBase);
   // Passed at spawn time because it is what the resolver answers with, not
@@ -385,10 +501,64 @@ export async function startDaemon({ port, registryBase, path = pidfilePath(), en
   // short of restarting it, which is why `enable` decides this before starting.
   if (proxy) args.push("--proxy", proxy);
 
-  const child = spawn(process.execPath, args, { detached: true, stdio: "ignore" });
+  // Truncated rather than appended: the only question this file ever answers is
+  // "why did the run I just did fail", and a previous crash above this run's
+  // output is how that question gets answered wrong.
+  await writeFile(log, "");
+  const handle = await open(log, "a");
+  let child;
+  try {
+    child = spawn(process.execPath, args, { detached: true, stdio: ["ignore", handle.fd, handle.fd] });
+  } finally {
+    // The child holds its own duplicate of the descriptor from spawn onward.
+    await handle.close();
+  }
+
+  // `error` covers the spawn itself failing — execPath gone, not executable —
+  // which never reaches `exit` at all.
+  const died = new Promise((resolve) => {
+    child.once("error", (error) => resolve({ reason: error.message }));
+    child.once("exit", (code, signal) => resolve({
+      reason: signal ? `killed by ${signal}` : `exited ${code} before it could serve`,
+      code,
+      signal,
+    }));
+  });
+
+  let gone = null;
+  let verified = false;
+  const deadline = Date.now() + readyTimeoutMs;
+  while (Date.now() < deadline) {
+    gone = await Promise.race([died, sleep(POLL_MS).then(() => null)]);
+    if (gone) break;
+    if (await probe({ host, port })) {
+      verified = true;
+      break;
+    }
+  }
+
   child.unref();
+
+  if (gone) {
+    // No pidfile for a process that is not there. Writing one anyway is what
+    // made the next `enable` believe a bridge was running and skip starting one.
+    await rm(path, { force: true });
+    return {
+      started: false,
+      alreadyRunning: false,
+      pid: null,
+      error: gone.reason,
+      log: await readLogTail(log),
+      logPath: log,
+    };
+  }
+
   await writeFile(path, `${child.pid}\n`);
-  return { started: true, pid: child.pid, alreadyRunning: false };
+  // `verified: false` is a process that is alive but had not answered by the
+  // deadline — a slow registry fetch on a slow link, most often. Reported as
+  // what it is rather than rounded up to success or down to failure: killing a
+  // bridge that was merely still waking up would be the worse mistake.
+  return { started: true, pid: child.pid, alreadyRunning: false, verified, logPath: log };
 }
 
 export async function stopDaemon(path = pidfilePath()) {

package/src/dns.mjs

@@ -2892,11 +2892,43 @@ export async function dnsCommand(args = [], out = console.log, deps = {}) {
         // too rather than pinning the answer to one family.
         proxy: proxyAddress ? (proxyAddress.v4 || proxyAddress.v6) : null,
       });
+    // The routing this is about to install is catch-all — every lookup on the
+    // machine, not just Moshpit ones — so a bridge that did not come up is not
+    // a degraded feature, it is the machine's resolver pointed at nothing.
+    // Refused here, before the drop-in is written, because the alternative was
+    // discovering it from a box that could no longer resolve its own package
+    // mirror. Nothing has been changed at this point except the restore point,
+    // which is removed on the way out.
+    if (!started.reused && !started.alreadyRunning && !started.started) {
+      out(`  FAIL bridge did not start on ${DEFAULT_HOST}:${wanted} — ${started.error}`);
+      if (started.log) {
+        out("");
+        for (const line of started.log.split("\n")) out(`       ${line}`);
+      }
+      out("");
+      out("Refusing to route this machine's DNS at a bridge that is not running.");
+      out("Nothing has been changed.");
+      if (started.logPath) out(`  the daemon's output is at ${started.logPath}`);
+      out(`  to watch it start in the foreground:  moshcode dns start --port ${wanted}`);
+      if (recorded2.ok) await applyPlan({ steps: [{ kind: "remove", path: manifestFile, why: "the switch never happened" }] });
+      return 1;
+    }
     out(started.reused
       ? `  ok   using the bridge already on ${DEFAULT_HOST}:${wanted} (pid ${reusing.pid || "?"}) — not starting a second one`
       : started.alreadyRunning
         ? `  ok   bridge already running (pid ${started.pid})`
-        : `  ok   bridge started on ${DEFAULT_HOST}:${wanted} (pid ${started.pid})`);
+        : started.verified === true
+          ? `  ok   bridge started on ${DEFAULT_HOST}:${wanted} (pid ${started.pid}) — answering`
+          : `  ok   bridge started on ${DEFAULT_HOST}:${wanted} (pid ${started.pid})`);
+    // Alive, but it had not answered a query by the deadline. Said out loud
+    // rather than swallowed: if the routing below fails to verify, this line is
+    // the reason, and it is cheaper to read it here than to derive it later.
+    // Strictly `false`, never merely absent: a starter that does not report on
+    // verification has not failed it, and rounding the two together would print
+    // a warning about every bridge that was started by something else.
+    if (started.started && started.verified === false) {
+      out(`  --   it has not answered a query yet — still starting, or it will not serve`);
+    }
 
     const outcome = await applyWith(plan, {
       verify: () => verify({ moshpit: moshpitProbe }),

package/src/settings-sync.mjs

@@ -0,0 +1,659 @@
+// Cloud sync for the pit's own settings — `/save` and `/load`.
+//
+// The pit accumulates configuration the way a shell rc does: aliases you built
+// up over months, herd rules you tuned for your agents. All of it lives under
+// ~/.moshcode on one machine, which means a new laptop, a fresh container, or a
+// reinstall starts from nothing and the pit feels like someone else's.
+//
+// `/save` pushes that configuration to your app.moshcode.sh account and `/load`
+// brings it back down. Two verbs rather than a background daemon: settings are
+// edited by a person, at a moment they can name, and a sync that runs on its own
+// is a sync that overwrites something you meant to keep at a moment you can't.
+//
+// Three rules the rest of this file exists to enforce:
+//
+//   1. An allowlist, never a directory walk. ~/.moshcode also holds
+//      credentials.json — the API token this very feature authenticates with —
+//      plus live herd state and a package cache. A walk that gains a file gains
+//      it silently; an allowlist has to be edited on purpose, in a diff someone
+//      reviews. NEVER_SYNCED is asserted on top of it so the review can't slip.
+//   2. The allowlist is checked again on the way *in*. The response is data from
+//      the network, and a path in it is a path this process would write: without
+//      the second check a bad snapshot spells `../../.ssh/authorized_keys` and
+//      `/load` is a remote write primitive.
+//   3. A revision, and refusal. Two machines both saving means one of them
+//      loses; the pit says so and asks, rather than picking for you.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { loadCreds } from "./auth.mjs";
+import { engineStatus } from "./engines.mjs";
+import { toolStatus } from "./tools.mjs";
+import { ash, moshcodeVersion } from "./ui.mjs";
+
+/** The snapshot shape this build writes and is willing to read. */
+export const SNAPSHOT_VERSION = 1;
+
+/** Owner-only, like everything else moshcode keeps under ~/.moshcode. */
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+/**
+ * One file at a time, and the whole snapshot. Generous for configuration —
+ * aliases.json is a few hundred bytes — and small enough that a stray heredoc
+ * pasted into a config file can't push a megabyte into your account, or arrive
+ * from it.
+ */
+export const MAX_FILE_BYTES = 64 * 1024;
+export const MAX_TOTAL_BYTES = 256 * 1024;
+
+/**
+ * What syncs, keyed by its path relative to ~/.moshcode.
+ *
+ * `json: true` means the file is parsed before it is sent and again before it is
+ * written. A settings sync that faithfully copies a broken aliases.json to every
+ * machine you own has taken one dead prompt and made it four.
+ */
+export const SYNCED_FILES = [
+  { path: "aliases.json", json: true, label: "pit aliases" },
+  { path: "herd/rules.json", json: true, label: "herd state rules" },
+];
+
+/**
+ * Paths that must never appear in a snapshot, whichever direction it is moving.
+ *
+ * Redundant with the allowlist today, and deliberately so: this is the assertion
+ * that survives someone adding a convenient-looking entry above. `credentials.json`
+ * is the account token — syncing it to the account would hand every machine that
+ * ran `/load` a credential it was never issued. `herd/sessions.json` is live
+ * state pinned to one tmux server, `pkg/` is a binary cache, and `*.sock` /
+ * `*.pid` describe processes on exactly one box.
+ */
+export const NEVER_SYNCED = [
+  "credentials.json",
+  "sync.json",
+  "herd/sessions.json",
+  "herd/hook.json",
+];
+
+/** True for a path this build is willing to read or write. */
+export function isSyncable(relative) {
+  const name = String(relative ?? "");
+  if (NEVER_SYNCED.includes(name)) return false;
+  if (name.startsWith("pkg/")) return false;
+  return SYNCED_FILES.some((f) => f.path === name);
+}
+
+export function moshcodeDir(home = os.homedir()) {
+  return path.join(home, ".moshcode");
+}
+
+/**
+ * Where the last sync is remembered: the revision we agreed with the server and
+ * the digest of the files as they were at that moment.
+ *
+ * That digest is the whole mechanism behind "you have local changes". Without it
+ * `/load` can tell that local and remote differ but not *why* — and "differ" is
+ * both "someone else saved from another machine" and "you edited this file five
+ * minutes ago", which want opposite answers.
+ */
+export function markerPath(home = os.homedir()) {
+  return path.join(moshcodeDir(home), "sync.json");
+}
+
+export function loadMarker(home = os.homedir()) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(markerPath(home), "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch { return null; }
+}
+
+export function saveMarker(marker, home = os.homedir()) {
+  const file = markerPath(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: DIR_MODE });
+  fs.writeFileSync(file, `${JSON.stringify(marker, null, 2)}\n`, { mode: FILE_MODE });
+  try { fs.chmodSync(file, FILE_MODE); } catch { /* best effort */ }
+}
+
+/**
+ * The digest of a set of files, over their names and contents.
+ *
+ * Canonical by construction — names sorted, every field framed by a NUL and
+ * preceded by its byte length — so the same files digest the same on every
+ * machine regardless of the order they were read in, and no content can be
+ * arranged to look like a different file list. NUL rather than a space because a
+ * space appears in file contents and a NUL does not appear in text config at
+ * all.
+ *
+ * The app computes the same digest over the same bytes
+ * (apps/pwa/src/routes/settings-sync.mjs). Both sides pin the value for a fixed
+ * input in their tests, because two implementations of one hash that quietly
+ * disagree is a comparison that silently stops meaning anything.
+ */
+export function digestFiles(files) {
+  const hash = crypto.createHash("sha256");
+  for (const name of Object.keys(files).sort()) {
+    const content = String(files[name]?.content ?? "");
+    hash.update(`${name}\0${Buffer.byteLength(content)}\0${content}\0`);
+  }
+  return hash.digest("hex");
+}
+
+/** Engines and tools this machine has, by name. Informational, never applied. */
+function installedHere() {
+  const names = (rows) => rows.filter((r) => r.installed).map((r) => r.key).sort();
+  try {
+    return { engines: names(engineStatus()), tools: names(toolStatus()) };
+  } catch { return { engines: [], tools: [] }; }
+}
+
+/**
+ * Read the local settings into a snapshot.
+ *
+ * Returns `{ snapshot, included, skipped }`. A file that is missing is simply
+ * absent — most people have never written herd/rules.json — while one that is
+ * present and unusable (too big, not the JSON it claims to be) is reported so
+ * the reason is visible rather than looking like it synced.
+ */
+export function collectSnapshot({
+  home = os.homedir(),
+  hostname = os.hostname(),
+  version = moshcodeVersion(),
+  installed = installedHere(),
+} = {}) {
+  const dir = moshcodeDir(home);
+  const files = {};
+  const included = [];
+  const skipped = [];
+  let total = 0;
+
+  for (const entry of SYNCED_FILES) {
+    const file = path.join(dir, entry.path);
+    let content;
+    try { content = fs.readFileSync(file, "utf8"); }
+    catch { continue; } // not here — nothing to say about it
+    const bytes = Buffer.byteLength(content);
+    if (bytes > MAX_FILE_BYTES) {
+      skipped.push({ path: entry.path, reason: `${bytes} bytes — the cap is ${MAX_FILE_BYTES}` });
+      continue;
+    }
+    if (entry.json) {
+      try { JSON.parse(content); }
+      catch { skipped.push({ path: entry.path, reason: "not valid JSON — fix it locally first" }); continue; }
+    }
+    if (total + bytes > MAX_TOTAL_BYTES) {
+      skipped.push({ path: entry.path, reason: "the snapshot is already at its size cap" });
+      continue;
+    }
+    total += bytes;
+    files[entry.path] = { content };
+    included.push({ path: entry.path, bytes, label: entry.label });
+  }
+
+  const snapshot = {
+    version: SNAPSHOT_VERSION,
+    host: String(hostname || "").slice(0, 60) || null,
+    moshcode: version || null,
+    installed,
+    files,
+  };
+  return { snapshot, included, skipped };
+}
+
+/**
+ * Check a snapshot that came off the network before anything is written.
+ *
+ * Returns `{ ok, error, files, rejected }`. Rejection is per-file and reported
+ * rather than fatal: a newer moshcode that syncs one more file must not make
+ * `/load` unusable on this one, so an unknown name is dropped with its reason
+ * and the files this build does understand still land.
+ */
+export function validateSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+    return { ok: false, error: "the saved settings are not a snapshot", files: {}, rejected: [] };
+  }
+  if (Number(snapshot.version) > SNAPSHOT_VERSION) {
+    return {
+      ok: false,
+      files: {},
+      rejected: [],
+      error: `these settings were saved by a newer moshcode (snapshot v${snapshot.version}) — run \`moshcode upgrade\` first`,
+    };
+  }
+  const raw = snapshot.files;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, error: "the snapshot carries no files", files: {}, rejected: [] };
+  }
+
+  const files = {};
+  const rejected = [];
+  let total = 0;
+  for (const [name, value] of Object.entries(raw)) {
+    // Every reason a name can be refused, in one place. `isSyncable` is the
+    // allowlist; the checks around it catch the shapes that never reach it —
+    // an absolute path, a traversal, a non-string body.
+    if (typeof name !== "string" || !name || name !== path.posix.normalize(name)
+        || path.posix.isAbsolute(name) || name.includes("..") || name.includes("\\")) {
+      rejected.push({ path: String(name), reason: "not a settings path" });
+      continue;
+    }
+    if (!isSyncable(name)) { rejected.push({ path: name, reason: "this moshcode does not sync that file" }); continue; }
+    const content = value?.content;
+    if (typeof content !== "string") { rejected.push({ path: name, reason: "no contents" }); continue; }
+    const bytes = Buffer.byteLength(content);
+    if (bytes > MAX_FILE_BYTES) { rejected.push({ path: name, reason: `${bytes} bytes — the cap is ${MAX_FILE_BYTES}` }); continue; }
+    if (total + bytes > MAX_TOTAL_BYTES) { rejected.push({ path: name, reason: "past the snapshot size cap" }); continue; }
+    const entry = SYNCED_FILES.find((f) => f.path === name);
+    if (entry?.json) {
+      try { JSON.parse(content); }
+      catch { rejected.push({ path: name, reason: "not valid JSON — refusing to write it" }); continue; }
+    }
+    total += bytes;
+    files[name] = { content };
+  }
+  return { ok: true, error: null, files, rejected };
+}
+
+/**
+ * What `/load` would do, file by file: `new`, `changed` or `same`.
+ *
+ * Computed before anything is written so --dry-run and the real thing report the
+ * same plan, and so "nothing to do" is an answer rather than four no-op writes.
+ */
+export function planApply(files, { home = os.homedir() } = {}) {
+  const dir = moshcodeDir(home);
+  return Object.keys(files).sort().map((name) => {
+    let current = null;
+    try { current = fs.readFileSync(path.join(dir, name), "utf8"); } catch { /* absent */ }
+    const content = files[name].content;
+    return {
+      path: name,
+      action: current === null ? "new" : current === content ? "same" : "changed",
+      bytes: Buffer.byteLength(content),
+    };
+  });
+}
+
+/** Write the snapshot's files. Returns the plan, with `written` marked. */
+export function applyFiles(files, { home = os.homedir() } = {}) {
+  const dir = moshcodeDir(home);
+  const plan = planApply(files, { home });
+  for (const item of plan) {
+    if (item.action === "same") continue;
+    const file = path.join(dir, item.path);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: DIR_MODE });
+    // Written beside the target and renamed over it: a settings file truncated
+    // by a full disk halfway through a write is a prompt that no longer starts.
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, files[item.path].content, { mode: FILE_MODE });
+    fs.renameSync(temp, file);
+    try { fs.chmodSync(file, FILE_MODE); } catch { /* best effort */ }
+    item.written = true;
+  }
+  return plan;
+}
+
+/**
+ * Which local files have drifted from the last sync.
+ *
+ * Names, not a boolean, because that list is the message: "aliases.json changed
+ * since you last saved" is actionable and "local and remote differ" is not.
+ */
+export function localDrift({ home = os.homedir() } = {}) {
+  const marker = loadMarker(home);
+  const { snapshot } = collectSnapshot({ home, installed: { engines: [], tools: [] } });
+  const digest = digestFiles(snapshot.files);
+  if (!marker?.digest) return { known: false, drifted: true, digest, files: Object.keys(snapshot.files).sort() };
+  if (marker.digest === digest) return { known: true, drifted: false, digest, files: [] };
+  const before = marker.files && typeof marker.files === "object" ? marker.files : null;
+  const files = before
+    ? [...new Set([...Object.keys(before), ...Object.keys(snapshot.files)])]
+      .filter((name) => (before[name] ?? null) !== fileDigest(snapshot.files[name]))
+      .sort()
+    : Object.keys(snapshot.files).sort();
+  return { known: true, drifted: true, digest, files };
+}
+
+/** Per-file digest, so the marker can name which file moved rather than just that one did. */
+function fileDigest(entry) {
+  if (!entry || typeof entry.content !== "string") return null;
+  return crypto.createHash("sha256").update(entry.content).digest("hex");
+}
+
+/** The marker to write after a successful push or pull. */
+export function markerFor({ revision, digest, files, host = os.hostname(), api }) {
+  return {
+    revision: Number(revision),
+    digest,
+    at: Date.now(),
+    host: String(host || "").slice(0, 60) || null,
+    api: api || null,
+    files: Object.fromEntries(Object.keys(files).sort().map((name) => [name, fileDigest(files[name])])),
+  };
+}
+
+/* ------------------------------------------------------------------ transport */
+
+const DEFAULT_API = "https://app.moshcode.sh";
+
+function endpoint(creds) {
+  return (process.env.MOSHCODE_API || creds?.api || DEFAULT_API).replace(/\/+$/, "");
+}
+
+/**
+ * A request against the settings API, with every failure turned into a value.
+ *
+ * `{ ok, status, body, error }`. The callers here print a line and set an exit
+ * code; a thrown network error inside the pit's dispatch loop would take the
+ * prompt down instead, which is a lost session over a dropped wifi connection.
+ */
+async function request(method, route, { creds, body = null, fetchImpl = fetch, timeoutMs = 20_000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`${endpoint(creds)}${route}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${creds?.token}`,
+      },
+      body: body === null ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await res.text().catch(() => "");
+    let parsed = null;
+    try { parsed = text ? JSON.parse(text) : null; } catch { /* not JSON — reported as a status */ }
+    return { ok: res.ok, status: res.status, body: parsed, error: null };
+  } catch (e) {
+    const aborted = e?.name === "AbortError";
+    return { ok: false, status: 0, body: null, error: aborted ? "the app did not answer in time" : "could not reach the app" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export const pushSnapshot = (snapshot, { ifRevision = null, ...opts }) =>
+  request("PUT", "/api/settings", { ...opts, body: { snapshot, ifRevision } });
+
+export const pullSnapshot = (opts) => request("GET", "/api/settings", opts);
+
+export const listRevisions = (opts) => request("GET", "/api/settings/revisions", opts);
+
+/* ------------------------------------------------------------------- commands */
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+function whenever(at) {
+  const seconds = Math.max(0, Math.floor((Date.now() - Number(at)) / 1000));
+  if (!Number.isFinite(seconds)) return "at an unknown time";
+  if (seconds < 60) return `${seconds}s ago`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
+  return `${Math.floor(seconds / 86400)}d ago`;
+}
+
+/** The flags both verbs share, plus whatever the caller adds. */
+function parseFlags(argv, allowed) {
+  const flags = new Set();
+  const unknown = [];
+  for (const arg of argv) {
+    const name = String(arg);
+    if (allowed.includes(name)) flags.add(name);
+    else unknown.push(name);
+  }
+  return { flags, unknown };
+}
+
+const notLoggedIn = (write) => {
+  write("not logged in — run `/login` (or `moshcode login`) first");
+  write("   settings sync stores your configuration on your app.moshcode.sh account");
+};
+
+/**
+ * `/save` — push the local settings to the account.
+ *
+ * Returns an exit code, the convention every other command module here uses, so
+ * `moshcode save` in a script can be tested for having worked.
+ */
+export async function saveCommand(argv = [], {
+  home = os.homedir(),
+  creds = loadCreds(),
+  fetchImpl = fetch,
+  write = (line) => console.log(line),
+  hostname = os.hostname(),
+  version = moshcodeVersion(),
+  installed = installedHere(),
+} = {}) {
+  const { flags, unknown } = parseFlags(argv, ["--dry-run", "--force", "--json"]);
+  if (unknown.length) {
+    write(`unknown option ${unknown[0]} — usage: save [--dry-run] [--force] [--json]`);
+    return 1;
+  }
+  const json = flags.has("--json");
+  const emit = (value) => { write(JSON.stringify(value, null, 2)); };
+
+  const { snapshot, included, skipped } = collectSnapshot({ home, hostname, version, installed });
+  const digest = digestFiles(snapshot.files);
+
+  if (!included.length) {
+    if (json) emit({ status: "nothing_to_save", files: [], skipped });
+    else {
+      write("nothing to save yet — the pit has no settings on this machine");
+      write('   make one first: `/alias set gs "git status"`');
+      for (const s of skipped) write(`   skipped ${s.path} — ${s.reason}`);
+    }
+    return 0;
+  }
+
+  if (!creds?.token) {
+    if (json) emit({ status: "not_logged_in", files: included });
+    else notLoggedIn(write);
+    return 1;
+  }
+
+  const marker = loadMarker(home);
+  if (flags.has("--dry-run")) {
+    if (json) emit({ status: "dry_run", digest, revision: marker?.revision ?? null, files: included, skipped });
+    else {
+      write(`would save ${plural(included.length, "file")} to ${endpoint(creds)}:`);
+      for (const f of included) write(`   ${f.path}  ${ash(`${f.bytes}b · ${f.label}`)}`);
+      for (const s of skipped) write(`   skipped ${s.path} — ${s.reason}`);
+    }
+    return 0;
+  }
+
+  // "Nothing changed" is the account's answer, not this machine's guess. The app
+  // recognises a byte-identical snapshot and hands back the revision it already
+  // holds without inserting one, so an unchanged `/save` still costs no history —
+  // and a machine whose local marker has gone stale (someone deleted the saved
+  // settings from the web) finds out instead of insisting it is up to date.
+  const res = await pushSnapshot(snapshot, {
+    creds,
+    fetchImpl,
+    // The revision we last agreed on. The server refuses the write if it has
+    // moved on, which is the whole conflict story: another machine saved, and
+    // this push would erase it silently.
+    ifRevision: flags.has("--force") ? null : (Number.isFinite(Number(marker?.revision)) ? Number(marker.revision) : null),
+  });
+
+  if (res.status === 409) {
+    const theirs = res.body?.revision;
+    if (json) emit({ status: "conflict", revision: theirs ?? null, mine: marker?.revision ?? null });
+    else if (Number(theirs) === 0) {
+      // Not a race: the account's saved settings were deleted (the web page's
+      // "forget"), so there is nothing to lose and nothing to load.
+      write(`the account has no saved settings — this machine last saw revision ${marker?.revision ?? "none"}`);
+      write("   `/save --force` to save this machine's settings as the new revision 1");
+    } else {
+      write(`another machine saved first — the account is at revision ${theirs ?? "?"}, this one last saw ${marker?.revision ?? "none"}`);
+      write("   `/load` to take theirs, or `/save --force` to overwrite it with this machine's settings");
+    }
+    return 1;
+  }
+  if (res.status === 401) {
+    if (json) emit({ status: "expired" });
+    else write("the app rejected this machine's credentials — run `/login` again");
+    return 1;
+  }
+  if (!res.ok || !res.body?.revision) {
+    if (json) emit({ status: "failed", error: res.error, http: res.status || null });
+    else write(`could not save: ${res.error || `the app returned ${res.status}`}`);
+    return 1;
+  }
+
+  saveMarker(markerFor({
+    revision: res.body.revision,
+    digest,
+    files: snapshot.files,
+    host: hostname,
+    api: endpoint(creds),
+  }), home);
+
+  if (res.body.unchanged) {
+    if (json) emit({ status: "unchanged", revision: res.body.revision, digest, files: included, skipped });
+    else write(`already saved — revision ${res.body.revision} holds these exact files${res.body.savedAt ? `, from ${whenever(res.body.savedAt)}` : ""}`);
+    return 0;
+  }
+
+  if (json) {
+    emit({ status: "saved", revision: res.body.revision, digest, files: included, skipped });
+    return 0;
+  }
+  write(`saved ${plural(included.length, "file")} to ${creds.email || "your account"} ${ash(`(revision ${res.body.revision})`)}`);
+  for (const f of included) write(`   ${f.path}  ${ash(f.label)}`);
+  for (const s of skipped) write(`   skipped ${s.path} — ${s.reason}`);
+  write(ash("   on another machine: `/login` then `/load`"));
+  return 0;
+}
+
+/** `/load` — bring the account's settings down onto this machine. */
+export async function loadCommand(argv = [], {
+  home = os.homedir(),
+  creds = loadCreds(),
+  fetchImpl = fetch,
+  write = (line) => console.log(line),
+  hostname = os.hostname(),
+  installed = installedHere(),
+} = {}) {
+  const { flags, unknown } = parseFlags(argv, ["--dry-run", "--force", "--json"]);
+  if (unknown.length) {
+    write(`unknown option ${unknown[0]} — usage: load [--dry-run] [--force] [--json]`);
+    return 1;
+  }
+  const json = flags.has("--json");
+  const emit = (value) => { write(JSON.stringify(value, null, 2)); };
+
+  if (!creds?.token) {
+    if (json) emit({ status: "not_logged_in" });
+    else notLoggedIn(write);
+    return 1;
+  }
+
+  const res = await pullSnapshot({ creds, fetchImpl });
+  if (res.status === 404) {
+    if (json) emit({ status: "empty" });
+    else {
+      write("nothing saved to this account yet");
+      write("   run `/save` on the machine whose settings you want, then `/load` here");
+    }
+    return 1;
+  }
+  if (res.status === 401) {
+    if (json) emit({ status: "expired" });
+    else write("the app rejected this machine's credentials — run `/login` again");
+    return 1;
+  }
+  if (!res.ok) {
+    if (json) emit({ status: "failed", error: res.error, http: res.status || null });
+    else write(`could not load: ${res.error || `the app returned ${res.status}`}`);
+    return 1;
+  }
+
+  const { ok: valid, error, files, rejected } = validateSnapshot(res.body?.snapshot);
+  if (!valid) {
+    if (json) emit({ status: "invalid", error });
+    else write(`could not load: ${error}`);
+    return 1;
+  }
+  const plan = planApply(files, { home });
+  const changes = plan.filter((p) => p.action !== "same");
+  const revision = res.body?.revision ?? null;
+  const from = res.body?.snapshot?.host || res.body?.host || null;
+
+  // Local edits that were never saved. Overwriting them is exactly what `/load`
+  // is for on a fresh machine and exactly what it must not do on a working one,
+  // and only the person at the prompt knows which this is.
+  const drift = localDrift({ home });
+  const clobbers = drift.drifted
+    ? changes.filter((c) => c.action === "changed" && (!drift.known || drift.files.includes(c.path)))
+    : [];
+  if (clobbers.length && !flags.has("--force") && !flags.has("--dry-run")) {
+    if (json) emit({ status: "local_changes", revision, files: clobbers.map((c) => c.path) });
+    else {
+      write(`${plural(clobbers.length, "local file")} changed since this machine last synced:`);
+      for (const c of clobbers) write(`   ${c.path}`);
+      write("   `/save` to keep them, `/load --force` to replace them, `/load --dry-run` to see the difference");
+    }
+    return 1;
+  }
+
+  if (flags.has("--dry-run")) {
+    if (json) emit({ status: "dry_run", revision, from, plan, rejected });
+    else {
+      write(changes.length
+        ? `revision ${revision} from ${from || "another machine"} would change ${plural(changes.length, "file")}:`
+        : `revision ${revision} from ${from || "another machine"} matches this machine — nothing to do`);
+      for (const item of plan) write(`   ${item.action.padEnd(8)} ${item.path}`);
+      for (const r of rejected) write(`   ignored  ${r.path} — ${r.reason}`);
+      if (clobbers.length) {
+        write(`   ${plural(clobbers.length, "file")} would replace local changes — a plain \`/load\` will ask for --force`);
+      }
+    }
+    return 0;
+  }
+
+  if (!changes.length) {
+    // Still write the marker: the files match, so this machine *is* at that
+    // revision, and recording it is what lets the next `/save` push without
+    // being told it might be clobbering someone.
+    saveMarker(markerFor({ revision, digest: digestFiles(files), files, host: hostname, api: endpoint(creds) }), home);
+    if (json) emit({ status: "unchanged", revision, files: [] });
+    else write(`already at revision ${revision} — nothing to change`);
+    return 0;
+  }
+
+  let applied;
+  try { applied = applyFiles(files, { home }); }
+  catch (e) {
+    if (json) emit({ status: "failed", error: String(e.message || e) });
+    else write(`could not write the settings: ${String(e.message || e)}`);
+    return 1;
+  }
+
+  saveMarker(markerFor({ revision, digest: digestFiles(files), files, host: hostname, api: endpoint(creds) }), home);
+
+  const written = applied.filter((p) => p.written);
+  if (json) {
+    emit({ status: "loaded", revision, from, files: written.map((w) => w.path), rejected });
+    return 0;
+  }
+  write(`loaded revision ${revision}${from ? ` from ${from}` : ""} — ${plural(written.length, "file")} written`);
+  for (const item of written) write(`   ${item.action === "new" ? "added   " : "replaced"} ${item.path}`);
+  for (const r of rejected) write(`   ignored  ${r.path} — ${r.reason}`);
+
+  // Names only, and only the missing ones. The snapshot records what the source
+  // machine had installed because that is most of what makes a pit feel like
+  // yours — but installing an engine is a download and a shell script, so this
+  // is a sentence, not an action.
+  const theirs = res.body?.snapshot?.installed || {};
+  const missing = [
+    ...(theirs.engines || []).filter((n) => !(installed.engines || []).includes(n)),
+    ...(theirs.tools || []).filter((n) => !(installed.tools || []).includes(n)),
+  ];
+  if (missing.length) {
+    write(ash(`   that machine also had ${missing.join(", ")} — \`/install <name>\` to match it`));
+  }
+  return 0;
+}

package/src/tui.mjs

@@ -15,6 +15,7 @@ import { runUpgrade } from "./upgrade.mjs";
 import { locate, tilde } from "./pwd.mjs";
 import { createPrd, listPrds, authoringPrompt } from "./prd.mjs";
 import { loginAuto, whoami, logout } from "./auth.mjs";
+import { loadCommand, saveCommand } from "./settings-sync.mjs";
 import { createMirror, teeOutput } from "./mirror.mjs";
 import { fetchMotdAd } from "./ads.mjs";
 import { runScript } from "./runtime.mjs";
@@ -728,6 +729,10 @@ export async function tui() {
       continue;
     }
     if (cmd === "logout") { logout(); continue; }
+    // Settings sync. Never closes readline: both are one request and some
+    // printing, and the prompt is where you were about to type `/load` again.
+    if (cmd === "save") { await saveCommand(rest, { write: (l) => console.log(`  ${l}`) }); continue; }
+    if (cmd === "load") { await loadCommand(rest, { write: (l) => console.log(`  ${l}`) }); continue; }
     if (cmd === "run") {
       await runFile(rest);
       continue;