@symbols-cli/cli 0.0.1

package/dist/sync/reconcile.js

@@ -0,0 +1,870 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// The sweep. **Reconcile is the guarantee; events are the optimisation.**
+//
+// Everything the watcher produces is a hint. This file is what makes the two
+// sides agree, and it must produce the same answer whether it was woken by an
+// event, by the 60s timer, or by `symbols sync` after three days offline.
+//
+// ## The order of operations is the safety property
+//
+// Read it as a gauntlet — each gate must pass before the next one is even
+// consulted, and every gate's failure mode is "do nothing", never "assume":
+//
+//   F1  the project root exists and is the directory we bound       (else OFFLINE)
+//   F4  the notebook answers and is ours                            (else OFFLINE)
+//   F3  no two server paths collide under casefold+NFC              (else FREEZE the pair)
+//       no server path escapes the root                             (else FREEZE the path)
+//       nothing local writes is in the diff at all                  (`isCliManaged`)
+//       the local scan, where a FAILED READ IS NOT AN ABSENCE       (else FREEZE the path)
+//   F2  the bulk-delete circuit breaker                             (else BLOCK all deletes)
+//       ...and only now, `decide()` per path.
+//   S2  the deny-list, enforced at `atomicWrite` — the only place server bytes
+//       reach the disk. It is a rule about WRITING, so it lives at the write.
+//
+// F1 and F4 both come before anything can produce a delete, and that ordering is
+// the whole point: an unplugged drive and a deleted notebook each look exactly
+// like "every file is gone" to a client that starts from the diff. The >20
+// breaker does not save you — it sees a mass delete that looks legitimate.
+//
+// ## Ported verbatim, each from an incident
+//
+//   * `content_hash` equality as the loop breaker, in BOTH directions — lives in
+//     `decide()` (`odin_notebook_writeback.rs:1603-1605`).
+//   * **Delete only on an affirmative "missing"** (`settle_vanish:513-519`). Here
+//     that is `scanLocal`: an `ENOENT` yields `local = null`, and ANY other error
+//     freezes the path instead. `PathStat::Error` kept the row; so do we.
+//   * `is_editor_temp` and `IGNORE_SEGMENTS` — `paths.ts`, applied in the local
+//     walk and again in the watcher.
+//   * The watcher starts BEFORE the initial materialize (`start():1746-1780`) —
+//     see `watch.ts`, which is the caller that sequences it.
+//
+// ## Atomic local writes
+//
+// Temp-file-then-rename, always, with `O_NOFOLLOW` on the temp file's DIRECTORY.
+// The apparent contradiction in the plan ("O_NOFOLLOW on the final open" reads as
+// write-in-place) resolves because `rename(2)` **does not follow a symlink at the
+// destination** — it replaces the link itself. So the final path is never opened
+// for writing at all, and the only handle we open with `O_NOFOLLOW` is the
+// directory the temp file goes into.
+//
+// Without this a `kill -9` mid-write leaves a truncated file, and a truncated
+// file has a hash that matches neither side — so the three-way table classifies
+// it as "edited locally" and FREEZES it as the winner. That is silent data loss
+// wearing a conflict's clothes, which is why the plan calls it out separately
+// from the security rules.
+import { promises as fs, constants as C } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, dirname, relative, sep } from "node:path";
+import { decide, baseAfter, baseAfterPush, deleteGuard, conflictSidecarPath, } from "./diff.js";
+import { shouldIgnore, resolveInRoot, isWritableTarget, assertNoSymlinkedParents, findCollisions, isCliManaged, safeDirname, dedupeDirnames, } from "./paths.js";
+import { snapshot, createFile, updateFile, deleteFile, MAX_FILE_BYTES, NotebookGoneError, CasConflictError, ProtectedFileError, RateLimitedError, TransportError, } from "./api.js";
+/** Absent, affirmatively. The ONLY value that may lead to a delete. */
+const ABSENT = { hash: null, size: 0, mtimeMs: 0, freeze: null, bytes: null };
+function sha256(buf) {
+    return createHash("sha256").update(buf).digest("hex");
+}
+/** Strict UTF-8. A lossy decode would re-encode to different bytes forever. */
+function decodeUtf8(buf) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(buf);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read one local path into a `LocalFile`.
+ *
+ * ⚠ THE PORTED RULE LIVES HERE. `ENOENT` — and only `ENOENT` — produces
+ * `hash: null`, which is what the three-way table needs before it will emit a
+ * delete. Every other error (`EACCES`, `EIO`, a dead network mount) produces a
+ * FROZEN path, exactly as `PathStat::Error` kept the row in `settle_vanish`
+ * (:513-519). A client that mapped "I could not read it" to "it is gone" would
+ * delete a user's files whenever a permission bit or a disk hiccup said so.
+ *
+ * ## The `(size, mtime)` fast path is what makes a 60s sweep affordable
+ *
+ * The container defaults its reconcile OFF because every settle was a `docker
+ * exec`. Locally the plan turns it ON by default, and the whole justification is
+ * that a no-op sweep of 5,000 files is **one `stat` each** — not 5,000 file
+ * reads. So when the ledger's cached `(size, mtimeMs)` still match, the cached
+ * hash is reused and the file is never opened.
+ *
+ * This is also why `ledger.ts` stores `mtime_ms` as REAL and has a test for the
+ * fractional round trip: truncating it to a whole second makes every sweep miss
+ * the cache and re-hash the entire project.
+ *
+ * On a cache hit `bytes` is `null` — the caller reads the file only when it
+ * actually needs the content, which is the push path and nothing else.
+ */
+async function statLocal(root, rel, cache) {
+    const abs = join(root, rel);
+    let st;
+    try {
+        st = await fs.lstat(abs);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return ABSENT;
+        return { ...ABSENT, freeze: `cannot stat '${rel}': ${code ?? String(err)}` };
+    }
+    if (st.isSymbolicLink()) {
+        // A symlink is not content we can round-trip: pushing it would upload the
+        // link target's bytes under the link's name, and pulling would replace the
+        // link with a regular file. Neither is what the user meant.
+        return { ...ABSENT, freeze: `'${rel}' is a symlink; not synced` };
+    }
+    if (st.isDirectory())
+        return ABSENT;
+    if (!st.isFile())
+        return { ...ABSENT, freeze: `'${rel}' is not a regular file` };
+    // ⚠ Strict equality on BOTH, and only when a hash was actually cached. A file
+    // rewritten with identical size within the same mtime tick is the known blind
+    // spot of every (size, mtime) cache; the 60s sweep does not close it, and the
+    // WATCHER is what does — an event marks the path dirty regardless of what stat
+    // says, and `syncProject` is called with it in `only`.
+    if (cache &&
+        cache.hash !== null &&
+        cache.size === st.size &&
+        cache.mtimeMs === st.mtimeMs) {
+        return { hash: cache.hash, size: st.size, mtimeMs: st.mtimeMs, freeze: null, bytes: null };
+    }
+    let bytes;
+    try {
+        bytes = await fs.readFile(abs);
+    }
+    catch (err) {
+        const code = err.code;
+        // A race with a delete IS an affirmative absence; anything else is not.
+        if (code === "ENOENT")
+            return ABSENT;
+        return { ...ABSENT, freeze: `cannot read '${rel}': ${code ?? String(err)}` };
+    }
+    const base = { size: st.size, mtimeMs: st.mtimeMs, bytes };
+    if (bytes.byteLength > MAX_FILE_BYTES) {
+        // Loud, not silent. This is precisely the container's worst property —
+        // `writeback_one:1563-1568` warns that such a file "lives only on the
+        // container" and then returns Ok(()), so weeks of plots and parquet exist
+        // nowhere else with nothing in the UI saying so. A frozen path shows up in
+        // `symbols status`.
+        return {
+            ...base,
+            hash: sha256(bytes),
+            freeze: `'${rel}' is ${bytes.byteLength} bytes, over the ${MAX_FILE_BYTES}-byte server limit — not synced`,
+        };
+    }
+    if (decodeUtf8(bytes) === null) {
+        // Mirrors `ReadResult::Binary` (:1557-1559), which skips deliberately —
+        // `project_files.content` is a TEXT column and cannot hold these bytes.
+        return { ...base, hash: sha256(bytes), freeze: `'${rel}' is not valid UTF-8 — not synced` };
+    }
+    return { ...base, hash: sha256(bytes), freeze: null };
+}
+/** Every syncable path under `root`, project-relative, POSIX-separated. */
+async function walk(root) {
+    const out = [];
+    const recurse = async (dir) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true, encoding: "utf8" });
+        }
+        catch {
+            // An unreadable directory is not an empty one. Skipping it means its
+            // files never appear as `local = null`, so they can never be deleted on
+            // the strength of a failure to read.
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(dir, e.name);
+            const rel = relative(root, abs).split(sep).join("/");
+            if (shouldIgnore(rel))
+                continue;
+            if (e.isDirectory())
+                await recurse(abs);
+            else if (e.isFile() || e.isSymbolicLink())
+                out.push(rel);
+        }
+    };
+    await recurse(root);
+    return out;
+}
+// ── the atomic writer ────────────────────────────────────────────────────────
+const O_DIRECTORY = C["O_DIRECTORY"] ?? 0;
+const O_NOFOLLOW = C["O_NOFOLLOW"] ?? 0;
+/**
+ * Write `content` to `<root>/<rel>` atomically, or refuse.
+ *
+ * Refuses on every class `paths.ts` names, then writes temp-and-renames. The
+ * caller must treat a `false` return as "the path is frozen", never as "the
+ * write failed, retry".
+ */
+export async function atomicWrite(root, rel, content) {
+    const resolved = resolveInRoot(root, rel);
+    if (!resolved.ok || !resolved.abs)
+        return { ok: false, reason: resolved.reason ?? "unsafe path" };
+    const writable = isWritableTarget(rel);
+    if (!writable.ok)
+        return { ok: false, reason: writable.reason ?? "refused by the deny-list" };
+    const abs = resolved.abs;
+    const dir = dirname(abs);
+    await fs.mkdir(dir, { recursive: true });
+    const parents = await assertNoSymlinkedParents(root, abs);
+    if (!parents.ok)
+        return { ok: false, reason: parents.reason ?? "symlinked parent" };
+    // O_NOFOLLOW ON THE DIRECTORY. Fails with ELOOP if `dir` is a symlink, which
+    // narrows the window `assertNoSymlinkedParents` (a lexical pass over lstat
+    // results) leaves open. Full TOCTOU-proofing is explicitly not required: the
+    // only process that can win that race is the same-uid agent, which can write
+    // anywhere directly. The parties this defends against are the server and
+    // imported content.
+    let dirFd = null;
+    try {
+        dirFd = await fs.open(dir, C.O_RDONLY | O_DIRECTORY | O_NOFOLLOW);
+        const viaFd = await dirFd.stat();
+        const viaPath = await fs.lstat(dir);
+        if (viaFd.dev !== viaPath.dev || viaFd.ino !== viaPath.ino) {
+            return { ok: false, reason: `'${dir}' changed identity mid-write` };
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        return { ok: false, reason: `cannot open '${dir}' safely (${code ?? String(err)})` };
+    }
+    finally {
+        await dirFd?.close().catch(() => { });
+    }
+    // A distinctive prefix so a crashed run's leftovers are identifiable, and so
+    // `shouldIgnore` has something to match if one is ever left behind.
+    const tmp = join(dir, `.symbols-tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    let handle = null;
+    try {
+        // O_EXCL means this cannot land on an existing symlink; O_NOFOLLOW is belt
+        // and braces for the same.
+        handle = await fs.open(tmp, C.O_WRONLY | C.O_CREAT | C.O_EXCL | O_NOFOLLOW, 0o644);
+        await handle.writeFile(content, "utf8");
+        // Durability before the rename. Without it a power loss can expose the
+        // renamed name with unflushed (zero-length) content — the "never a prefix"
+        // property the kill-9 row asserts.
+        await handle.sync();
+    }
+    catch (err) {
+        await handle?.close().catch(() => { });
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        return { ok: false, reason: `write failed: ${err.message}` };
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+    try {
+        // ⚠ `rename(2)` REPLACES A SYMLINK AT THE DESTINATION rather than following
+        // it, so even a hostile `<root>/notes.md -> /etc/passwd` is overwritten as a
+        // link, not written through. That is why the final path is never opened.
+        await fs.rename(tmp, abs);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        return { ok: false, reason: `rename failed: ${err.message}` };
+    }
+    return { ok: true };
+}
+// ── the sweep ────────────────────────────────────────────────────────────────
+function offline(project, reason) {
+    return {
+        project: project.name,
+        offline: true,
+        offlineReason: reason,
+        pulled: 0,
+        pushed: 0,
+        localDeletes: 0,
+        serverDeletes: 0,
+        conflicts: 0,
+        frozen: [],
+        apiWrites: 0,
+        deletesBlocked: null,
+    };
+}
+/**
+ * F1 — the project-root existence gate.
+ *
+ * An absent root means the project is OFFLINE, not emptied. This is the guard
+ * that stops an unplugged external drive or an evicted iCloud folder from wiping
+ * an account, and it has to run before the diff because the diff cannot tell the
+ * difference: "no local files" is what both look like.
+ *
+ * The inode check is the second half. `project.json` is agent-writable and
+ * Finder-copyable, so a directory that exists at the bound path is not
+ * necessarily the directory we bound.
+ */
+export async function rootGate(project) {
+    let st;
+    try {
+        st = await fs.lstat(project.root);
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "ENOENT"
+            ? `project directory ${project.root} is not present — treating the project as OFFLINE. ` +
+                `No file was deleted. If you moved it, run \`symbols project detach\` and \`symbols up\` there.`
+            : `project directory ${project.root} is unreadable (${code ?? "unknown error"}) — treating the project as OFFLINE`;
+    }
+    if (!st.isDirectory()) {
+        return `${project.root} is not a directory — treating the project as OFFLINE`;
+    }
+    if (project.inode !== null && (st.ino !== project.inode || st.dev !== project.deviceNo)) {
+        return (`${project.root} is a DIFFERENT directory than the one bound to this notebook ` +
+            `(inode ${st.ino} vs ${project.inode}). Sync is frozen rather than guessing which is real — ` +
+            `run \`symbols project detach\` if you replaced it deliberately.`);
+    }
+    return null;
+}
+export async function syncProject(opts) {
+    const { ledger, project } = opts;
+    const log = opts.log ?? (() => { });
+    const root = project.root;
+    // ── F1 ─────────────────────────────────────────────────────────────────────
+    if (project.frozenReason)
+        return offline(project, project.frozenReason);
+    const rootProblem = await rootGate(project);
+    if (rootProblem) {
+        ledger.freezeProject(project.id, rootProblem);
+        return offline(project, rootProblem);
+    }
+    // ── F4 ─────────────────────────────────────────────────────────────────────
+    //
+    // A notebook 404 or ownership failure reads NAIVELY as "all files missing",
+    // and the >20 circuit breaker is blind to it — it sees a mass delete that
+    // looks like a legitimate cleanup. So it never reaches the breaker: the
+    // project freezes offline and zero deletes are computed.
+    let server;
+    try {
+        server = await snapshot(project.notebookId);
+    }
+    catch (err) {
+        if (err instanceof NotebookGoneError) {
+            const reason = err.message;
+            ledger.freezeProject(project.id, reason);
+            return offline(project, reason);
+        }
+        if (err instanceof RateLimitedError) {
+            return offline(project, `${err.message} — no files were touched`);
+        }
+        if (err instanceof TransportError) {
+            // A failed read is never an absence. Same rule, one layer up.
+            return offline(project, `could not reach the server (${err.status}) — no files were touched`);
+        }
+        return offline(project, `could not reach the server: ${err.message}`);
+    }
+    // A project that WAS frozen and now answers is unfrozen — otherwise a
+    // transient 404 would strand the project forever.
+    ledger.unfreezeProject(project.id);
+    const serverByPath = new Map();
+    for (const f of server.files)
+        serverByPath.set(f.path, f);
+    const localPaths = await walk(root);
+    const ledgerRows = ledger.files(project.id);
+    const universe = new Set([
+        ...serverByPath.keys(),
+        ...localPaths,
+        ...ledgerRows.map((r) => r.path),
+    ]);
+    const frozen = [];
+    const freeze = (path, reason) => {
+        frozen.push({ path, reason });
+        if (!opts.dryRun)
+            ledger.freezeFile(project.id, path, reason);
+    };
+    // ── F3 ─────────────────────────────────────────────────────────────────────
+    //
+    // Postgres holds `A.py` and `a.py` as two rows; default APFS collapses them to
+    // one file, and the survivor's content is then pushed back to BOTH rows. No
+    // delete is produced, so the circuit breaker never sees it. Freeze the group;
+    // never pick a winner.
+    const collisions = findCollisions([...universe]);
+    const collided = new Set();
+    for (const c of collisions) {
+        for (const p of c.paths) {
+            collided.add(p);
+            freeze(p, `collides with ${c.paths.filter((o) => o !== p).join(", ")} on this filesystem ` +
+                `(case/Unicode-insensitive). Both are frozen; rename one on the server to resolve.`);
+        }
+    }
+    // A watcher batch narrows what we ACT on; it never narrows the guards above,
+    // which all need the whole picture to be meaningful.
+    const scope = opts.only ? new Set(opts.only) : null;
+    const planned = [];
+    let localDeleteCount = 0;
+    let serverDeleteCount = 0;
+    for (const path of universe) {
+        if (collided.has(path))
+            continue;
+        if (shouldIgnore(path))
+            continue;
+        // ── escape ─────────────────────────────────────────────────────────────
+        //
+        // Purely lexical, so it is cheap enough to run on every path of a 5,000-file
+        // project. A server path that escapes the root can never be acted on in
+        // either direction.
+        const resolved = resolveInRoot(root, path);
+        if (!resolved.ok) {
+            freeze(path, `refused: ${resolved.reason}`);
+            continue;
+        }
+        // ── files we own ───────────────────────────────────────────────────────
+        //
+        // ⚠ THE S2 DENY-LIST IS NOT APPLIED HERE, DELIBERATELY. It is a rule about
+        // WRITING server content, and it is enforced where that happens
+        // (`atomicWrite`). Running it over the whole universe froze `Makefile`,
+        // `package.json` and `conftest.py` — the user's OWN project files — so they
+        // could never be pushed, and froze `<root>/.symbols/project.json`, a file
+        // this CLI writes itself, on every sweep of every project.
+        //
+        // `isCliManaged` is the right question for this loop: files something local
+        // writes are excluded from the diff in both directions. A SERVER row at one
+        // of those paths is still surfaced — the plan's answer to its own
+        // "`CLAUDE.md` is also a legal `project_files` row" gap.
+        if (isCliManaged(path)) {
+            if (serverByPath.has(path)) {
+                freeze(path, `the server has a file at '${path}', which this CLI manages locally. It is NOT ` +
+                    `written to disk (it would become configuration a tool executes) and the local ` +
+                    `copy is NOT pushed. Rename the server row to sync it.`);
+            }
+            continue;
+        }
+        const row = ledgerRows.find((r) => r.path === path);
+        const srv = serverByPath.get(path);
+        // The ledger's cache. ⚠ Only the FIRST stat of a path may use it — the
+        // re-reads below (after a write, before a delete) exist precisely to learn
+        // what changed, and handing them a cache would answer with what we already
+        // believed.
+        const local = await statLocal(root, path, row ? { size: row.size, mtimeMs: row.mtimeMs, hash: row.localHash } : undefined);
+        if (local.freeze) {
+            freeze(path, local.freeze);
+            continue;
+        }
+        const base = row ? row.base : null;
+        const action = decide({ path, server: srv?.contentHash ?? null, local: local.hash, base });
+        if (action.kind === "pull-delete")
+            localDeleteCount += 1;
+        if (action.kind === "push-delete")
+            serverDeleteCount += 1;
+        if (scope && !scope.has(path))
+            continue;
+        planned.push({
+            path,
+            action,
+            local,
+            server: srv,
+            base,
+            wasFrozen: row?.frozenReason != null,
+        });
+    }
+    // ── F2 ─────────────────────────────────────────────────────────────────────
+    //
+    // Counted over the WHOLE project, not the scoped subset — a watcher batch that
+    // happens to contain 19 deletes must not slip under a limit the full picture
+    // would fail. `rm -rf`, a bad `git clean`, and a real cleanup are
+    // indistinguishable from here.
+    const guard = deleteGuard({
+        totalTracked: universe.size,
+        deletions: localDeleteCount + serverDeleteCount,
+        confirmed: opts.confirmDeletes ?? false,
+    });
+    let pulled = 0;
+    let pushed = 0;
+    let localDeletes = 0;
+    let serverDeletes = 0;
+    let conflicts = 0;
+    let apiWrites = 0;
+    for (const p of planned) {
+        const { path, action, local, server: srv } = p;
+        const abs = join(root, path);
+        if ((action.kind === "pull-delete" || action.kind === "push-delete") && !guard.allowed) {
+            freeze(path, `delete withheld: ${guard.reason}`);
+            continue;
+        }
+        switch (action.kind) {
+            case "none": {
+                // ⚠ THE LOOP BREAKER'S OTHER HALF. `S === L` means nothing to transfer,
+                // but B may still disagree (a crash lost the confirm, or the same edit
+                // was made on both sides). Advancing B here is the repair, and it is
+                // what makes a second sweep issue ZERO API writes.
+                if (!opts.dryRun && local.hash !== null && p.base !== local.hash) {
+                    ledger.confirm({
+                        projectId: project.id,
+                        path,
+                        base: local.hash,
+                        fileId: srv?.id ?? null,
+                        size: local.size,
+                        mtimeMs: local.mtimeMs,
+                        localHash: local.hash,
+                    });
+                }
+                // ⚠ AND THE FREEZE CLEARS HERE. Without this a conflict is PERMANENT:
+                // the user merges the two copies, both sides agree, and `symbols status`
+                // still reports the path as frozen forever. A status that never goes
+                // green is a status nobody reads.
+                //
+                // This is also why a frozen path is re-decided on every sweep rather
+                // than skipped — skipping it would mean nothing ever notices that it
+                // was resolved. Re-deciding costs one hash and issues no writes, because
+                // an unresolved conflict returns `conflict` again and a resolved one
+                // returns `none`.
+                if (!opts.dryRun && p.wasFrozen)
+                    ledger.unfreezeFile(project.id, path);
+                break;
+            }
+            case "pull": {
+                if (!srv)
+                    break;
+                if (srv.skipped || srv.content === null) {
+                    // We know it changed (the hash says so) and we cannot fetch it. Say so
+                    // rather than skipping forever, which is the failure `skipped`'s hash
+                    // was added to make visible in the first place.
+                    freeze(path, `server copy is ${srv.size ?? "?"} bytes, over the ${MAX_FILE_BYTES}-byte transfer limit — not pulled`);
+                    break;
+                }
+                if (opts.dryRun) {
+                    pulled += 1;
+                    break;
+                }
+                const w = await atomicWrite(root, path, srv.content);
+                if (!w.ok) {
+                    freeze(path, w.reason);
+                    break;
+                }
+                pulled += 1;
+                // Re-read AFTER the write. If something moved under us the write is
+                // still on disk, but B must not record a state we cannot vouch for.
+                const after = await statLocal(root, path);
+                const next = baseAfter({
+                    hashAtDecision: srv.contentHash,
+                    hashAfter: after.hash,
+                    confirmed: true,
+                });
+                if (next !== "hold") {
+                    ledger.confirm({
+                        projectId: project.id,
+                        path,
+                        base: next,
+                        fileId: srv.id,
+                        size: after.size,
+                        mtimeMs: after.mtimeMs,
+                        localHash: after.hash,
+                    });
+                }
+                break;
+            }
+            case "push": {
+                if (local.hash === null)
+                    break;
+                // ⚠ `bytes` is null on a `(size, mtime)` CACHE HIT — the fast path never
+                // opened the file. A push is the one action that needs the content, so
+                // this is where it is read, and it is re-verified against the hash we
+                // decided on: if the file moved between the stat and this read, pushing
+                // the new bytes under the old hash's decision would send content the
+                // diff never saw.
+                let bytes = local.bytes;
+                if (bytes === null) {
+                    // The seam sits BEFORE the read: the guard's whole subject is bytes
+                    // that moved between the scan and this read, so a hook firing after
+                    // the read cannot express the race at all.
+                    await opts.raceHook?.("before-push", path);
+                    try {
+                        bytes = await fs.readFile(join(root, path));
+                    }
+                    catch (err) {
+                        freeze(path, `cannot read '${path}' to push it: ${err.message}`);
+                        break;
+                    }
+                    if (sha256(bytes) !== local.hash) {
+                        log(`  ~ ${path} changed between the scan and the push — re-diffing next sweep`);
+                        break;
+                    }
+                }
+                const text = decodeUtf8(bytes);
+                if (text === null) {
+                    freeze(path, `'${path}' is not valid UTF-8 — not synced`);
+                    break;
+                }
+                if (opts.dryRun) {
+                    pushed += 1;
+                    break;
+                }
+                let fileId = srv?.id ?? null;
+                try {
+                    if (fileId === null) {
+                        const created = await createFile(project.notebookId, path, text);
+                        fileId = created.id;
+                    }
+                    else {
+                        // ⚠ CAS ON EVERY PUSH. The base is what the SERVER had when we
+                        // diffed, not our ledger base — those differ exactly when the server
+                        // moved, which is the case the CAS exists to catch.
+                        await updateFile(fileId, text, srv?.contentHash ?? null);
+                    }
+                    apiWrites += 1;
+                }
+                catch (err) {
+                    if (err instanceof CasConflictError) {
+                        // The server moved between our read and our write. Do NOT retry: the
+                        // next sweep re-diffs with fresh hashes and will produce a proper
+                        // conflict if both sides really moved.
+                        freeze(path, `server copy changed mid-push — will re-diff next sweep`);
+                        break;
+                    }
+                    if (err instanceof ProtectedFileError) {
+                        freeze(path, err.message);
+                        break;
+                    }
+                    if (err instanceof RateLimitedError) {
+                        freeze(path, err.message);
+                        break;
+                    }
+                    freeze(path, `push failed: ${err.message}`);
+                    break;
+                }
+                pushed += 1;
+                // ⚠ RE-READ L AFTER THE WRITE, and record what the SERVER confirmed.
+                //
+                // `baseAfterPush` — not `baseAfter` — because the two answer different
+                // questions and the pull rule produces a spurious conflict here. The
+                // server acknowledged `local.hash`, so `B` is that, whatever the local
+                // file did during the request. If it moved, the next sweep sees
+                // `S == B != L` and pushes again, which is the plan's stated outcome.
+                const after = await statLocal(root, path);
+                const next = baseAfterPush({ hashAtDecision: local.hash, confirmed: true });
+                if (next !== "hold") {
+                    ledger.confirm({
+                        projectId: project.id,
+                        path,
+                        base: next,
+                        fileId,
+                        size: after.size,
+                        mtimeMs: after.mtimeMs,
+                        localHash: after.hash,
+                    });
+                }
+                if (after.hash !== local.hash) {
+                    log(`  ~ ${path} changed while pushing — it will be pushed again next sweep`);
+                }
+                break;
+            }
+            case "pull-delete": {
+                if (opts.dryRun) {
+                    localDeletes += 1;
+                    break;
+                }
+                // Re-stat immediately before unlinking. Between the plan and here the
+                // user may have re-created the file, and deleting it then would destroy
+                // work that never entered the diff.
+                await opts.raceHook?.("before-unlink", path);
+                const now = await statLocal(root, path);
+                if (now.hash !== local.hash) {
+                    log(`  ~ ${path} changed since it was planned for deletion — skipped`);
+                    break;
+                }
+                try {
+                    await fs.rm(abs, { force: true });
+                }
+                catch (err) {
+                    freeze(path, `could not delete '${path}': ${err.message}`);
+                    break;
+                }
+                ledger.tombstone(project.id, path);
+                localDeletes += 1;
+                break;
+            }
+            case "push-delete": {
+                if (!srv) {
+                    // No row to delete: it is already gone server-side. Tombstone so the
+                    // path is not re-pulled — "no row" and "confirmed deleted" are
+                    // different states, and only the second one stays deleted.
+                    if (!opts.dryRun)
+                        ledger.tombstone(project.id, path);
+                    break;
+                }
+                if (opts.dryRun) {
+                    serverDeletes += 1;
+                    break;
+                }
+                try {
+                    await deleteFile(srv.id);
+                    apiWrites += 1;
+                }
+                catch (err) {
+                    if (err instanceof ProtectedFileError) {
+                        // The file backs a live regime or widget. RESTORE the local copy —
+                        // the user's delete cannot be honoured and leaving the local side
+                        // missing would silently diverge from a server that still has it.
+                        if (srv.content !== null) {
+                            const w = await atomicWrite(root, path, srv.content);
+                            if (w.ok)
+                                log(`  + ${path} restored (${err.message})`);
+                        }
+                        freeze(path, err.message);
+                        break;
+                    }
+                    freeze(path, `server delete failed: ${err.message}`);
+                    break;
+                }
+                ledger.tombstone(project.id, path);
+                serverDeletes += 1;
+                break;
+            }
+            case "conflict": {
+                conflicts += 1;
+                // KEEP LOCAL. Write the server copy BESIDE it and freeze the path. Never
+                // last-writer-wins: on a laptop "offline three days" is normal, and LWW
+                // there silently eats three days of work.
+                const sidecar = conflictSidecarPath(path);
+                let sidecarNote = ` Your file is untouched; the server copy is at ${sidecar}.`;
+                if (!opts.dryRun && srv?.content != null) {
+                    const w = await atomicWrite(root, sidecar, srv.content);
+                    if (!w.ok) {
+                        // ⚠ A FAILED SIDECAR WRITE MUST CHANGE THE MESSAGE, not just log.
+                        //
+                        // An earlier version logged and froze with the standard text — so on
+                        // a full disk, or a permission problem, the user was told "the server
+                        // copy is at f.server.py" about a file that had never been written.
+                        // Sending someone to a path that does not exist during a conflict is
+                        // worse than saying nothing, and the soak surfaced it (the log
+                        // callback is optional, so on most callers it went nowhere at all).
+                        sidecarNote =
+                            ` Your file is untouched, but the server copy could NOT be written to ` +
+                                `${sidecar} (${w.reason}) — it is still on the server.`;
+                        log(`  ! could not write ${sidecar}: ${w.reason}`);
+                    }
+                }
+                else if (srv?.content == null) {
+                    sidecarNote =
+                        ` Your file is untouched. The server copy was not written beside it ` +
+                            `(its content is not available — it may be over the size limit).`;
+                }
+                freeze(path, `${action.reason}.${sidecarNote} Resolve, then \`symbols sync\`.`);
+                break;
+            }
+            case "freeze": {
+                freeze(path, action.reason);
+                break;
+            }
+        }
+    }
+    return {
+        project: project.name,
+        offline: false,
+        offlineReason: null,
+        pulled,
+        pushed,
+        localDeletes,
+        serverDeletes,
+        conflicts,
+        frozen,
+        apiWrites,
+        deletesBlocked: guard.allowed ? null : (guard.reason ?? "deletes withheld"),
+    };
+}
+/** `<root>/.symbols/project.json` — the identity anchor. */
+export function projectJsonPath(root) {
+    return join(root, ".symbols", "project.json");
+}
+/**
+ * Create/bind the local directory for every notebook the server lists.
+ *
+ * The local analogue of `materialize_all`, minus the content — the sweep pulls
+ * that. Three decisions here are load-bearing:
+ *
+ * **1. The DIRNAME COMES FROM THE SERVER, always.** `safeDirname` and
+ * `dedupeDirnames` exist in `paths.ts` to VERIFY that answer, not to replace it.
+ * Two clients that disagree by one character produce two directories for one
+ * notebook, each with its own watcher, each pushing over the other. A mismatch is
+ * reported, never acted on.
+ *
+ * **2. AN EXISTING BINDING WINS OVER THE SERVER'S CURRENT DIRNAME.** The server's
+ * dedupe iterates `ORDER BY created_at, id`, so deleting one notebook RENAMES its
+ * same-named siblings' directories (`cli_projects.rs:39-45`). Following that by
+ * renaming the user's directory would move a folder out from under an open editor,
+ * a shell, and a project-scope plugin install whose `projectPath` is a literal
+ * string. Identity is the notebook id plus the inode, not the name — so the drift
+ * is REPORTED and the directory stays put.
+ *
+ * **3. Ambiguity freezes.** `ledger.bindProject` throws when a second directory
+ * claims a notebook (a Finder duplicate, or an edited `project.json`). Caught
+ * here and surfaced; never resolved by picking one.
+ */
+export async function ensureProjects(ledger, projects, workspace) {
+    const out = [];
+    // The verification copy. Computed over the whole list because the dedupe is
+    // positional — checking one name in isolation cannot reproduce `-2`/`-3`.
+    const expected = dedupeDirnames(projects.map((p) => safeDirname(p.name, p.id)));
+    await fs.mkdir(workspace, { recursive: true });
+    for (let i = 0; i < projects.length; i += 1) {
+        const p = projects[i];
+        const mine = expected[i];
+        const drift = mine !== undefined && mine !== p.dirname
+            ? `the server calls this project's directory '${p.dirname}'; this client computes ` +
+                `'${mine}'. Using the server's answer — report this, it means the two ` +
+                `safe_dirname implementations have diverged.`
+            : null;
+        const existing = ledger.project(p.id);
+        const root = existing && (await rootGate(existing)) === null ? existing.root : join(workspace, p.dirname);
+        const nameDrift = existing && existing.root !== join(workspace, p.dirname)
+            ? `the server now calls this directory '${p.dirname}' but it is bound at ` +
+                `'${existing.root}'. The directory is NOT renamed — identity is the notebook id, ` +
+                `not the name, and deleting a same-named sibling renames these server-side.`
+            : null;
+        try {
+            await fs.mkdir(root, { recursive: true });
+            const st = await fs.stat(root);
+            const bound = ledger.bindProject({
+                id: existing?.id ?? p.id,
+                notebookId: p.id,
+                name: p.name,
+                dirname: p.dirname,
+                root,
+                inode: st.ino,
+                deviceNo: st.dev,
+            });
+            // The identity anchor. Written every time so a deleted or edited one is
+            // repaired — it is ours, and `.symbols/**` is on the deny-list precisely so
+            // no server content can ever land here.
+            await fs.mkdir(dirname(projectJsonPath(root)), { recursive: true });
+            await fs.writeFile(projectJsonPath(root), `${JSON.stringify({ notebook_id: p.id, name: p.name }, null, 2)}\n`, "utf8");
+            out.push({
+                project: bound,
+                notebookId: p.id,
+                name: p.name,
+                problem: null,
+                dirnameDrift: drift ?? nameDrift,
+            });
+        }
+        catch (err) {
+            out.push({
+                project: null,
+                notebookId: p.id,
+                name: p.name,
+                problem: err.message,
+                dirnameDrift: drift ?? nameDrift,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Every project in the ledger, swept in sequence.
+ *
+ * Serial on purpose. Concurrency here buys little (the cost is one `combined`
+ * per project) and costs a lot: the per-device rate limit is 600/min across the
+ * whole device, and parallel sweeps of 20 projects are exactly how a client
+ * discovers that as a 429 storm rather than a queue.
+ */
+export async function syncAll(ledger, opts = {}) {
+    const out = [];
+    for (const project of ledger.projects()) {
+        out.push(await syncProject({ ...opts, ledger, project }));
+    }
+    return out;
+}