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

package/dist/ui-prefs.js

@@ -1,9 +1,9 @@
-// Host-agnostic dialog size preferences (owner decision 2026-10-19: host
-// kv, not the config file — UI settings are per-host and synced by
-// opencode itself). dialog width maps to the host's fixed dialog widths;
-// height is a percent of terminal rows. v1 dialogs apply these directly
-// (dialogs.tsx); the settings dialog edits them through this module so the
-// flows stay host-agnostic.
+// Host-agnostic dialog size preferences, stored in host kv rather than the
+// config file because UI settings are per-host and synced by opencode
+// itself. Dialog width maps to the host's fixed dialog widths; height is a
+// percent of terminal rows. v1 dialogs apply these directly (dialogs.tsx);
+// the settings dialog edits them through this module so the flows stay
+// host-agnostic.
 export const UI_WIDTH_KV = "openshare.ui-width";
 export const UI_HEIGHT_PERCENT_KV = "openshare.ui-height-percent";
 export const HEIGHT_PERCENT_MIN = 25;

package/dist/v2-server.js

@@ -177,12 +177,11 @@ export function createV2ServerSetup() {
         // the client adapter and feed them into the engine as the v1 events it
         // understands (session.updated / message.updated / message.part.updated).
         // The engine's keyed queue makes repeated re-syncs idempotent.
-        // NOTE: no content-hash dedupe here — a refresh that runs while the
-        // session is still dormant (pre-flag) would poison the cache without
-        // emitting anything, and the flag-time refresh would then SKIP the
-        // unchanged messages (live-caught in the v2 mock suite: the share's
-        // first assistant content arrived only as the next change). The dedupe
-        // belongs engine-side, where dormancy is known, if it's ever needed.
+        // NOTE: no content-hash dedupe here. A refresh running while the session
+        // is still dormant (pre-flag) would poison the cache without emitting
+        // anything, and the flag-time refresh would then SKIP the unchanged
+        // messages, so the share's first assistant content would only arrive on
+        // the next change. Dedupe belongs engine-side, where dormancy is known.
         const pendingRefresh = new Map();
         // queued inbox inputs per session: v2 persists the prompt in the inbox
         // (delivery "queue") while the current turn still runs — the message

package/openshare.config.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Open(code)Share plugin config. Priority: OPENSHARE_* env vars > plugin options > this file > code defaults. Sync cadence keys are clamped into the worker's policy window (see worker SOCKET_POLICY/DEBOUNCE_MIN_MS/DEBOUNCE_MAX_MS/COMPLETED_DELAY_MAX_MS). Keys: workerUrl (your openshare-worker deployment; empty = plugin stays disabled), createToken (legacy: the worker's CREATE_TOKEN — keep OUT of git), servers (multi-server memberships: url -> {token, code, label, active, adminToken (root token for the TUI admin console)}; the active entry (or the first) receives new sessions; with no token the plugin ENROLLS itself — public servers take anyone, private ones need a code from the hoster; enrolled tokens persist to ~/.config/opencode/openshare.config.json), debounceMs (sync interval: max time between syncs while streaming; default 10000), completedDelayMs (idle this long before the share says completed; default 5000, 0 = immediate), modelLabel ($Provider/$Model placeholders; literal text sends as-is; empty string hides the model), ttlDays (per-share TTL, capped by the worker), openTasksInNewTab (task rows open subagent pages in a new tab), authLogin/authPassword (optional read gate on the share pages; sent on create AND resume; empty on resume removes protection), spoolDir (temporary unacked-frame buffer; default XDG data home), urlFile (write each share URL to this file; empty = default openshare.urls.txt in the session's directory; \"none\" = no URL file), announceStderr (false silences the [openshare] live: / url file: log lines; the share itself is unaffected).",
+  "$comment": "Open(code)Share plugin config. Priority: OPENSHARE_* env vars > plugin options > this file > code defaults. Sync cadence keys are clamped into the worker's policy window (see worker SOCKET_POLICY/DEBOUNCE_MIN_MS/DEBOUNCE_MAX_MS/COMPLETED_DELAY_MAX_MS). Keys: workerUrl (your openshare-worker deployment; empty = plugin stays disabled), createToken (legacy: the worker's CREATE_TOKEN — keep OUT of git), servers (multi-server memberships: url -> {token, code, label, active, adminToken (root token for the TUI admin console)}; the active entry (or the first) receives new sessions; with no token the plugin ENROLLS itself — public servers take anyone, private ones need a code from the hoster; enrolled tokens persist to ~/.config/opencode/openshare.config.json), debounceMs (sync interval: max time between syncs while streaming; default 10000), completedDelayMs (idle this long before the share says completed; default 5000, 0 = immediate), modelLabel ($Provider/$Model placeholders; literal text sends as-is; empty string hides the model), ttlDays (per-share TTL, capped by the worker), authLogin/authPassword (optional read gate on the share pages; sent on create AND resume; empty on resume removes protection), spoolDir (temporary unacked-frame buffer; default XDG data home), urlFile (write each share URL to this file; empty = default openshare.urls.txt in the session's directory; \"none\" = no URL file), announceStderr (false silences the [openshare] live: / url file: log lines; the share itself is unaffected).",
   "workerUrl": "",
   "createToken": "",
   "servers": {},
@@ -7,7 +7,6 @@
   "completedDelayMs": 5000,
   "modelLabel": "$Provider/$Model",
   "ttlDays": 90,
-  "openTasksInNewTab": true,
   "authLogin": "",
   "authPassword": "",
   "spoolDir": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirrowel/opencode-openshare",
-  "version": "0.2.0",
+  "version": "0.3.0-dev.1",
   "type": "module",
   "description": "Open(code)Share — re:share: self-hosted session sharing for opencode. Server plugin (single file or package), optional TUI for interactive opt-in sharing.",
   "license": "MIT",

package/src/banner.txt

@@ -19,7 +19,7 @@
 // > code defaults. Keys: servers (multi-server: url -> {token, code,
 // label, active, adminToken}), workerUrl, createToken (legacy pair),
 // shareMode ("all" | "manual"; default = TUI presence), debounceMs,
-// completedDelayMs, modelLabel, ttlDays, openTasksInNewTab,
+// completedDelayMs, modelLabel, ttlDays,
 // authLogin, authPassword, spoolDir, urlFile ("none" = off),
 // announceStderr.
 //

package/src/binding-queue.ts

@@ -5,8 +5,8 @@
  * the servers map) and the TUI (`patchSessionBinding` in share-flow.ts —
  * opt-outs, collision resolution). Their PATCHes interleave at the host:
  * writer A reads at T0, writer B reads at T1, A PATCHes at T2, B PATCHes
