@panphora/clayjs 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
   "license": "MIT",

package/src/core/save.js

@@ -117,6 +117,37 @@ let lastSavedContents = '';
 // A save was requested while one was on the wire; run one more when it settles.
 let pendingSave = false;
 
+// ============================================
+// AUTOSAVE SUSPENSION
+// ============================================
+//
+// clay.wire holds this for the length of an agent request. The save is
+// last-writer-wins with a backup, so an autosave landing while a local process is
+// writing the same file posts the pre-agent document: the server backs the agent's
+// bytes up and writes the browser's, the watcher's revalidation then fails, and
+// the agent's work exists only in Backups while the page reports success.
+//
+// It suspends AUTOsave only. An explicit savePage — Cmd+S, a [trigger-save]
+// button, or the wire's own pre-send flush — is a deliberate act and still runs.
+//
+// Reference counted, because two overlapping requests each hold it. A save
+// skipped while suspended is replayed on release, or the user's edits would sit
+// unsaved until something else happened to mutate the page.
+let autosaveSuspended = 0;
+let autosaveMissed = false;
+
+export function suspendAutosave() {
+  autosaveSuspended++;
+}
+
+export function resumeAutosave() {
+  if (autosaveSuspended === 0) return;
+  autosaveSuspended--;
+  if (autosaveSuspended > 0 || !autosaveMissed) return;
+  autosaveMissed = false;
+  savePageThrottled();
+}
+
 function skipped_(msg) {
   return { ok: false, msg, msgType: 'skipped', code: null, etag: null };
 }
@@ -451,6 +482,16 @@ export function savePageThrottled(callback = () => {}) {
     return Promise.resolve(skipped);
   }
 
+  // Every autosave path lands here — the mutation-driven one, the [persist] input
+  // timer, and live-sync's convergence save after a protected apply — which is
+  // why the suspension lives at this one entry rather than at each caller.
+  if (autosaveSuspended > 0) {
+    autosaveMissed = true;
+    const skipped = skipped_('Autosave suspended');
+    callback(skipped);
+    return Promise.resolve(skipped);
+  }
+
   // For autosave: while the page is still settling, content must differ from BOTH
   // the load-time baseline and the last save, so module setup churn cannot trigger
   // a save. Once settled, the baseline veto is disarmed and only the last save

package/src/lib/dirty-gate.js

@@ -27,6 +27,7 @@
 
 import Mutation from './mutation.js';
 import { isEditMode } from '../core/is-edit-mode.js';
+import { STRIP_FROM_COMPARISON, SNAPSHOT_REMOVE_SELECTOR } from './region-policy.js';
 
 let changes = 0;
 let clearedAt = 0;
@@ -34,6 +35,22 @@ let paused = false;
 let started = false;
 
 const PERSIST_CONTROLS = 'input[persist], textarea[persist], select[persist]';
