@mirrowel/opencode-openshare 0.0.0-stage → 0.1.0

package/dist/core.js

@@ -0,0 +1,1944 @@
+// Open(code)Share — the forwarding engine.
+//
+// Design contract (unchanged from the original single file):
+//  - Dumb forwarder: it forwards events, never diffs. Delivery reliability
+//    = ack + retain-until-acked disk spool (temporary buffer, replayed on
+//    reconnect) + the share binding persisted INSIDE opencode (session
+//    metadata) so recovery never depends on the spool.
+//  - One share per MAIN session; child sessions (session info.parentID)
+//    route into the parent's share. (message info.parentID is the
+//    replied-to message — NOT a subagent marker.)
+//  - Status = last signal: busy -> live; idle -> completed, or error if
+//    any part error / retry was seen. Always resumable.
+//  - Model label: config template ($Provider/$Model placeholders,
+//    literals as-is, "" hides) resolved from the user message's actual
+//    model; rides every user message (robust, free).
+//  - Optional read auth: authLogin/authPassword are sent on create AND
+//    attach (resume retroactively applies/updates credentials; empty on
+//    attach REMOVES protection — an intentional owner action).
+//  - Mismatch protocol: attach refused / share gone / worker rev below
+//    our acked rev -> fresh create (never merge into a bad base); nacked
+//    or dropped frames -> spool replay; stale extras -> left for the
+//    next prompt's keyed merge to correct. All logged loudly.
+//  - Undo needs nothing here: opencode publishes info.revert on the
+//    session item; the viewer hides the reverted range while it is set.
+//
+// Share modes:
+//  - "all": every session shares from its first event (the CI shape —
+//    behavior identical to the original single-file plugin).
+//  - "manual": sessions stay dormant until metadata.openshare.enabled is
+//    set on the MAIN session (the TUI /share flow). Activation runs a
+//    full backfill (session tree, messages, parts, models, diff) through
+//    the same keyed queue, so a share started mid-session is complete.
+//    Clearing the flag (or deleting the key) deletes the share — the
+//    same path as session.deleted.
+//
+// Session metadata shape (metadata.openshare):
+//  - all-mode binding: { id, secret, rev, url }
+//  - manual-mode:      { id, secret, rev, url, enabled: true, opts? }
+//    opts: { ttlDays?, authLogin?, authPassword?, modelLabel? } optional
+//    per-session overrides (capture at activation; modelLabel applies
+//    immediately, the rest at create/attach).
+//  - The plugin strips this key from everything it syncs — the write
+//    secret must never reach viewers.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { METADATA_KEY, loadConfig, resolveShareMode, spoolDirFor, URL_FILE_NONE, resolveServer, saveServerToken } from "./config.js";
+const DEFAULT_POLICY = {
+    mode: "persistent",
+    turnGraceMs: 120000,
+    idleDropMs: 600000,
+    finalizeAfterMs: 300000,
+    debounceMinMs: 0,
+    debounceMaxMs: Infinity,
+    completedDelayMaxMs: Infinity,
+};
+// Stderr policy (owner directive): in manual mode (TUI present) stderr is
+// for ACTUAL ERRORS only — informational lines (live:/url file:/mode
+// banner, lifecycle traces) are suppressed; the TUI surfaces the URL.
+// All-mode (CI/server-only) keeps its stderr contract (announce lines,
+// silenceable via announceStderr). Error-class lines always reach stderr.
+let stderrInfoAllowed = true;
+const log = (...a) => {
+    if (!stderrInfoAllowed)
+        return;
+    try {
+        console.error(`[${METADATA_KEY}]`, ...a);
+    }
+    catch { }
+};
+/** Error-class log: reaches stderr in BOTH modes (worker down, refused
+ * init, mismatch recreate, timeouts — things an owner must see even with
+ * the TUI installed). */
+const logError = (...a) => {
+    try {
+        console.error(`[${METADATA_KEY}]`, ...a);
+    }
+    catch { }
+};
+function formatLabel(template, model) {
+    if (template === "")
+        return "";
+    if (!model)
+        return template ?? "";
+    return (template ?? "")
+        .replace(/\$Provider/g, model.providerID ?? "")
+        .replace(/\$provider/g, model.providerID ?? "")
+        .replace(/\$Model/g, model.modelID ?? "")
+        .replace(/\$model/g, model.modelID ?? "");
+}
+function itemFor(type, data, sessionID) {
+    if (type === "model")
+        return { key: `model/${sessionID}`, item: { type, sessionID, data } };
+    if (type === "prefs")
+        return { key: "prefs", item: { type, data } };
+    if (type === "session")
+        return { key: `session/${data?.id ?? ""}`, item: { type, data } };
+    if (type === "message")
+        return { key: `message/${data?.id ?? ""}`, item: { type, data } };
+    if (type === "part")
+        return { key: `part/${data?.messageID ?? ""}/${data?.id ?? ""}`, item: { type, data } };
+    if (type === "session_diff")
+        return { key: `session_diff/${sessionID}`, item: { type, sessionID, data } };
+    return undefined;
+}
+// session items must never carry our binding (the secret would reach
+// viewers) — strip our metadata key from anything we enqueue
+function redact(info) {
+    if (!info?.metadata || typeof info.metadata !== "object")
+        return info;
+    if (!(METADATA_KEY in info.metadata))
+        return info;
+    const metadata = { ...info.metadata };
+    delete metadata[METADATA_KEY];
+    return { ...info, metadata };
+}
+function shareFlag(info) {
+    const raw = info?.metadata?.[METADATA_KEY];
+    if (!raw || typeof raw !== "object")
+        return { enabled: false, opts: undefined };
+    const record = raw;
+    if (record.enabled !== true)
+        return { enabled: false, opts: undefined };
+    const optsRaw = record.opts;
+    const opts = {};
+    if (optsRaw && typeof optsRaw === "object") {
+        const o = optsRaw;
+        if (typeof o.ttlDays === "number" && o.ttlDays > 0)
+            opts.ttlDays = o.ttlDays;
+        if (typeof o.authLogin === "string")
+            opts.authLogin = o.authLogin;
+        if (typeof o.authPassword === "string")
+            opts.authPassword = o.authPassword;
+        if (typeof o.modelLabel === "string")
+            opts.modelLabel = o.modelLabel;
+    }
+    return { enabled: true, opts: Object.keys(opts).length ? opts : undefined };
+}
+export function createEngine(deps) {
+    let cfg = loadConfig(deps.pluginDir, deps.options);
+    const mode = resolveShareMode(cfg, deps);
+    // stderr = errors only when the TUI part exists (the TUI surfaces URLs)
+    if (mode === "manual")
+        stderrInfoAllowed = false;
+    if (process.env.OPENSHARE_DEBUG_FILE) {
+        // diagnostic ground truth for the suites (never set in production)
+        try {
+            writeFileSync(process.env.OPENSHARE_DEBUG_FILE, JSON.stringify({
+                mode,
+                directory: deps.directory,
+                worktree: deps.worktree,
+                pluginDir: deps.pluginDir,
+                shareModeCfg: cfg.shareMode ?? null,
+            }, null, 2));
+        }
+        catch { }
+    }
+    const server = resolveServer(cfg);
+    if (!server || !server.url) {
+        log("disabled: no share server configured (workerUrl or a servers entry)");
+        return {
+            mode,
+            config: () => cfg,
+            hooks: {
+                event: async () => { },
+                dispose: async () => { },
+            },
+        };
+    }
+    log(`share mode: ${mode} (directory: ${deps.directory ?? "?"} worktree: ${deps.worktree ?? "?"})`);
+    const resolveTargets = () => {
+        const merged = {};
+        if (cfg.workerUrl)
+            merged[cfg.workerUrl] = { token: cfg.createToken || "", active: true };
+        if (cfg.servers)
+            for (const [u, e] of Object.entries(cfg.servers))
+                merged[u] = { ...merged[u], ...e };
+        const urls = Object.keys(merged);
+        const actives = urls.filter((u) => merged[u].active);
+        const chosen = actives.length ? actives : urls.slice(0, 1);
+        return chosen.map((url) => ({ url, entry: merged[url] }));
+    };
+    let targets = resolveTargets();
+    // ---- per-server credentials (identity) ----------------------------------
+    // Each server enrolls INDEPENDENTLY: a legacy root CREATE_TOKEN works
+    // forever (server-side bootstrap); an osk_ user token is the normal
+    // shape. With no token the plugin ENROLLS: public servers take anyone,
+    // private ones need servers.{url}.code. Tokens persist to the settings
+    // home so enrollment happens once per server.
+    const credState = new Map();
+    const credOf = (url) => {
+        let s = credState.get(url);
+        if (!s) {
+            s = { credential: "", error: "", lastEnrollAt: 0 };
+            credState.set(url, s);
+        }
+        return s;
+    };
+    const seedCredentials = () => {
+        for (const t of targets) {
+            const c = credOf(t.url);
+            if (t.entry.token) {
+                if (c.credential !== t.entry.token) {
+                    c.credential = t.entry.token;
+                    c.error = "";
+                }
+            }
+            else if (!c.credential && !c.error) {
+                c.credential = ""; // enrolled token may arrive via config refresh
+            }
+        }
+    };
+    seedCredentials();
+    const ENROLL_RETRY_MS = 60000;
+    const ensureCredential = async (url) => {
+        const c = credOf(url);
+        const target = targets.find((t) => t.url === url);
+        if (c.credential)
+            return c.credential;
+        if (Date.now() - c.lastEnrollAt < ENROLL_RETRY_MS)
+            return "";
+        c.lastEnrollAt = Date.now();
+        try {
+            const h = await fetch(`${url}/health`, { signal: AbortSignal.timeout(8000) });
+            const hb = h.ok ? (await h.json().catch(() => null)) : null;
+            const authMode2 = hb?.auth?.mode;
+            const code = target?.entry.code ?? "";
+            if (authMode2 === "public" || code) {
+                const r = await fetch(`${url}/api/enroll`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ code }),
+                    signal: AbortSignal.timeout(10000),
+                });
+                const b = r.ok ? (await r.json().catch(() => null)) : null;
+                if (b?.ok && typeof b.token === "string") {
+                    c.credential = b.token;
+                    c.error = "";
+                    const savedTo = saveServerToken(url, c.credential);
+                    log(`enrolled at ${url} (user ${b.userId} "${b.label}")${savedTo ? " - token saved" : ""}`);
+                    return c.credential;
+                }
+                c.error = `enroll refused: ${b?.error ?? `HTTP ${r.status}`}`;
+            }
+            else if (authMode2 === "private") {
+                c.error = "private server: add servers.{url}.code (or token) to enroll";
+            }
+            else {
+                c.error = `server health unreachable (HTTP ${h.status})`;
+            }
+        }
+        catch (e) {
+            c.error = `enrollment failed: ${e?.message || e}`;
+        }
+        logError(`no credential for ${url}: ${c.error}`);
+        return "";
+    };
+    const remoteFor = (st, url) => {
+        let r = st.remotes.get(url);
+        if (!r) {
+            r = {
+                url,
+                shareId: null,
+                secret: null,
+                ackedRev: 0,
+                ws: null,
+                wsReady: false,
+                connecting: false,
+                socketSeq: 0,
+                initTimer: null,
+                initWasAttach: false,
+                backoff: 1000,
+                reconnectTimer: null,
+                intentionalClose: false,
+                connectQueued: false,
+                authBlocked: false,
+                pending: [],
+                announced: false,
+                settleTimer: null,
+                idleDropTimer: null,
+                collided: null,
+            };
+            st.remotes.set(url, r);
+        }
+        return r;
+    };
+    // ---- server policy (worker-owned, per server) ---------------------------
+    // The worker defines the socket policy and the allowed sync-cadence
+    // window; the plugin clamps its own preferences into the INTERSECTION
+    // of every connected server's window (cfg is shared across remotes).
+    // Received in the WS init ack (authoritative) and from /health (covers
+    // the pure HTTP fallback). Defaults apply until a server answers.
+    const policyMap = new Map();
+    const policyAsked = new Set();
+    const policyOf = (url) => policyMap.get(url) ?? DEFAULT_POLICY;
+    const clampToPolicy = () => {
+        const policies = [...policyMap.values()];
+        if (!policies.length)
+            return;
+        const min = Math.max(0, ...policies.map((p) => p.debounceMinMs));
+        const max = Math.min(...policies.map((p) => p.debounceMaxMs));
+        cfg.debounceMs = Math.min(Math.max(cfg.debounceMs, min), Math.max(min, max));
+        const cd = Math.min(...policies.map((p) => p.completedDelayMaxMs));
+        cfg.completedDelayMs = Math.min(Math.max(cfg.completedDelayMs, 0), cd);
+    };
+    const applyPolicy = (raw, url) => {
+        if (!raw || typeof raw !== "object")
+            return;
+        const p = raw;
+        const num = (v, d) => {
+            const n = Number(v);
+            return Number.isFinite(n) && n >= 0 ? n : d;
+        };
+        const prev = policyOf(url);
+        policyMap.set(url, {
+            mode: p.mode === "turn" ? "turn" : "persistent",
+            turnGraceMs: num(p.turnGraceMs, prev.turnGraceMs),
+            idleDropMs: num(p.idleDropMs, prev.idleDropMs),
+            finalizeAfterMs: num(p.finalizeAfterMs, prev.finalizeAfterMs),
+            debounceMinMs: num(p.debounceMinMs, 0),
+            debounceMaxMs: Math.max(num(p.debounceMaxMs, Infinity), num(p.debounceMinMs, 0)),
+            completedDelayMaxMs: num(p.completedDelayMaxMs, Infinity),
+        });
+        clampToPolicy();
+        if (debugEvents)
+            log(`policy ${url}: ${JSON.stringify(policyOf(url))}`);
+    };
+    const askPolicy = (url) => {
+        if (policyAsked.has(url))
+            return;
+        policyAsked.add(url);
+        void fetch(`${url}/health`, { signal: AbortSignal.timeout(8000) })
+            .then((r) => (r.ok ? r.json() : null))
+            .then((b) => {
+            if (b && typeof b === "object" && b.policy) {
+                applyPolicy(b.policy, url);
+            }
+        })
+            .catch(() => {
+            // unreachable worker: defaults stay; the init ack will correct us
+            policyAsked.delete(url);
+        });
+    };
+    const wsUrl = (url) => url.replace(/^http/, "ws");
+    // ---- spool root ---------------------------------------------------------
+    let spoolRoot = spoolDirFor(cfg);
+    try {
+        mkdirSync(spoolRoot, { recursive: true });
+    }
+    catch { }
+    // ---- per-main-session state -------------------------------------------
+    const sessions = new Map(); // mainSid -> st
+    const childToParent = new Map(); // childSid -> mainSid
+    // all-mode opt-in ledger: sessions that predate plugin start and are
+    // neither flagged nor already bound stay unshared (log once each)
+    const bootTime = Date.now();
+    const preExistingRetired = new Set();
+    const verifying = new Set();
+    let chain = Promise.resolve();
+    let lastUrlFile = null;
+    let urlFileAnnounced = false;
+    const newSt = (sid) => ({
+        sid,
+        client: deps.client,
+        queue: new Map(),
+        timer: null,
+        metaTimer: null,
+        completedTimer: null,
+        lastFlushAt: 0,
+        statusEpoch: 0,
+        remotes: new Map(),
+        status: "live",
+        badSignal: false,
+        lastSentStatus: null,
+        closed: false,
+        prefsSent: false,
+        binding: null,
+        bindingQueried: false,
+        optOuts: new Set(),
+        opts: undefined,
+        activated: false,
+        wroteBinding: false,
+        everConnected: false,
+    });
+    const refreshConfig = () => {
+        // settings may change between activations (the TUI writes the config
+        // file); each activation re-reads. env always wins, so CI is stable.
+        const next = loadConfig(deps.pluginDir, deps.options);
+        const resolved = resolveServer(next);
+        if (resolved?.url) {
+            cfg = next;
+            spoolRoot = spoolDirFor(cfg);
+            const before = new Set(targets.map((t) => t.url));
+            targets = resolveTargets();
+            seedCredentials();
+            clampToPolicy();
+            if (debugEvents) {
+                const after = targets.map((t) => t.url);
+                const added = after.filter((u) => !before.has(u));
+                if (added.length)
+                    log(`fan-out set grew: ${added.join(", ")}`);
+            }
+        }
+    };
+    /** Activate a main session: create state, connect, backfill when gated
+     * (manual mode always; all-mode flag activations need the history too —
+     * an opted-in old session deserves a complete page, not just the events
+     * after the flag). */
+    const activate = (sid, opts, info, opts2) => {
+        refreshConfig();
+        let st = sessions.get(sid);
+        if (!st) {
+            st = newSt(sid);
+            sessions.set(sid, st);
+        }
+        else if (st.activated) {
+            if (opts)
+                st.opts = opts;
+            return st;
+        }
+        st.activated = true;
+        st.opts = opts;
+        const gated = mode === "manual" || opts2?.gated === true;
+        if (gated) {
+            // seed the share status from the session's CURRENT state before
+            // anything flushes: activating an idle session must not ship a
+            // phantom "live" badge. backfill follows, then the connection —
+            // through the same single-flight queue as everyone else.
+            chain = chain
+                .then(() => seedManualStatus(st))
+                .then(() => backfill(st, info))
+                .then(() => queueConnectAll(st))
+                .catch((e) => logError("activation error", e?.message || e));
+        }
+        else {
+            queueConnectAll(st);
+        }
+        return st;
+    };
+    const seedManualStatus = async (st) => {
+        if (!st.client || typeof st.client.session.status !== "function")
+            return;
+        try {
+            const map = unwrap(await st.client.session.status({
+                ...(deps.directory ? { query: { directory: deps.directory } } : {}),
+            }));
+            const type = map && typeof map === "object" ? map[st.sid]?.type : undefined;
+            if (type === "busy" || type === "retry") {
+                st.status = "live";
+                if (type === "retry")
+                    st.badSignal = true;
+            }
+            else {
+                // idle (or absent from the map = not running): completed unless
+                // the backfilled history shows errors (resolved after backfill)
+                st.status = "completed";
+            }
+        }
+        catch {
+            // status unknown: keep "live" (a prompt may be running)
+        }
+    };
+    /** Existing state for an event sid, or null (manual mode never creates
+     * state on sight — activation is flag-driven). */
+    const stFor = (sid) => {
+        const main = childToParent.get(sid) ?? sid;
+        return sessions.get(main) ?? null;
+    };
+    // ---- durable binding: session metadata (inside opencode's db) ---------
+    // NOTE: the plugin SDK client can hit a foreign server when something
+    // else listens on Server.url's port — error envelopes don't throw, so
+    // every call is checked and degradation (spool covers reconnects) is
+    // logged loudly instead of failing silently.
+    const unwrap = (res) => {
+        if (res && typeof res === "object" && "error" in res && res.error) {
+            throw new Error(`client error: ${JSON.stringify(res.error).slice(0, 120)}`);
+        }
+        return res?.data ?? res;
+    };
+    async function sessionInfo(client, sid) {
+        if (!client)
+            return undefined;
+        try {
+            const info = unwrap(await client.session.get({
+                path: { id: sid },
+                ...(deps.directory ? { query: { directory: deps.directory } } : {}),
+            }));
+            return info;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async function writeMetadata(st, value) {
+        if (!st.client)
+            return;
+        try {
+            const info = unwrap(await st.client.session.get({
+                path: { id: st.sid },
+                ...(deps.directory ? { query: { directory: deps.directory } } : {}),
+            }));
+            const metadata = { ...(info?.metadata ?? {}) };
+            if (value === null)
+                delete metadata[METADATA_KEY];
+            else
+                metadata[METADATA_KEY] = value;
+            unwrap(await st.client.session.update({
+                path: { id: st.sid },
+                body: { metadata },
+                ...(deps.directory ? { query: { directory: deps.directory } } : {}),
+            }));
+        }
+        catch (e) {
+            log("metadata write failed (spool still covers reconnects):", e?.message || e);
+        }
+    }
+    /** Parse the metadata binding: v2 map ({v:2, servers:{url:{id,secret,
+     * rev,url,enabled?}}}) or legacy flat ({id,secret,rev,url}) which maps
+     * onto the first target. Returns per-server live entries. */
+    const parseBinding = (record) => {
+        const out = new Map();
+        if (record.servers && typeof record.servers === "object") {
+            for (const [url, raw] of Object.entries(record.servers)) {
+                if (!raw || typeof raw !== "object")
+                    continue;
+                const e = raw;
+                if (typeof e.id === "string" && typeof e.secret === "string" && e.id && e.secret) {
+                    out.set(url, { id: e.id, secret: e.secret, rev: typeof e.rev === "number" ? e.rev : 0 });
+                }
+                else if (e.optedOut === true) {
+                    out.set(url, { id: "", secret: "", rev: 0, optedOut: true });
+                }
+            }
+            return out;
+        }
+        if (typeof record.id === "string" && typeof record.secret === "string" && record.id) {
+            const url = targets[0]?.url ?? "";
+            if (url)
+                out.set(url, { id: record.id, secret: record.secret, rev: typeof record.rev === "number" ? record.rev : 0 });
+        }
+        return out;
+    };
+    async function readBinding(st) {
+        if (!st.client || st.bindingQueried)
+            return;
+        st.bindingQueried = true;
+        try {
+            const info = await sessionInfo(st.client, st.sid);
+            const b = info?.metadata?.[METADATA_KEY];
+            if (b && typeof b === "object") {
+                const record = b;
+                if (mode === "manual" && record.enabled !== true) {
+                    // flagless binding (unshared, or legacy): stay dormant
+                    return;
+                }
+                const found = parseBinding(record);
+                if (found.size) {
+                    for (const [url, e] of found) {
+                        if (e.optedOut)
+                            continue;
+                        const r = remoteFor(st, url);
+                        if (!r.shareId) {
+                            r.shareId = e.id;
+                            r.secret = e.secret;
+                            r.ackedRev = e.rev;
+                        }
+                    }
+                    if (mode === "manual")
+                        st.opts = shareFlag(info).opts ?? st.opts;
+                    log(`binding recovered from session metadata: ${[...found.keys()].join(", ")}`);
+                }
+            }
+        }
+        catch (e) {
+            log("metadata read failed (degrading to spool):", e?.message || e);
+        }
+    }
+    async function writeBinding(st) {
+        if (!st.client)
+            return;
+        const servers = {};
+        let any = false;
+        for (const [url, r] of st.remotes) {
+            if (!r.shareId || !r.secret)
+                continue;
+            any = true;
+            const entry = { id: r.shareId, secret: r.secret, rev: r.ackedRev, url: `${url}/s/${r.shareId}` };
+            if (r.collided)
+                entry.collided = r.collided;
+            servers[url] = entry;
+        }
+        if (!any)
+            return;
+        // preserve per-session opt-outs in the written map — a retired remote
+        // is absent from `servers`, and dropping the marker would let the next
+        // refreshOptOuts resurrect (and re-create) the opted-out server
+        for (const url of st.optOuts)
+            if (!servers[url])
+                servers[url] = { optedOut: true };
+        // A binding in session metadata means opted-in — enabled: true in BOTH
+        // modes (live-caught: all-mode bindings without `enabled` made the TUI
+        // gate fall through to the consent dialog on an already-shared session;
+        // live is now uniformly "url && enabled !== false").
+        const value = { v: 2, servers, enabled: true };
+        if (mode === "manual" && st.opts)
+            value.opts = st.opts;
+        st.binding = value;
+        st.wroteBinding = true;
+        await writeMetadata(st, value);
+    }
+    const scheduleBindingWrite = (st) => {
+        if (st.metaTimer)
+            return;
+        st.metaTimer = setTimeout(() => {
+            st.metaTimer = null;
+            chain = chain.then(() => writeBinding(st)).catch(() => { });
+        }, 30000);
+    };
+    // ---- spool (temporary buffer for unacked frames) ----------------------
+    // One spool per session per server: `<sid>.<h8(url)>.meta/queue`. The
+    // legacy suffix-less files (single-server era) migrate onto the first
+    // target at load.
+    const h8 = (url) => {
+        let h = 5381;
+        for (let i = 0; i < url.length; i++)
+            h = ((h << 5) + h + url.charCodeAt(i)) >>> 0;
+        return h.toString(16).padStart(8, "0");
+    };
+    const metaPath = (st, url) => join(spoolRoot, `${st.sid}.${h8(url)}.meta.json`);
+    const queuePath = (st, url) => join(spoolRoot, `${st.sid}.${h8(url)}.queue.jsonl`);
+    const legacyMetaPath = (st) => join(spoolRoot, `${st.sid}.meta.json`);
+    const legacyQueuePath = (st) => join(spoolRoot, `${st.sid}.queue.jsonl`);
+    const spoolSave = (st, r) => {
+        try {
+            writeFileSync(metaPath(st, r.url), JSON.stringify({ shareId: r.shareId, secret: r.secret, ackedRev: r.ackedRev, sid: st.sid, url: r.url }));
+            writeFileSync(queuePath(st, r.url), r.pending.map((f) => JSON.stringify(f)).join("\n") + (r.pending.length ? "\n" : ""));
+        }
+        catch (e) {
+            logError("spool save failed", e?.message || e);
+        }
+    };
+    const spoolLoad = (st, r) => {
+        try {
+            const meta = JSON.parse(readFileSync(metaPath(st, r.url), "utf8"));
+            // metadata binding (db) is authoritative when both exist and disagree
+            if (!r.shareId && meta.shareId) {
+                r.shareId = meta.shareId;
+                r.secret = meta.secret;
+                r.ackedRev = meta.ackedRev ?? 0;
+            }
+            if (existsSync(queuePath(st, r.url))) {
+                r.pending = readFileSync(queuePath(st, r.url), "utf8")
+                    .split("\n")
+                    .filter((l) => l.trim())
+                    .map((l) => JSON.parse(l));
+            }
+        }
+        catch {
+            r.pending = [];
+        }
+        // single-server-era spool (no url suffix): belongs to the first target
+        if (!r.shareId && targets[0]?.url === r.url) {
+            try {
+                const meta = JSON.parse(readFileSync(legacyMetaPath(st), "utf8"));
+                if (meta.shareId && !r.shareId) {
+                    r.shareId = meta.shareId;
+                    r.secret = meta.secret;
+                    r.ackedRev = meta.ackedRev ?? 0;
+                    if (existsSync(legacyQueuePath(st))) {
+                        r.pending = readFileSync(legacyQueuePath(st), "utf8")
+                            .split("\n")
+                            .filter((l) => l.trim())
+                            .map((l) => JSON.parse(l));
+                    }
+                    log(`migrated legacy spool for ${st.sid.slice(0, 18)} onto ${r.url}`);
+                }
+            }
+            catch { }
+        }
+    };
+    const spoolClear = (st, r) => {
+        try {
+            rmSync(metaPath(st, r.url), { force: true });
+            rmSync(queuePath(st, r.url), { force: true });
+        }
+        catch { }
+    };
+    // ---- websocket transport (per remote) ----------------------------------
+    const wsSend = (r, obj) => {
+        if (debugEvents)
+            log(`ws ${r.url.slice(0, 24)} #${r.socketSeq} send ${obj?.op} (ready=${r.wsReady})`);
+        try {
+            r.ws?.send(JSON.stringify(obj));
+        }
+        catch {
+            return false;
+        }
+        return true;
+    };
+    /** Sync frames are chunked (~1MB WS cap on CF; a 5000-message backfill
+     * must ride several frames — worker apply is keyed-idempotent, chunks
+     * just bump rev). Status rides each chunk; last write wins. */
+    const SYNC_CHUNK = 200;
+    const sendSync = (r, f) => {
+        if (!f.items.length)
+            return wsSend(r, { op: "sync", items: [], status: f.status });
+        for (let i = 0; i < f.items.length; i += SYNC_CHUNK) {
+            wsSend(r, { op: "sync", items: f.items.slice(i, i + SYNC_CHUNK), status: f.status });
+        }
+        return true;
+    };
+    const announceUrl = (st, r) => {
+        if (r.announced)
+            return;
+        r.announced = true;
+        const url = `${r.url}/s/${r.shareId}`;
+        if (cfg.announceStderr)
+            log(`live: ${url}`);
+        if (mode === "all" && cfg.urlFile !== URL_FILE_NONE) {
+            // default: the file lives where the session lives (its directory,
+            // falling back to the process cwd) — never a fixed global path.
+            // Explicit urlFile config/env wins ("none" disables the file).
+            // Append: CI reads the file after each run; keeping every share
+            // URL lets one file serve a whole workflow (the legacy original
+            // overwrote with the latest only).
+            const file = cfg.urlFile || join(deps.directory ?? process.cwd(), "openshare.urls.txt");
+            try {
+                appendFileSync(file, url + "\n");
+                if (cfg.announceStderr && (file !== lastUrlFile || !urlFileAnnounced)) {
+                    urlFileAnnounced = true;
+                    lastUrlFile = file;
+                    log(`url file: ${file}`);
+                }
+            }
+            catch { }
+        }
+    };
+    const authFrame = (st) => {
+        // always send both (empty strings included): attach with empty values
+        // REMOVES protection — an intentional owner action. Session opts
+        // override the global config when set.
+        const login = st.opts?.authLogin ?? cfg.authLogin ?? "";
+        const password = st.opts?.authPassword ?? cfg.authPassword ?? "";
+        return { authLogin: login, authPassword: password };
+    };
+    const ttlFor = (st) => st.opts?.ttlDays ?? cfg.ttlDays;
+    /** Best-effort cleanup of a share we are about to abandon (refused
+     * attach, mismatch recreate). Prevents husk litter; failures are fine —
+     * the TTL sweeper collects strays eventually. */
+    const deleteAbandoned = (r) => {
+        const id = r.shareId;
+        const secret = r.secret;
+        if (!id || !secret)
+            return;
+        void fetch(`${r.url}/api/share/${id}`, {
+            method: "DELETE",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ secret }),
+            signal: AbortSignal.timeout(8000),
+        }).catch(() => { });
+    };
+    /** Single-flight connect queuing: multiple paths (activation, event
+     * reconnect, backfill chain) may want a socket before any connect has
+     * STARTED — the connecting flag alone guards execution, not the queue,
+     * and double connects used to create duplicate shares + init storms
+     * (live-caught in the S11 repro: ws#1 create AND ws#2 create). */
+    const queueConnect = (st, r) => {
+        if (st.closed || r.connectQueued || r.connecting || r.authBlocked || r.collided)
+            return;
+        r.connectQueued = true;
+        chain = chain
+            .then(() => {
+            r.connectQueued = false;
+            return connect(st, r);
+        })
+            .catch((e) => logError("connect error", e?.message || e));
+    };
+    /** Connect every target (activation, resume) — remotes materialize from
+     * targets ∪ binding (a share bound on a no-longer-active server keeps
+     * receiving updates until explicitly unshared there). Opted-out servers
+     * (this session) are skipped entirely. */
+    const queueConnectAll = (st) => {
+        if (st.closed)
+            return;
+        for (const t of targets) {
+            if (st.optOuts.has(t.url))
+                continue;
+            queueConnect(st, remoteFor(st, t.url));
+        }
+        for (const r of st.remotes.values()) {
+            if (st.optOuts.has(r.url))
+                continue;
+            queueConnect(st, r);
+        }
+    };
+    /** Re-read the session's binding map for per-server opt-outs (written by
+     * the TUI: "stop sharing here" deletes the share then opts out; "leave
+     * as-is" just opts out). Live remotes for newly opted-out servers are
+     * retired — the share keeps living server-side until its TTL.
+     * Also resolves collisions the TUI answered: entry removed → re-arm the
+     * remote (fresh create + backfill) unless opted out. */
+    const refreshOptOuts = async (st) => {
+        if (!st.client)
+            return;
+        try {
+            const info = await sessionInfo(st.client, st.sid);
+            const raw = info?.metadata?.[METADATA_KEY];
+            if (!raw || typeof raw !== "object")
+                return;
+            const servers = raw.servers;
+            if (!servers || typeof servers !== "object")
+                return;
+            const entryUrls = new Set();
+            for (const [url, e] of Object.entries(servers)) {
+                entryUrls.add(url);
+                const out = !!(e && typeof e === "object" && e.optedOut === true);
+                if (out)
+                    st.optOuts.add(url);
+                else
+                    st.optOuts.delete(url);
+            }
+            // retire remotes that just got opted out (socket closed; spool
+            // dropped — the share is out of our hands by the TUI's choice)
+            for (const url of [...st.optOuts]) {
+                const r = st.remotes.get(url);
+                if (!r)
+                    continue;
+                if (debugEvents)
+                    log(`remote ${url.slice(0, 24)} opted out for ${st.sid.slice(0, 18)} - retiring`);
+                r.intentionalClose = true;
+                try {
+                    r.ws?.close(1000, "opted out");
+                }
+                catch { }
+                spoolClear(st, r);
+                st.remotes.delete(url);
+            }
+            // collisions resolved by the TUI: the binding entry for the server
+            // was removed — re-arm unless the same patch also opted out
+            for (const r of [...st.remotes.values()]) {
+                if (!r.collided || st.optOuts.has(r.url))
+                    continue;
+                if (entryUrls.has(r.url))
+                    continue;
+                if (debugEvents)
+                    log(`collision on ${r.url.slice(0, 24)} resolved - re-arming`);
+                r.collided = null;
+                r.shareId = null;
+                r.secret = null;
+                r.ackedRev = 0;
+                r.pending = [];
+                r.announced = false;
+                queueConnect(st, r);
+            }
+        }
+        catch { }
+    };
+    const connect = async (st, r) => {
+        if (st.closed || r.connecting || r.authBlocked || r.collided)
+            return;
+        // "connecting" spans the WHOLE handshake: socket open + init ack. It
+        // is only cleared on init-ok, socket death or the init timeout — an
+        // event arriving mid-handshake must NEVER spawn a second socket (the
+        // old connect() returned after merely SENDING init; a second socket
+        // raced it, and the loser's late init-ok poisoned the winner's state
+        // — live-caught: duplicate shares, mismatch storms, empty pages).
+        r.connecting = true;
+        r.socketSeq += 1;
+        const seq = r.socketSeq;
+        // supersede any previous socket: its frames are dead to us now
+        if (r.ws) {
+            const old = r.ws;
+            try {
+                old.close(4000, "superseded");
+            }
+            catch { }
+        }
+        try {
+            await readBinding(st);
+            spoolLoad(st, r);
+            askPolicy(r.url);
+            // was this socket's init an ATTACH (resume) or a CREATE? A create
+            // ack legitimately starts at rev 0 — the mismatch guard is for
+            // attaches only (live-caught: create-ack rev 0 tripped it and
+            // spawned a fresh husk share with the content dropped).
+            r.initWasAttach = !!(r.shareId && r.secret);
+            if (debugEvents)
+                log(`ws ${r.url.slice(0, 24)} #${seq} opening (${r.initWasAttach ? `attach ${r.shareId}` : "create"})`);
+            // creates need a credential (enrolls on demand — first contact with
+            // a server); attaches ride the share secret alone when tokenless
+            const cred = credOf(r.url);
+            const token = r.initWasAttach ? cred.credential : cred.credential || (await ensureCredential(r.url));
+            if (!r.initWasAttach && !token && cred.error) {
+                // the server is reachable but enrollment is impossible (private,
+                // no valid code / enroll refused). A tokenless create would just
+                // be refused in a loop — block this remote, surface once.
+                r.authBlocked = true;
+                r.connecting = false;
+                r.ws = null;
+                logError(`sharing to ${r.url} disabled (no credential): ${cred.error}`);
+                return;
+            }
+            const ws = new WebSocket(`${wsUrl(r.url)}/api/ws?token=${encodeURIComponent(token ?? "")}`);
+            r.ws = ws;
+            await new Promise((resolve, reject) => {
+                const t = setTimeout(() => reject(new Error("ws open timeout")), 15000);
+                ws.addEventListener("open", () => {
+                    clearTimeout(t);
+                    resolve(undefined);
+                }, { once: true });
+                ws.addEventListener("error", () => {
+                    clearTimeout(t);
+                    reject(new Error("ws open error"));
+                }, { once: true });
+            });
+            ws.addEventListener("message", (ev) => {
+                // stale sockets never touch live state (defense in depth: even a
+                // superseded socket that still delivers frames is dropped here)
+                if (seq !== r.socketSeq)
+                    return;
+                let frame;
+                try {
+                    frame = JSON.parse(ev.data);
+                }
+                catch {
+                    return;
+                }
+                handleFrame(st, r, frame).catch((e) => logError("frame error", e?.message || e));
+            });
+            ws.addEventListener("close", () => {
+                if (seq !== r.socketSeq)
+                    return;
+                r.wsReady = false;
+                r.connecting = false;
+                // a deliberate turn-mode drop must not trigger the reconnect
+                // backoff loop — the next event reconnects on demand
+                if (r.intentionalClose) {
+                    r.intentionalClose = false;
+                    return;
+                }
+                if (!st.closed)
+                    scheduleReconnect(st, r);
+            });
+            if (r.initWasAttach) {
+                wsSend(r, { op: "init", attach: { id: r.shareId, secret: r.secret, ...authFrame(st) } });
+            }
+            else {
+                wsSend(r, { op: "init", create: { sessionID: st.sid, ttlDays: ttlFor(st), ...authFrame(st) } });
+            }
+            // handshake deadline: init sent but no ack (silent worker death)
+            // — close, let the close listener reconnect us
+            r.initTimer = setTimeout(() => {
+                if (seq !== r.socketSeq)
+                    return;
+                logError(`ws ${r.url.slice(0, 24)} #${seq} init ack timeout`);
+                r.connecting = false;
+                try {
+                    ws.close(4000, "init timeout");
+                }
+                catch { }
+                if (!st.closed)
+                    scheduleReconnect(st, r);
+            }, 20000);
+        }
+        catch (e) {
+            r.connecting = false;
+            logError("socket failed:", e?.message || e, "- falling back to HTTP, will retry");
+            r.wsReady = false;
+            void flushViaHttp(st, r).catch(() => { });
+            scheduleReconnect(st, r);
+            return;
+        }
+    };
+    const scheduleReconnect = (st, r) => {
+        if (st.closed || r.reconnectTimer)
+            return;
+        const wait = r.backoff;
+        r.backoff = Math.min(r.backoff * 2, 60000);
+        r.reconnectTimer = setTimeout(() => {
+            r.reconnectTimer = null;
+            queueConnect(st, r);
+        }, wait);
+    };
+    // ---- turn-scoped socket lifecycle (server policy "turn") ---------------
+    const dropSocket = (st, r, why) => {
+        if (debugEvents)
+            log(`turn: drop socket (${why}) ${r.url.slice(0, 24)} sid=${st.sid.slice(0, 18)}`);
+        r.wsReady = false;
+        r.intentionalClose = true;
+        try {
+            r.ws?.close(1000, why);
+        }
+        catch { }
+        r.ws = null;
+    };
+    const cancelSettleDrop = (r) => {
+        if (r.settleTimer) {
+            clearTimeout(r.settleTimer);
+            r.settleTimer = null;
+        }
+    };
+    const armSettleDrop = (st) => {
+        for (const r of st.remotes.values()) {
+            const p = policyOf(r.url);
+            if (p.mode !== "turn" || p.turnGraceMs <= 0)
+                continue;
+            cancelSettleDrop(r);
+            r.settleTimer = setTimeout(() => {
+                r.settleTimer = null;
+                if (st.closed || !r.ws)
+                    return;
+                dropSocket(st, r, "turn end");
+            }, p.turnGraceMs);
+        }
+    };
+    const armIdleDrop = (st) => {
+        for (const r of st.remotes.values()) {
+            const p = policyOf(r.url);
+            if (p.mode !== "turn" || p.idleDropMs <= 0)
+                continue;
+            if (r.idleDropTimer)
+                clearTimeout(r.idleDropTimer);
+            r.idleDropTimer = setTimeout(() => {
+                r.idleDropTimer = null;
+                if (st.closed || !r.ws)
+                    return;
+                // no signal for idleDropMs (incl. hosts that never emit idle):
+                // drop; the next event reconnects and the spool replays the gap
+                dropSocket(st, r, "idle timeout");
+            }, p.idleDropMs);
+        }
+    };
+    /** Any activity: the turn is alive — cancel the settle drop, reset the
+     * no-signal fallback timer (per server). */
+    const touch = (st) => {
+        for (const r of st.remotes.values())
+            cancelSettleDrop(r);
+        armIdleDrop(st);
+    };
+    /** An event arrived with no live socket (post-drop or post-fallback):
+     * reconnect now — the queue rides the normal flush path afterwards.
+     * Target-set refresh is throttled (config files on disk per event would
+     * be heavy); 5s catches TUI server switches quickly enough. */
+    let lastTargetsCheck = 0;
+    const ensureConnected = (st) => {
+        if (st.closed)
+            return;
+        if (Date.now() - lastTargetsCheck > 5000) {
+            lastTargetsCheck = Date.now();
+            refreshConfig();
+        }
+        for (const t of targets) {
+            if (st.optOuts.has(t.url))
+                continue;
+            const r = remoteFor(st, t.url);
+            if (r.connecting || r.reconnectTimer || r.wsReady || r.authBlocked || r.collided)
+                continue;
+            queueConnect(st, r);
+        }
+        for (const r of st.remotes.values()) {
+            if (st.optOuts.has(r.url))
+                continue;
+            if (r.connecting || r.reconnectTimer || r.wsReady || r.authBlocked || r.collided)
+                continue;
+            queueConnect(st, r);
+        }
+    };
+    const handleFrame = async (st, r, frame) => {
+        if (frame.op === "init") {
+            if (!frame.ok) {
+                const err = String(frame.error ?? "");
+                if (/frozen/i.test(err)) {
+                    // owner frozen: every control path is severed server-side.
+                    // Re-enrolling would orphan the shares — surface and stop.
+                    r.authBlocked = true;
+                    logError(`${r.url}: share frozen by the hoster (owner frozen) - edits refused; contact the server admin`);
+                    try {
+                        r.ws?.close(4000, "frozen");
+                    }
+                    catch { }
+                    return;
+                }
+                if (/forbidden|bad secret/i.test(err) && r.initWasAttach && r.secret) {
+                    // COLLISION: the binding's secret no longer opens this share and
+                    // the socket token doesn't own it either (share recreated by a
+                    // later run? host-side restore?). Auto-recreating could dupe a
+                    // share someone else now owns — stop, mark, let the TUI offer
+                    // copy-debug / share-on-new / don't-share (headless: share-new).
+                    r.collided = err;
+                    r.connecting = false;
+                    logError(`${r.url}: attach refused (${err}) - credential collision on share ${r.shareId}; not auto-recreating`);
+                    try {
+                        r.ws?.close(4000, "collision");
+                    }
+                    catch { }
+                    // persist the collision into the binding so the TUI can offer
+                    // the choice; writeBinding marks collided remotes
+                    st.wroteBinding = false;
+                    chain = chain.then(() => writeBinding(st)).catch(() => { });
+                    // headless (all-mode): resolve as "share on a new share"
+                    if (mode === "all")
+                        resolveCollision(st, r);
+                    return;
+                }
+                if (/token|credential/i.test(err) && !r.initWasAttach) {
+                    // our token was rejected (revoked/expired): drop it, re-enroll
+                    // (60s-gated; public server or a fresh code), reconnect. A
+                    // legacy root token never lands here.
+                    const cred = credOf(r.url);
+                    if (cred.credential) {
+                        cred.credential = "";
+                        logError(`${r.url}: server rejected our token - re-enrolling`);
+                    }
+                    try {
+                        r.ws?.close(4000, "auth");
+                    }
+                    catch { }
+                    r.connecting = false;
+                    if (!st.closed)
+                        queueConnect(st, r);
+                    return;
+                }
+                // share swept / removed / revoked: start fresh, never merge into a
+                // bad base (mismatch protocol). Content REPLAYS to the new share —
+                // pending is never dropped on a reset (live-caught: the recreate
+                // husk had the title but zero messages).
+                logError(`${r.url}: init refused:`, frame.error, "- creating fresh share");
+                deleteAbandoned(r);
+                r.shareId = null;
+                r.secret = null;
+                r.ackedRev = 0;
+                wsSend(r, { op: "init", create: { sessionID: st.sid, ttlDays: ttlFor(st), ...authFrame(st) } });
+                return;
+            }
+            if (r.initWasAttach && typeof frame.rev === "number" && frame.rev < r.ackedRev) {
+                // worker lost data behind our back (ATTACH only — a create ack
+                // legitimately starts at rev 0; the old guard misread that as
+                // data loss and spawned a fresh husk, live-caught)
+                logError(`${r.url}: mismatch: worker rev ${frame.rev} < acked ${r.ackedRev} - recreating`);
+                deleteAbandoned(r);
+                r.shareId = null;
+                r.secret = null;
+                r.ackedRev = 0;
+                wsSend(r, { op: "init", create: { sessionID: st.sid, ttlDays: ttlFor(st), ...authFrame(st) } });
+                return;
+            }
+            const wasFanoutCreate = !r.initWasAttach && st.everConnected;
+            const shareChanged = !!frame.id && frame.id !== r.shareId;
+            if (shareChanged)
+                r.announced = false;
+            r.shareId = frame.id ?? r.shareId;
+            r.secret = frame.secret ?? r.secret;
+            r.ackedRev = frame.rev ?? 0;
+            r.wsReady = true;
+            r.connecting = false;
+            r.initWasAttach = false;
+            r.collided = null;
+            if (r.initTimer) {
+                clearTimeout(r.initTimer);
+                r.initTimer = null;
+            }
+            r.backoff = 1000;
+            st.everConnected = true;
+            if (frame.policy)
+                applyPolicy(frame.policy, r.url);
+            r.intentionalClose = false;
+            touch(st);
+            announceUrl(st, r);
+            // first binding write is immediate (the TUI waits on the URL in
+            // session metadata); ack-driven rev updates stay debounced
+            if (!st.wroteBinding) {
+                chain = chain.then(() => writeBinding(st)).catch(() => { });
+            }
+            else {
+                scheduleBindingWrite(st);
+            }
+            spoolSave(st, r);
+            if (r.pending.length) {
+                for (const f of r.pending)
+                    sendSync(r, f);
+            }
+            else if (st.queue.size) {
+                flush(st);
+            }
+            if (wasFanoutCreate) {
+                // a server joined an ALREADY-live session (fan-out add, or a
+                // post-mismatch recreate): its fresh share needs the full history —
+                // backfill is keyed-idempotent, other servers just re-upsert
+                chain = chain.then(() => backfill(st)).catch((e) => logError("fan-out backfill error", e?.message || e));
+            }
+            return;
+        }
+        if (frame.op === "ack") {
+            r.ackedRev = frame.rev ?? r.ackedRev;
+            r.pending = [];
+            spoolSave(st, r);
+            scheduleBindingWrite(st);
+            return;
+        }
+        if (frame.op === "nack" || frame.op === "error") {
+            logError(`${r.url}: worker refused frame:`, JSON.stringify(frame).slice(0, 200));
+            // the control socket lost its attach state (worker-side eviction of
+            // the control DO): force a reconnect — init attach replays pending
+            if (frame.op === "error" && r.wsReady && !st.closed) {
+                r.wsReady = false;
+                try {
+                    r.ws?.close();
+                }
+                catch { }
+                scheduleReconnect(st, r);
+            }
+        }
+    };
+    /** Collision resolution "share on a new share": forget the dead binding
+     * entry for this server (debug info logged first), delete the husk if
+     * we still can, and reconnect — the create path makes a fresh share and
+     * the fan-out backfill fills it. */
+    const resolveCollision = (st, r) => {
+        logError(`collision debug: server=${r.url} share=${r.shareId} rev=${r.ackedRev} sid=${st.sid}`);
+        deleteAbandoned(r);
+        r.collided = null;
+        r.shareId = null;
+        r.secret = null;
+        r.ackedRev = 0;
+        r.pending = [];
+        r.announced = false;
+        queueConnect(st, r);
+    };
+    // ---- flush -------------------------------------------------------------
+    const frameFrom = (st) => {
+        const items = Array.from(st.queue.values());
+        st.queue.clear();
+        const statusChanged = st.status !== st.lastSentStatus;
+        if (!items.length && !statusChanged) {
+            if (debugEvents)
+                log(`flush skip (no items, status ${st.status}==${st.lastSentStatus})`);
+            return null;
+        }
+        st.lastSentStatus = st.status;
+        if (debugEvents)
+            log(`frame: ${items.length} items, status ${st.status}`);
+        return { items, status: st.status };
+    };
+    // returns a promise when the frame goes out via HTTP (the dispose path
+    // awaits it - an unawaited fetch dies with the exiting process and the
+    // final status never lands, live-caught as shares stuck on "live")
+    const flush = (st) => {
+        if (st.closed)
+            return;
+        const f = frameFrom(st);
+        if (!f)
+            return;
+        // fan out to every remote; each carries its own pending copy and acks
+        // independently. Remotes mid-handshake or auth-blocked just buffer.
+        let httpWork;
+        for (const r of st.remotes.values()) {
+            // never send syncs before the init ack: the worker's per-socket
+            // ControlDO has no attach until OUR init completes, and a racing
+            // sync dies as "unknown op" (live-caught: post-drop reconnects
+            // lost whole turns). The init-ok handler flushes pending itself.
+            r.pending.push(f);
+            spoolSave(st, r);
+            if (r.ws && !r.wsReady)
+                continue;
+            if (r.wsReady) {
+                sendSync(r, f);
+                continue;
+            }
+            const viaHttp = flushViaHttp(st, r);
+            if (viaHttp)
+                httpWork = (httpWork ?? Promise.resolve()).then(() => viaHttp);
+        }
+        if (st.remotes.size)
+            st.lastFlushAt = Date.now();
+        return httpWork;
+    };
+    const flushViaHttp = async (st, r) => {
+        if (!r.shareId || !r.pending.length)
+            return;
+        // ALL pending frames, merged (keyed upserts — later wins). Sending
+        // only the last frame dropped every earlier batch's items whenever
+        // the HTTP fallback carried more than one (live-caught class:
+        // content loss on reconnect paths).
+        const items = [];
+        let status;
+        for (const f of r.pending) {
+            for (const it of f.items)
+                items.push(it);
+            if (f.status)
+                status = f.status;
+        }
+        const cred = credOf(r.url);
+        const res = await fetch(`${r.url}/api/share/${r.shareId}/sync`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(cred.credential ? { authorization: `Bearer ${cred.credential}` } : {}) },
+            body: JSON.stringify({ secret: r.secret ?? "", data: items, status }),
+            signal: AbortSignal.timeout(15000),
+        }).catch(() => null);
+        if (res && res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            r.ackedRev = body.rev ?? r.ackedRev;
+            r.pending = [];
+            spoolSave(st, r);
+        }
+    };
+    const scheduleFlush = (st) => {
+        if (st.timer)
+            return;
+        // sync interval is a rate limit anchored at the PREVIOUS flush: an
+        // event arriving after the interval already elapsed flushes
+        // immediately; one arriving right after a flush waits the remainder.
+        // The very first batch flushes as soon as it exists (a viewer that
+        // just opened the link sees the opening prompt fast).
+        const elapsed = Date.now() - st.lastFlushAt;
+        const wait = Math.max(0, cfg.debounceMs - elapsed);
+        st.timer = setTimeout(() => {
+            st.timer = null;
+            if (debugEvents)
+                log(`flush timer fired sid=${st.sid.slice(0, 18)} queue=${st.queue.size} remotes=${st.remotes.size}`);
+            chain = chain.then(() => flush(st)).catch((e) => logError("flush error", e?.message || e));
+        }, wait);
+    };
+    const enqueue = (st, entry) => {
+        if (!st || !entry)
+            return;
+        st.queue.set(entry.key, entry.item);
+        if (debugEvents)
+            log(`enqueue sid=${st.sid.slice(0, 18)} ${entry.item.type} queue=${st.queue.size}`);
+        touch(st);
+        ensureConnected(st);
+        scheduleFlush(st);
+    };
+    const remove = (st) => {
+        st.closed = true;
+        st.activated = false;
+        if (st.timer)
+            clearTimeout(st.timer);
+        if (st.metaTimer)
+            clearTimeout(st.metaTimer);
+        if (st.completedTimer) {
+            clearTimeout(st.completedTimer);
+            st.completedTimer = null;
+        }
+        for (const r of st.remotes.values()) {
+            r.connecting = false;
+            r.connectQueued = false;
+            if (r.initTimer) {
+                clearTimeout(r.initTimer);
+                r.initTimer = null;
+            }
+            if (r.reconnectTimer) {
+                clearTimeout(r.reconnectTimer);
+                r.reconnectTimer = null;
+            }
+            cancelSettleDrop(r);
+            if (r.idleDropTimer) {
+                clearTimeout(r.idleDropTimer);
+                r.idleDropTimer = null;
+            }
+            if (r.wsReady)
+                wsSend(r, { op: "delete" });
+            else if (r.shareId && r.secret) {
+                // turn mode may have dropped the socket after the last settle; the
+                // goodbye still must land — say it over HTTP
+                void fetch(`${r.url}/api/share/${r.shareId}`, {
+                    method: "DELETE",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ secret: r.secret }),
+                    signal: AbortSignal.timeout(8000),
+                }).catch(() => { });
+            }
+        }
+        setTimeout(() => {
+            for (const r of st.remotes.values()) {
+                try {
+                    r.ws?.close();
+                }
+                catch { }
+            }
+        }, 1000);
+        for (const r of st.remotes.values())
+            spoolClear(st, r);
+        sessions.delete(st.sid);
+        try {
+            chain = chain.then(async () => {
+                if (!st.client)
+                    return;
+                const res = await st.client.session
+                    .get({
+                    path: { id: st.sid },
+                    ...(deps.directory ? { query: { directory: deps.directory } } : {}),
+                })
+                    .catch(() => null);
+                const info = res?.data ?? res;
+                if (info?.metadata?.[METADATA_KEY]) {
+                    const metadata = { ...info.metadata };
+                    delete metadata[METADATA_KEY];
+                    await st.client.session
+                        .update({
+                        path: { id: st.sid },
+                        body: { metadata },
+                        ...(deps.directory ? { query: { directory: deps.directory } } : {}),
+                    })
+                        .catch(() => { });
+                }
+            });
+        }
+        catch { }
+    };
+    // ---- manual-mode backfill ----------------------------------------------
+    // Activation may happen mid-session: fetch the whole session tree
+    // through the client and enqueue everything through the same keyed
+    // queue (idempotent; live events keep overwriting the same keys).
+    const PAGE_SIZE = 100;
+    const MAX_PAGES = 50;
+    const query = () => (deps.directory ? { directory: deps.directory } : {});
+    async function fetchMessages(client, sid) {
+        if (typeof client.session.messages !== "function")
+            return [];
+        const out = [];
+        let before;
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const q = { ...query(), limit: PAGE_SIZE };
+            if (before !== undefined)
+                q.before = before;
+            const result = unwrap(await client.session.messages({
+                path: { id: sid },
+                query: q,
+            }));
+            if (!Array.isArray(result) || result.length === 0)
+                break;
+            out.push(...result);
+            if (result.length < PAGE_SIZE)
+                break;
+            const last = result[result.length - 1];
+            const nextBefore = typeof last?.info?.id === "string" ? last.info.id : typeof last?.id === "string" ? last.id : undefined;
+            if (!nextBefore || nextBefore === before)
+                break;
+            before = nextBefore;
+        }
+        return out;
+    }
+    const backfillSession = async (st, client, sid, info) => {
+        const sessionInfoValue = info ?? (await sessionInfo(client, sid));
+        if (sessionInfoValue)
+            enqueue(st, itemFor("session", redact(sessionInfoValue), sid));
+        const messages = await fetchMessages(client, sid);
+        let modelSeen = false;
+        for (const message of messages) {
+            const m = (message.info ?? message);
+            if (!m || typeof m.id !== "string")
+                continue;
+            enqueue(st, itemFor("message", m, sid));
+            if (m.role === "user" && m.model) {
+                modelSeen = true;
+                const label = formatLabel(st.opts?.modelLabel ?? cfg.modelLabel, m.model);
+                enqueue(st, itemFor("model", [{ id: m.model.modelID, providerID: m.model.providerID, name: label }], sid));
+            }
+            for (const part of message.parts ?? []) {
+                const p = part;
+                if (!p || typeof p.id !== "string" || typeof p.messageID !== "string")
+                    continue;
+                if (p.state?.status === "error")
+                    st.badSignal = true;
+                enqueue(st, itemFor("part", p, sid));
+            }
+        }
+        if (!modelSeen && sessionInfoValue?.model) {
+            // hosts whose user messages carry no model (v2): label from the
+            // session's own model
+            const label = formatLabel(st.opts?.modelLabel ?? cfg.modelLabel, sessionInfoValue.model);
+            enqueue(st, itemFor("model", [{ id: sessionInfoValue.model.modelID, providerID: sessionInfoValue.model.providerID, name: label }], sid));
+        }
+        return messages;
+    };
+    const backfill = async (st, info) => {
+        const client = st.client;
+        if (!client)
+            return;
+        const messages = await backfillSession(st, client, st.sid, info);
+        if (messages.length === 0 && !info) {
+            // nothing synced yet and no info in hand: the session item is the
+            // one thing a viewer always needs — fetch it explicitly
+            const fetched = await sessionInfo(client, st.sid);
+            if (fetched)
+                enqueue(st, itemFor("session", redact(fetched), st.sid));
+        }
+        // children (subagent sessions) share the parent's page
+        if (typeof client.session.list === "function") {
+            try {
+                const result = unwrap(await client.session.list({ query: query() }));
+                if (Array.isArray(result)) {
+                    for (const raw of result) {
+                        if (!raw || typeof raw.id !== "string")
+                            continue;
+                        if (raw.parentID !== st.sid)
+                            continue;
+                        childToParent.set(raw.id, st.sid);
+                        await backfillSession(st, client, raw.id, raw);
+                    }
+                }
+            }
+            catch (e) {
+                log("backfill child list failed:", e?.message || e);
+            }
+        }
+        if (typeof client.session.diff === "function") {
+            try {
+                const diff = unwrap(await client.session.diff({
+                    path: { id: st.sid },
+                    query: query(),
+                }));
+                if (diff !== undefined)
+                    enqueue(st, itemFor("session_diff", diff, st.sid));
+            }
+            catch {
+                // diff is best-effort
+            }
+        }
+        // seeded "completed" but history contains errors -> "error"
+        if (st.status === "completed" && st.badSignal)
+            st.status = "error";
+    };
+    // ---- events ------------------------------------------------------------
+    const debugEvents = !!process.env.OPENSHARE_DEBUG_EVENTS;
+    const trackChild = (sid, info) => {
+        if (info?.parentID) {
+            const parent = childToParent.get(sid) ?? info.parentID;
+            childToParent.set(sid, parent);
+            return parent;
+        }
+        return null;
+    };
+    /** A child session whose events arrived BEFORE its session.created got
+     * created as a bogus MAIN st (own share). When the parent relationship
+     * is finally known, merge: move queued items into the parent's share
+     * and retire the bogus one (worker delete + metadata cleanup). */
+    const adoptStrayChild = (childSid, parentSid) => {
+        const stray = sessions.get(childSid);
+        const parent = sessions.get(parentSid);
+        if (!stray || stray.closed)
+            return;
+        if (parent && parent !== stray) {
+            for (const [key, item] of stray.queue)
+                parent.queue.set(key, item);
+            stray.queue.clear();
+            // a stray's remotes may hold shares/pending the parent should adopt:
+            // merge per-server state so the parent's fan-out covers them
+            for (const [url, sr] of stray.remotes) {
+                const pr = remoteFor(parent, url);
+                if (!pr.shareId && sr.shareId) {
+                    pr.shareId = sr.shareId;
+                    pr.secret = sr.secret;
+                    pr.ackedRev = sr.ackedRev;
+                }
+                for (const frame of sr.pending)
+                    pr.pending.push(frame);
+                sr.pending = [];
+                sr.shareId = null;
+                sr.secret = null;
+            }
+            scheduleFlush(parent);
+        }
+        for (const sr of stray.remotes.values()) {
+            if (sr.shareId)
+                log(`stray child share ${sr.shareId} (${sr.url}) -> merging into ${parentSid}`);
+        }
+        remove(stray);
+    };
+    const handleSessionEvent = (t, sid, info) => {
+        const parent = trackChild(sid, info);
+        if (mode === "manual") {
+            if (parent) {
+                // children follow their parent's share; a child event never
+                // activates anything on its own
+                const st = sessions.get(parent);
+                if (st?.activated && !st.closed) {
+                    if (!st.prefsSent) {
+                        st.prefsSent = true;
+                        enqueue(st, itemFor("prefs", { openTasksInNewTab: cfg.openTasksInNewTab !== false }, sid));
+                    }
+                    if (info)
+                        enqueue(st, itemFor("session", redact(info), sid));
+                }
+                return;
+            }
+            const flag = shareFlag(info);
+            const st = sessions.get(sid);
+            if (flag.enabled) {
+                if (st?.activated && !st.closed) {
+                    // already sharing: opts updates apply, flag removal handled below
+                    if (flag.opts)
+                        st.opts = flag.opts;
+                    if (!st.prefsSent) {
+                        st.prefsSent = true;
+                        enqueue(st, itemFor("prefs", { openTasksInNewTab: cfg.openTasksInNewTab !== false }, sid));
+                    }
+                    if (info)
+                        enqueue(st, itemFor("session", redact(info), sid));
+                    if (t === "session.updated")
+                        chain = chain.then(() => refreshOptOuts(st)).catch(() => { });
+                    return;
+                }
+                activate(sid, flag.opts, info);
+                const fresh = sessions.get(sid);
+                if (fresh && !fresh.prefsSent) {
+                    fresh.prefsSent = true;
+                    enqueue(fresh, itemFor("prefs", { openTasksInNewTab: cfg.openTasksInNewTab !== false }, sid));
+                }
+                return;
+            }
+            if (st?.activated && !st.closed && t === "session.updated") {
+                // flag removed -> unshare (same path as session.deleted)
+                log(`share disabled for ${sid} - removing`);
+                chain = chain.then(() => remove(st)).catch((e) => logError("remove error", e?.message || e));
+                return;
+            }
+            return;
+        }
+        // all-mode: NEW sessions share automatically; sessions that predate
+        // plugin start share only when explicitly opted in (metadata flag) or
+        // already carrying a binding (resume keeps the same share). This is
+        // critical: attaching the plugin to a long-lived server must never
+        // retro-share the user's entire session history on first prompt.
+        const main = parent ?? sid;
+        if (parent && parent !== sid && sessions.has(sid)) {
+            // stray child discovered: its events created a bogus main share
+            // before the parentID was known — fold it into the parent's
+            if (!sessions.has(main)) {
+                const created = newSt(main);
+                created.activated = true;
+                sessions.set(main, created);
+                queueConnectAll(created);
+            }
+            adoptStrayChild(sid, main);
+        }
+        let st = sessions.get(main);
+        if (!st && !parent) {
+            const flag = shareFlag(info);
+            const hasBinding = !!info?.metadata?.[METADATA_KEY];
+            const createdMs = info?.time?.created;
+            const isPreExisting = typeof createdMs === "number" && createdMs < bootTime;
+            if (isPreExisting && !flag.enabled && !hasBinding) {
+                if (!preExistingRetired.has(main)) {
+                    preExistingRetired.add(main);
+                    log(`session ${main} predates plugin start - not shared (set the share flag to share it)`);
+                }
+                return;
+            }
+            if (flag.enabled) {
+                // explicit opt-in on a pre-existing session: full gated activation
+                // (status seed + backfill + connect) so the page carries history
+                activate(main, flag.opts, info, { gated: true });
+                st = sessions.get(main);
+            }
+            else {
+                const created = newSt(main);
+                created.activated = true;
+                sessions.set(main, created);
+                st = created;
+                queueConnectAll(created);
+            }
+        }
+        if (!st)
+            return;
+        if (!st.prefsSent) {
+            st.prefsSent = true;
+            enqueue(st, itemFor("prefs", { openTasksInNewTab: cfg.openTasksInNewTab !== false }, sid));
+        }
+        if (info)
+            enqueue(st, itemFor("session", redact(info), sid));
+        if (t === "session.updated" && st.activated && !st.closed) {
+            chain = chain.then(() => refreshOptOuts(st)).catch(() => { });
+        }
+    };
+    return {
+        mode,
+        config: () => cfg,
+        hooks: {
+            event: async ({ event }) => {
+                const t = event?.type;
+                const p = event?.properties || {};
+                const sid = p.sessionID;
+                if (!sid)
+                    return;
+                if (debugEvents) {
+                    const par = p.info?.parentID;
+                    log(`event: ${t} ${sid}${par ? ` (child of ${par})` : ""}`);
+                }
+                if (t === "session.created" || t === "session.updated") {
+                    handleSessionEvent(t, sid, p.info);
+                }
+                else if (t === "session.status") {
+                    const st = stFor(sid);
+                    if (!st)
+                        return;
+                    const type = p.status?.type;
+                    touch(st);
+                    if (type === "busy") {
+                        // work resumed: a pending completed flip is cancelled (opencode
+                        // idles between sequential automation prompts — that is NOT
+                        // "done"), a recovered retry is forgiven, share is live again.
+                        // The busy epoch is the completed-flip guard: only WORK
+                        // invalidates a pending settle (v1.18 republishes the
+                        // status/idle pair on failure paths — a repeated idle must
+                        // NOT void it, live-caught as a share stuck on live forever)
+                        st.statusEpoch++;
+                        if (st.completedTimer) {
+                            clearTimeout(st.completedTimer);
+                            st.completedTimer = null;
+                        }
+                        st.badSignal = false;
+                        st.status = "live";
+                        ensureConnected(st);
+                        scheduleFlush(st);
+                    }
+                    else if (type === "idle") {
+                        // opencode's idle is authoritative turn end (v1 holds busy
+                        // through steps, tool runs and permission waits). CONTENT
+                        // flushes now — turn-end batches must not ride the sync
+                        // interval (live-caught: subagent finals lagged one interval).
+                        // Only the completed flip waits out completedDelayMs, guarded
+                        // by the busy epoch: work resuming voids it, repeated idle
+                        // publications do not. Dispose flushes a pending flip, so CI
+                        // runs still land their final status.
+                        if (st.timer)
+                            clearTimeout(st.timer);
+                        st.timer = null;
+                        chain = chain
+                            .then(() => flush(st))
+                            .catch((e) => logError("idle flush error", e?.message || e));
+                        const epoch = st.statusEpoch;
+                        const settle = () => {
+                            st.status = st.badSignal ? "error" : "completed";
+                            st.badSignal = false;
+                            if (st.timer)
+                                clearTimeout(st.timer);
+                            st.timer = null;
+                            chain = chain
+                                .then(() => flush(st))
+                                .then(() => {
+                                armSettleDrop(st);
+                            })
+                                .catch((e) => logError("settle flush error", e?.message || e));
+                        };
+                        if (cfg.completedDelayMs <= 0) {
+                            settle();
+                        }
+                        else if (!st.completedTimer && !st.closed) {
+                            st.completedTimer = setTimeout(() => {
+                                st.completedTimer = null;
+                                if (st.closed || st.statusEpoch !== epoch)
+                                    return;
+                                settle();
+                            }, cfg.completedDelayMs);
+                        }
+                    }
+                    else if (type === "retry") {
+                        // scheduled backoff retry (attempt/next): NOT terminal — busy
+                        // forgiveness above clears it when work resumes and completes
+                        st.badSignal = true;
+                    }
+                }
+                else if (t === "session.error") {
+                    // terminal turn error (aborted run, context overflow): the share
+                    // says error at the following idle; recovered retries never set it
+                    const st = stFor(sid);
+                    if (st) {
+                        st.badSignal = true;
+                        touch(st);
+                    }
+                }
+                else if (t === "message.removed" || t === "message.part.removed") {
+                    // opencode undo: revert() only marks the session (the viewer
+                    // hides the range); the NEXT prompt hard-deletes the reverted
+                    // messages/parts via cleanup() and publishes these events.
+                    // The worker's store is upsert-only, so without an explicit
+                    // tombstone the deleted items live forever and reappear the
+                    // moment the revert marker clears (live-caught in production).
+                    const st = stFor(sid);
+                    if (!st || !st.activated || st.closed)
+                        return;
+                    const messageID = p.messageID;
+                    if (!messageID)
+                        return;
+                    if (t === "message.removed") {
+                        enqueue(st, { key: `message/${messageID}`, item: { type: "message", del: true, data: { id: messageID } } });
+                    }
+                    else {
+                        const partID = p.partID;
+                        if (!partID)
+                            return;
+                        enqueue(st, { key: `part/${messageID}/${partID}`, item: { type: "part", del: true, data: { id: partID, messageID } } });
+                    }
+                }
+                else if (t === "message.updated") {
+                    // resumed sessions may emit the user message BEFORE any session.*
+                    // event — in all-mode an unknown sid is optimistically treated as
+                    // main and VERIFIED against the session record (children announce
+                    // via session.created+parentID first); in manual-mode unknown
+                    // sids are dropped (the flag-bearing session.updated activates,
+                    // and backfill fills the past)
+                    const main = childToParent.get(sid) ?? sid;
+                    let st = sessions.get(main);
+                    if (!st && mode === "all" && !preExistingRetired.has(main)) {
+                        const created = newSt(main);
+                        created.activated = true;
+                        sessions.set(main, created);
+                        st = created;
+                        // pre-existing-session gate for the no-info path: verify
+                        // against the session record BEFORE connecting (a retired
+                        // session never reaches the worker, never announces, never
+                        // writes the url file); a pass connects, and queued events
+                        // ride the normal pending replay
+                        if (!verifying.has(main)) {
+                            verifying.add(main);
+                            chain = chain
+                                .then(async () => {
+                                if (created.closed)
+                                    return;
+                                const info = await sessionInfo(created.client, main);
+                                verifying.delete(main);
+                                if (created.closed)
+                                    return;
+                                const flag = shareFlag(info);
+                                const hasBinding = !!info?.metadata?.[METADATA_KEY];
+                                const createdMs = info?.time?.created;
+                                const isPreExisting = typeof createdMs === "number" && createdMs < bootTime;
+                                if (debugEvents) {
+                                    log(`verify ${main}: created=${createdMs} boot=${bootTime} pre=${isPreExisting} flag=${flag.enabled} binding=${hasBinding} infoMissing=${!info}`);
+                                }
+                                if (isPreExisting && !flag.enabled && !hasBinding) {
+                                    preExistingRetired.add(main);
+                                    log(`session ${main} predates plugin start - not shared (set the share flag to share it)`);
+                                    remove(created);
+                                    return;
+                                }
+                                queueConnectAll(created);
+                            })
+                                .catch((e) => {
+                                verifying.delete(main);
+                                logError("verify error", e?.message || e);
+                            });
+                        }
+                    }
+                    if (!st || !st.activated || st.closed)
+                        return;
+                    enqueue(st, itemFor("message", p.info, sid));
+                    const info = p.info;
+                    if (info?.role === "user" && info?.model) {
+                        const label = formatLabel(st.opts?.modelLabel ?? cfg.modelLabel, info.model);
+                        enqueue(st, itemFor("model", [{ id: info.model.modelID, providerID: info.model.providerID, name: label }], sid));
+                    }
+                    // an assistant message that DIED (finish:"error") — e.g. all
+                    // retries exhausted — surfaces as a 200 response with an errored
+                    // message, NOT as session.error (live-caught in the suite); the
+                    // share must still say error
+                    if (info?.role === "assistant" && info.finish === "error") {
+                        st.badSignal = true;
+                    }
+                }
+                else if (t === "message.part.updated") {
+                    const st = stFor(sid);
+                    if (!st || !st.activated || st.closed)
+                        return;
+                    const part = p.part;
+                    if (part?.state?.status === "error")
+                        st.badSignal = true;
+                    enqueue(st, itemFor("part", part, sid));
+                }
+                else if (t === "session.diff") {
+                    const st = stFor(sid);
+                    if (!st || !st.activated || st.closed)
+                        return;
+                    enqueue(st, itemFor("session_diff", p.diff, sid));
+                }
+                else if (t === "session.deleted") {
+                    // a CHILD session ending (task done, gc) must NEVER take the
+                    // parent's share down with it — the page keeps the subagent's
+                    // output; only the MAIN session's deletion unshares
+                    const isChild = childToParent.has(sid);
+                    if (isChild) {
+                        if (debugEvents)
+                            log("event: child session.deleted (ignored)", sid);
+                        return;
+                    }
+                    const st = sessions.get(sid);
+                    if (!st)
+                        return;
+                    chain = chain.then(() => remove(st)).catch((e) => logError("remove error", e?.message || e));
+                }
+            },
+            dispose: async () => {
+                for (const st of sessions.values()) {
+                    if (st.completedTimer) {
+                        // a pending idle never got its delay: resolve now so the
+                        // final status lands even though the process is exiting
+                        // (the timer existing implies idle was the last signal; the
+                        // epoch guard is satisfied by definition — nothing newer ran)
+                        clearTimeout(st.completedTimer);
+                        st.completedTimer = null;
+                        st.status = st.badSignal ? "error" : "completed";
+                        st.badSignal = false;
+                    }
+                    if (st.timer)
+                        clearTimeout(st.timer);
+                    st.timer = null;
+                    for (const r of st.remotes.values()) {
+                        if (r.initTimer) {
+                            clearTimeout(r.initTimer);
+                            r.initTimer = null;
+                        }
+                        cancelSettleDrop(r);
+                        if (r.idleDropTimer) {
+                            clearTimeout(r.idleDropTimer);
+                            r.idleDropTimer = null;
+                        }
+                    }
+                    const flushed = flush(st);
+                    if (flushed && typeof flushed.then === "function")
+                        await flushed.catch(() => { });
+                    // dispose with a mid-handshake socket: the deferred pending
+                    // would die with the process — land it over HTTP instead
+                    for (const r of st.remotes.values()) {
+                        if (!r.wsReady && r.shareId && r.pending.length) {
+                            await flushViaHttp(st, r).catch(() => { });
+                        }
+                    }
+                    if (st.metaTimer)
+                        clearTimeout(st.metaTimer);
+                    st.metaTimer = null;
+                    await writeBinding(st).catch(() => { });
+                }
+                for (const st of sessions.values()) {
+                    for (const r of st.remotes.values()) {
+                        try {
+                            r.ws?.close();
+                        }
+                        catch { }
+                    }
+                }
+            },
+        },
+    };
+}