@mirrowel/opencode-openshare 0.2.0 → 0.3.0-dev.1

package/dist/core.js

@@ -36,17 +36,19 @@
 // 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
+//    opts: { ttlHours?, 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 { homedir } from "node:os";
 import { createHash } from "node:crypto";
-import { join } from "node:path";
-import { METADATA_KEY, loadConfig, resolveShareMode, spoolDirFor, URL_FILE_NONE, resolveServer, saveServerToken } from "./config.js";
+import { isAbsolute, join } from "node:path";
+import { METADATA_KEY, DEFAULTS, configHomePath, configSourceMap, loadConfig, resolveShareMode, spoolDirFor, URL_FILE_NONE, resolveServer, saveServerToken } from "./config.js";
 import { cursorFor, isV2NativeMessage, messageTombstone, normalizeV1Diff, normalizeV1Message } from "./contract.js";
 import { queueBindingWrite } from "./binding-queue.js";
+import { activeRules, redactItem } from "./redact.js";
 const DEFAULT_POLICY = {
     mode: "persistent",
     turnGraceMs: 120000,
@@ -56,9 +58,9 @@ const DEFAULT_POLICY = {
     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.
+// Stderr policy: in manual mode (TUI present) stderr is for ACTUAL ERRORS
+// only. Informational lines (live:/url file:/mode banner, lifecycle
+// traces) are suppressed because the TUI surfaces the URL itself.
 // All-mode (CI/server-only) keeps its stderr contract (announce lines,
 // silenceable via announceStderr). Error-class lines always reach stderr.
 let stderrInfoAllowed = true;
@@ -117,6 +119,22 @@ function redact(info) {
     delete metadata[METADATA_KEY];
     return { ...info, metadata };
 }
+/** Wave 3 data-inventory split: machine-local facts leave the PUBLIC
+ * session item. Viewers recover them from the envelope's private block
+ * (gated+authenticated shares only); anonymous shares never store them. */
+function stripLocalFacts(info) {
+    if (!info || typeof info !== "object")
+        return info;
+    const out = { ...info };
+    let changed = false;
+    for (const k of ["directory", "worktree"]) {
+        if (out[k] !== undefined) {
+            delete out[k];
+            changed = true;
+        }
+    }
+    return changed ? out : info;
+}
 function shareFlag(info) {
     const raw = info?.metadata?.[METADATA_KEY];
     if (!raw || typeof raw !== "object")
@@ -128,8 +146,11 @@ function shareFlag(info) {
     const opts = {};
     if (optsRaw && typeof optsRaw === "object") {
         const o = optsRaw;
-        if (typeof o.ttlDays === "number" && o.ttlDays > 0)
-            opts.ttlDays = o.ttlDays;
+        // legacy days-shaped opts migrate x24 (old bindings)
+        if (typeof o.ttlHours === "number" && o.ttlHours > 0)
+            opts.ttlHours = Math.floor(o.ttlHours);
+        else if (typeof o.ttlDays === "number" && o.ttlDays > 0)
+            opts.ttlHours = Math.floor(o.ttlDays * 24);
         if (typeof o.authLogin === "string")
             opts.authLogin = o.authLogin;
         if (typeof o.authPassword === "string")
@@ -139,6 +160,28 @@ function shareFlag(info) {
     }
     return { enabled: true, opts: Object.keys(opts).length ? opts : undefined };
 }
+/** The LIVE engine's resolved target urls (shared module state: the TUI
+ * entry reads this so surfaces that gate on "is anything configured" agree
+ * with what the engine actually targets - file config alone can miss
+ * plugin-options-layer config the TUI cannot see). */
+let liveTargets = [];
+// the live engine registers its counter here (the TUI imports the
+// accessor without holding the engine instance)
+let statsProvider = null;
+// Wave 3 preflight ledger: per-session redaction hits (count + first
+// samples, verbatim, so false positives are visible in the consent
+// preview before anything is published)
+const redactionLedger = new Map();
+/** Preflight stats for the consent dialog: message/tool counts plus the
+ * redaction ledger (what would be stripped before publishing). */
+export function sessionStatsFor(sid) {
+    const led = redactionLedger.get(sid) ?? { count: 0, samples: [] };
+    const counts = statsProvider ? statsProvider(sid) : { messages: 0, toolCalls: 0 };
+    return { ...counts, redaction: led };
+}
+export function engineTargetUrls() {
+    return liveTargets;
+}
 export function createEngine(deps) {
     let cfg = loadConfig(deps.pluginDir, deps.options);
     const mode = resolveShareMode(cfg, deps);
@@ -173,8 +216,16 @@ export function createEngine(deps) {
     log(`share mode: ${mode} (directory: ${deps.directory ?? "?"} worktree: ${deps.worktree ?? "?"})`);
     const resolveTargets = () => {
         const merged = {};
-        if (cfg.workerUrl)
+        const hasServers = !!cfg.servers && Object.keys(cfg.servers).length > 0;
+        // layer-aware legacy rule: a FILE workerUrl beside a FILE servers group
+        // would silently dual-home the session; an ENV workerUrl is the
+        // highest-priority layer and always joins.
+        const envWorker = !!process.env.OPENSHARE_WORKER_URL;
+        if (cfg.workerUrl && (!hasServers || envWorker))
             merged[cfg.workerUrl] = { token: cfg.createToken || "", active: true };
+        if (cfg.workerUrl && hasServers && !envWorker && !cfg.servers[cfg.workerUrl]) {
+            log(`legacy workerUrl ${cfg.workerUrl} ignored: a servers group is configured - remove one of the two`);
+        }
         if (cfg.servers)
             for (const [u, e] of Object.entries(cfg.servers))
                 merged[u] = { ...merged[u], ...e };
@@ -184,6 +235,7 @@ export function createEngine(deps) {
         return chosen.map((url) => ({ url, entry: merged[url] }));
     };
     let targets = resolveTargets();
+    liveTargets = targets.map((t) => t.url);
     // ---- 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
@@ -215,42 +267,116 @@ export function createEngine(deps) {
     };
     seedCredentials();
     const ENROLL_RETRY_MS = 60000;
+    // B4 Class B (server-SUGGESTED modelLabel/shareMode): fetch once per
+    // server per boot, adopt ONLY keys with no explicit local source, and
+    // persist the adoption to the settings home (owner: no repeated CF
+    // fetches). One flag per URL for the whole process lifetime.
+    const setsFetched = new Set();
+    const adoptServerSuggestions = async (url, token) => {
+        if (setsFetched.has(url))
+            return;
+        setsFetched.add(url);
+        try {
+            const r = await fetch(`${url}/api/token/sets`, {
+                headers: { authorization: `Bearer ${token}` },
+                signal: AbortSignal.timeout(8000),
+            });
+            const body = r.ok ? (await r.json().catch(() => null)) : null;
+            const sets = body?.sets ?? {};
+            const pick = sets[cfg.configSet ?? ""] ?? Object.values(sets)[0];
+            if (!pick)
+                return;
+            const wantModel = typeof pick.modelLabel === "string" && !pick.modelLabel ? undefined : pick.modelLabel;
+            const wantMode = pick.shareMode === "all" || pick.shareMode === "manual" ? pick.shareMode : undefined;
+            // adopt only what is UNSPECIFIED locally: modelLabel sits at the
+            // default template, shareMode is unset and env carry no override
+            const src = configSourceMap(deps.pluginDir ?? "");
+            const modelUnset = cfg.modelLabel === DEFAULTS.modelLabel && !src.modelLabel;
+            const modeUnset = cfg.shareMode === undefined && !src.shareMode;
+            const adoptModel = wantModel && modelUnset;
+            const adoptMode = wantMode && modeUnset;
+            if (!adoptModel && !adoptMode)
+                return;
+            // surgical write into the settings home: read, patch just these
+            // keys when they are absent, write back (never clobber explicit
+            // values that appeared since load)
+            const home = configHomePath();
+            if (!home)
+                return;
+            let doc = {};
+            try {
+                doc = JSON.parse(readFileSync(home, "utf8"));
+                if (!doc || typeof doc !== "object")
+                    doc = {};
+            }
+            catch { }
+            let dirty = false;
+            if (adoptModel && doc.modelLabel === undefined) {
+                doc.modelLabel = wantModel;
+                dirty = true;
+                log(`${url}: adopted modelLabel from the server config set`);
+            }
+            if (adoptMode && doc.shareMode === undefined) {
+                doc.shareMode = wantMode;
+                dirty = true;
+                log(`${url}: adopted shareMode from the server config set`);
+            }
+            if (dirty)
+                writeFileSync(home, JSON.stringify(doc, null, 2) + "\n");
+        }
+        catch {
+            // suggestions are best-effort; a failed fetch never blocks sharing
+        }
+    };
     const ensureCredential = async (url) => {
         const c = credOf(url);
         const target = targets.find((t) => t.url === url);
-        if (c.credential)
+        if (c.credential) {
+            void adoptServerSuggestions(url, 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;
+        // A configured code IS expressed onboarding intent (headless-safe: CI
+        // carries it precisely to enroll). Without one, never auto-enroll:
+        // public servers share anonymously (the ask-once TUI flow offers an
+        // account), private ones refuse until the user connects via
+        // /openshare.
+        const code = target?.entry.code ?? "";
+        if (!code) {
+            try {
+                const h = await fetch(`${url}/health`, { signal: AbortSignal.timeout(8000) });
+                const hb = h.ok ? (await h.json().catch(() => null)) : null;
+                if (hb?.auth?.mode === "public") {
+                    c.error = ""; // anonymous standing - tokenless create works
+                    return "";
                 }
-                c.error = `enroll refused: ${b?.error ?? `HTTP ${r.status}`}`;
+                c.error = "private server - onboard via /openshare (needs an access code)";
             }
-            else if (authMode2 === "private") {
-                c.error = "private server: add servers.{url}.code (or token) to enroll";
+            catch (e) {
+                c.error = `server unreachable: ${e?.message || e}`;
             }
-            else {
-                c.error = `server health unreachable (HTTP ${h.status})`;
+            logError(`no credential for ${url}: ${c.error}`);
+            return "";
+        }
+        try {
+            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" : ""}`);
+                void adoptServerSuggestions(url, c.credential);
+                return c.credential;
             }
+            c.error = `enroll refused: ${b?.error ?? `HTTP ${r.status}`}`;
         }
         catch (e) {
             c.error = `enrollment failed: ${e?.message || e}`;
@@ -385,7 +511,8 @@ export function createEngine(deps) {
         badSignal: false,
         lastSentStatus: null,
         closed: false,
-        prefsSent: false,
+        lastError: null,
+        ttlClamped: null,
         binding: null,
         bindingQueried: false,
         optOuts: new Set(),
@@ -406,6 +533,7 @@ export function createEngine(deps) {
             spoolRoot = spoolDirFor(cfg);
             const before = new Set(targets.map((t) => t.url));
             targets = resolveTargets();
+            liveTargets = targets.map((t) => t.url);
             seedCredentials();
             clampToPolicy();
             if (debugEvents) {
@@ -619,13 +747,17 @@ export function createEngine(deps) {
         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").
+        // A binding in session metadata means opted-in, so enabled: true is
+        // written in BOTH modes. All-mode bindings without `enabled` made the
+        // TUI gate fall through to the consent dialog on an already-shared
+        // session; live is uniformly "url && enabled !== false".
         const value = { v: 2, servers, enabled: true };
         if (mode === "manual" && st.opts)
             value.opts = st.opts;
+        if (st.lastError)
+            value.lastError = st.lastError;
+        if (st.ttlClamped)
+            value.ttlClamped = st.ttlClamped;
         st.binding = value;
         st.wroteBinding = true;
         await writeMetadata(st, value);
@@ -675,9 +807,9 @@ export function createEngine(deps) {
             appendFileSync(queuePath(st, r.url), (f.wire ?? JSON.stringify(f)) + "\n");
         }
         catch (e) {
-            // the frame lives ONLY in memory now — flag the remote so the next
-            // spoolLoad does NOT replace in-memory pending with the shorter
-            // disk queue (silent loss otherwise; live-caught class in review)
+            // the frame lives ONLY in memory now, so flag the remote: the next
+            // spoolLoad must NOT replace in-memory pending with the shorter disk
+            // queue (silent loss otherwise).
             r.spoolAppendFailed = true;
             logError("spool append failed", e?.message || e);
         }
@@ -700,10 +832,10 @@ export function createEngine(deps) {
     };
     const spoolLoad = (st, r) => {
         // meta first (share binding recovery), in its OWN try: a missing meta
-        // file is normal (it's only written after the first successful
-        // handshake) and must NOT touch pending (live-caught class: the old
-        // blanket catch wiped in-memory pending AND skipped the queue read,
-        // so everything queued before the first successful connect was lost).
+        // file is normal (written only after the first successful handshake)
+        // and must NOT touch pending. A blanket catch here wipes in-memory
+        // pending AND skips the queue read, so everything queued before the
+        // first successful connect is lost.
         try {
             const meta = JSON.parse(readFileSync(metaPath(st, r.url), "utf8"));
             // metadata binding (db) is authoritative when both exist and disagree
@@ -887,27 +1019,99 @@ export function createEngine(deps) {
             // 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");
+            const file = cfg.urlFile
+                ? isAbsolute(cfg.urlFile)
+                    ? cfg.urlFile
+                    : join(deps.directory ?? process.cwd(), cfg.urlFile)
+                : join(deps.directory ?? process.cwd(), "openshare.urls.txt");
             try {
-                appendFileSync(file, url + "\n");
+                // "json" format: one machine-readable object per line (CI parses
+                // fields instead of URLs). Status is the engine's current signal
+                // at announce time; the completed flip updates the SHARE, not
+                // this file line.
+                const line = cfg.urlFileFormat === "json"
+                    ? JSON.stringify({
+                        id: r.shareId,
+                        url,
+                        status: st.lastSentStatus ?? "waiting",
+                        gated: (st.opts?.authLogin ?? cfg.authLogin ?? "") !== "",
+                    }) + "\n"
+                    : url + "\n";
+                appendFileSync(file, line);
                 if (cfg.announceStderr && (file !== lastUrlFile || !urlFileAnnounced)) {
                     urlFileAnnounced = true;
                     lastUrlFile = file;
                     log(`url file: ${file}`);
                 }
             }
-            catch { }
+            catch (e) {
+                // a CI pipeline reads this file after the process exits; a silent
+                // failure means the run's share URL is simply gone
+                logError(`url file write failed (${file}):`, e?.message || e);
+            }
         }
     };
+    let halfAuthWarned = false;
     const authFrame = (st) => {
         // always send both (empty strings included): attach with empty values
-        // REMOVES protection — an intentional owner action. Session opts
+        // 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 ?? "";
+        // both-or-none: the server builds a gate only from a full pair, so a
+        // half pair silently means "no gate" - refuse to send one and say so
+        if ((login === "") !== (password === "")) {
+            if (!halfAuthWarned) {
+                halfAuthWarned = true;
+                logError("read auth needs BOTH a login and a password - gate disabled until fixed");
+            }
+            return { authLogin: "", authPassword: "" };
+        }
         return { authLogin: login, authPassword: password };
     };
-    const ttlFor = (st) => st.opts?.ttlDays ?? cfg.ttlDays;
+    const ttlFor = (st) => st.opts?.ttlHours ?? cfg.ttlHours;
+    // free-form labels for team directories/admin listings: ${NAME} refs
+    // resolve from the process env at send time; unresolved refs stay
+    // literal (visible beats silently-empty). Cached env lookup, max 20
+    // keys/500 chars per value (config loader caps the same).
+    const metaFor = () => {
+        if (!cfg.meta || typeof cfg.meta !== "object")
+            return undefined;
+        const out = {};
+        let n = 0;
+        for (const [k, v] of Object.entries(cfg.meta)) {
+            if (n >= 20)
+                break;
+            out[k] = v.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (m, name) => process.env[name] ?? m);
+            n++;
+        }
+        return Object.keys(out).length ? out : undefined;
+    };
+    /** Apply a metadata opts update. On a CHANGED opts set for a session with
+     * live sockets, re-send the attach frame over each open socket: the
+     * worker's attach path applies read-auth retroactively (rotating viewer
+     * tokens on change) and now also honors an explicit ttlHours override -
+     * so settings heal immediately instead of waiting for a reconnect.
+     * Re-attach is idempotent (no once-guard on init; earlySyncs empty at
+     * steady state) and revalidates the token. */
+    const applyOpts = (st, opts) => {
+        if (!opts)
+            return;
+        const prev = st.opts ? JSON.stringify(st.opts) : "";
+        st.opts = opts;
+        if (prev === JSON.stringify(opts))
+            return;
+        for (const [url, r] of st.remotes) {
+            if (!r.shareId || !r.secret || !r.wsReady)
+                continue;
+            const attach = { id: r.shareId, secret: r.secret, ...authFrame(st) };
+            if (st.opts?.ttlHours)
+                attach.ttlHours = st.opts.ttlHours;
+            const sent = wsSend(r, { op: "init", attach });
+            if (sent)
+                log(`opts re-synced to ${url.slice(0, 24)}${st.opts?.ttlHours ? ` (ttl ${st.opts.ttlHours}h)` : ""}`);
+        }
+    };
     /** 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. */
@@ -925,9 +1129,9 @@ export function createEngine(deps) {
     };
     /** 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). */
+     * STARTED. The connecting flag alone guards execution, not the queue,
+     * and double connects create duplicate shares and init storms (one
+     * create per socket). */
     const queueConnect = (st, r) => {
         if (st.closed || r.connectQueued || r.connecting || r.authBlocked || r.collided)
             return;
@@ -1000,7 +1204,7 @@ export function createEngine(deps) {
                 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
+            // 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;
@@ -1016,18 +1220,41 @@ export function createEngine(deps) {
                 r.announced = false;
                 queueConnect(st, r);
             }
+            // re-share after "leave as-is": the entry kept its id/secret and the
+            // opt-out marker is gone - re-arm a remote that ATTACHES the same
+            // page (same URL), then backfill so the frozen gap catches up
+            // (dedupe hashes describe the OLD remote set, not this revival)
+            let rearmed = false;
+            for (const [url, e] of Object.entries(servers)) {
+                if (st.optOuts.has(url) || st.remotes.has(url))
+                    continue;
+                const ee = e;
+                if (typeof ee.id !== "string" || typeof ee.secret !== "string" || !ee.id)
+                    continue;
+                const r = remoteFor(st, url);
+                r.shareId = ee.id;
+                r.secret = ee.secret;
+                r.ackedRev = typeof ee.rev === "number" ? ee.rev : 0;
+                log(`re-share: re-arming ${url.slice(0, 24)} on share ${ee.id}`);
+                queueConnect(st, r);
+                rearmed = true;
+            }
+            if (rearmed) {
+                st.sentHash.clear();
+                chain = chain.then(() => backfill(st)).catch((e) => logError("re-share backfill error", e?.message || e));
+            }
         }
         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
+        // "connecting" spans the WHOLE handshake: socket open plus init ack.
+        // It is cleared only 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).
+        // (duplicate shares, mismatch storms, empty pages).
         r.connecting = true;
         r.socketSeq += 1;
         const seq = r.socketSeq;
@@ -1044,9 +1271,9 @@ export function createEngine(deps) {
             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).
+            // ack legitimately starts at rev 0, so the mismatch guard is for
+            // attaches only. Applying it to a create spawns 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"})`);
@@ -1140,7 +1367,7 @@ export function createEngine(deps) {
                 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) } });
+                wsSend(r, { op: "init", create: { sessionID: st.sid, ttlHours: ttlFor(st), ...authFrame(st), ...(cfg.configSet ? { set: cfg.configSet } : {}), ...(metaFor() ? { meta: metaFor() } : {}) } });
             }
             // handshake deadline: init sent but no ack (silent worker death)
             // — close, let the close listener reconnect us
@@ -1277,8 +1504,10 @@ export function createEngine(deps) {
                 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.
+                    // Re-enrolling would orphan the shares - surface and stop.
                     r.authBlocked = true;
+                    st.lastError = `share frozen by the hoster (owner frozen) - contact the server admin`;
+                    scheduleBindingWrite(st);
                     logError(`${r.url}: share frozen by the hoster (owner frozen) - edits refused; contact the server admin`);
                     try {
                         r.ws?.close(4000, "frozen");
@@ -1327,14 +1556,16 @@ export function createEngine(deps) {
                     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).
+                // bad base (mismatch protocol). Content REPLAYS to the new share,
+                // and pending is never dropped on a reset: dropping it leaves the
+                // recreate as a husk with the title and zero messages.
                 if (/limit|too many|rate/i.test(err)) {
                     // quota/429 ("max shares reached", "daily create limit", the
                     // anonymous caps): an immediate re-init on the same socket is a
-                    // hot loop against the server — back off through the normal
+                    // hot loop against the server - back off through the normal
                     // reconnect cadence instead
+                    st.lastError = `create refused: ${frame.error ?? "rate limited"}`;
+                    scheduleBindingWrite(st);
                     logError(`${r.url}: create refused:`, frame.error, "- retrying with backoff");
                     r.connecting = false;
                     try {
@@ -1346,23 +1577,25 @@ export function createEngine(deps) {
                     return;
                 }
                 logError(`${r.url}: init refused:`, frame.error, "- creating fresh share");
+                st.lastError = `init refused: ${frame.error ?? "unknown"}`;
+                scheduleBindingWrite(st);
                 deleteAbandoned(r);
                 r.shareId = null;
                 r.secret = null;
                 r.ackedRev = 0;
-                wsSend(r, { op: "init", create: { sessionID: st.sid, ttlDays: ttlFor(st), ...authFrame(st) } });
+                wsSend(r, { op: "init", create: { sessionID: st.sid, ttlHours: ttlFor(st), ...authFrame(st), ...(cfg.configSet ? { set: cfg.configSet } : {}), ...(metaFor() ? { meta: metaFor() } : {}) } });
                 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)
+                // worker lost data behind our back (ATTACH only: a create ack
+                // legitimately starts at rev 0, and misreading that as data loss
+                // spawns a fresh husk)
                 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) } });
+                wsSend(r, { op: "init", create: { sessionID: st.sid, ttlHours: ttlFor(st), ...authFrame(st), ...(cfg.configSet ? { set: cfg.configSet } : {}), ...(metaFor() ? { meta: metaFor() } : {}) } });
                 return;
             }
             const wasFanoutCreate = !r.initWasAttach && st.everConnected;
@@ -1384,11 +1617,10 @@ export function createEngine(deps) {
                 clearTimeout(r.initTimer);
                 r.initTimer = null;
             }
-            // backoff reset is DEFERRED until the socket proves stable: a
-            // server that accepts init then immediately drops would otherwise
-            // reconnect once per second forever (~1 cycle/s per session-server
-            // pair, live-caught in the optimization audit). 30s alive (socket
-            // still ready, no reconnect pending) or a second acked sync.
+            // backoff reset is DEFERRED until the socket proves stable: a server
+            // that accepts init then immediately drops would otherwise reconnect
+            // once per second per session-server pair. Stability means 30s alive
+            // (socket still ready, no reconnect pending) or a second acked sync.
             if (r.backoffResetTimer)
                 clearTimeout(r.backoffResetTimer);
             r.backoffResetTimer = setTimeout(() => {
@@ -1401,6 +1633,56 @@ export function createEngine(deps) {
                 applyPolicy(frame.policy, r.url);
             r.intentionalClose = false;
             touch(st);
+            // the ack carries the RESOLVED ttl: surface a server/token clamp to
+            // the binding once, and a successful handshake clears any stale
+            // refusal reason the TUI may be showing
+            const ackTtl = typeof frame.ttlHours === "number" ? frame.ttlHours : (typeof frame.ttlDays === "number" ? frame.ttlDays * 24 : undefined);
+            if (typeof ackTtl === "number") {
+                const wanted = ttlFor(st);
+                const clamp = wanted != null && ackTtl !== wanted ? { requested: wanted, effective: ackTtl } : null;
+                if (JSON.stringify(clamp) !== JSON.stringify(st.ttlClamped)) {
+                    st.ttlClamped = clamp;
+                    scheduleBindingWrite(st);
+                }
+            }
+            if (st.lastError) {
+                st.lastError = null;
+                scheduleBindingWrite(st);
+            }
+            // ack-level gate assurance (B2): we asked for a gate (both fields
+            // set) but the server reports none - the page is actually public.
+            // Once per remote; the next init-ok re-checks after a fix.
+            const wantedGate = (st.opts?.authLogin ?? cfg.authLogin ?? "") !== "" && (st.opts?.authPassword ?? cfg.authPassword ?? "") !== "";
+            if (wantedGate && frame.auth === false && !r.warnedNoGate) {
+                r.warnedNoGate = true;
+                logError(`${r.url}: read auth requested but the page has NO gate - check the server's auth handling`);
+            }
+            else if (frame.auth === true) {
+                r.warnedNoGate = false;
+            }
+            // Wave 3 pmeta: machine-local facts (directory/worktree) ride their
+            // OWN tiny sync once per init-ok, only to remotes we hold a
+            // credential for - anonymous (ownerless) shares never store them.
+            // Server-side they land in the private block, readable with share
+            // auth. Idempotent upsert; rides no shared frame so fan-out
+            // remotes with mixed identity each get exactly their due.
+            if (credOf(r.url).credential) {
+                const priv = {};
+                const dir = (deps.directory ?? "");
+                if (dir)
+                    priv.directory = dir;
+                if (deps.worktree)
+                    priv.worktree = String(deps.worktree);
+                // the sharer's home lets the server mask absolute paths as ~/...
+                try {
+                    priv.home = homedir();
+                }
+                catch { }
+                if (Object.keys(priv).length) {
+                    const seq = ++nextSeq;
+                    wsSend(r, { op: "sync", items: [{ type: "pmeta", sessionID: st.sid, data: priv }], status: undefined, seq });
+                }
+            }
             announceUrl(st, r);
             // first binding write is immediate (the TUI waits on the URL in
             // session metadata); ack-driven rev updates stay debounced
@@ -1420,12 +1702,12 @@ export function createEngine(deps) {
             }
             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.
-                // The enqueue dedupe must step aside: those hashes say "already
-                // entered the machinery", but the NEW remote never received any
-                // of it (live-caught by F3: the join's backfill was fully
-                // deduped away and the joined share stayed empty).
+                // post-mismatch recreate): its fresh share needs the full history,
+                // and backfill is keyed-idempotent while other servers simply
+                // re-upsert. The enqueue dedupe must step aside here: those hashes
+                // say "already entered the machinery", but the NEW remote received
+                // none of it, so a deduped join backfills nothing and the joined
+                // share stays empty.
                 st.sentHash.clear();
                 chain = chain.then(() => backfill(st)).catch((e) => logError("fan-out backfill error", e?.message || e));
             }
@@ -1533,8 +1815,8 @@ export function createEngine(deps) {
         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")
+    // awaits it: an unawaited fetch dies with the exiting process and the
+    // final status never lands, leaving the share stuck on "live")
     const flush = (st) => {
         if (st.closed)
             return;
@@ -1544,8 +1826,8 @@ export function createEngine(deps) {
         // fan out to every remote; each carries its own pending copy and acks
         // independently. Remotes mid-handshake or auth-blocked just buffer.
         // PENDING IS CHUNK-SHAPED (seq-tagged): one logical frame becomes N
-        // chunk-frames so a partial-ack can never erase unsent chunks
-        // (live-caught class: chunk-1 ack + socket death erased chunks 2..N).
+        // chunk-frames, so a partial ack can never erase unsent chunks (a
+        // chunk-1 ack followed by socket death used to drop chunks 2..N).
         const chunks = f.items.length ? chunkedFrames(f.items, 200, 512 * 1024) : [];
         let httpWork;
         for (const r of st.remotes.values()) {
@@ -1571,8 +1853,8 @@ export function createEngine(deps) {
             }
             // 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.
+            // sync dies as "unknown op", losing whole turns on post-drop
+            // reconnects. The init-ok handler flushes pending itself.
             if (r.ws && !r.wsReady)
                 continue;
             if (r.wsReady) {
@@ -1612,13 +1894,12 @@ export function createEngine(deps) {
     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). DEDUPE BY KEY before chunking:
-        // a streaming message appearing in k pending frames shipped k
-        // copies (up to 25x on a replay burst) — every duplicate was also a
-        // server row-write + a rebroadcast frame.
+        // 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, losing content on reconnect paths.
+        // DEDUPE BY KEY before chunking: a streaming message appearing in k
+        // pending frames shipped k copies (up to 25x on a replay burst), and
+        // every duplicate cost a server row-write plus a rebroadcast frame.
         const byKey = new Map();
         const unkeyed = [];
         let status;
@@ -1690,16 +1971,24 @@ export function createEngine(deps) {
                 .catch((e) => logError("flush error", e?.message || e));
         }, wait);
     };
+    const homeDir = (() => { try {
+        return homedir();
+    }
+    catch {
+        return "";
+    } })();
+    const userPatterns = cfg.redact?.patterns;
+    const redactionRules = activeRules(userPatterns);
     const enqueue = (st, entry) => {
         if (!st || !entry)
             return;
         // content dedupe at the machinery boundary: an identical re-feed has
-        // either entered the queue already or been flushed into every
-        // remote's pending/spool (the per-remote delivery machinery owns it
-        // from there) — re-sending it bumps rev, rewrites storage and
-        // re-folds every viewer for nothing. This is the engine-side home
-        // the v2-adapter dedupe lacked (an adapter-side cache poisoned while
-        // dormant and skipped the flag-time content — live-caught).
+        // either entered the queue already or been flushed into every remote's
+        // pending/spool, and the per-remote delivery machinery owns it from
+        // there. Re-sending it bumps rev, rewrites storage and re-folds every
+        // viewer for nothing. This is the engine-side home dedupe belongs in:
+        // an adapter-side cache can be poisoned while the session is still
+        // dormant, and then the flag-time content is skipped.
         let h;
         try {
             h = createHash("sha256").update(JSON.stringify(entry.item)).digest("hex");
@@ -1714,6 +2003,26 @@ export function createEngine(deps) {
         }
         if (h)
             st.sentHash.set(entry.key, h);
+        // Wave 3 trust pass: redaction on UNGATED shares only (a gated share
+        // is private from casual observers already; the server owner sees
+        // content either way until encryption lands). The light path
+        // transform applies regardless. Zero-copy when nothing matches.
+        {
+            const gate = authFrame(st);
+            const gated = gate.authLogin !== "" && gate.authPassword !== "";
+            const pass = redactItem(entry.item, { rules: redactionRules, home: homeDir, enabled: !gated });
+            if (pass.item !== entry.item)
+                entry = { ...entry, item: pass.item };
+            if (pass.hits.length) {
+                const led = redactionLedger.get(st.sid) ?? { count: 0, samples: [] };
+                led.count += pass.hits.length;
+                for (const hit of pass.hits) {
+                    if (led.samples.length < 5 && !led.samples.some((x) => x.kind === hit.kind))
+                        led.samples.push(hit);
+                }
+                redactionLedger.set(st.sid, led);
+            }
+        }
         st.queue.set(entry.key, entry.item);
         indexMessage(entry);
         if (debugEvents)
@@ -1722,12 +2031,30 @@ export function createEngine(deps) {
         ensureConnected(st);
         scheduleFlush(st);
     };
+    // Wave 3 preflight counts: the module-level accessor delegates here
+    statsProvider = (sid) => {
+        const st = sessions.get(sid);
+        let messages = 0;
+        let toolCalls = 0;
+        if (st) {
+            for (const [, merged] of st.merged) {
+                messages++;
+                const content = merged.content;
+                if (Array.isArray(content))
+                    toolCalls += content.filter((c) => !!c && c.type === "tool").length;
+            }
+            for (const it of st.queue.values()) {
+                if (it?.type === "message")
+                    messages++;
+            }
+        }
+        return { messages, toolCalls };
+    };
     const msgIndex = new Map(); // `${sid}:${messageID}`
     /** message ids tombstoned this run: stampsPass must never re-upsert an
-     * undone message (live-caught class: dropMergedMessage removed the
-     * merged entry but msgIndex kept the corpse; a neighboring-segment
-     * change recomputed its stamps and reEnqueueMessage resurrected the
-     * deleted turn server-side). */
+     * undone message. dropMergedMessage removes the merged entry but msgIndex
+     * keeps the corpse, so a neighboring-segment change recomputes its
+     * stamps and reEnqueueMessage resurrects the deleted turn server-side. */
     const tombstoned = new Set();
     const indexMessage = (entry) => {
         if (entry.item.type !== "message")
@@ -1791,11 +2118,11 @@ export function createEngine(deps) {
                 const agent = segmentAgent(list, users[k]);
                 const d = list[users[k]].data;
                 const want = k > 0 && agent && prev && agent !== prev ? agent : undefined;
-                // only touch metadata when the stamp actually CHANGES — a blanket
-                // `d.metadata ??= {}` polluted every user message (including the
+                // only touch metadata when the stamp actually CHANGES: a blanket
+                // `d.metadata ??= {}` pollutes every user message (including the
                 // host's live objects on v2 pass-through) with an empty metadata
-                // object, which re-emitted the message once per refresh (rev churn
-                // per feed — live-caught by the enqueue-dedupe rev check)
+                // object, which re-emits the message once per refresh and churns
+                // rev per feed.
                 if (want !== d.metadata?.agentSwitch) {
                     if (want) {
                         const meta = (d.metadata ??= {});
@@ -1869,8 +2196,8 @@ export function createEngine(deps) {
         }
     };
     /** file tools get metadata.language (shiki lang id, from the path the
-     * call touched) - the viewer highlights from the stamp and never guesses
-     * (owner directive; the viewer's extension map is an old-share fallback) */
+     * call touched). The viewer highlights from this stamp and never
+     * guesses; its extension map only covers old shares without one. */
     const LANG_BY_EXT = {
         ts: "typescript", tsx: "tsx", mts: "typescript", cts: "typescript",
         js: "javascript", jsx: "jsx", mjs: "javascript", cjs: "javascript",
@@ -1899,6 +2226,10 @@ export function createEngine(deps) {
                 const meta = state?.metadata;
                 if (!meta)
                     continue;
+                // paths stay absolute here: the server rewrites them against the
+                // session's working folder on read (wireItems), so old shares get
+                // the same treatment and the host's message objects are never
+                // mutated
                 const raw = state.input?.path ?? state.input?.filePath;
                 // language stamp (shiki id from the path)
                 if (typeof meta.language !== "string" && typeof raw === "string") {
@@ -2063,9 +2394,9 @@ export function createEngine(deps) {
                 r.idleDropTimer = null;
             }
             // wsReady delete only when THIS remote still owns a share: a stray
-            // child teardown clears shareId after adopting into the parent —
-            // the ControlDO's server-side attach would otherwise delete the
-            // very share the parent just inherited (live-caught adoption churn)
+            // child teardown clears shareId after adopting into the parent, and
+            // the ControlDO's server-side attach would then delete the very
+            // share the parent just inherited.
             if (r.wsReady && r.shareId) {
                 wsSend(r, { op: "delete" });
                 // backstop: the WS delete is fire-and-forget on the wire — a
@@ -2185,9 +2516,9 @@ export function createEngine(deps) {
             const lastInfo = (last?.info ?? last);
             const lastID = typeof lastInfo?.id === "string" ? lastInfo.id : undefined;
             // `before` is an OPAQUE cursor: base64url({id, time}) of the page
-            // tail (message-v2.ts codec). A bare message id 400s on hosts with
-            // cursor pagination — every v1 backfill silently truncated to one
-            // 100-message page (live-caught).
+            // tail (message-v2.ts codec). Hosts with cursor pagination 400 on a
+            // bare message id, which truncates a v1 backfill to its first
+            // 100-message page.
             const lastTime = lastInfo?.time?.created;
             if (!lastID || typeof lastTime !== "number")
                 break;
@@ -2206,7 +2537,7 @@ export function createEngine(deps) {
     const backfillSession = async (st, client, sid, info) => {
         const sessionInfoValue = info ?? (await sessionInfo(client, sid));
         if (sessionInfoValue)
-            enqueue(st, itemFor("session", redact(sessionInfoValue), sid));
+            enqueue(st, itemFor("session", stripLocalFacts(redact(sessionInfoValue)), sid));
         let modelSeen = false;
         const consume = (messages) => {
             for (const message of messages) {
@@ -2251,7 +2582,7 @@ export function createEngine(deps) {
             // 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));
+                enqueue(st, itemFor("session", stripLocalFacts(redact(fetched)), st.sid));
         }
         // children (subagent sessions) share the parent's page
         if (typeof client.session.list === "function") {
@@ -2343,12 +2674,8 @@ export function createEngine(deps) {
                 // 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));
+                        enqueue(st, itemFor("session", stripLocalFacts(redact(info)), sid));
                 }
                 return;
             }
@@ -2358,23 +2685,14 @@ export function createEngine(deps) {
                 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));
-                    }
+                        applyOpts(st, flag.opts);
                     if (info)
-                        enqueue(st, itemFor("session", redact(info), sid));
+                        enqueue(st, itemFor("session", stripLocalFacts(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") {
@@ -2431,12 +2749,8 @@ export function createEngine(deps) {
         }
         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));
+            enqueue(st, itemFor("session", stripLocalFacts(redact(info)), sid));
         if (t === "session.updated" && st.activated && !st.closed) {
             chain = chain.then(() => refreshOptOuts(st)).catch(() => { });
         }
@@ -2466,12 +2780,12 @@ export function createEngine(deps) {
                     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)
+                        // idles between sequential automation prompts, which is NOT
+                        // "done"), a recovered retry is forgiven, and the 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, and a repeated idle must NOT void it or
+                        // the share stays on live forever.
                         st.statusEpoch++;
                         if (st.completedTimer) {
                             clearTimeout(st.completedTimer);
@@ -2485,8 +2799,8 @@ export function createEngine(deps) {
                     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).
+                        // flushes now, because turn-end batches must not ride the sync
+                        // interval (subagent finals lagged one interval otherwise).
                         // 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
@@ -2631,11 +2945,11 @@ export function createEngine(deps) {
                         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. Works for v2-native messages too
-                    // (finish lives on the message itself).
+                    // an assistant message that DIED (finish:"error"), e.g. all
+                    // retries exhausted, surfaces as a 200 response with an errored
+                    // message rather than session.error. The share must still say
+                    // error. Works for v2-native messages too (finish lives on the
+                    // message itself).
                     if (info?.finish === "error") {
                         st.badSignal = true;
                     }
@@ -2701,7 +3015,7 @@ export function createEngine(deps) {
                     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
+                    // 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(() => { });
@@ -2722,6 +3036,26 @@ export function createEngine(deps) {
                     st.metaTimer = null;
                     await writeBinding(st).catch(() => { });
                 }
+                // URL-at-exit barrier: a very short `opencode run` can exit before
+                // the create handshake finishes, and CI reads the urlFile the
+                // moment the process ends. Bounded 5s wait for every share that is
+                // mid-handshake or not yet announced (a dead worker costs exactly
+                // the cap; a healthy one is instant).
+                const barrierStart = Date.now();
+                while (Date.now() - barrierStart < 5000) {
+                    let pendingAnnounce = false;
+                    for (const st of sessions.values()) {
+                        for (const r of st.remotes.values()) {
+                            if (r.authBlocked || r.collided)
+                                continue;
+                            if ((r.shareId && !r.announced) || (!r.shareId && (r.ws || r.connecting)))
+                                pendingAnnounce = true;
+                        }
+                    }
+                    if (!pendingAnnounce)
+                        break;
+                    await new Promise((res) => setTimeout(res, 100));
+                }
                 for (const st of sessions.values()) {
                     for (const r of st.remotes.values()) {
                         try {