+
+// Regions the comparison never sees. The hub feed already skips them, through
+// `require: 'autosave'`, and the input feed has to skip them for the same
+// reason: their content is stripped from the comparison clone, so an edit inside
+// one can never produce a dirty root, and counting it marks the page dirty with
+// nothing for the oracle to find — permanently, since only a save clears the
+// counter and churn in these regions triggers none.
+//
+// This is not a relaxation of "never under-report". A control here is absent
+// from the clone by definition, so there is nothing about it to under-report.
+// It matters because a mounted tool (redpen's answer field, any panel that
+// marks itself no-save) is a real <textarea> in the document: one keystroke in
+// it used to freeze the live-sync save baseline for the rest of the session,
+// after which every incoming disk change was diffed against a stale base, and
+// the previous change was spliced back over the newer one and written to disk.
+const GATE_IGNORE = `${STRIP_FROM_COMPARISON}, ${SNAPSHOT_REMOVE_SELECTOR}`;
 const probeCache = new WeakMap();
 
 function onUserInput(event) {
@@ -42,9 +59,9 @@ function onUserInput(event) {
   // during a morph's async resource wait, which must keep the page dirty.
   const el = event.target;
   if (!el || el.nodeType !== 1) return;
-  if (el.matches('input, textarea, select') || el.isContentEditable) {
-    changes++;
-  }
+  if (!(el.matches('input, textarea, select') || el.isContentEditable)) return;
+  if (el.closest(GATE_IGNORE)) return;
+  changes++;
 }
 
 export function startDirtyGate() {

package/src/loader-logic.js

@@ -21,10 +21,11 @@ export const PLUGIN_PATHS = {
   sortable:  { path: "plugins/sortable.js",        editOnly: true,  default: false },
   undo:      { path: "plugins/undo.js",            editOnly: true,  default: false },
   cms:       { path: "vendor/hypercms.vendor.js",  editOnly: false, default: false },
+  wire:      { path: "plugins/wire.js",            editOnly: false, default: false },
   demo:      { path: "plugins/demo.js",            editOnly: false, default: false },
 };
 
-const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync", "demo"];
+const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync", "wire", "demo"];
 
 function parseCsv(params, key, enabled, apply) {
   const raw = params.get(key);

package/src/loader.js

@@ -102,6 +102,8 @@ function attachPluginMember(path, mod) {
     clay.morph = mod.morph;
   } else if (path === "vendor/hypercms.vendor.js") {
     clay.cms = mod.cms || mod.default;
+  } else if (path === "plugins/wire.js") {
+    clay.wire = mod.wire || mod.default;
   } else if (path === "plugins/demo.js") {
     clay.demo = mod.demo;
   } else if (path === "vendor/richclay.vendor.js") {

package/src/plugins/wire.js

@@ -0,0 +1,598 @@
+import { isEditMode } from "../core/is-edit-mode.js";
+
+/**
+ * clay.wire — a per-file control channel between this page and a local process.
+ *
+ * The page sends a request ("rewrite the section I circled"), a process running
+ * in the user's own terminal answers with progress and a terminal frame, and
+ * that process edits the FILE. HTML never rides the wire: the agent's change
+ * reaches this page as an ordinary external file change, through live-sync. That
+ * split is why this module has no morphing, no content lane, and no opinion
+ * about what a payload contains.
+ *
+ * Three constraints shape everything below.
+ *
+ * It must not import the sync plugin. `sync/live-sync.js` opens an EventSource
+ * on evaluation, so a static import here would give every wire page a live-sync
+ * connection it never asked for. The one thing this module needs from live-sync,
+ * "a disk frame just landed", arrives as the `clay:sync-applied` DOM event, which
+ * couples the two through the document rather than through the module graph.
+ *
+ * It runs in view mode (`editOnly: false` in the loader's plugin table), because
+ * the `/htmlfile questions` consumer and every read-only review page need it. So
+ * nothing here may assume the save lane exists: on a view-mode page `clay.save`
+ * is absent, and the save-protection below is skipped entirely rather than
+ * guarded at each call site.
+ *
+ * The stream is lazy. A browser allows six connections per origin, the pool is
+ * shared across tabs, and live-sync already holds one per tab, so a second
+ * permanent stream means three tabs of one project saturate the origin and the
+ * next save queues behind them. The wire is idle between requests by definition,
+ * so it connects on the first in-flight request and disconnects after the last
+ * one ends.
+ */
+
+// Every request carries a deadline, from before its POST until it ends. Nothing
+// else can end one: the wire has no "the handler detached" signal, and a handler
+// that acknowledged and then died would otherwise leave the request open, its
+// promise unresolved, and saving paused for the rest of the session. That is the
+// worst outcome available here, worse than reporting a slow agent as failed,
+// because the page silently stops saving.
+//
+// It runs on two lengths. Before the first frame, the handler has taken the
+// request (the POST already reports delivered: 0 when nobody was attached) and
+// only has to say so.
+const ACK_TIMEOUT_MS = 15000;
+
+// After that, it is an inactivity deadline: every frame rearms it, and `wire
+// serve` streams the child's stdout as status frames, so an agent that reports
+// what it is doing keeps its request alive indefinitely. A silent one gets this
+// long. Its work still reaches the page if it lands later, through live-sync,
+// since the wire never carried the content anyway.
+const SILENCE_TIMEOUT_MS = 120000;
+
+// `wire/done` means the handler finished writing the file. It does not mean this
+// page has rendered the change: that arrives on the live-sync lane after the
+// watcher's quiet interval, and nothing orders the two. So a finished request
+// waits in `landing` for the disk frame, and gives up waiting after this.
+const LANDING_TIMEOUT_MS = 4000;
+
+const SAVE_FLUSH_TIMEOUT_MS = 5000;
+
+// A long review session sends many requests. Records outlive their request so a
+// UI can still show what happened, so the map needs a ceiling; terminated ones
+// are dropped oldest-first.
+const MAX_RECORDS = 50;
+
+const OPEN_STATES = new Set(["sent", "acked"]);
+
+// Once a request has ended it stays ended. Several things can arrive after the
+// end and each would otherwise rewrite it: a POST that was already on the wire
+// when the user cancelled, an ack timer that fires after a fast error, a done
+// for a request the handler also errored.
+const TERMINAL_STATES = new Set(["done", "error", "cancelled"]);
+
+const records = new Map();
+const listeners = new Set();
+
+let stream = null;
+let streamReady = null;
+let landingWatch = 0;
+let landingHandler = null;
+
+function newId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `page-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+// Every URL is resolved against the real origin. A `<base href>` in the authored
+// document would otherwise point this page's control channel at an origin the
+// document chose, which is the same trap live-sync documents on its own stream.
+function wireURL(path) {
+  return new URL(path, window.location.origin).href;
+}
+
+function view(rec) {
+  return {
+    id: rec.id,
+    type: rec.type,
+    state: rec.state,
+    text: rec.text,
+    error: rec.error,
+    startedAt: rec.startedAt,
+  };
+}
+
+function emit(rec) {
+  const snapshot = view(rec);
+  for (const fn of listeners) {
+    try {
+      fn(snapshot);
+    } catch (err) {
+      console.error("clay.wire: a listener threw", err);
+    }
+  }
+  document.dispatchEvent(new CustomEvent("clay:wire-state", { detail: snapshot }));
+}
+
+function setState(rec, state) {
+  if (rec.state === state) return;
+  rec.state = state;
+  emit(rec);
+}
+
+// The request deadline. Armed before the POST and rearmed by every frame, so a
+// request is bounded from end to end rather than only up to its ack.
+function arm(rec, ms, message) {
+  clearTimeout(rec.timer);
+  rec.timer = setTimeout(() => {
+    rec.timer = null;
+    finish(rec, "error", message);
+  }, ms);
+}
+
+function disarm(rec) {
+  clearTimeout(rec.timer);
+  rec.timer = null;
+}
+
+function prune() {
+  if (records.size <= MAX_RECORDS) return;
+  for (const [id, rec] of records) {
+    if (records.size <= MAX_RECORDS) break;
+    if (!OPEN_STATES.has(rec.state) && rec.state !== "landing") records.delete(id);
+  }
+}
+
+// --- the stream ------------------------------------------------------------
+
+// A page never names a file and never asks for the handler role. Its target
+// comes from its own URL, through the same funnel live-sync's save uses, and any
+// file it supplied would be discarded server-side; the handler slot is refused
+// to browsers outright, since a page holding it could receive every request on
+// the file, including other tabs', and answer with fabricated terminal frames.
+function openStream() {
+  if (streamReady) return streamReady;
+
+  const path = `/_/wire/subscribe?page-url=${encodeURIComponent(window.location.href)}`;
+  stream = new EventSource(wireURL(path));
+
+  stream.onmessage = (event) => {
+    let frame;
+    try {
+      frame = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    handleFrame(frame);
+  };
+
+  // Native EventSource reconnects on its own and carries Last-Event-ID, and wire
+  // frames are stamped with one, so the server replays any terminal frame this
+  // page missed during the gap: an in-flight request recovers without help. A
+  // request cancelled during the gap is dropped by handleFrame, since its record
+  // is no longer open. What a reconnect cannot bring back is a status frame,
+  // which is display only. So there is nothing to do here.
+  stream.onerror = () => {};
+
+  streamReady = new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    stream.onopen = finish;
+    // Sending is more important than subscribing: a request that never goes out
+    // because the stream would not open is worse than one whose early frames
+    // are missed.
+    setTimeout(finish, 2000);
+  });
+  return streamReady;
+}
+
+function closeStreamIfIdle() {
+  for (const rec of records.values()) {
+    if (OPEN_STATES.has(rec.state)) return;
+  }
+  if (!stream) return;
+  stream.close();
+  stream = null;
+  streamReady = null;
+}
+
+function handleFrame(frame) {
+  if (!frame || typeof frame.id !== "string") return;
+  const rec = records.get(frame.id);
+  // An id this page did not issue, or one it has stopped caring about. Cancel
+  // means stop completely, so a cancelled request's late frames are dropped here
+  // rather than reopening a lifecycle the user ended.
+  if (!rec || !OPEN_STATES.has(rec.state)) return;
+
+  switch (frame.type) {
+    case "wire/ack":
+      // Rearmed, not cleared. The handler acknowledges within milliseconds of
+      // picking a request up, so clearing here would leave every working request
+      // with no deadline at all.
+      arm(rec, SILENCE_TIMEOUT_MS, "the agent stopped responding");
+      setState(rec, "acked");
+      break;
+    case "wire/status":
+      arm(rec, SILENCE_TIMEOUT_MS, "the agent stopped responding");
+      rec.text = typeof frame.text === "string" ? frame.text : "";
+      rec.state = "acked";
+      emit(rec);
+      break;
+    case "wire/done":
+      land(rec);
+      break;
+    case "wire/error":
+      finish(rec, "error", frame.text || "the handler reported an error");
+      break;
+    default:
+      break;
+  }
+}
+
+// --- the landing state -----------------------------------------------------
+
+// `clay:sync-applied` fires on every successful remote morph, from live-sync's
+// single apply choke point, whether or not the sync plugin was loaded by this
+// page's own URL. Listening for it is what makes "done" mean "you can see it"
+// instead of "the agent stopped typing", and it costs no import.
+function watchLandings() {
+  if (landingHandler) return;
+  landingHandler = (event) => {
+    // Both apply paths dispatch this event. A peer frame is another tab's edit,
+    // so completing a landing on one would report done for bytes that are not
+    // the ones this request asked for.
+    if (event.detail?.source === "peer") return;
+    // One record per frame, oldest first (Map iteration is insertion order). A
+    // frame proves one landing and says nothing about any other request, and a
+    // request left waiting still ends on its own next frame or its timer.
+    for (const rec of records.values()) {
+      if (rec.state === "landing") {
+        finish(rec, "done", null);
+        return;
+      }
+    }
+  };
+  document.addEventListener("clay:sync-applied", landingHandler);
+}
+
+function unwatchLandingsIfIdle() {
+  if (landingWatch > 0 || !landingHandler) return;
+  document.removeEventListener("clay:sync-applied", landingHandler);
+  landingHandler = null;
+}
+
+function land(rec) {
+  if (TERMINAL_STATES.has(rec.state) || rec.state === "landing") return;
+  disarm(rec);
+  rec.state = "landing";
+  landingWatch++;
+  watchLandings();
+  rec.landingTimer = setTimeout(() => {
+    // The change may have landed in a way this page cannot observe (no sync
+    // plugin, a frame that morphed nothing). Reporting done late is right;
+    // reporting a working agent as failed is not.
+    finish(rec, "done", null);
+  }, LANDING_TIMEOUT_MS);
+  emit(rec);
+  // The wire is done with this request even though the page is still waiting for
+  // its bytes, so the connection can go now.
+  closeStreamIfIdle();
+}
+
+function finish(rec, state, error) {
+  if (TERMINAL_STATES.has(rec.state)) return;
+  const wasLanding = rec.state === "landing";
+  disarm(rec);
+  clearTimeout(rec.landingTimer);
+  rec.landingTimer = null;
+  // A POST still on the wire has nothing left to report to, and an unbounded
+  // fetch is the one thing the deadline cannot otherwise reach.
+  rec.abort?.abort();
+  if (wasLanding) {
+    landingWatch--;
+    unwatchLandingsIfIdle();
+  }
+  rec.error = error;
+  rec.state = state;
+  releaseSaving(rec);
+  emit(rec);
+  closeStreamIfIdle();
+  prune();
+  if (rec.settle) {
+    const settle = rec.settle;
+    rec.settle = null;
+    settle(view(rec));
+  }
+}
+
+// --- save protection -------------------------------------------------------
+//
+// Two outbound problems the scoped live-sync merge does not touch, because it
+// fixes the return path only.
+//
+// Save before send: autosave is debounced, so a request sent within that window
+// hands the agent a file that does not contain the paragraph the user just typed
+// and is asking about.
+//
+// Suspend autosave while a request is in flight: the save is last-writer-wins
+// with a backup, not a reject. An autosave landing inside the watcher's poll and
+// quiet window posts the pre-agent document, the server backs the agent's bytes
+// up and still writes the browser's, the watcher's revalidation then fails, and
+// nothing is published. The handler reports done, the page shows success, and
+// the agent's work exists only in Backups.
+//
+// The lever is the save lane's own suspension, not a mutation-hub pause. Two
+// reasons. The [persist] input autosave never goes through the hub at all — it is
+// a raw input listener and a timer (autosave.js) — so a hub pause misses the
+// clobber it is supposed to prevent. And pausing the hub blinds the scoped-sync
+// dirty gate, whose one invariant is that it may over-report but must never
+// under-report: a DOM edit the user made during the request would then read as
+// clean, and the agent's frame would full-morph it away.
+
+let saveDepth = 0;
+let saveLane = null;
+
+// Imported lazily and only in edit mode, through one shared promise. The module
+// is not loaded on a view-mode page, so a static import from this
+// `editOnly: false` plugin would drag the save lane into view mode to do nothing.
+let saveLaneReady = null;
+function loadSaveLane() {
+  if (!saveLaneReady) saveLaneReady = import("../core/save.js");
+  return saveLaneReady;
+}
+
+async function holdSaving(rec) {
+  if (!isEditMode || rec.holdsSave) return;
+  // Resolve the module BEFORE claiming the hold. Claiming it first and awaiting
+  // afterwards leaves a window where a cancel releases a hold that was never
+  // taken, and the import that resumes after it suspends a lane nothing will
+  // ever resume.
+  const lane = await loadSaveLane();
+  if (rec.state !== "sent") return;
+  saveLane = lane;
+  rec.holdsSave = true;
+  if (saveDepth++ > 0) return;
+  lane.suspendAutosave();
+}
+
+function releaseSaving(rec) {
+  if (!rec.holdsSave) return;
+  rec.holdsSave = false;
+  if (--saveDepth > 0) return;
+  saveDepth = 0;
+  saveLane?.resumeAutosave();
+}
+
+function once(eventName, timeout) {
+  return new Promise((resolve) => {
+    let done = false;
+    const settle = () => {
+      if (done) return;
+      done = true;
+      document.removeEventListener(eventName, settle);
+      resolve();
+    };
+    document.addEventListener(eventName, settle);
+    setTimeout(settle, timeout);
+  });
+}
+
+/**
+ * Put what the user is looking at on disk, or fail the request.
+ *
+ * The wire's promise is that the agent reads the document the user is asking
+ * about. A flush that could not deliver that has to end the request: posting
+ * anyway means an agent editing a file without the paragraph it was asked about,
+ * silently, which is worse than an error the UI can show.
+ */
+async function flushSave() {
+  if (!isEditMode) return;
+  const clay = window.clay;
+  if (!clay || typeof clay.save !== "function") return;
+
+  // isSaveInProgress comes from the module, not from clay.internals: that
+  // surface is an opt-in satellite script, absent on every page the loader
+  // builds, so reading it here made "is a save on the wire" permanently false.
+  const { isSaveInProgress } = await import("../core/save-core.js");
+  const deadline = Date.now() + SAVE_FLUSH_TIMEOUT_MS;
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (isSaveInProgress()) {
+      await once("clay:save-saved", Math.max(0, deadline - Date.now()));
+    }
+
+    const result = await clay.save();
+    // `ok` is the outcome and msgType is the server's severity, so a save that
+    // landed with a warning is a success. `skipped` covers two outcomes: nothing
+    // to save, and a save already on the wire. Only the second means these bytes
+    // never left, and asking whether one is still in progress tells them apart.
+    if (result?.ok) return;
+    if (result?.msgType === "skipped" && !isSaveInProgress()) return;
+    if (result?.msgType === "error" || result?.msgType === "unknown") {
+      throw new Error(`could not save this page first: ${result.msg || result.msgType}`);
+    }
+    if (Date.now() >= deadline) break;
+  }
+  throw new Error("could not save this page before sending");
+}
+
+// --- sending ---------------------------------------------------------------
+
+async function postFrame(body, signal) {
+  const response = await fetch(wireURL("/_/wire/send"), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Page-URL": window.location.href,
+    },
+    body: JSON.stringify(body),
+    signal,
+  });
+  let reply = null;
+  try {
+    reply = await response.json();
+  } catch {
+    reply = null;
+  }
+  return { ok: response.ok, status: response.status, reply };
+}
+
+/**
+ * Send one request and track it to a terminal state.
+ *
+ * Returns a handle immediately; `handle.done` resolves with the final snapshot
+ * and never rejects, because a failed request is an outcome the UI renders
+ * rather than an exception it catches.
+ */
+function send(payload, opts = {}) {
+  const id = typeof opts.id === "string" && opts.id ? opts.id : newId();
+  const type = typeof opts.type === "string" && opts.type ? opts.type : "wire/request";
+
+  // The id is request identity on the wire, on both sides: a reused one would
+  // route the first request's frames to the second record, leaving the first
+  // unresolvable and its save hold never released. Refused as an outcome rather
+  // than thrown, so a UI renders it the way it renders any other failure.
+  if (records.has(id)) {
+    const clash = {
+      id,
+      type,
+      state: "error",
+      text: "",
+      error: "a request with this id is already on the wire",
+      startedAt: Date.now(),
+    };
+    return {
+      id,
+      get state() {
+        return clash.state;
+      },
+      done: Promise.resolve(view(clash)),
+      cancel: () => false,
+    };
+  }
+
+  const rec = {
+    id,
+    type,
+    state: "sent",
+    text: "",
+    error: null,
+    startedAt: Date.now(),
+    timer: null,
+    landingTimer: null,
+    abort: typeof AbortController === "function" ? new AbortController() : null,
+    holdsSave: false,
+    settle: null,
+  };
+  rec.done = new Promise((resolve) => {
+    rec.settle = resolve;
+  });
+  records.set(id, rec);
+  emit(rec);
+
+  const dispatch = async () => {
+    // The record is re-checked after every await. A cancel can land in any of
+    // these gaps, and a step that ran on regardless would open a stream nobody
+    // closes or post a request the user already took back.
+    await holdSaving(rec);
+    if (rec.state !== "sent") return;
+
+    await flushSave();
+    if (rec.state !== "sent") return;
+
+    // Subscribe before posting. A handler can acknowledge in single-digit
+    // milliseconds, a fresh subscription deliberately replays nothing, and only
+    // terminal frames are retained at all, so posting first is how a page ends
+    // up watching a request whose ack it already missed.
+    await openStream();
+    if (rec.state !== "sent") {
+      closeStreamIfIdle(); // the stream this cancelled request just opened
+      return;
+    }
+
+    // Armed BEFORE the POST, not after it. A stalled fetch would otherwise leave
+    // the request unbounded, and an ack that arrives while the POST is still in
+    // flight — the ordinary case, since the page subscribed first — would be
+    // followed by a fresh ack timer that fails a healthy request 15s later.
+    arm(rec, ACK_TIMEOUT_MS, "the agent never answered");
+
+    const { ok, status, reply } = await postFrame(
+      { type: rec.type, id: rec.id, text: opts.text, payload },
+      rec.abort?.signal
+    );
+
+    // A frame may have moved this request on while its own POST was in flight.
+    // Only a request still waiting on that POST may be failed by it.
+    if (rec.state !== "sent") return;
+
+    if (!ok) {
+      finish(rec, "error", `the wire refused this request (${status})`);
+      return;
+    }
+    if (!reply || reply.delivered === 0) {
+      // Accepted by the router and taken by nobody. Reporting this as an error
+      // rather than a pending request is the difference between a UI that says
+      // "start an agent" and one that spins forever.
+      finish(rec, "error", "no agent is attached to this file");
+    }
+  };
+
+  dispatch().catch((err) => {
+    finish(rec, "error", err && err.message ? err.message : String(err));
+  });
+
+  return {
+    id,
+    get state() {
+      return rec.state;
+    },
+    done: rec.done,
+    cancel: () => cancel(id),
+  };
+}
+
+/**
+ * Stop completely: the request ends here, its late frames are ignored, and the
+ * handler is asked to stop. A cancel that only hid the spinner would leave the
+ * agent writing the file the user just took back.
+ */
+function cancel(id) {
+  const rec = records.get(id);
+  if (!rec || !OPEN_STATES.has(rec.state)) return false;
+  postFrame({ type: "wire/cancel", id }).catch(() => {});
+  finish(rec, "cancelled", null);
+  return true;
+}
+
+function get(id) {
+  const rec = records.get(id);
+  return rec ? view(rec) : undefined;
+}
+
+function list() {
+  return [...records.values()].map(view);
+}
+
+function isBusy() {
+  for (const rec of records.values()) {
+    if (OPEN_STATES.has(rec.state)) return true;
+  }
+  return false;
+}
+
+function on(fn) {
+  if (typeof fn !== "function") return () => {};
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+export const wire = { send, cancel, get, list, isBusy, on };
+
+export default wire;

package/src/sync/live-sync.js

@@ -423,6 +423,34 @@ class LiveSync {
       if (this.onConnect) this.onConnect();
     };
 
+    // The cursor frame is a NAMED SSE event, so it never reaches onmessage and
+    // never looks like data. Its `resync` flag says the server could not retain
+    // everything between where this client resumed and the baseline it is
+    // sending: what this page holds is stale in a way no replay will fix.
+    //
+    // The repair is the token-free fetch of the served document this class
+    // already runs for a change too large to send, so noticing the flag is the
+    // whole of the work.
+    this.sse.addEventListener('cursor', (event) => {
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      if (!data || data.resync !== true) return;
+      console.log('[LiveSync] Server could not replay everything; refetching the document');
+      // _fetchServedDocument, deliberately, and not _fetchExternalChange: that
+      // one drops a fetch whose seq is at or below the external watermark, and
+      // the cursor baseline routinely is, since it is the server's high-water
+      // mark and our own last applied change may already have reached it. A
+      // resync that skipped itself for being "already seen" would leave the page
+      // permanently stale, which is the exact failure the flag exists to report.
+      this._fetchServedDocument(typeof data.seq === 'number' ? data.seq : undefined, {
+        repair: true,
+      });
+    });
+
     this.sse.onmessage = (event) => {
       const data = JSON.parse(event.data);
 
@@ -654,20 +682,29 @@ class LiveSync {
    * frame the epoch check refused (the fetched body is whatever disk holds
    * NOW, which is always safe to apply).
    */
-  _fetchServedDocument(seq, attempt = 0) {
+  _fetchServedDocument(seq, { attempt = 0, repair = false } = {}) {
     const epoch = this._saveEpoch;
     fetch(new URL(window.location.href), { cache: 'no-store' })
       .then((response) => (response.ok ? response.text() : null))
       .then((html) => {
         if (this.isDestroyed || html == null) return;
-        if (typeof seq === 'number' && seq < this._lastExternalSeq) return;
+        if (typeof seq === 'number' && seq < this._lastExternalSeq) {
+          // A newer external change superseded this one, and its own fetch will
+          // queue a body. Except for a repair: that one exists because the server
+          // said replay cannot fix this page, so if the newer fetch fails there is
+          // nothing else coming. Refetch rather than drop the only repair.
+          if (repair && attempt < 3) {
+            this._fetchServedDocument(seq, { attempt: attempt + 1, repair });
+          }
+          return;
+        }
         if (this._saveEpoch > epoch) {
           // An own save landed while the GET was in flight, so this body may
           // predate it. Save-response order proves nothing about disk-write
           // order — refetch for the newest bytes instead of dropping.
           if (attempt < 3) {
             console.log('[LiveSync] Refetching external change: own save landed mid-fetch');
-            this._fetchServedDocument(seq, attempt + 1);
+            this._fetchServedDocument(seq, { attempt: attempt + 1, repair });
           }
           return;
         }
@@ -989,8 +1026,12 @@ class LiveSync {
       // onmessage before applyUpdate is ever called. Covers every SSE morph
       // source (peer edit, version restore, body-swap) since they all funnel
       // through this single choke point.
+      //
+      // `source` is what lets a listener tell the two apply paths apart. clay.wire
+      // waits for a DISK frame to call an agent's write landed, and another tab's
+      // edit arriving first would otherwise report the wrong bytes as delivered.
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq }
+        detail: { seq, source: 'peer' }
       }));
     } finally {
       this._log('applyUpdate - morph complete, resuming mutations');
@@ -1042,7 +1083,14 @@ class LiveSync {
       const parser = new DOMParser();
       const newDoc = parser.parseFromString(html, 'text/html');
 
-      if (pageMaybeDirty()) {
+      // Lane-guarded exactly like the peer path. A view-mode tab has no save
+      // baseline — every writer of lastSavedContents is edit-gated — so
+      // protectDiskDoc can only ever refuse, and the frame would hold, retry
+      // every 3s, and hold again forever. The gate still reads dirty there,
+      // because persistProbeDirty inspects the live DOM and a visitor can type
+      // into a [persist] field. Before the resync repair this path was
+      // unreachable outside the live lane; now it is the repair's own route.
+      if (this.lane === 'live' && pageMaybeDirty()) {
         const protection = protectDiskDoc({ newDoc });
         if (!protection.ok) {
           // Hold: nothing morphs, no baseline moves, and deliberately NO
@@ -1094,7 +1142,7 @@ class LiveSync {
 
       window.scrollTo(scrollX, scrollY);
 
-      if (retainedRoots === 0 && !pageMaybeDirty()) {
+      if (this.lane === 'live' && retainedRoots === 0 && !pageMaybeDirty()) {
         // Clean apply: the DOM now IS the disk state, so a local comparison
         // capture of it is the truthful baseline. The next no-op save skips,
         // beforeunload stays quiet. The dirty re-check matters: typing that
@@ -1115,7 +1163,7 @@ class LiveSync {
       }
 
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq }
+        detail: { seq, source: 'disk' }
       }));
     } finally {
       this._log('applyExternal - morph complete, resuming mutations');