@jive-sh/skill-sync 0.1.2-latest-linux-arm64 → 0.1.2

package/src/daemons/skill-sync-daemon.ts

@@ -0,0 +1,104 @@
+import { watch } from "node:fs";
+import { existsSync } from "node:fs";
+import { exitWhenUninstalled } from "jive-abstract-library";
+import { loadConfig, loadState, saveState } from "../internal/config";
+import { notify } from "../internal/notify";
+import { syncOnce } from "../internal/sync";
+
+/**
+ * Keeps this machine's skills directory identical to every other machine's.
+ *
+ * Polls rather than subscribes: 30 seconds of latency on a file you edit a few times a day is not worth
+ * a durable connection, and a poll recovers from a dropped network by itself. A local change does not
+ * wait for the next poll — the watcher below brings the next cycle forward.
+ */
+
+const POLL_INTERVAL_MS = 30_000;
+/** Long enough that an editor's write-rename-write lands as one cycle, short enough to feel immediate. */
+const SETTLE_MS = 1_000;
+
+exitWhenUninstalled();
+
+const loaded = loadConfig();
+if (!loaded.ok) {
+  console.error(`skill-sync is not configured: ${loaded.reason}`);
+  // Zero, not one: the service manager restarts a daemon that fails, and retrying every few seconds
+  // against a config nobody has filled in yet would just fill the log.
+  process.exit(0);
+}
+const config = loaded.config;
+
+const state = loadState();
+let cycleQueued = false;
+let running = false;
+
+/**
+ * Conflicts already reported to the desktop.
+ *
+ * A conflict persists until a human resolves it, so every cycle keeps finding it — notifying each time
+ * would put a popup on screen twice a minute until they gave up and turned notifications off, which
+ * costs them the one notification that mattered. Only newly-conflicting paths are announced, and a path
+ * drops out of the set once it stops conflicting so a later recurrence is announced again.
+ *
+ * Held in memory, not in the state file: a restart re-announcing an unresolved conflict is correct.
+ */
+const announced = new Set<string>();
+
+function announceConflicts(conflicts: ReadonlyArray<string>): void {
+  for (const path of [...announced]) {
+    if (!conflicts.includes(path)) announced.delete(path);
+  }
+
+  const fresh = conflicts.filter((path) => !announced.has(path));
+  if (fresh.length === 0) return;
+  for (const path of fresh) announced.add(path);
+
+  notify(
+    "Skill sync conflict",
+    fresh.length === 1
+      ? `${fresh[0]} changed on two machines. Your version is saved as ${fresh[0]}.local`
+      : `${fresh.length} skills changed on two machines. Your versions are saved alongside them as .local`,
+  );
+}
+
+async function runCycle(): Promise<void> {
+  if (running) {
+    cycleQueued = true;
+    return;
+  }
+  running = true;
+  try {
+    const report = await syncOnce(config, state);
+    saveState(state);
+
+    for (const path of report.pulled) console.log(`pulled ${path}`);
+    for (const path of report.pushed) console.log(`pushed ${path}`);
+    for (const path of report.deletedLocally) console.log(`deleted ${path}`);
+    for (const path of report.conflicts) {
+      console.error(`conflict on ${path} — another machine changed it too; your copy is at ${path}.local`);
+    }
+    for (const path of report.rejected) console.error(`refused a path the server sent: ${path}`);
+    announceConflicts(report.conflicts);
+  } catch (cause) {
+    // One failed cycle must not end the daemon: the usual cause is the network, and the next poll retries.
+    console.error(`sync failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+  } finally {
+    running = false;
+    if (cycleQueued) {
+      cycleQueued = false;
+      setTimeout(runCycle, SETTLE_MS);
+    }
+  }
+}
+
+if (existsSync(config.skillsDir)) {
+  let settle: ReturnType<typeof setTimeout> | undefined;
+  watch(config.skillsDir, { recursive: true }, () => {
+    if (settle !== undefined) clearTimeout(settle);
+    settle = setTimeout(runCycle, SETTLE_MS);
+  });
+}
+
+console.log(`watching ${config.skillsDir}, syncing with ${config.endpoint} as ${config.machine}`);
+await runCycle();
+setInterval(runCycle, POLL_INTERVAL_MS);

package/src/entrypoints/skill-sync.ts

@@ -0,0 +1,140 @@
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { existsSync, rmSync, writeFileSync } from "node:fs";
+import { Command } from "commander";
+import { CONFIG_PATH, TOKEN_PATH, loadConfig, loadSettings, loadState, saveState } from "../internal/config";
+import { syncOnce } from "../internal/sync";
+
+/**
+ * The CLI that accompanies the daemon.
+ *
+ * The daemon never authenticates anyone — it reads a token the CLI left behind and nothing more. Signing
+ * in needs a browser and a person, which a process started at login has neither of, and a daemon that
+ * could prompt for credentials would be a daemon that prompts you at every login.
+ */
+
+const program = new Command("skill-sync")
+  .description("keep one skills directory identical across every machine you work on");
+
+program
+  .command("login")
+  .description("verify with your passkey in the browser and store this machine's sync token")
+  .action(async () => {
+    // A missing token is exactly what we are here to fix, so only the settings have to be usable.
+    const settings = loadSettings();
+    if (settings === undefined) {
+      console.error(`Fill in ${CONFIG_PATH} with an endpoint, a machine name and a skillsDir first.`);
+      process.exit(1);
+    }
+
+    const token = await captureToken(settings.endpoint, settings.machine);
+    writeFileSync(TOKEN_PATH, `${JSON.stringify({ token }, null, 2)}\n`, { mode: 0o600 });
+    console.log(`Signed in. Token saved to ${TOKEN_PATH}`);
+  });
+
+program
+  .command("logout")
+  .description("forget this machine's sync token")
+  .action(async () => {
+    const loaded = loadConfig();
+    if (loaded.ok) {
+      // Revoke first: if this fails, the token is still on disk and you can try again. Deleting it first
+      // would leave a live token on the server that nobody can revoke any more.
+      const response = await fetch(`${loaded.config.endpoint}/cli/token`, {
+        method: "DELETE",
+        headers: { authorization: `Bearer ${loaded.config.token}` },
+      });
+      console.log(response.ok ? "Revoked on the server." : `Server revoke failed (${response.status}).`);
+    }
+    rmSync(TOKEN_PATH, { force: true });
+    console.log(`Removed ${TOKEN_PATH}`);
+  });
+
+program
+  .command("status")
+  .description("show what this machine is configured to sync, and whether it can")
+  .action(async () => {
+    const loaded = loadConfig();
+    if (!loaded.ok) {
+      console.log(`Not ready: ${loaded.reason}`);
+      return;
+    }
+    const { endpoint, skillsDir, machine } = loaded.config;
+    console.log(`machine     ${machine}`);
+    console.log(`skills      ${skillsDir}${existsSync(skillsDir) ? "" : "  (does not exist)"}`);
+    console.log(`endpoint    ${endpoint}`);
+    console.log(`settings    ${CONFIG_PATH}`);
+    console.log(`cursor      ${loadState().cursor}`);
+
+    const response = await fetch(`${endpoint}/files?since=0`, {
+      headers: { authorization: `Bearer ${loaded.config.token}` },
+    });
+    console.log(response.ok
+      ? `server      reachable, ${((await response.json()) as { files: unknown[] }).files.length} file(s)`
+      : `server      ${response.status} ${response.statusText} — try \`skill-sync login\``);
+  });
+
+program
+  .command("sync")
+  .description("run one sync cycle now instead of waiting for the daemon")
+  .action(async () => {
+    const loaded = loadConfig();
+    if (!loaded.ok) {
+      console.error(`Not ready: ${loaded.reason}`);
+      process.exit(1);
+    }
+    const state = loadState();
+    const report = await syncOnce(loaded.config, state);
+    saveState(state);
+    for (const path of report.pulled) console.log(`pulled  ${path}`);
+    for (const path of report.pushed) console.log(`pushed  ${path}`);
+    for (const path of report.deletedLocally) console.log(`deleted ${path}`);
+    for (const path of report.conflicts) console.log(`CONFLICT ${path} — your copy is at ${path}.local`);
+    for (const path of report.rejected) console.log(`REJECTED ${path}`);
+    if (Object.values(report).every((list) => list.length === 0)) console.log("already in sync");
+  });
+
+program.parse();
+if (process.argv.length <= 2) program.help();
+
+/**
+ * Opens the browser at the service's login endpoint and waits for it to come back with a token.
+ *
+ * The browser does the authenticating, with a passkey for the service's domain; this only has to be
+ * listening when it finishes. The listener is bound to 127.0.0.1 so nothing off this machine can receive
+ * the redirect, and the port is whatever the OS hands out so two machines — or two attempts — never
+ * contend for one.
+ */
+async function captureToken(endpoint: string, machine: string): Promise<string> {
+  return await new Promise<string>((resolve, reject) => {
+    const server = createServer((request, response) => {
+      const token = new URL(request.url ?? "/", "http://127.0.0.1").searchParams.get("token");
+      response.writeHead(200, { "content-type": "text/html" });
+      response.end(token
+        ? "<p>Signed in. You can close this tab.</p>"
+        : "<p>No token in the redirect. Check the service logs.</p>");
+      server.close();
+      token ? resolve(token) : reject(new Error("the redirect carried no token"));
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const port = (server.address() as { port: number }).port;
+      const url = `${endpoint}/cli/login?port=${port}&machine=${encodeURIComponent(machine)}`;
+      console.log(`Opening ${url}`);
+      openBrowser(url);
+    });
+
+    setTimeout(() => {
+      server.close();
+      reject(new Error("timed out waiting for the browser"));
+    }, 180_000).unref();
+  });
+}
+
+function openBrowser(url: string): void {
+  const command = process.platform === "darwin" ? "open"
+    : process.platform === "win32" ? "cmd"
+    : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  spawn(command, args, { stdio: "ignore", detached: true }).unref();
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * What the service needs from this package.
+ *
+ * The daemon and CLI are the product; this entrypoint exists so the service can share the path rules
+ * and wire types rather than restate them. A rule restated is a rule that drifts, and these two are
+ * exactly the pair that must not: one validates what the other writes to disk.
+ */
+
+export { invalidPathReason, isValidPath } from "./internal/path";
+export type { ListFilesResponse, PutFileRequest, RemoteFile } from "./internal/wire";

package/src/internal/config.ts

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { join, relative, sep } from "node:path";
+
+/**
+ * Per-machine settings and sync state, both under `~/.jive/`.
+ *
+ * A file rather than environment variables: which directory holds this machine's skills, and which
+ * machine this is, differ per computer and have to survive a login, which is exactly what a config file
+ * is for and exactly what an environment variable is not.
+ */
+
+const JIVE_HOME = join(homedir(), ".jive");
+export const CONFIG_PATH = join(JIVE_HOME, "skill-sync.json");
+/**
+ * The token lives on its own, outside `~/.jive/`, because it is the one part that must not travel with
+ * the rest. Endpoint, machine name and skills directory are settings you could paste into a gist; this
+ * is a credential, and keeping it in a separate file makes "do not copy this one" a property of the
+ * filesystem rather than a thing you have to remember.
+ */
+export const TOKEN_PATH = join(homedir(), ".skill-sync-token.json");
+const STATE_PATH = join(JIVE_HOME, "skill-sync-state.json");
+
+/** Managed by Claude's own cloud sync; see `Config.exclude`. */
+const DEFAULT_EXCLUDE = ["synced"] as const;
+
+export interface Config {
+  readonly endpoint: string;
+  /**
+   * Top-level directory names under `skillsDir` to leave alone.
+   *
+   * `synced` holds the skills Claude already pulls from the cloud itself. Syncing them here would mean
+   * two systems writing the same files, each undoing the other, and none of them are yours to edit.
+   */
+  readonly exclude: ReadonlyArray<string>;
+  readonly token: string;
+  readonly skillsDir: string;
+  /** Names this machine in conflict messages, so "who overwrote this" has an answer. */
+  readonly machine: string;
+}
+
+/** Either the settings, or the one sentence telling the user what to go and fill in. */
+export type ConfigResult =
+  | { readonly ok: true; readonly config: Config }
+  | { readonly ok: false; readonly reason: string };
+
+export interface State {
+  /** Highest server sequence number already applied. */
+  cursor: number;
+  /** Last hash this machine agreed with the server on, per relative path. Absent means never synced. */
+  known: Record<string, string>;
+}
+
+/**
+ * The settings alone, with no token required.
+ *
+ * `login` needs these precisely when the token is missing, so it cannot go through `loadConfig` — that
+ * reports "not configured" for a missing token and would refuse to run the command that supplies one.
+ */
+export function loadSettings(): { endpoint: string; machine: string; skillsDir: string } | undefined {
+  loadConfig();
+  const settings = readJson<Partial<Config>>(CONFIG_PATH);
+  if (!settings.endpoint || !settings.machine || !settings.skillsDir) return undefined;
+  return { endpoint: settings.endpoint, machine: settings.machine, skillsDir: settings.skillsDir };
+}
+
+/** Reads both files, writing a template for whichever is missing, and says what is still needed. */
+export function loadConfig(): ConfigResult {
+  if (!existsSync(CONFIG_PATH)) {
+    mkdirSync(JIVE_HOME, { recursive: true });
+    writeFileSync(CONFIG_PATH, `${JSON.stringify({
+      endpoint: "https://skill-sync.jive.sh",
+      skillsDir: detectSkillsDir(),
+      machine: machineName(),
+      exclude: DEFAULT_EXCLUDE,
+    }, null, 2)}\n`);
+  }
+
+  if (!existsSync(TOKEN_PATH)) {
+    // 0600 from the moment it exists, rather than written open and tightened afterwards — there is no
+    // window in between for anything else on the machine to read it.
+    writeFileSync(TOKEN_PATH, `${JSON.stringify({ token: "" }, null, 2)}\n`, { mode: 0o600 });
+  }
+
+  const settings = readJson<Partial<Config>>(CONFIG_PATH);
+  const token = readJson<{ token?: string }>(TOKEN_PATH).token;
+
+  if (!settings.endpoint || !settings.skillsDir || !settings.machine) {
+    return { ok: false, reason: `${CONFIG_PATH} needs an endpoint, a skillsDir and a machine name` };
+  }
+  if (!token) {
+    return { ok: false, reason: `${TOKEN_PATH} needs the sync token` };
+  }
+  return { ok: true, config: { exclude: DEFAULT_EXCLUDE, ...settings, token } as Config };
+}
+
+function readJson<T>(path: string): T {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } catch {
+    return {} as T;
+  }
+}
+
+export function loadState(): State {
+  try {
+    return JSON.parse(readFileSync(STATE_PATH, "utf-8")) as State;
+  } catch {
+    return { cursor: 0, known: {} };
+  }
+}
+
+export function saveState(state: State): void {
+  mkdirSync(JIVE_HOME, { recursive: true });
+  writeFileSync(STATE_PATH, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+/** `HOSTNAME` is not set on macOS, so the template was writing "unknown" on exactly this machine. */
+function machineName(): string {
+  return hostname().replace(/\.local$/, "").replace(/[^A-Za-z0-9-]+/g, "-") || "unknown";
+}
+
+/**
+ * The skills directory this machine actually has, rather than the one it ought to have.
+ *
+ * Claude's home is not always `~/.claude` — an account with a suffixed home (`~/.claude-alex`) keeps its
+ * skills there, and writing the conventional path into the template just hands the user a wrong value to
+ * notice and correct. Pick the one that exists; fall back to the conventional path only if none does.
+ */
+function detectSkillsDir(): string {
+  const candidates = readdirSync(homedir())
+    .filter((entry) => entry === ".claude" || entry.startsWith(".claude-"))
+    .map((entry) => join(homedir(), entry, "skills"))
+    .filter((dir) => existsSync(dir))
+    .sort();
+  return candidates[0] ?? join(homedir(), ".claude", "skills");
+}
+
+export function hashBytes(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Suffix for the copy kept when an incoming change would have overwritten a local edit. */
+export const CONFLICT_SUFFIX = ".local";
+
+/**
+ * Every file under the skills directory, as paths relative to it with forward slashes.
+ *
+ * Normalised because the same skill synced from Windows and macOS must be one row, not two.
+ *
+ * Conflict copies are skipped. They are this machine's evidence of a collision, not content anyone else
+ * asked for, and syncing them spreads one machine's mess to every other machine.
+ */
+export function listLocalFiles(skillsDir: string, exclude: ReadonlyArray<string> = DEFAULT_EXCLUDE): string[] {
+  if (!existsSync(skillsDir)) return [];
+
+  const found: string[] = [];
+  const walk = (dir: string, top: boolean): void => {
+    for (const entry of readdirSync(dir)) {
+      if (entry.startsWith(".")) continue;
+      if (top && exclude.includes(entry)) continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full, false);
+      else if (!entry.endsWith(CONFLICT_SUFFIX)) found.push(relative(skillsDir, full).split(sep).join("/"));
+    }
+  };
+  walk(skillsDir, true);
+  return found.sort();
+}

package/src/internal/notify.ts

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+
+/**
+ * A desktop notification, best effort.
+ *
+ * Best effort is the whole contract: a daemon that cannot tell you about a conflict is worse than one
+ * that cannot sync, but a daemon that *dies* because a notification helper is missing is worse than
+ * both. Every failure here is swallowed.
+ *
+ * This works because these daemons are registered per-user and run inside the logged-in session — a
+ * LaunchAgent, a `systemctl --user` unit, a scheduled task. A system-wide service would have no desktop
+ * to post to.
+ */
+
+/** No shell anywhere below: the arguments carry file paths, and a path is not a safe thing to interpolate. */
+function run(command: string, args: ReadonlyArray<string>): void {
+  try {
+    spawn(command, [...args], { stdio: "ignore", detached: true }).unref();
+  } catch {
+    // Swallowed on purpose; see above.
+  }
+}
+
+export function notify(title: string, body: string): void {
+  switch (process.platform) {
+    case "darwin":
+      // AppleScript string literals take double quotes and backslashes as escapes, and nothing else.
+      return run("osascript", [
+        "-e",
+        `display notification "${escapeAppleScript(body)}" with title "${escapeAppleScript(title)}"`,
+      ]);
+    case "linux":
+      return run("notify-send", [title, body]);
+    case "win32":
+      return run("powershell", [
+        "-NoProfile", "-NonInteractive", "-Command",
+        "[reflection.assembly]::LoadWithPartialName('System.Windows.Forms') > $null;"
+        + "$n = New-Object System.Windows.Forms.NotifyIcon;"
+        + "$n.Icon = [System.Drawing.SystemIcons]::Warning; $n.Visible = $true;"
+        + `$n.ShowBalloonTip(10000, '${escapeSingleQuotes(title)}', '${escapeSingleQuotes(body)}', 'Warning')`,
+      ]);
+    default:
+      return;
+  }
+}
+
+function escapeAppleScript(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function escapeSingleQuotes(value: string): string {
+  return value.replace(/'/g, "''");
+}

package/src/internal/path.ts

@@ -0,0 +1,32 @@
+/**
+ * Validation for the one piece of untrusted input that becomes a filesystem path.
+ *
+ * Shared by the Worker and the daemon on purpose, and deliberately free of any Node import so the Worker
+ * can bundle it. Both ends check: the server so one compromised client cannot poison what every machine
+ * pulls, and the daemon because a server it does not control is not a thing to take paths from either.
+ *
+ * Without this, a pushed path of `../../.ssh/authorized_keys` is joined to the skills directory and
+ * written wherever the daemon's user can write.
+ */
+
+/** Long enough for any real nesting, short enough that nothing can be used to exhaust anything. */
+const MAX_LENGTH = 512;
+
+export function invalidPathReason(path: string): string | undefined {
+  if (path.length === 0 || path.length > MAX_LENGTH) return "path is empty or too long";
+  if (path.includes("\0")) return "path contains a null byte";
+  if (path.includes("\\")) return "path must use forward slashes";
+  if (path.startsWith("/")) return "path must be relative";
+  // A Windows drive letter is absolute on the machine that matters even though it has no leading slash.
+  if (/^[A-Za-z]:/.test(path)) return "path must be relative";
+
+  for (const segment of path.split("/")) {
+    if (segment === "") return "path has an empty segment";
+    if (segment === "." || segment === "..") return "path must not contain . or .. segments";
+  }
+  return undefined;
+}
+
+export function isValidPath(path: string): boolean {
+  return invalidPathReason(path) === undefined;
+}

package/src/internal/sync.ts

@@ -0,0 +1,165 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFLICT_SUFFIX, hashBytes, listLocalFiles, type Config, type State } from "./config";
+import { invalidPathReason } from "./path";
+
+/**
+ * One sync cycle: take everything the server has that we do not, then offer everything we have that it
+ * does not.
+ *
+ * Pull before push, deliberately. Pushing first would send a file the server already changed, get it
+ * refused, and report a conflict that pulling would have resolved on its own.
+ */
+
+interface RemoteFile {
+  readonly path: string;
+  readonly hash: string | null;
+  readonly deleted: boolean;
+  readonly updatedBy: string;
+}
+
+export interface Report {
+  readonly pulled: string[];
+  readonly pushed: string[];
+  readonly deletedLocally: string[];
+  readonly conflicts: string[];
+  /** Paths the server offered that this machine refused to write. */
+  readonly rejected: string[];
+}
+
+export async function syncOnce(config: Config, state: State): Promise<Report> {
+  const report: Report = { pulled: [], pushed: [], deletedLocally: [], conflicts: [], rejected: [] };
+  const present = new Set(listLocalFiles(config.skillsDir, config.exclude));
+
+  /**
+   * Files deleted here since the last cycle, worked out before anything is fetched.
+   *
+   * A push does not advance this machine's cursor, so the next pull sees its own earlier write as news.
+   * With the file now gone from disk that looked like "remote has it, we do not" and the pull put it
+   * straight back, undoing the delete every time. Deciding what was deleted up front, and refusing to
+   * recreate those paths, is what lets the push below turn them into tombstones.
+   */
+  const pendingDeletes = new Set(Object.keys(state.known).filter((path) => !present.has(path)));
+
+  // `present` is passed through both passes and kept current: the pull removes tombstoned files and adds
+  // new ones, and a push that read a stale snapshot would try to open a file the pull had just deleted.
+  await pull(config, state, report, pendingDeletes, present);
+  await push(config, state, report, present);
+  return report;
+}
+
+async function pull(
+  config: Config, state: State, report: Report, pendingDeletes: Set<string>, present: Set<string>,
+): Promise<void> {
+  const response = await call(config, `/files?since=${state.cursor}`);
+  const body = await response.json() as { cursor: number; files: RemoteFile[] };
+
+  for (const file of body.files) {
+    // The server is not trusted to supply a path either: one bad row would otherwise write outside the
+    // skills directory on every machine that syncs.
+    const badPath = invalidPathReason(file.path);
+    if (badPath) {
+      report.rejected.push(`${file.path} (${badPath})`);
+      continue;
+    }
+    const local = join(config.skillsDir, file.path);
+    // Deleted here and not yet reported; the push pass owns this path for the rest of the cycle.
+    if (pendingDeletes.has(file.path)) continue;
+
+    if (file.deleted) {
+      if (existsSync(local)) {
+        // Never destroy content this machine never agreed with the server on. A file written here that
+        // the server happens to have tombstoned — a fresh machine, or one that was offline through the
+        // delete — is not the same file, and deleting it silently would lose work nobody could recover.
+        const localHash = hashBytes(readFileSync(local));
+        if (localHash !== state.known[file.path]) {
+          writeFileSync(`${local}${CONFLICT_SUFFIX}`, readFileSync(local));
+          report.conflicts.push(file.path);
+        }
+        rmSync(local, { force: true });
+        report.deletedLocally.push(file.path);
+      }
+      present.delete(file.path);
+      delete state.known[file.path];
+      continue;
+    }
+
+    const localHash = existsSync(local) ? hashBytes(readFileSync(local)) : undefined;
+    if (localHash === file.hash) {
+      // Already identical — record agreement so the push pass does not treat it as a local edit.
+      state.known[file.path] = file.hash!;
+      continue;
+    }
+
+    // A local edit we have not pushed yet would be destroyed by overwriting. Keep it beside the incoming
+    // copy and let the push pass raise the conflict rather than deciding which one wins here.
+    if (localHash !== undefined && localHash !== state.known[file.path]) {
+      writeFileSync(`${local}${CONFLICT_SUFFIX}`, readFileSync(local));
+      report.conflicts.push(file.path);
+    }
+
+    const content = new Uint8Array(await (await call(config, `/content/${file.hash}`)).arrayBuffer());
+    mkdirSync(dirname(local), { recursive: true });
+    writeFileSync(local, content);
+    state.known[file.path] = file.hash!;
+    present.add(file.path);
+    report.pulled.push(file.path);
+  }
+
+  state.cursor = body.cursor;
+}
+
+async function push(config: Config, state: State, report: Report, present: Set<string>): Promise<void> {
+  for (const path of present) {
+    const bytes = readFileSync(join(config.skillsDir, path));
+    const hash = hashBytes(bytes);
+    if (state.known[path] === hash) continue;
+
+    const accepted = await put(config, {
+      path,
+      baseHash: state.known[path] ?? null,
+      hash,
+      content: Buffer.from(bytes).toString("base64"),
+    });
+    if (accepted) {
+      state.known[path] = hash;
+      report.pushed.push(path);
+    } else {
+      report.conflicts.push(path);
+    }
+  }
+
+  // A path we previously agreed on that is no longer on disk was deleted here, and the server needs the
+  // tombstone or the next machine to sync will upload it back.
+  for (const path of Object.keys(state.known)) {
+    if (present.has(path)) continue;
+    if (await put(config, { path, baseHash: state.known[path]!, hash: null, content: null })) {
+      delete state.known[path];
+      report.pushed.push(`${path} (deleted)`);
+    } else {
+      report.conflicts.push(path);
+    }
+  }
+}
+
+/** True when the server accepted the write; false means another machine got there first. */
+async function put(config: Config, body: {
+  path: string; baseHash: string | null; hash: string | null; content: string | null;
+}): Promise<boolean> {
+  const response = await fetch(`${config.endpoint}/files`, {
+    method: "PUT",
+    headers: { authorization: `Bearer ${config.token}`, "content-type": "application/json" },
+    body: JSON.stringify({ ...body, machine: config.machine }),
+  });
+  if (response.status === 409) return false;
+  if (!response.ok) throw new Error(`PUT /files ${body.path}: ${response.status} ${await response.text()}`);
+  return true;
+}
+
+async function call(config: Config, path: string): Promise<Response> {
+  const response = await fetch(`${config.endpoint}${path}`, {
+    headers: { authorization: `Bearer ${config.token}` },
+  });
+  if (!response.ok) throw new Error(`GET ${path}: ${response.status} ${await response.text()}`);
+  return response;
+}