- * at T3 — A's change is silently lost (live-caught class: a TUI opt-out
- * erased by the engine's binding refresh).
+ * at T3, and A's change is silently lost (a TUI opt-out erased by the
+ * engine's binding refresh).
  *
  * Both route their whole read-modify-write through this per-session FIFO.
  * The queue never breaks on errors; entries drop when the process exits.

package/src/commands.ts

@@ -5,14 +5,14 @@
 // auth — one surface, no duplicated manager); on an unshared session it
 // asks consent and creates the share. /openshare opens settings.
 //
-// LAYER SHAPE (live-caught 2026-10-19): the v1 host keymap gates layers
-// that declare `mode` on the mode stack (resting mode is "base"), so a
-// plugin layer MUST NOT pass mode ("global" made the whole layer
-// unreachable — no palette entries, no slash commands, no shadow) and
-// must not carry undefined-valued command fields. The registration shape
-// is exactly what the proven family plugins use: {commands, bindings},
-// commands with only defined fields, category "OpenShare" (own group,
-// deliberately NOT joined into the shared family palette category).
+// LAYER SHAPE: the v1 host keymap gates layers that declare `mode` on the
+// mode stack (resting mode is "base"), so a plugin layer MUST NOT pass mode
+// ("global" made the whole layer unreachable: no palette entries, no slash
+// commands, no shadow) and must not carry undefined-valued command fields.
+// The registration shape is exactly what the proven family plugins use:
+// {commands, bindings}, commands with only defined fields, category
+// "OpenShare" (own group, deliberately NOT joined into the shared family
+// palette category).
 
 import {
   clearGoneBindingEntries,
@@ -27,6 +27,7 @@ import {
   verifyShare,
 } from "./share-flow.js"
 import { onboardingDialog, settingsDialog } from "./settings.js"
+import { engineTargetUrls } from "./core.js"
 import { dbgLog } from "./sidebar.js"
 import type { ShareHostApi, ShareHostLayerCommand } from "./tui-host.js"
 
@@ -152,7 +153,9 @@ export function buildShareCommand(host: ShareHostApi, sessionID: () => string |
       dbgLog(`/share run: entered (sid=${sessionID() ?? "none"})`)
       host.ui.dialog.clear()
       const cfg = currentConfig()
-      if (!isConfigured(cfg)) {
+      // engine-aware gate: project-level plugin options can configure
+      // targets the TUI's file chain cannot see - trust the live engine
+      if (!isConfigured(cfg) && !engineTargetUrls().length) {
         void onboardingDialog(host)
         return
       }
@@ -171,12 +174,12 @@ export function buildShareCommand(host: ShareHostApi, sessionID: () => string |
       // enabled:true; legacy all-mode bindings without the field are live
       // too — only an explicit false is dormant)
       if (all.some((b) => b.url && b.enabled !== false)) {
-        // THE session menu — identical to /openshare → This session by
-        // construction (one surface, no duplicated manager). No
-        // dialog.clear() after: settings owns its chain end-to-end (the
-        // old fire-and-forget menu + immediate clear wiped it instantly —
-        // live-caught as "/share did nothing" on a shared session).
-        await settingsDialog(host, sid)
+        // THE session menu - identical to /openshare  This session by
+        // construction (one surface, no duplicated manager), opened
+        // DIRECTLY (owner: "/share is supposed to be the same menu, not
+        // the settings root one hop away"). No dialog.clear() after:
+        // settings owns its chain end-to-end.
+        await settingsDialog(host, sid, "session")
         return
       }
       // everything was just cleared by the gone modal and the user chose

package/src/config.ts

@@ -37,6 +37,9 @@ export type ServerEntry = {
   label?: string
   active?: boolean
   adminToken?: string
+  /** The user DECLINED onboarding for this server (asked once, remembered):
+   * shares go out anonymously (public servers only). Cleared by enrolling. */
+  anonymous?: boolean
 }
 
 export type ShareConfig = {
@@ -48,15 +51,31 @@ export type ShareConfig = {
   debounceMs: number
   completedDelayMs: number
   modelLabel: string
-  ttlDays: number
-  openTasksInNewTab: boolean
+  /** Default share lifetime in HOURS (Wave 3; default 2160 = 90d).
+   * Legacy ttlDays config/env is accepted and converted x24. */
+  ttlHours: number
   authLogin: string
   authPassword: string
   spoolDir: string
   urlFile: string
+  /** urlFile line format: "url" (default, one bare URL per line) or
+   * "json" (one JSON object per line: id, url, status, gated) for CI
+   * consumers that want machine-readable lines without parsing URLs. */
+  urlFileFormat: "url" | "json"
   /** false silences the `[openshare] live:` (and `url file:`) stderr
    * lines. The share itself is unaffected. */
   announceStderr: boolean
+  /** Wave 3 redaction: user-supplied regex rules (client-side only)
+   * applied beside the built-in detectors on UNGATED shares. */
+  redact?: { patterns?: string[] }
+  /** B4: which named config set on the server token this agent uses
+   * (unset = the token's first/default set). Rides the create frame. */
+  configSet?: string
+  /** Free-form string metadata stamped onto every share at create
+   * (labels for team directories/admin listings). Values may reference
+   * env vars as ${NAME} - interpolated at send time; unresolved refs
+   * stay literal so misconfiguration is visible. */
+  meta?: Record<string, string>
   shareMode?: ShareMode
 }
 
@@ -77,12 +96,13 @@ export const DEFAULTS: ShareConfig = {
   // pending flip, so CI runs still land their final status.
   completedDelayMs: 5000,
   modelLabel: "$Provider/$Model",
-  ttlDays: 90,
-  openTasksInNewTab: true,
+  ttlHours: 90 * 24,
   authLogin: "",
   authPassword: "",
   spoolDir: "",
   urlFile: "",
+  urlFileFormat: "url",
+  configSet: "",
   announceStderr: true,
 }
 
@@ -144,9 +164,8 @@ export type WriteCandidate = { path: string; label: string; always?: boolean }
 
 /** Write-target candidates for the TUI picker: the global settings home
  * (always writable) plus every OTHER file in the read chain that already
- * exists on disk (deploy-time overrides are never created from the TUI —
- * owner rule). Order: global first (default), then the rest by read
- * precedence (highest first). */
+ * exists on disk, since the TUI never creates deploy-time overrides. Order:
+ * global first (default), then the rest by read precedence (highest first). */
 export function writeCandidates(pluginDir: string, env: NodeJS.ProcessEnv = process.env): WriteCandidate[] {
   const candidates: WriteCandidate[] = [{ path: configHomePath(env), label: "global settings (~/.config/opencode)", always: true }]
   const labels: Array<[string, string]> = [
@@ -180,10 +199,13 @@ export function configSourceMap(pluginDir: string, env: NodeJS.ProcessEnv = proc
     debounceMs: env.OPENSHARE_DEBOUNCE_MS,
     completedDelayMs: env.OPENSHARE_COMPLETED_DELAY_MS,
     modelLabel: env.OPENSHARE_MODEL_LABEL,
+    ttlHours: env.OPENSHARE_TTL_HOURS,
     ttlDays: env.OPENSHARE_TTL_DAYS,
     authLogin: env.OPENSHARE_AUTH_LOGIN,
     authPassword: env.OPENSHARE_AUTH_PASSWORD,
     urlFile: env.OPENSHARE_URL_FILE,
+    urlFileFormat: env.OPENSHARE_URL_FILE_FORMAT,
+    configSet: env.OPENSHARE_CONFIG_SET,
     spoolDir: env.OPENSHARE_SPOOL_DIR,
     announceStderr: env.OPENSHARE_ANNOUNCE_STDERR,
     shareMode: env.OPENSHARE_SHARE_MODE,
@@ -191,6 +213,23 @@ export function configSourceMap(pluginDir: string, env: NodeJS.ProcessEnv = proc
   for (const [key, value] of Object.entries(envKeys)) {
     if (value !== undefined && value !== "") sources[key] = "environment"
   }
+  // legacy days-shaped env feeds the same knob as ttlHours
+  if (sources.ttlDays && !sources.ttlHours) sources.ttlHours = sources.ttlDays
+  delete sources.ttlDays
+  // OPENSHARE_CONFIG_JSON sits between env and the files: it loses only
+  // to a specific env var, so it overrides any file's key
+  if (env.OPENSHARE_CONFIG_JSON) {
+    try {
+      const raw = JSON.parse(env.OPENSHARE_CONFIG_JSON)
+      if (raw && typeof raw === "object") {
+        for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+          if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") continue
+          if (sources[key] === "environment") continue
+          if (key === "servers" || known.has(key)) sources[key] = "OPENSHARE_CONFIG_JSON"
+        }
+      }
+    } catch {}
+  }
   // configPaths() is ordered lowest-priority-first? No: index 0 is the
   // ADJACENT file (highest). Merge order reverses it; attribution walks
   // it as-is so the first hit is the winning (highest) source.
@@ -240,6 +279,7 @@ export function normalizeServers(raw: unknown): Record<string, ServerEntry> | un
     if (typeof e.label === "string" && e.label) entry.label = e.label
     if (typeof e.adminToken === "string" && e.adminToken) entry.adminToken = e.adminToken
     if (e.active === true) entry.active = true
+    if (e.anonymous === true) entry.anonymous = true
     out[url] = entry
   }
   return Object.keys(out).length ? out : undefined
@@ -247,9 +287,8 @@ export function normalizeServers(raw: unknown): Record<string, ServerEntry> | un
 
 /** Field-level merge of servers groups: entries only carry present fields
  * (normalizeServers), so a static `code` in plugin options and a persisted
- * `token` in the settings home combine instead of shadowing — per-URL
- * wholesale replacement would re-enroll on every boot (live-caught in
- * suite design review). */
+ * `token` in the settings home combine instead of shadowing. Per-URL
+ * wholesale replacement would re-enroll on every boot. */
 export function mergeServerGroups(base: Record<string, ServerEntry> | undefined, add: Record<string, ServerEntry>): Record<string, ServerEntry> {
   const merged: Record<string, ServerEntry> = { ...(base ?? {}) }
   for (const [url, entry] of Object.entries(add)) merged[url] = { ...(merged[url] ?? {}), ...entry }
@@ -257,10 +296,10 @@ export function mergeServerGroups(base: Record<string, ServerEntry> | undefined,
 }
 
 /** The server new sessions share to: the `active` entry (or the first).
- * Legacy workerUrl/createToken merge in as the implicit first entry — with
- * the root token ALSO filed as adminToken (the createToken IS root; filing
- * it only as `token` made the TUI offer user-actions like rotate to a root
- * holder — live-caught "can either be admin or user but not both"). */
+ * Legacy workerUrl/createToken merge in as the implicit first entry, with
+ * the root token ALSO filed as adminToken: the createToken IS root, and
+ * filing it only as `token` offers user-actions like rotate to a root
+ * holder, while an identity is either admin or user, not both. */
 export function resolveServer(cfg: ShareConfig): { url: string; token: string; entry: ServerEntry } | undefined {
   const servers: Record<string, ServerEntry> = {}
   if (cfg.workerUrl) servers[cfg.workerUrl] = { token: cfg.createToken || "", adminToken: cfg.createToken || "", active: true }
@@ -330,25 +369,58 @@ export function loadConfig(pluginDir: string, options?: Record<string, unknown>)
 
   const emptyMeansUnset = new Set(["workerUrl", "createToken", "urlFile", "spoolDir"])
   const known = new Set([...(Object.keys(DEFAULTS) as string[]), "shareMode"])
+  const applyObject = (raw: unknown) => {
+    if (!raw || typeof raw !== "object") return
+    for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+      if (key === "servers") {
+        const servers = normalizeServers(value)
+        if (servers) cfg.servers = mergeServerGroups(cfg.servers, servers)
+        continue
+      }
+      if (key === "redact") {
+        if (value && typeof value === "object" && Array.isArray((value as { patterns?: unknown }).patterns)) {
+          const pats = (value as { patterns: unknown[] }).patterns.filter((x): x is string => typeof x === "string" && x.length > 0 && x.length < 500).slice(0, 50)
+          cfg.redact = { patterns: pats }
+        }
+        continue
+      }
+      if (key === "meta") {
+        // string-to-string only: meta rides the create frame verbatim
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          const clean: Record<string, string> = {}
+          for (const [mk, mv] of Object.entries(value as Record<string, unknown>)) {
+            if (typeof mv === "string" && mv.length <= 500 && mk.length <= 64) clean[mk] = mv
+          }
+          if (Object.keys(clean).length) cfg.meta = { ...cfg.meta, ...clean }
+        }
+        continue
+      }
+      if (key === "ttlDays") {
+        // legacy days-shaped file/options value converts to hours once
+        const d = Math.floor(Number(value))
+        if (Number.isFinite(d) && d > 0) cfg.ttlHours = d * 24
+        continue
+      }
+      if (!known.has(key)) continue
+      if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") continue
+      if (typeof value === "string" && value === "" && emptyMeansUnset.has(key)) continue
+      ;(cfg as Record<string, unknown>)[key] = value
+    }
+  }
+
   for (const path of [...configPaths(pluginDir)].reverse()) {
     try {
       // strict JSON: the $comment key (what our templates use) is valid
       // JSON; comment-stripping is deliberately avoided because a naive
       // stripper eats "//" inside workerUrl values
-      const raw = JSON.parse(readFileSync(path, "utf8"))
-      if (!raw || typeof raw !== "object") continue
-      for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
-        if (key === "servers") {
-          const servers = normalizeServers(value)
-          if (servers) cfg.servers = mergeServerGroups(cfg.servers, servers)
-          continue
-        }
-        if (!known.has(key)) continue
-        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") continue
-        if (typeof value === "string" && value === "" && emptyMeansUnset.has(key)) continue
-        ;(cfg as Record<string, unknown>)[key] = value
-      }
-    } catch {}
+      applyObject(JSON.parse(readFileSync(path, "utf8")))
+    } catch (e) {
+      // a malformed config file is a real setup error the user must hear
+      // about - silence here looks like "no share server configured".
+      // (Absent files are normal chain candidates - only broken content
+      // is worth a line.)
+      if (existsSync(path)) console.error(`[openshare] config file ${path} could not be parsed - ignored:`, (e as Error)?.message ?? e)
+    }
   }
 
   if (options && typeof options === "object") {
@@ -366,15 +438,30 @@ export function loadConfig(pluginDir: string, options?: Record<string, unknown>)
   }
 
   const env = process.env
+  // OPENSHARE_CONFIG_JSON: a complete config object in one env var. Sits
+  // between the file/options layers and the per-key OPENSHARE_* env (a
+  // specific env var still wins) - CI sets one variable instead of nine,
+  // and secrets never touch a file. Malformed JSON is a loud error, not
+  // silence (same rule as files).
+  if (env.OPENSHARE_CONFIG_JSON) {
+    try {
+      applyObject(JSON.parse(env.OPENSHARE_CONFIG_JSON))
+    } catch (e) {
+      console.error("[openshare] OPENSHARE_CONFIG_JSON could not be parsed - ignored:", (e as Error)?.message ?? e)
+    }
+  }
   if (env.OPENSHARE_WORKER_URL) cfg.workerUrl = env.OPENSHARE_WORKER_URL
   if (env.OPENSHARE_CREATE_TOKEN) cfg.createToken = env.OPENSHARE_CREATE_TOKEN
   if (env.OPENSHARE_DEBOUNCE_MS) cfg.debounceMs = num(env.OPENSHARE_DEBOUNCE_MS, cfg.debounceMs)
   if (env.OPENSHARE_COMPLETED_DELAY_MS !== undefined) cfg.completedDelayMs = num(env.OPENSHARE_COMPLETED_DELAY_MS, cfg.completedDelayMs)
   if (env.OPENSHARE_MODEL_LABEL !== undefined) cfg.modelLabel = env.OPENSHARE_MODEL_LABEL
-  if (env.OPENSHARE_TTL_DAYS) cfg.ttlDays = num(env.OPENSHARE_TTL_DAYS, cfg.ttlDays)
+  if (env.OPENSHARE_TTL_HOURS) cfg.ttlHours = num(env.OPENSHARE_TTL_HOURS, cfg.ttlHours)
+  if (env.OPENSHARE_TTL_DAYS) cfg.ttlHours = Math.max(1, Math.floor(num(env.OPENSHARE_TTL_DAYS, 90) * 24))
   if (env.OPENSHARE_AUTH_LOGIN !== undefined) cfg.authLogin = env.OPENSHARE_AUTH_LOGIN
   if (env.OPENSHARE_AUTH_PASSWORD !== undefined) cfg.authPassword = env.OPENSHARE_AUTH_PASSWORD
   if (env.OPENSHARE_URL_FILE !== undefined) cfg.urlFile = env.OPENSHARE_URL_FILE
+  if (env.OPENSHARE_URL_FILE_FORMAT === "json" || env.OPENSHARE_URL_FILE_FORMAT === "url") cfg.urlFileFormat = env.OPENSHARE_URL_FILE_FORMAT
+  if (env.OPENSHARE_CONFIG_SET) cfg.configSet = env.OPENSHARE_CONFIG_SET
   if (env.OPENSHARE_SPOOL_DIR) cfg.spoolDir = env.OPENSHARE_SPOOL_DIR
   if (env.OPENSHARE_ANNOUNCE_STDERR !== undefined) cfg.announceStderr = !/^(0|false|no|off)$/i.test(env.OPENSHARE_ANNOUNCE_STDERR.trim())
   if (env.OPENSHARE_SHARE_MODE === "all" || env.OPENSHARE_SHARE_MODE === "manual") cfg.shareMode = env.OPENSHARE_SHARE_MODE
@@ -382,6 +469,16 @@ export function loadConfig(pluginDir: string, options?: Record<string, unknown>)
   // normalize the disable sentinel (case-insensitive from any source)
   if (cfg.urlFile.trim().toLowerCase() === URL_FILE_NONE) cfg.urlFile = URL_FILE_NONE
 
+  // URL hygiene: a trailing slash on a server url becomes
+  // wss://host//api/ws and https://host//s/<id> downstream - strip once,
+  // at the source, so every consumer agrees
+  if (cfg.workerUrl) cfg.workerUrl = cfg.workerUrl.trim().replace(/\/+$/, "")
+  if (cfg.servers) {
+    const fixed: Record<string, ServerEntry> = {}
+    for (const [u, e] of Object.entries(cfg.servers)) fixed[u.trim().replace(/\/+$/, "")] = e
+    cfg.servers = fixed
+  }
+
   return cfg
 }
 
@@ -415,9 +512,9 @@ function specPath(spec: string): string | undefined {
 
 /** Does this plugin spec (tui.json entry) point at the openshare package?
  * Accepts the bare npm name, name@version, and the /tui (or any) subpath
- * form — older docs shipped the subpath spec and presence detection must
- * never silently miss it (all-mode would keep auto-sharing while the user
- * believes they installed manual mode — live-caught in review). */
+ * form. Older docs shipped the subpath spec, and presence detection must
+ * never silently miss it: all-mode would keep auto-sharing while the user
+ * believes they installed manual mode. */
 export function isOpenShareSpec(spec: unknown): spec is string {
   if (typeof spec !== "string" || spec.length === 0) return false
   if (spec === NPM_NAME) return true

package/src/contract.ts

@@ -21,9 +21,9 @@
 export const CONTRACT_VERSION = 2
 
 /** Message tombstone item. sessionID MUST ride along: viewers key
- * messages as message/<sessionID>/<id> — an unstamped del misses the
- * key and undone turns resurrect on the live page (live-caught
- * 2026-10-21, refresh-correct because the worker keys differently). */
+ * messages as message/<sessionID>/<id>, so an unstamped del misses the key
+ * and undone turns resurrect on the live page (a refresh hides them because
+ * the worker keys items differently). */
 export function messageTombstone(sessionID: string, messageID: string) {
   return { type: "message", del: true, sessionID, data: { id: messageID } } as const
 }
@@ -313,8 +313,8 @@ export function normalizeV1Diff(diff: unknown): unknown {
 
 /** v1 hosts paginate messages with an opaque cursor: base64url of
  * {id, time} where time = the page tail's time_created (message-v2.ts
- * cursor codec). A bare message id is rejected with 400 — that silently
- * truncated every v1 backfill to one page (live-caught). */
+ * cursor codec). A bare message id is rejected with 400, which silently
+ * truncates a v1 backfill to one page. */
 export function cursorFor(id: string, time: number): string {
   return Buffer.from(JSON.stringify({ id, time })).toString("base64url")
 }