slidemind 0.3.20 → 0.4.0

package/src/workspace/sync.mjs

@@ -0,0 +1,1119 @@
+// Automatic remote synchronization of a deck's shared plan record — the
+// algorithm in synchronization.md, as one per-record queue.
+//
+//   state/workspace-sync.json   the queue: idle | pending | sending |
+//                               applying | blocked | outcome-unknown, the
+//                               latest unsent local hash, the operation in
+//                               flight (base, sent snapshot, response), the
+//                               network claim, and a conflict when blocked.
+//   state/record.json           the CONFIRMED remote baseline (record-state);
+//                               advanced only from what the service answered.
+//
+// A local save never waits on the network: it commits, then `scheduleSync`
+// marks the queue pending. `drainOnce` is the coordinator — one drain per
+// record at a time, in the daemon (startSyncLoop) or in a headless command
+// (`record sync`): claim and snapshot under the deck lock, do the network
+// call without it, reacquire to apply. A crash anywhere leaves enough on disk
+// to finish or to ask: a persisted `sending`/`outcome-unknown` operation is
+// read back before anything is sent again, never resent blindly.
+//
+// `blocked` is always explicit: it ends with a sign-in, a policy change, a
+// resolve (unblockSync) — never with the next tick. Transient failures stay
+// `pending` with a `retryAt`.
+//
+// Generic plan.md decks are not synchronized here (contracts §7): without an
+// installed adapter the queue stays idle.
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+
+import { Merge3Error, SERVER_OWNED_TOP_LEVEL, merge3 } from "../lib/merge-json.mjs";
+import { pidAlive } from "../lib/revision.mjs";
+import { createRecord, getRecord, putRecord, recordSelector, resolveRecordBackend } from "../lib/record-client.mjs";
+import { planToSend, readRecordState, recordStateFrom, resolveStoredFile, writeRecordState } from "../lib/record-state.mjs";
+import { dispatchAdapter } from "./adapters.mjs";
+import { EDIT_FILE, SCHEMA_VERSION as EDIT_SCHEMA_VERSION } from "./edit.mjs";
+import { runDeckOperation } from "./operations.mjs";
+import { hasEditablePlan, readDestination, writeDestination } from "./remote-status.mjs";
+import { getTask, listTasks, requestTask, respondTask, supersedeTask } from "./tasks.mjs";
+
+export const SYNC_FILE = "workspace-sync.json";
+export const SCHEMA_VERSION = 1;
+export const STATES = ["idle", "pending", "sending", "applying", "blocked", "outcome-unknown"];
+export const OPERATION_KINDS = ["create", "save", "approve"];
+export const BACKOFF_MIN_MS = 2_000;
+export const BACKOFF_MAX_MS = 60_000;
+export const CLAIM_TTL_MS = 10 * 60_000;
+
+const NONCE = randomUUID();
+const inFlight = new Set(); // workspaceDirs with a request on the wire in THIS process
+let wakeHook = null; // the daemon loop, when one runs in this process
+
+const nowIso = (now) => new Date(now()).toISOString();
+const wsDir = (dir) => (path.basename(dir) === ".slidemind" ? dir : path.join(dir, ".slidemind"));
+const typed = (code, message, extra = {}) => Object.assign(new Error(message), { code, ...extra });
+const SHA = /^sha256:[a-f0-9]{64}$/;
+const isBound = (binding) => Boolean(binding?.url || (binding?.driveId && binding?.itemId));
+const approvedHash = (plan) => plan?.approval?.planHash ?? null;
+
+/** True while a shared approval is in flight: ordinary saves are buffered by the caller, sends wait (synchronization.md "Approval in flight"). */
+export function approvalInProgress(workspaceDir) {
+  return readSync(workspaceDir).operation?.kind === "approve";
+}
+
+export function syncPath(workspaceDir) {
+  return path.join(wsDir(workspaceDir), "state", SYNC_FILE);
+}
+
+function writeAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+}
+
+const EMPTY = () => ({ schemaVersion: SCHEMA_VERSION, state: "idle", pendingHash: null, attempt: 0, retryAt: null, operation: null, lastError: null, lastConfirmedAt: null });
+
+/** `null` for a well-formed queue, else the `recovery_required` reason (fixtures: sync/cases.json). */
+export function validateSync(data) {
+  if (!data || typeof data !== "object") return "not an object";
+  if (data.schemaVersion !== SCHEMA_VERSION) return `schemaVersion ${data.schemaVersion} is not ${SCHEMA_VERSION}`;
+  if (!STATES.includes(data.state)) return `state '${data.state}' is unknown`;
+  if (data.pendingHash !== null && typeof data.pendingHash !== "string") return "pendingHash must be a hash or null";
+  if (!Number.isInteger(data.attempt) || data.attempt < 0) return "attempt must be a non-negative integer";
+  const op = data.operation;
+  if (op !== null && op !== undefined) {
+    if (typeof op !== "object" || typeof op.id !== "string") return "operation.id must be a string";
+    if (!OPERATION_KINDS.includes(op.kind)) return `operation.kind '${op.kind}' is unknown`;
+    if (!op.sent || typeof op.sent.hash !== "string") return "operation.sent.hash must be a string";
+  }
+  return null;
+}
+
+/** The queue as stored. Missing → idle; malformed → throws `recovery_required`, the file kept on disk. */
+export function readSync(workspaceDir) {
+  let raw;
+  try {
+    raw = fs.readFileSync(syncPath(workspaceDir), "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return EMPTY();
+    throw err;
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    throw typed("recovery_required", `${SYNC_FILE} is not JSON: ${err.message}`, { file: syncPath(workspaceDir) });
+  }
+  const problem = validateSync(data);
+  if (problem) throw typed("recovery_required", `${SYNC_FILE}: ${problem}; inspect it before syncing this deck`, { file: syncPath(workspaceDir) });
+  return { ...EMPTY(), ...data };
+}
+
+function writeSync(workspaceDir, data) {
+  const problem = validateSync(data);
+  if (problem) throw new Error(`refusing to write an invalid ${SYNC_FILE}: ${problem}`);
+  writeAtomic(syncPath(workspaceDir), data);
+  return data;
+}
+
+/** The queue, summarized for a status line or a card. `synced` = nothing pending, in flight or blocked. */
+export function syncStatus(workspaceDir) {
+  const q = readSync(workspaceDir);
+  return {
+    exists: fs.existsSync(syncPath(workspaceDir)),
+    state: q.state,
+    synced: q.state === "idle" && q.pendingHash === null && !q.operation,
+    pendingHash: q.pendingHash,
+    attempt: q.attempt,
+    retryAt: q.retryAt,
+    operation: q.operation ? { id: q.operation.id, kind: q.operation.kind, startedAt: q.operation.startedAt, sent: q.operation.sent.hash } : null,
+    lastError: q.lastError,
+    lastConfirmedAt: q.lastConfirmedAt,
+    conflict: q.conflict ?? null,
+    claim: q.claim ?? null,
+  };
+}
+
+/**
+ * After an ACCEPTED local save: remember the latest local hash and mark the
+ * queue pending. Coalesces — ten saves during one held network call become
+ * one send of the newest value. A blocked queue keeps its block (a new edit
+ * does not erase a conflict); an operation in flight is left alone and the
+ * hash is picked up when it settles. Call only for validated values.
+ */
+export function scheduleSync(workspaceDir, { hash } = {}) {
+  if (typeof hash !== "string") throw typed("validation_failed", "scheduleSync needs the accepted local hash");
+  const ws = wsDir(workspaceDir);
+  const q = readSync(ws);
+  q.pendingHash = hash;
+  if (q.state === "idle") {
+    q.state = "pending";
+    q.attempt = 0;
+    q.retryAt = null;
+  }
+  // 7.7: a deck pointed at a folder before it had a plan creates its record on the first accepted save.
+  if (!q.createTarget && !isBound(readRecordState(ws))) {
+    const dest = readDestination(ws);
+    if (dest && !dest.malformed && dest.webUrl && dest.name) q.createTarget = { folderUrl: dest.webUrl, name: dest.name };
+  }
+  writeSync(ws, q);
+  wakeHook?.(ws);
+  return syncStatus(ws);
+}
+
+/**
+ * A first share: the next drain POSTs the current plan to `{ folderUrl, name }`.
+ * A queue blocked on `waiting_for_plan` (destination selected before a plan
+ * existed) resumes here.
+ */
+export function scheduleCreate(workspaceDir, { hash, folderUrl, name }) {
+  const q = readSync(workspaceDir);
+  q.createTarget = { folderUrl, name };
+  if (q.state === "blocked" && q.lastError?.code === "waiting_for_plan") {
+    q.state = "idle";
+    q.lastError = null;
+  }
+  writeSync(workspaceDir, q);
+  return scheduleSync(workspaceDir, { hash });
+}
+
+/**
+ * Explicit resume after a block: a sign-in, a policy change, a resolve. Clears
+ * the block (and the conflict when `conflictId` names the current one) and
+ * marks pending.
+ */
+export function unblockSync(workspaceDir, { conflictId = null } = {}) {
+  const q = readSync(workspaceDir);
+  if (q.conflict) {
+    if (conflictId !== q.conflict.conflictId) throw typed("stale_subject", "that conflict is no longer the current one");
+    q.conflict = null;
+  }
+  if (q.state === "blocked") {
+    q.state = q.operation ? (q.operation.response ? "applying" : "outcome-unknown") : "pending";
+    q.lastError = null;
+    q.retryAt = null;
+    q.staleRetries = 0;
+  }
+  writeSync(workspaceDir, q);
+  wakeHook?.(wsDir(workspaceDir));
+  return syncStatus(workspaceDir);
+}
+
+// ---------------------------------------------------------------------------
+// io — the adapter, the record service, the clock: all injectable
+// ---------------------------------------------------------------------------
+
+function adapterIo(adapter, ws) {
+  if (!adapter) return null;
+  if (typeof adapter.read === "function") return adapter; // a fake: { id, read, applyRemote }
+  if (!adapter.entry) return null;
+  const deckRoot = path.dirname(ws);
+  const call = async (method, payload, token) => {
+    const answer = await dispatchAdapter(adapter.entry, { method, deckRoot, payload, ownerToken: token });
+    if (answer.status === "ok") return { ok: true, ...answer.data };
+    return { ok: false, code: answer.error?.code ?? "validation_failed", message: answer.error?.message, ...(answer.data ?? {}) };
+  };
+  return {
+    id: adapter.id,
+    read: (token) => call("read", {}, token),
+    applyRemote: (payload, token) => call("apply-remote", payload, token),
+    saveLocal: (payload, token) => call("save-local", payload, token),
+    approve: (payload, token) => call("approve", payload, token),
+  };
+}
+
+async function defaultClient(binding) {
+  const backendURL = await resolveRecordBackend(binding);
+  const { sharedRecordsSupport } = await import("../bridge/client/transport.mjs");
+  const kind = binding?.recordKind ?? null; // the service the binding was made against
+  return {
+    backendURL,
+    capabilities: () => sharedRecordsSupport(backendURL, { kind, refresh: true }),
+    get: (selector) => getRecord(backendURL, selector, { kind }),
+    put: (args) => putRecord(backendURL, { kind, ...args }),
+    create: (args) => createRecord(backendURL, { kind, ...args }),
+  };
+}
+
+/** Same content, ignoring what the service stamps itself — decides whether a write of unknown outcome landed. */
+export function sameContent(a, b) {
+  const strip = (v) => {
+    if (!v || typeof v !== "object") return v;
+    const copy = { ...v };
+    for (const k of SERVER_OWNED_TOP_LEVEL) delete copy[k];
+    return copy;
+  };
+  return isDeepStrictEqual(strip(a), strip(b));
+}
+
+export function backoffMs(attempt, random = Math.random) {
+  const base = Math.min(BACKOFF_MAX_MS, BACKOFF_MIN_MS * 2 ** Math.max(0, attempt - 1));
+  return Math.round(base * (1 + random() * 0.25));
+}
+
+// One verdict per network failure: what to persist, and whether to retry.
+// `null` means it is not a network verdict at all — rethrown.
+function classify(err) {
+  const code = err?.code;
+  if (code === "bridge_timeout" || code === "timeout" || /timed out/i.test(String(err?.message ?? ""))) return { code: "outcome_unknown", unknown: true };
+  if (code === "version_unknown") return { code: "outcome_unknown", unknown: true, written: err?.body?.written === true };
+  if (code === "offline") return { code: "offline", retryable: true };
+  if (err?.status === 429 || code === "rate_limited") {
+    const after = Number(err?.headers?.["retry-after"] ?? err?.retryAfter);
+    return { code: "rate_limited", retryable: true, retryAfterMs: Number.isFinite(after) && after > 0 ? after * 1000 : null };
+  }
+  if (err?.status >= 500) return { code: "offline", retryable: true };
+  if (code === "sharepoint_write_disabled" || code === "write_disabled") return { code: "write_disabled" };
+  if (code === "not_found" || code === "remote_missing") return { code: "remote_missing" };
+  if (code === "login_required" || code === "access_denied" || code === "name_exists") return { code };
+  if (code === "backend_ambiguous") return { code: "capability_unknown" };
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// the coordinator
+// ---------------------------------------------------------------------------
+
+/**
+ * Drain this record's queue once: read back an unfinished operation, send the
+ * newest local value if any, apply what came back. Resolves to `syncStatus`
+ * plus `action`: `noop`, `busy`, `deferred`, `blocked`, `recovered`, `applied`.
+ *
+ * `adapter` is `{ id, entry }` (installed pack) or a fake `{ id, read,
+ * applyRemote }`; `client` replaces the record service (`{ capabilities, get,
+ * put, create, backendURL }`); `owner` is runDeckOperation's (`false` in the
+ * daemon); `now`/`random` are the clock. The deck lock is never held across a
+ * network call.
+ */
+export async function drainOnce(workspaceDir, { adapter = null, client = null, owner, now = Date.now, random = Math.random } = {}) {
+  const ws = wsDir(workspaceDir);
+  const io = adapterIo(adapter, ws);
+  // Same signature as `refreshOnce`'s and `activateDestination`'s: the settled
+  // approval below rides out on `approval`, and a one-parameter `result` dropped
+  // it silently — the daemon's `if (r.approval?.ok)` observer could never fire,
+  // so a crashed shared approval was finalized without the open page hearing it.
+  const result = (action, extra = {}) => ({ action, ...syncStatus(ws), ...extra });
+  if (!io) return result("noop");
+
+  const binding = readRecordState(ws);
+  let net = client;
+  if (!net) {
+    try {
+      net = await defaultClient(binding);
+    } catch (err) {
+      const verdict = classify(err) ?? { code: "capability_unknown" };
+      persistBlock(ws, { ...verdict, message: err.message }, now);
+      return result("blocked");
+    }
+  }
+
+  // 1. claim + snapshot, under the lock.
+  const claimed = await runDeckOperation(ws, { kind: "sync-claim", owner }, async (op) => {
+    const q = readSync(ws);
+    if (q.claim) {
+      const mine = q.claim.nonce === NONCE;
+      if (mine || (pidAlive(q.claim.pid) && now() - Date.parse(q.claim.at) < CLAIM_TTL_MS)) return { busy: true };
+      // a dead claimant: whatever it had on the wire is of unknown outcome, not "nothing sent"
+      if (q.state === "sending") q.state = "outcome-unknown";
+      delete q.claim;
+    }
+    if (q.state === "blocked") return { blocked: true };
+    if (q.state === "pending" && q.retryAt && Date.parse(q.retryAt) > now()) return { deferred: true };
+    // the approval barrier: a shared approval on the wire is finished (read back, finalized) before any ordinary send
+    if (q.operation?.kind === "approve" && q.state === "sending") return { busy: true };
+    // an unsent operation is re-snapshotted: newer local edits ride along
+    if (q.operation && q.state === "pending" && !q.operation.response) q.operation = null;
+    if (q.state === "idle" && !q.pendingHash) return { idle: true };
+
+    if (!q.operation) {
+      const isCreate = !binding?.url && !(binding?.driveId && binding?.itemId);
+      if (isCreate && !q.createTarget) return { blocked: true, error: { code: "waiting_for_plan", message: "no shared record and no destination yet", retryable: false } };
+      const local = await io.read(op.token);
+      if (!local.ok) return { blocked: true, error: { code: local.code, message: local.message } };
+      q.operation = {
+        id: randomUUID(),
+        kind: isCreate ? "create" : "save",
+        base: { eTag: binding?.eTag ?? null, value: binding?.base ?? null },
+        sent: { hash: local.hash, value: planToSend(local.value) },
+        ...(isCreate ? { target: q.createTarget } : {}),
+        startedAt: nowIso(now),
+      };
+      q.pendingHash = null;
+      q.state = "pending";
+    }
+    q.claim = { pid: process.pid, nonce: NONCE, operationId: q.operation.id, at: nowIso(now) };
+    writeSync(ws, q);
+    return { q };
+  });
+  if (claimed.busy) return result("busy");
+  if (claimed.idle) return result("noop");
+  if (claimed.deferred) return result("deferred");
+  if (claimed.blocked) {
+    if (claimed.error) persistBlock(ws, claimed.error, now);
+    return result("blocked");
+  }
+
+  let q = claimed.q;
+  try {
+    // 2. an operation of unknown outcome is read back before anything is sent.
+    if (q.state === "sending" || q.state === "outcome-unknown") {
+      const back = await readBack(ws, q, net, binding);
+      if (back.blocked) return result("blocked");
+      q = back.q;
+      if (!q.operation) return result("recovered"); // an approval that never landed is void: the human decides again
+    }
+
+    // 3. send, when there is still something to send.
+    if (q.state === "pending") {
+      const caps = await net.capabilities();
+      if (caps.status !== "supported") {
+        release(ws, (queue) => {
+          queue.operation = null;
+          queue.state = "blocked";
+          queue.lastError = {
+            code: "capability_unknown",
+            message: caps.status === "unknown" ? "the backend's capabilities could not be read; nothing was sent" : "the backend does not advertise shared records",
+            retryable: caps.status === "unknown",
+          };
+        });
+        return result("blocked");
+      }
+      q.state = "sending";
+      q.attempt += 1;
+      q.retryAt = null;
+      q.lastError = null;
+      // The deck lock is long gone and `q` is the snapshot taken under it (pendingHash
+      // nulled there). A browser save landing during these network windows writes a
+      // fresh pendingHash, which a whole-snapshot write would silently erase — the page
+      // would then report "Synced" over an edit nothing will ever send. Patch fields.
+      patch(ws, q, ["state", "attempt", "retryAt", "lastError"]);
+      inFlight.add(ws);
+      let response;
+      try {
+        response = await send(net, q.operation, binding);
+      } catch (err) {
+        inFlight.delete(ws);
+        const verdict = classify(err);
+        if (verdict?.unknown) {
+          q.state = "outcome-unknown";
+          q.lastError = { code: "outcome_unknown", message: `the request may have reached the service: ${err.message}`, retryable: false, ...(verdict.written ? { written: true } : {}) };
+          patch(ws, q, ["state", "lastError"]);
+          const back = await readBack(ws, q, net, binding);
+          if (back.blocked) return result("blocked");
+          q = back.q;
+          if (q.state === "pending") return result("recovered"); // resend on the next drain, with a fresh snapshot
+        } else if (err?.code === "conflict") {
+          conflictBlock(ws, q, err.body, now);
+          await conflictTask(ws, io.id, owner);
+          return result("blocked");
+        } else if (err?.code === "stale") {
+          if ((q.staleRetries ?? 0) >= 1) {
+            // one automatic retry only: repeated contention is shown, not looped on
+            release(ws, (queue) => {
+              queue.state = "blocked";
+              queue.lastError = { code: "stale", message: "the shared record keeps moving; sync again once it settles", retryable: true };
+            });
+            return result("blocked");
+          }
+          // the answer carries the current record: merge it in, then send once more
+          q.operation.response = { ...err.body, staleAnswer: true };
+          q.state = "applying";
+          patch(ws, q, ["operation", "state"]);
+        } else if (verdict?.retryable) {
+          release(ws, (queue) => {
+            queue.state = "pending";
+            queue.retryAt = new Date(now() + (verdict.retryAfterMs ?? backoffMs(queue.attempt, random))).toISOString();
+            queue.lastError = { code: verdict.code, message: err.message, retryable: true };
+          });
+          return result("deferred");
+        } else if (verdict) {
+          release(ws, (queue) => {
+            queue.state = "blocked";
+            queue.lastError = { code: verdict.code, message: err.message, retryable: false };
+          });
+          return result("blocked");
+        } else {
+          throw err;
+        }
+      }
+      if (response) {
+        inFlight.delete(ws);
+        q.operation.response = response;
+        q.state = "applying";
+        patch(ws, q, ["operation", "state"]);
+      }
+    }
+
+    // 4. apply, under the lock again.
+    if (q.state === "applying") {
+      if (q.operation.kind === "approve") {
+        // a crashed shared approval: finalize what landed (or void what did not), and answer its task
+        const fin = await finalizeApprove(ws, q, io, binding, net.backendURL, owner, now);
+        if (fin.ok) await completeApproveTask(ws, q.operation, fin.evidence, owner);
+        return result(fin.ok ? "applied" : "recovered", { approval: fin });
+      }
+      const stale = q.operation.response?.staleAnswer === true;
+      await apply(ws, q, io, binding, net.backendURL, owner, now);
+      const after = readSync(ws);
+      if (after.state === "blocked" && after.conflict) await conflictTask(ws, io.id, owner);
+      if (stale && after.state === "pending") {
+        // the stale answer is merged in; the one automatic retry sends the result now
+        release(ws);
+        return drainOnce(ws, { adapter, client: net, owner, now, random });
+      }
+      return result(after.state === "blocked" ? "blocked" : "applied");
+    }
+    return result("noop");
+  } finally {
+    inFlight.delete(ws);
+    release(ws);
+  }
+}
+
+// A conflict is a task for the human (contracts §4 `sync-conflict`): one per
+// local version, so an older conflict task is voided when the inputs move.
+async function conflictTask(ws, adapterId, owner) {
+  const c = readSync(ws).conflict;
+  if (!c || !SHA.test(c.expectedHash ?? "")) return;
+  const deckRoot = path.dirname(ws);
+  for (const t of listTasks(deckRoot, { status: "pending" })) {
+    if (t.kind === "sync-conflict" && t.subject.hash !== c.expectedHash) await supersedeTask(deckRoot, t.id, { owner });
+  }
+  await requestTask(deckRoot, { kind: "sync-conflict", subject: { hash: c.expectedHash, remoteETag: c.currentETag ?? null }, adapterId }, { owner });
+}
+
+// The confirmed baseline is what was observed remotely — conflict or not.
+function advanceBaseline(ws, R, binding, backendURL) {
+  const previous = readRecordState(ws) ?? binding;
+  const file = resolveStoredFile(ws, previous?.file) ?? path.join(ws, "plan.json");
+  writeRecordState(ws, recordStateFrom(R, { file, deckDir: ws, link: previous?.link ?? null, backendURL: backendURL ?? previous?.backendURL ?? null, previous }));
+}
+
+// A remote draft newer than the FROZEN approved plan (plan/context.json) is
+// staged beside it, never over it: the pack's cold resume reads
+// state/plan-incoming.json and warns (resume.mjs). `hash` is the pack's local
+// version, which only the pack computes — null here.
+function stageIncoming(ws, R, now) {
+  let ctx;
+  try {
+    ctx = JSON.parse(fs.readFileSync(path.join(ws, "plan", "context.json"), "utf8"));
+  } catch {
+    return;
+  }
+  if (!ctx?.planHash || approvedHash(R.plan) === ctx.planHash) return;
+  writeAtomic(path.join(ws, "state", "plan-incoming.json"), { schemaVersion: 1, eTag: R.eTag ?? null, hash: null, planHash: approvedHash(R.plan), value: R.plan, stagedAt: nowIso(now) });
+}
+
+/**
+ * 7.4 — read the shared record and bring it in: applied as-is when local is at
+ * the confirmed base, merged three ways otherwise, a same-field clash kept as a
+ * conflict. Never PUTs, never touches the PPTX binding. `busy` while a send,
+ * an apply or another process's claim is in progress; `blocked` when the queue
+ * is (a conflict, a policy block) or the read itself failed (`error`).
+ */
+export async function refreshOnce(workspaceDir, { adapter = null, client = null, owner, now = Date.now } = {}) {
+  const ws = wsDir(workspaceDir);
+  const io = adapterIo(adapter, ws);
+  const result = (action, extra = {}) => ({ action, ...syncStatus(ws), ...extra });
+  const binding = readRecordState(ws);
+  if (!io || !isBound(binding)) return result("noop");
+  const q = readSync(ws);
+  if (q.claim && (q.claim.nonce === NONCE || (pidAlive(q.claim.pid) && now() - Date.parse(q.claim.at) < CLAIM_TTL_MS))) return result("busy");
+  if (["sending", "applying", "outcome-unknown"].includes(q.state) || q.operation?.response) return result("busy");
+  if (q.state === "blocked") return result("blocked");
+
+  let net = client;
+  let remote;
+  try {
+    net ??= await defaultClient(binding);
+    remote = await net.get(recordSelector(binding));
+  } catch (err) {
+    const verdict = classify(err) ?? (client ? null : { code: "capability_unknown" });
+    if (!verdict) throw err;
+    return result("blocked", { error: { code: verdict.code, message: err.message } });
+  }
+  if (remote.eTag && remote.eTag === binding.eTag) return result("noop");
+
+  try {
+    await runDeckOperation(ws, { kind: "sync-refresh", owner }, async (op) => {
+      const cur = readSync(ws);
+      if (cur.state !== q.state || cur.operation?.response || cur.claim) return; // moved under us: the next refresh sees it
+      stageIncoming(ws, remote, now);
+      await settle(ws, { io, R: remote, base: { eTag: binding.eTag ?? null, value: binding.base ?? null }, sent: { hash: "sha256:base", value: binding.base ?? {} }, binding, backendURL: net.backendURL, token: op.token, now });
+    });
+  } catch (err) {
+    if (err?.code === "deck_busy") return result("busy");
+    throw err;
+  }
+  const after = readSync(ws);
+  if (after.state === "blocked" && after.conflict) {
+    await conflictTask(ws, io.id, owner);
+    return result("conflict");
+  }
+  return result(after.state === "pending" ? "merged" : after.state === "blocked" ? "blocked" : "applied");
+}
+
+/**
+ * 7.5 — the human's answer to a conflict. `conflictId` must be the current
+ * conflict and `expectedHash` the current local version, else `stale_subject`
+ * with the recomputed conflict (its id kept, inputs refreshed, a new task
+ * asked). The resolved `value` is committed as a local save, the baseline set
+ * to the latest remote, the block lifted and one drain run.
+ */
+export async function resolveConflict(workspaceDir, { adapter = null, client = null, owner, conflictId, expectedHash, value, now = Date.now } = {}) {
+  const ws = wsDir(workspaceDir);
+  const io = adapterIo(adapter, ws);
+  const fail = (code, message, extra = {}) => ({ ok: false, code, message, ...extra });
+  const c = readSync(ws).conflict;
+  if (!io) return fail("validation_failed", "no installed adapter for this deck");
+  if (!c || c.conflictId !== conflictId) return fail("stale_subject", "that conflict is no longer the current one", { conflictId: c?.conflictId ?? null, expectedHash: c?.expectedHash ?? null });
+  if (!value || typeof value !== "object") return fail("validation_failed", "a resolution is the whole plan value");
+  const binding = readRecordState(ws);
+  let net = client;
+  let remote;
+  try {
+    net ??= await defaultClient(binding);
+    remote = await net.get(recordSelector(binding));
+  } catch (err) {
+    const verdict = classify(err) ?? (client ? null : { code: "capability_unknown" });
+    if (!verdict) throw err;
+    return fail(verdict.code, err.message);
+  }
+
+  const out = await runDeckOperation(ws, { kind: "conflict-resolve", owner }, async (op) => {
+    const cur = readSync(ws);
+    if (cur.conflict?.conflictId !== conflictId) return { refused: fail("stale_subject", "that conflict is no longer the current one", { conflictId: cur.conflict?.conflictId ?? null }) };
+    const local = await io.read(op.token);
+    if (!local.ok) return { refused: fail(local.code, local.message) };
+    if (local.hash !== expectedHash || (remote.eTag ?? null) !== (c.currentETag ?? null)) {
+      // the inputs moved since the conflict was shown: recompute, keep the id, refuse this answer
+      let merged;
+      try {
+        merged = merge3(c.base ?? c.sent?.value ?? {}, remote.plan, local.value);
+      } catch (err) {
+        if (!(err instanceof Merge3Error)) throw err;
+        merged = { merged: null, conflicts: [{ path: err.path, code: "duplicate_id" }] };
+      }
+      cur.conflict = { ...c, expectedHash: local.hash, currentETag: remote.eTag ?? null, current: remote.plan, local: local.value, merged: merged.merged, conflicts: merged.conflicts, at: nowIso(now) };
+      writeSync(ws, cur);
+      return { stale: cur.conflict };
+    }
+    op.note({ before: local.hash });
+    const committed = await io.saveLocal({ base: { hash: local.hash, value: local.value }, value }, op.token);
+    if (!committed.ok) return { refused: fail(committed.code ?? "validation_failed", committed.message ?? "the resolution was refused", { conflicts: committed.conflicts, merged: committed.merged }) };
+    op.note({ after: committed.hash });
+    writeAtomic(path.join(ws, "state", EDIT_FILE), { schemaVersion: EDIT_SCHEMA_VERSION, adapterId: io.id, hash: committed.hash, value: committed.value, updatedAt: nowIso(now) });
+    advanceBaseline(ws, remote, binding, net.backendURL);
+    return { hash: committed.hash };
+  });
+  if (out.stale) {
+    await conflictTask(ws, io.id, owner);
+    return fail("stale_subject", "the plan or the shared record changed since this conflict was shown; decide again", { conflictId, expectedHash: out.stale.expectedHash, merged: out.stale.merged, conflicts: out.stale.conflicts, supersede: out.stale.expectedHash !== expectedHash });
+  }
+  if (out.refused) return out.refused;
+  scheduleSync(ws, { hash: out.hash });
+  unblockSync(ws, { conflictId });
+  const drained = await drainOnce(ws, { adapter, client: net, owner, now });
+  return { ok: true, hash: out.hash, ...drained };
+}
+
+/**
+ * 7.6 — approve a SHARED plan: local edits are flushed, the reviewed content
+ * must be what is local AND what the service holds (semantically — a revision
+ * the flush restamped is not a change), the pack prepares the approval on that
+ * exact version, the conditional write is read back for the exact approved
+ * hash, and only then does the pack finalize context and evidence. The
+ * operation (`kind: "approve"`) is the barrier: while it exists ordinary sends
+ * wait and `approvalInProgress` is true; an unknown outcome keeps it until a
+ * readback settles it. `response.actor` is the signed-in account (the caller
+ * resolved it); `task.subject.hash` is the version the human saw.
+ */
+export async function approveShared(workspaceDir, { adapter = null, client = null, owner, task, response, now = Date.now } = {}) {
+  const ws = wsDir(workspaceDir);
+  const io = adapterIo(adapter, ws);
+  const fail = (code, message, extra = {}) => ({ ok: false, code, message, ...extra });
+  const stale = (message, extra = {}) => fail("stale_subject", message, { supersede: true, ...extra });
+  const binding = readRecordState(ws);
+  if (!io || !isBound(binding)) return fail("validation_failed", "this plan is not shared");
+  if (!task?.subject?.hash || !response?.actor) return fail("validation_failed", "approveShared needs the task and the attributed response");
+  let net = client;
+  try {
+    net ??= await defaultClient(binding);
+  } catch (err) {
+    return fail(classify(err)?.code ?? "capability_unknown", err.message);
+  }
+
+  // 0. the human saw THIS local version
+  const reviewed = await io.read();
+  if (!reviewed.ok) return fail(reviewed.code, reviewed.message);
+  if (reviewed.hash !== task.subject.hash) return stale("the plan changed since it was reviewed", { current: reviewed.hash });
+
+  // 1. local edits go first; a queue that cannot drain cannot carry an approval
+  const flushed = await drainOnce(ws, { adapter, client: net, owner, now });
+  if (flushed.action === "busy") return fail("deck_busy", "another sync is in progress; try again in a moment");
+  if (flushed.state === "blocked") return fail(flushed.lastError?.code ?? "blocked", `the shared plan is not synchronized (${flushed.lastError?.code ?? "blocked"}); resolve that first`);
+  if (flushed.operation?.kind === "approve") return fail("approval_in_progress", "an approval of this plan is already in flight");
+  if (flushed.state !== "idle" || flushed.operation) return fail("sync_pending", "local edits are still being synchronized; try again in a moment");
+
+  // 2. the barrier, under the lock: the reviewed content stands, the pack prepares on exactly this version
+  const claimed = await runDeckOperation(ws, { kind: "approve-claim", owner }, async (op) => {
+    const q = readSync(ws);
+    if (q.operation?.kind === "approve") return { code: "approval_in_progress", message: "an approval of this plan is already in flight" };
+    if (q.claim || q.state !== "idle" || q.pendingHash) return { code: "sync_pending", message: "a save landed meanwhile; try again in a moment" };
+    const local = await io.read(op.token);
+    if (!local.ok) return { code: local.code, message: local.message };
+    if (!sameContent(local.value, reviewed.value)) return { code: "stale_subject", message: "synchronizing brought in changes nobody reviewed; the view is refreshed", supersede: true, current: local.hash };
+    const prep = await io.approve({ phase: "prepare", approvedBy: response.actor, expectedHash: local.hash, approvedAt: response.at }, op.token);
+    if (!prep.ok) return { code: prep.code, message: prep.message, supersede: prep.code === "stale_subject" };
+    if (!prep.prepared?.approved || typeof prep.prepared.hash !== "string") return { code: "extension_incompatible", message: "the pack's prepare answer carries no approved record" };
+    q.operation = {
+      id: randomUUID(),
+      kind: "approve",
+      base: { eTag: binding.eTag ?? null, value: binding.base ?? null },
+      sent: { hash: local.hash, value: planToSend(prep.prepared.approved, { approval: true }) },
+      prepared: prep.prepared,
+      task: { id: task.id, subjectHash: task.subject.hash, response },
+      startedAt: nowIso(now),
+    };
+    q.state = "sending";
+    q.claim = { pid: process.pid, nonce: NONCE, operationId: q.operation.id, at: nowIso(now) };
+    writeSync(ws, q);
+    return { q, local };
+  });
+  if (claimed.code) return fail(claimed.code, claimed.message, { supersede: claimed.supersede === true, current: claimed.current });
+
+  const q = claimed.q;
+  const prepared = q.operation.prepared;
+  const voided = (R) =>
+    release(ws, (queue) => {
+      queue.operation = null;
+      queue.state = queue.pendingHash ? "pending" : "idle";
+      if (R?.plan) advanceBaseline(ws, R, binding, net.backendURL);
+    });
+  try {
+    // 3. what the service holds must be the reviewed content
+    let remote;
+    try {
+      remote = await net.get(recordSelector(binding));
+    } catch (err) {
+      const verdict = classify(err);
+      if (!verdict) throw err;
+      voided();
+      return fail(verdict.code === "outcome_unknown" ? "offline" : verdict.code, err.message);
+    }
+    if (approvedHash(remote.plan) === prepared.hash) {
+      // an earlier attempt landed: nothing to send, finalize what is there
+      q.operation.response = { ...remote, submittedApplied: true, recovered: true };
+    } else {
+      if (!sameContent(remote.plan, claimed.local.value)) {
+        voided(remote);
+        return stale("the shared plan changed since it was reviewed; the view is refreshed");
+      }
+      q.attempt += 1;
+      patch(ws, q, ["attempt"]);
+      inFlight.add(ws);
+      let R;
+      try {
+        R = await net.put({ selector: recordSelector(binding), base: { eTag: remote.eTag ?? null, plan: remote.plan }, plan: q.operation.sent.value });
+      } catch (err) {
+        inFlight.delete(ws);
+        const verdict = classify(err);
+        if (verdict?.unknown) {
+          q.state = "outcome-unknown";
+          q.lastError = { code: "outcome_unknown", message: `the approval may have reached the service: ${err.message}`, retryable: false };
+          patch(ws, q, ["state", "lastError"]);
+          return fail("outcome_unknown", "the approval's outcome is unknown; it is read back before anything else happens", { pending: true });
+        }
+        if (err?.code === "conflict" || err?.code === "stale") {
+          voided(err.body?.plan ? { plan: err.body.plan, eTag: err.body.eTag } : null);
+          return stale("the shared plan moved while approving; the view is refreshed");
+        }
+        voided();
+        if (verdict) return fail(verdict.code, err.message);
+        throw err;
+      }
+      inFlight.delete(ws);
+      q.operation.response = R;
+    }
+    q.state = "applying";
+    patch(ws, q, ["state", "operation"]);
+
+    // 4/5. exact readback, then the pack finalizes under the lock; the task is answered with the evidence
+    const fin = await finalizeApprove(ws, q, io, binding, net.backendURL, owner, now);
+    if (fin.ok) fin.task = await completeApproveTask(ws, q.operation, fin.evidence, owner);
+    return fin;
+  } finally {
+    inFlight.delete(ws);
+    release(ws);
+  }
+}
+
+// The persisted approve operation's response is on disk: verify it carries the
+// exact approved hash, then let the pack write context and evidence. Anything
+// else voids the operation (the task stays pending for a fresh decision).
+async function finalizeApprove(ws, q, io, binding, backendURL, owner, now) {
+  const op = q.operation;
+  const R = op.response;
+  const fail = (code, message, extra = {}) => ({ ok: false, code, message, ...extra });
+  const clear = (edit) => release(ws, (queue) => { if (queue.operation?.id === op.id) queue.operation = null; edit?.(queue); });
+  if (R.staleAnswer || approvedHash(R.plan) !== op.prepared?.hash) {
+    advanceBaseline(ws, R, binding, backendURL);
+    clear((queue) => { queue.state = queue.pendingHash ? "pending" : "idle"; });
+    return fail("stale_subject", "the approval was overtaken by another change; the view is refreshed", { supersede: true });
+  }
+  return runDeckOperation(ws, { operationId: `${op.id}:finalize`, kind: "approve-finalize", owner }, async (opctx) => {
+    if (readSync(ws).operation?.id !== op.id) return fail("outcome_unknown", "the approval was settled by another process");
+    const local = await io.read(opctx.token);
+    if (!local.ok) return fail(local.code, local.message);
+    if (local.hash !== op.sent.hash) {
+      // a raw edit during approval: the remote is approved, the local draft is not — it is sent as an amendment, the task is void
+      advanceBaseline(ws, R, binding, backendURL);
+      clear((queue) => { queue.state = "pending"; queue.pendingHash = local.hash; });
+      return fail("stale_subject", "the plan was edited while it was being approved; reconcile and decide again", { supersede: true });
+    }
+    const fin = await io.approve({ phase: "finalize", prepared: op.prepared, sharedVersion: R.eTag ?? null }, opctx.token);
+    if (!fin.ok) {
+      if (fin.code === "stale_subject") {
+        advanceBaseline(ws, R, binding, backendURL);
+        clear((queue) => { queue.state = queue.pendingHash ? "pending" : "idle"; });
+        return fail("stale_subject", fin.message ?? "the pack refused to finalize", { supersede: true });
+      }
+      // the pack died or errored: the outcome of its context write is unknown — the next drain retries the finalize
+      return fail("outcome_unknown", fin.message ?? "the pack did not finalize the approval", { pending: true });
+    }
+    advanceBaseline(ws, R, binding, backendURL);
+    writeAtomic(path.join(ws, "state", EDIT_FILE), { schemaVersion: EDIT_SCHEMA_VERSION, adapterId: io.id, hash: fin.hash, value: fin.value, updatedAt: nowIso(now) });
+    clear((queue) => {
+      queue.lastError = null;
+      queue.attempt = 0;
+      queue.retryAt = null;
+      if (queue.pendingHash && queue.pendingHash !== fin.hash) queue.state = "pending";
+      else {
+        queue.state = "idle";
+        queue.pendingHash = null;
+        queue.lastConfirmedAt = nowIso(now);
+      }
+    });
+    return { ok: true, evidence: { record: `context.json#${fin.planHash ?? op.prepared.hash}`, hash: op.task?.subjectHash ?? op.sent.hash, remoteETag: R.eTag ?? null } };
+  });
+}
+
+// Answer the task the approval was for, with the recorded response — from the
+// coordinator or from a later drain that finished a crashed approval.
+async function completeApproveTask(ws, op, evidence, owner) {
+  const deckRoot = path.dirname(ws);
+  const t = op.task;
+  if (!t?.id || !t.response || !getTask(deckRoot, t.id)) return null;
+  const r = t.response;
+  try {
+    const out = await respondTask(deckRoot, t.id, { operationId: r.operationId, expectedHash: t.subjectHash ?? op.sent.hash, action: r.action ?? "approve", actor: r.actor, payload: r.comment ? { comment: r.comment } : null, selfDeclared: r.selfDeclared === true }, { invoke: () => ({ evidence }), owner });
+    return out.task;
+  } catch (err) {
+    if (err?.code === "stale_subject" || err?.code === "validation_failed") return null; // answered or voided elsewhere; the approval itself stands
+    throw err;
+  }
+}
+
+/**
+ * 7.7 — create the shared record in the saved destination when a plan exists
+ * and policy allows. `waiting_for_plan` until a structurally editable plan is
+ * there; `blocked` (destination kept) when support or writes are missing or
+ * the name is taken; `created` once the binding is confirmed; `noop` with a
+ * `reason` when there is nothing to do. The uncertain-create readback is the
+ * queue's (`drainOnce`).
+ */
+export async function activateDestination(workspaceDir, { adapter = null, client = null, owner, now = Date.now } = {}) {
+  const ws = wsDir(workspaceDir);
+  const io = adapterIo(adapter, ws);
+  const result = (action, extra = {}) => ({ action, ...syncStatus(ws), ...extra });
+  const blocked = (code, message) => result("blocked", { error: { code, message, retryable: false } });
+  const binding = readRecordState(ws);
+  const dest = readDestination(ws);
+  if (dest?.malformed) return blocked("recovery_required", "destination.json is unreadable; inspect it before creating a record");
+  if (!dest) return result("noop", { reason: "no_destination" });
+  if (isBound(binding)) {
+    if (dest.state !== "created") writeDestination(ws, { ...dest, state: "created" });
+    return result("noop", { reason: "already_shared" });
+  }
+  if (!io) return result("noop", { reason: "no_adapter" });
+  if (!hasEditablePlan(ws)) {
+    if (dest.state !== "waiting_for_plan") writeDestination(ws, { ...dest, state: "waiting_for_plan" });
+    return result("waiting_for_plan");
+  }
+  let net = client;
+  try {
+    net ??= await defaultClient({ backendURL: dest.backendURL });
+  } catch (err) {
+    return blocked(classify(err)?.code ?? "capability_unknown", err.message);
+  }
+  const caps = await net.capabilities();
+  if (caps.status !== "supported") {
+    writeDestination(ws, { ...dest, state: "ready_to_create", writes: "unknown" });
+    return blocked("capability_unknown", caps.status === "unknown" ? "the backend's capabilities could not be read; nothing was created" : "the backend does not advertise shared records");
+  }
+  if (caps.sharepointPublish === false) {
+    writeDestination(ws, { ...dest, state: "ready_to_create", writes: "disabled" });
+    return blocked("write_disabled", "this deployment has record writing switched off; the destination is kept");
+  }
+  const target = { folderUrl: dest.webUrl, name: dest.name };
+  try {
+    await net.get({ url: candidateUrl(target) });
+    return blocked("name_exists", `${dest.name} already exists in ${dest.folderName ?? "that folder"}; open it or choose another name`);
+  } catch (err) {
+    const verdict = classify(err);
+    if (!verdict) throw err;
+    if (verdict.code !== "remote_missing") return blocked(verdict.code, err.message);
+  }
+  const local = await io.read();
+  if (!local.ok) return blocked(local.code, local.message);
+  scheduleCreate(ws, { hash: local.hash, ...target });
+  const drained = await drainOnce(ws, { adapter, client: net, owner, now });
+  if (isBound(readRecordState(ws))) {
+    writeDestination(ws, { ...readDestination(ws), state: "created", writes: "enabled" });
+    return result("created");
+  }
+  return drained.action === "blocked" ? result("blocked", { error: drained.lastError }) : result(drained.action);
+}
+
+function persistBlock(ws, error, now) {
+  release(ws, (q) => {
+    q.state = "blocked";
+    q.lastError = { code: error.code, message: error.message ?? error.code, retryable: error.retryable === true };
+    q.updatedAt = nowIso(now);
+  });
+}
+
+// Write only `fields` of an in-memory snapshot over the queue on disk: a save
+// that landed while the request was on the wire (pendingHash) is kept.
+function patch(ws, snapshot, fields) {
+  const q = readSync(ws);
+  for (const f of fields) q[f] = snapshot[f];
+  writeSync(ws, q);
+}
+
+// Drop our claim, editing the queue in the same write.
+function release(ws, edit = null) {
+  let q;
+  try {
+    q = readSync(ws);
+  } catch {
+    return;
+  }
+  if (q.claim?.nonce === NONCE) delete q.claim;
+  if (edit) edit(q);
+  writeSync(ws, q);
+}
+
+function send(net, operation, binding) {
+  if (operation.kind === "create") return net.create({ folderUrl: operation.target.folderUrl, name: operation.target.name, plan: operation.sent.value });
+  return net.put({ selector: recordSelector(binding), base: { eTag: operation.base.eTag, plan: operation.base.value }, plan: operation.sent.value });
+}
+
+// The file a create lands at: the destination's folder link plus the record
+// name (destination.json, 7.7). The record service resolves that link like any
+// pasted one, so the candidate is read through the same client as the record.
+const candidateUrl = (target) => `${String(target.folderUrl).replace(/\/+$/, "")}/${encodeURIComponent(target.name)}`;
+
+// Did a write of unknown outcome land? Content for a save; content AND the
+// exact approval for an approve — `sameContent` ignores what the service owns.
+const landed = (remote, op) => sameContent(remote.plan, op.sent.value) && (op.kind !== "approve" || approvedHash(remote.plan) === op.prepared?.hash);
+
+// A GET before another PUT: did the write of unknown outcome land? Leaves the
+// queue `applying` (it did — the readback is the response), `pending` (it did
+// not, and the remote is where we left it — resend), `applying` with a stale
+// answer (the remote moved without us — merge, then send), or blocked.
+async function readBack(ws, q, net, binding) {
+  const op = q.operation;
+  let remote;
+  try {
+    remote = op.kind === "create" ? await net.get({ url: candidateUrl(op.target) }) : await net.get(recordSelector(binding));
+  } catch (err) {
+    const verdict = classify(err);
+    if (!verdict) throw err;
+    if (verdict.code === "remote_missing" && op.kind === "create") {
+      q.state = "pending"; // nothing at that name: the create never landed
+      writeSync(ws, q);
+      return { q };
+    }
+    release(ws, (queue) => {
+      queue.state = verdict.retryable || verdict.unknown ? "outcome-unknown" : "blocked";
+      queue.lastError = { code: verdict.unknown ? "outcome_unknown" : verdict.code, message: err.message, retryable: Boolean(verdict.retryable) };
+    });
+    return { blocked: true };
+  }
+  if (landed(remote, op)) {
+    q.operation.response = { ...remote, submittedApplied: true, recovered: true };
+    q.state = "applying";
+  } else if (op.kind === "approve") {
+    // never resend an approval blindly: nothing of it landed, so it is void — the human decides again
+    q.operation = null;
+    q.state = q.pendingHash ? "pending" : "idle";
+    q.lastError = null;
+  } else if (op.kind === "create") {
+    // a different file sits at that name: never overwrite it, never invent a second name
+    release(ws, (queue) => {
+      queue.state = "blocked";
+      queue.lastError = { code: "name_exists", message: `${op.target.name} exists in that folder with different content`, retryable: false };
+    });
+    return { blocked: true };
+  } else if (remote.eTag === op.base.eTag) {
+    q.state = "pending"; // remote unchanged since our base: the write never arrived
+    q.lastError = null;
+  } else {
+    q.operation.response = { ...remote, staleAnswer: true };
+    q.state = "applying";
+  }
+  writeSync(ws, q);
+  return { q };
+}
+
+// Apply a persisted response under the lock: merge what came back over what
+// was typed since, advance the confirmed baseline, settle the queue. Keyed by
+// the operation id — a second application of the same response is a no-op.
+async function apply(ws, q, io, binding, backendURL, owner, now) {
+  const op = q.operation;
+  const R = op.response;
+  return runDeckOperation(ws, { operationId: `${op.id}:apply`, kind: "sync-apply", owner }, async (opctx) => {
+    const current = readSync(ws);
+    if (current.operation?.id !== op.id || !current.operation.response) return;
+    const staleAnswer = R.staleAnswer === true;
+    // A stale answer means nothing of ours landed: merge R over our BASE so
+    // every local change since the base is carried forward and sent next.
+    const sent = staleAnswer ? { hash: "sha256:base", value: op.base.value ?? {} } : op.sent;
+    await settle(ws, { io, R, base: op.base, sent, binding, backendURL, token: opctx.token, now, staleAnswer, operation: op });
+  });
+}
+
+// Merge what the service holds over what is local (the pack's rule), advance
+// the confirmed baseline, settle the queue. Shared by a response (`apply`) and
+// a read (`refreshOnce`) — `operation` is the former's, cleared here.
+async function settle(ws, { io, R, base, sent, binding, backendURL, token, now, staleAnswer = false, operation = null }) {
+  const merged = await io.applyRemote({ base, sent, returned: { eTag: R.eTag ?? null, value: R.plan } }, token);
+  advanceBaseline(ws, R, binding, backendURL);
+
+  const next = readSync(ws);
+  if (!merged.ok) {
+    next.state = "blocked";
+    if (merged.code === "remote_conflict") {
+      next.conflict = {
+        conflictId: randomUUID(),
+        expectedHash: merged.hash ?? null,
+        currentETag: R.eTag ?? null,
+        current: R.plan,
+        local: merged.local ?? null,
+        base: base?.value ?? null,
+        sent: operation?.sent ?? sent,
+        merged: merged.merged ?? null,
+        conflicts: merged.conflicts ?? [],
+        at: nowIso(now),
+      };
+      next.operation = null;
+      next.lastError = { code: "remote_conflict", message: `${next.conflict.conflicts.length} field(s) changed on both sides`, retryable: false };
+    } else {
+      // the pack refused the apply: keep the response for a later attempt
+      next.lastError = { code: merged.code, message: merged.message ?? merged.code, retryable: false };
+    }
+    writeSync(ws, next);
+    return merged;
+  }
+  writeAtomic(path.join(ws, "state", EDIT_FILE), { schemaVersion: EDIT_SCHEMA_VERSION, adapterId: io.id, hash: merged.hash, value: merged.value, updatedAt: nowIso(now) });
+  next.operation = null;
+  next.conflict = null;
+  next.lastError = null;
+  next.attempt = 0;
+  next.retryAt = null;
+  if (merged.pending || staleAnswer) {
+    next.state = "pending";
+    next.pendingHash = merged.hash;
+    next.staleRetries = (next.staleRetries ?? 0) + (staleAnswer ? 1 : 0);
+  } else {
+    next.state = "idle";
+    next.pendingHash = null;
+    next.staleRetries = 0;
+    next.lastConfirmedAt = nowIso(now);
+  }
+  writeSync(ws, next);
+  return merged;
+}
+
+function conflictBlock(ws, q, body, now) {
+  release(ws, (queue) => {
+    queue.conflict = {
+      conflictId: randomUUID(),
+      expectedHash: q.operation.sent.hash,
+      currentETag: body?.eTag ?? null,
+      current: body?.current ?? null,
+      local: null,
+      base: q.operation.base?.value ?? null,
+      sent: q.operation.sent,
+      merged: body?.merged ?? null,
+      conflicts: Array.isArray(body?.conflicts) ? body.conflicts : [],
+      at: nowIso(now),
+    };
+    queue.operation = null;
+    queue.state = "blocked";
+    queue.lastError = { code: "remote_conflict", message: `${queue.conflict.conflicts.length} field(s) changed on both sides`, retryable: false };
+  });
+}
+
+/** Stop hook: a request on the wire when the process goes down is of unknown outcome. */
+export function markInFlightUnknown() {
+  for (const ws of inFlight) {
+    try {
+      const q = readSync(ws);
+      if (q.state === "sending") {
+        q.state = "outcome-unknown";
+        q.lastError = { code: "outcome_unknown", message: "the process stopped while the request was on the wire", retryable: false };
+        writeSync(ws, q);
+      }
+    } catch {
+      /* the next drain reports it */
+    }
+  }
+  inFlight.clear();
+}
+
+/**
+ * The daemon's sender: every `intervalMs` (and on `wake`) drain each deck whose
+ * queue has work. One drain per deck at a time. `decks()` lists workspace
+ * dirs, `adapterFor(ws)` the installed adapter or null. Returns `{ stop,
+ * wake }`; `stop` marks in-flight sends unknown — register it as a stop hook.
+ */
+export function startSyncLoop({ decks, adapterFor, intervalMs = 2_000, track = (p) => p, log = () => {}, owner = false } = {}) {
+  const running = new Set();
+  const drain = (ws) => {
+    if (running.has(ws)) return;
+    running.add(ws);
+    track(
+      drainOnce(ws, { adapter: adapterFor(ws), owner })
+        .catch((err) => log(`sync ${ws}: ${err?.code ?? ""} ${err?.message ?? err}`))
+        .finally(() => running.delete(ws)),
+    );
+  };
+  const tick = () => {
+    for (const ws of decks()) {
+      try {
+        const { state, retryAt } = syncStatus(ws);
+        const due = state === "pending" && (!retryAt || Date.parse(retryAt) <= Date.now());
+        if (due || state === "sending" || state === "applying" || state === "outcome-unknown") drain(ws);
+      } catch (err) {
+        log(`sync ${ws}: ${err?.message ?? err}`);
+      }
+    }
+  };
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  wakeHook = drain;
+  tick();
+  return {
+    wake: (ws) => drain(wsDir(ws)),
+    stop() {
+      clearInterval(timer);
+      if (wakeHook === drain) wakeHook = null;
+      markInFlightUnknown();
+    },
+  };
+}