dsh-zen-remote 2.3.11 → 2.4.1

package/src/relay-server.ts

@@ -30,11 +30,11 @@ import { withPeer } from './owner-peer.js'
 import { controlProjectionFrame } from './merge-streams.js'
 import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { Readable, Transform } from 'node:stream'
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { join } from 'node:path'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ShareStore } from './share-store.js'
+import { ensureServerIdMigrated, readStateFile, STATE_FILE_NAME, writeStateFile } from './state-store.js'
 import { decideHttpRoute, decideInvoke, decideStream, decideUploadQuery, parseEventResultBody } from './relay-access.js'
 import {
   createWorkspaceFollowState,
@@ -79,6 +79,26 @@ export { MAX_UPLOAD_BYTES }
  * host's own registration (RT dsh-client-file-upload lib/index.js:73). */
 export const UPLOAD_HTTP_PATH = '/api/session/uploadFileBinary'
 
+/**
+ * The duplex uplink's buffering ceiling (TA-1): how many bytes of
+ * not-yet-consumed uplink frames one live stream may hold — the same budget
+ * the host's own stream inbox applies (`DEFAULT_STREAM_INBOX_BYTES`), so a
+ * stalled terminal consumer backs up at exactly the point the local session
+ * would have. Past it the `/v1/stream-uplink` route answers 413
+ * `uplink-overflow` and the stream is aborted.
+ */
+export const MAX_STREAM_UPLINK_BYTES = 262_144
+
+/** The per-stream uplink window the client may advertise (TA-1): how many
+ * bytes the host's uplink inbox buffers before it stops draining, and the
+ * per-frame framing overhead it charges against that budget. The relay
+ * forwards it verbatim — only the shape is validated, the numbers are the
+ * host's own contract with itself. */
+export interface RelayUplinkWindow {
+  maxBytes: number
+  frameOverheadBytes: number
+}
+
 /** Error messages forwarded to the client are clipped to this many chars. */
 const MAX_MESSAGE_CHARS = 500
 
@@ -187,6 +207,12 @@ export interface RelayGateway {
     args: unknown
     signal?: AbortSignal
     peer?: unknown
+    /** TA-1: the duplex uplink queue (a duplex method like `terminal/attach`
+     * reads keystrokes/resize frames from it). Absent on one-direction
+     * streams — the field's presence IS the duplex flag. */
+    uplink?: AsyncIterable<unknown>
+    /** TA-1: the client's advertised uplink window, forwarded verbatim. */
+    uplinkWindow?: RelayUplinkWindow
   }): Promise<AsyncIterable<unknown>>
   /** The host's wire adapter, shared by the WebSocket mux and the local
    * transports. `open` is the async 0.2.0 method. */
@@ -316,30 +342,38 @@ export interface RelayHandler {
  * countable about the deployment. */
 const SERVER_ID_PATTERN = /^[0-9a-f]{8}$/
 
-const SERVER_ID_FILE = 'zen-remote-server.json'
+/**
+ * The state file the server identity lives in since MS-1 — the same file the
+ * share table (`sessions`) and the paired-servers list (`servers`) use, so
+ * every writer of one field must preserve the other two. `loadServerId`
+ * reads and writes it only through state-store's merged doors.
+ */
+const SERVER_ID_FILE = STATE_FILE_NAME
 
 /**
  * Read the persisted server id, creating (and persisting) one on first use.
- * A missing file is the normal first run; an unreadable or damaged file must
- * never take the host down, so every failure degrades to a fresh per-process
- * id that simply is not remembered across restarts.
+ * A pre-multi-server `zen-remote-server.json` identity migrates in first
+ * (and its file is deleted) — an upgraded host keeps its id, so paired
+ * devices never see a stranger. A missing file is the normal first run; an
+ * unreadable or damaged file must never take the host down, so every failure
+ * degrades to a fresh per-process id that simply is not remembered across
+ * restarts.
  */
 export function loadServerId(home: string): string {
   const file = join(home, SERVER_ID_FILE)
+  ensureServerIdMigrated(file)
   try {
-    const parsed: unknown = JSON.parse(readFileSync(file, 'utf8'))
-    const id = (parsed as { serverId?: unknown } | null)?.serverId
-    if (typeof id === 'string' && SERVER_ID_PATTERN.test(id)) return id
+    const state = readStateFile(file)
+    if (state.serverId !== undefined && SERVER_ID_PATTERN.test(state.serverId)) return state.serverId
   } catch {
-    // First run, unreadable path, or unparsable JSON — mint a new one below.
+    // Damaged state: mint a new one below (state-store never throws, but the
+    // belt stays on).
   }
   const id = randomBytes(4).toString('hex')
   try {
-    // tmp + rename, the same atomic dance the share table uses: a crash
-    // mid-write must not leave a half-file that would corrupt the next read.
-    mkdirSync(home, { recursive: true })
-    writeFileSync(`${file}.tmp`, JSON.stringify({ serverId: id }))
-    renameSync(`${file}.tmp`, file)
+    // The merged write: sessions/servers already in the file survive, and the
+    // atomic tmp(0600)+rename dance is state-store's job now.
+    writeStateFile(file, (current) => ({ ...current, version: 1, serverId: id }))
   } catch {
     // Unwritable home: the id stays process-local. Nothing may throw here.
   }
@@ -782,6 +816,114 @@ function errorOf(error: unknown): { code: string; message?: string; details?: Re
   return out
 }
 
+/**
+ * The bounded async queue behind one live duplex stream's uplink half (TA-1).
+ * The `/v1/stream-uplink` route pushes the client's frames in; the gateway's
+ * stream implementation (the host's own uplink consumer) pulls them out.
+ *
+ * Three states beyond "open", each with its own door:
+ * - `ended`: the client half-closed (`end: true`). Queued items still drain;
+ *   the iteration finishes cleanly once the buffer is empty. A push AFTER the
+ *   end is a client bug — it records `failure` and aborts the stream.
+ * - `failure`: a post-end push or a buffer overflow. The recorded error is
+ *   thrown to the consumer, and the stream's abort fires (the route cannot
+ *   push anymore, so the downstream is torn down with it).
+ * - `closed`: the stream is over (its own finally, or closeAll). Everything
+ *   is dropped; further pushes are silently swallowed (`'ok'`) — the route's
+ *   answer for a dead stream is the 404 unknown-stream, so the swallow only
+ *   covers the race between the two.
+ *
+ * The waiter is woken on EVERY state change (item, end, close, failure) so a
+ * parked `next()` never sits on a stale promise: the iteration is the host's
+ * consumer, and a missed wake would hang a terminal that just died.
+ */
+class RelayUplinkQueue {
+  private readonly items: Array<{ value: unknown; bytes: number }> = []
+  private bufferedBytes = 0
+  private ended = false
+  private closed = false
+  private failure: Error | undefined
+  private waiter: (() => void) | undefined
+
+  constructor(
+    private readonly maxBytes: number,
+    private readonly onFail: () => void,
+  ) {}
+
+  /** One frame in. `frameBytes` is the frame's serialized size — the same
+   * accounting the host's inbox charges, so the ceiling here means the same
+   * thing it means locally. */
+  push(value: unknown, frameBytes: number): 'ok' | 'after-end' | 'overflow' {
+    if (this.closed || this.failure !== undefined) return 'ok'
+    if (this.ended) {
+      this.failure = new Error('uplink frame arrived after end')
+      this.wake()
+      this.onFail()
+      return 'after-end'
+    }
+    if (this.bufferedBytes + frameBytes > this.maxBytes) {
+      this.failure = new Error('uplink buffer overflow')
+      this.wake()
+      this.onFail()
+      return 'overflow'
+    }
+    this.items.push({ value, bytes: frameBytes })
+    this.bufferedBytes += frameBytes
+    this.wake()
+    return 'ok'
+  }
+
+  /** The client half-closed: queued items still drain, then the iteration
+   * ends. Idempotent. */
+  end(): void {
+    if (this.ended) return
+    this.ended = true
+    this.wake()
+  }
+
+  /** The whole stream is over: drop everything, finish every parked reader,
+   * swallow all future pushes. Idempotent. */
+  close(): void {
+    if (this.closed) return
+    this.closed = true
+    this.items.length = 0
+    this.bufferedBytes = 0
+    this.wake()
+  }
+
+  private wake(): void {
+    const wake = this.waiter
+    this.waiter = undefined
+    wake?.()
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    return {
+      next: () => this.next(),
+      return: () => {
+        this.close()
+        return Promise.resolve({ value: undefined, done: true })
+      },
+    }
+  }
+
+  private async next(): Promise<IteratorResult<unknown>> {
+    while (true) {
+      if (this.closed) return { value: undefined, done: true }
+      const entry = this.items.shift()
+      if (entry !== undefined) {
+        this.bufferedBytes -= entry.bytes
+        return { value: entry.value, done: false }
+      }
+      if (this.failure !== undefined) throw this.failure
+      if (this.ended) return { value: undefined, done: true }
+      await new Promise<void>((resolve) => {
+        this.waiter = resolve
+      })
+    }
+  }
+}
+
 /**
  * One live `$zr/events` subscription's forwarding bookkeeping (T32). The
  * answer route (`relay/v1/event-result`) proves an `eventId` was forwarded
@@ -896,6 +1038,27 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
    * subscription removes itself; closeAll empties the set. */
   const liveEventSubscriptions = new Set<EventsSubscription>()
 
+  /**
+   * The live duplex streams' uplink halves (TA-1), keyed by the `streamId`
+   * the handshake line handed the client. The `/v1/stream-uplink` route
+   * resolves every post through THIS table, which is the whole ownership
+   * story: the id is a 16-byte random value only the opening device ever
+   * learned, the device check binds it to that one pairing, the session
+   * list is re-judged against the share table at post time, and the seq
+   * counter keeps replays and reordered posts out. A stream's own finally
+   * removes its entry; closeAll closes every queue first so no consumer
+   * parks on a dead stream.
+   */
+  interface ActiveUplinkStream {
+    streamId: string
+    device: string
+    sessionIds: readonly string[]
+    nextSeq: number
+    queue: RelayUplinkQueue
+    abort: () => void
+  }
+  const liveUplinkStreams = new Map<string, ActiveUplinkStream>()
+
   /** Latest `job/list` rows seen per session — the recent-state half of the
    * job ownership check (the other half is a one-shot list on a cache miss).
    * An unshared session's rows are forgotten (T22b-fix): its jobs are none of
@@ -2287,6 +2450,69 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
       return
     }
 
+    if (req.method === 'POST' && pathname === `${RELAY_PREFIX}/v1/stream-uplink`) {
+      // The duplex uplink's post route (TA-1): one JSON body of frames for a
+      // stream opened with `uplink: true`, resolved against the live-uplink
+      // table. Four walls in order, each with its own status: the shape
+      // (400), the stream id and its owning device (404 — unknown-stream,
+      // deliberately indistinguishable between "no such stream" and "not
+      // yours", so a foreign device learns nothing), the share table at post
+      // time (403 — an unshared session's keystrokes must die with the
+      // share), and the sequence counter (409 — replays and reordered posts
+      // would corrupt the host's own input sequencing).
+      const body = await readBodyOrRespond(req, res)
+      if (body === undefined) return
+      const streamId = body.streamId
+      const seq = body.seq
+      const items = body.items
+      const end = body.end
+      if (
+        typeof streamId !== 'string' ||
+        streamId === '' ||
+        typeof seq !== 'number' ||
+        !Number.isSafeInteger(seq) ||
+        seq < 1 ||
+        (items !== undefined && !Array.isArray(items)) ||
+        (end !== undefined && typeof end !== 'boolean') ||
+        !((Array.isArray(items) && items.length > 0) || end === true)
+      ) {
+        responseJson(res, 400, { ok: false, error: { code: 'bad-request' } })
+        return
+      }
+      const device = headerValue(req, 'x-zen-remote-device') ?? ''
+      const entry = liveUplinkStreams.get(streamId)
+      if (entry === undefined || entry.device !== device) {
+        responseJson(res, 404, { ok: false, error: { code: 'unknown-stream' } })
+        return
+      }
+      if (!entry.sessionIds.every((id) => isAccessible(id))) {
+        responseJson(res, 403, { ok: false, error: { code: 'not-shared' } })
+        return
+      }
+      if (seq !== entry.nextSeq) {
+        responseJson(res, 409, { ok: false, error: { code: 'out-of-order' } })
+        return
+      }
+      entry.nextSeq += 1
+      if (Array.isArray(items)) {
+        for (const item of items) {
+          const itemBytes = Buffer.byteLength(JSON.stringify(item) ?? '', 'utf8')
+          const status = entry.queue.push(item, itemBytes)
+          if (status === 'after-end') {
+            responseJson(res, 400, { ok: false, error: { code: 'uplink-after-end' } })
+            return
+          }
+          if (status === 'overflow') {
+            responseJson(res, 413, { ok: false, error: { code: 'uplink-overflow' } })
+            return
+          }
+        }
+      }
+      if (end === true) entry.queue.end()
+      responseJson(res, 200, { ok: true })
+      return
+    }
+
     if (req.method === 'POST' && pathname === `${RELAY_PREFIX}/v1/stream`) {
       // Body validation identical to invoke: one JSON object naming the
       // method and carrying object args.
@@ -2314,6 +2540,25 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         responseJson(res, 403, { ok: false, error: { code: decision.reason } })
         return
       }
+      // TA-1: the client's advertised uplink window, shape-checked ONCE here —
+      // only a well-formed window travels to the gateway; garbage (a zero or
+      // negative budget, a fractional value) is dropped, never refused: the
+      // numbers are the host's own contract with itself, and a missing one
+      // just means the host default applies.
+      let uplinkWindow: RelayUplinkWindow | undefined
+      if (isPlainObject(body.uplinkWindow)) {
+        const candidate = body.uplinkWindow
+        if (
+          typeof candidate.maxBytes === 'number' &&
+          Number.isSafeInteger(candidate.maxBytes) &&
+          candidate.maxBytes > 0 &&
+          typeof candidate.frameOverheadBytes === 'number' &&
+          Number.isSafeInteger(candidate.frameOverheadBytes) &&
+          candidate.frameOverheadBytes >= 0
+        ) {
+          uplinkWindow = { maxBytes: candidate.maxBytes, frameOverheadBytes: candidate.frameOverheadBytes }
+        }
+      }
       const device = headerValue(req, 'x-zen-remote-device') ?? ''
       if ((streamsByDevice.get(device) ?? 0) >= MAX_STREAMS_PER_DEVICE) {
         responseJson(res, 429, { ok: false, error: { code: 'too-many-streams' } })
@@ -2479,6 +2724,31 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
           })
         }
 
+        // ---- TA-1: the duplex uplink -------------------------------------
+        // A duplex decision the client took up: build the bounded queue the
+        // gateway will read keystrokes from, register it for the
+        // /v1/stream-uplink route, and send the handshake line FIRST —
+        // before the upstream is even open — so the client may start posting
+        // the moment it sees the id. The write chain serializes the line
+        // ahead of any frame; registration precedes the open so a post that
+        // races the handshake still finds the entry (its seq order and the
+        // share table keep it honest either way).
+        let uplinkStreamId: string | undefined
+        let uplinkQueue: RelayUplinkQueue | undefined
+        if (decision.uplink === true && body.uplink === true) {
+          uplinkStreamId = randomBytes(16).toString('hex')
+          uplinkQueue = new RelayUplinkQueue(MAX_STREAM_UPLINK_BYTES, () => hangUp.abort())
+          liveUplinkStreams.set(uplinkStreamId, {
+            streamId: uplinkStreamId,
+            device,
+            sessionIds: decision.sessionIds,
+            nextSeq: 1,
+            queue: uplinkQueue,
+            abort: () => hangUp.abort(),
+          })
+          void writeLine({ type: 'uplink', streamId: uplinkStreamId })
+        }
+
         // ---- share-change synchronization (T22b §4) --------------------
 
         // The `$zr/events` forwarding bookkeeping (T32): registered for the
@@ -2638,11 +2908,25 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
           } else {
             // `$zr/events` opens through the wire adapter (the ONLY door to
             // the forwarded-event stream); every other route is a typert
-            // stream method.
+            // stream method. TA-1: a duplex stream rides with its uplink
+            // queue (the field's PRESENCE is the duplex flag the gateway
+            // reads) and the shape-checked window, both optional.
             const iterable =
               eventsSub !== undefined
                 ? await openEventsStream(hangUp.signal)
-                : await gateway.stream(withPeer({ namespace, method, args, signal: hangUp.signal }, options.getPeer))
+                : await gateway.stream(
+                    withPeer(
+                      {
+                        namespace,
+                        method,
+                        args,
+                        signal: hangUp.signal,
+                        ...(uplinkQueue !== undefined ? { uplink: uplinkQueue } : {}),
+                        ...(uplinkWindow !== undefined ? { uplinkWindow } : {}),
+                      },
+                      options.getPeer,
+                    ),
+                  )
             for await (const frame of iterable) {
               if (finished || clientGone) break
               if (namespace === 'job' && method === 'list') rememberJobs(ownerSessionIdOf(args), frame)
@@ -2667,6 +2951,12 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
           clearInterval(heartbeat)
           unsubscribe()
           tableUnsubscribers.delete(unsubscribe)
+          // TA-1: the uplink half dies with the stream — deregistered BEFORE
+          // the queue closes, so a post racing the teardown answers
+          // unknown-stream instead of feeding a dead queue, and the gateway's
+          // consumer is finished instead of parked forever.
+          if (uplinkStreamId !== undefined) liveUplinkStreams.delete(uplinkStreamId)
+          uplinkQueue?.close()
           if (eventsSub !== undefined) {
             liveEventSubscriptions.delete(eventsSub)
             eventsSub.events.clear()
@@ -2710,6 +3000,12 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
       sub.events.clear()
     }
     liveEventSubscriptions.clear()
+    // TA-1: the duplex uplinks die with the handler — close() finishes every
+    // parked gateway consumer (a terminal read must not hang on a reload)
+    // and later posts answer unknown-stream; the streams' own finallys then
+    // find their entries already gone and delete nothing.
+    for (const entry of liveUplinkStreams.values()) entry.queue.close()
+    liveUplinkStreams.clear()
     // Remember the reason for requests still inside their ownership probe —
     // they read it at the pre-open gate. Killing the open streams runs their
     // normal teardown (error line, res.end, abort), whose finally releases

package/src/restart-fields.ts

@@ -3,10 +3,10 @@
  * effect (T17): `role` chooses which halves load; `port` / `host` /
  * `targetPort` / `rateLimit` / `trustedProxies` become the gateway child's
  * runtime shape; `vapidSubject` / `lang` / `pushEvents` / `pushDebounceMs` /
- * `pushSummary` / `pushTurnEnd` / `pushTool` are the push leg's startup
- * values. Everything else (serverName, idleHours, autoShareNewSessions,
- * serverUrl, deviceToken, and the interface-half knobs) is read live per use
- * and needs no reload.
+ * `pushSummary` / `pushTurnEnd` / `pushTool` / `pushEnabled` /
+ * `pushSessionName` are the push leg's startup values. Everything else
+ * (serverName, idleHours, autoShareNewSessions, serverUrl, deviceToken, and
+ * the interface-half knobs) is read live per use and needs no reload.
  *
  * Single source shared by both halves: the host's restart watcher
  * (src/restart-watcher.ts) fingerprints exactly these fields, and the
@@ -30,6 +30,8 @@ export const RESTART_FIELDS = [
   'pushSummary',
   'pushTurnEnd',
   'pushTool',
+  'pushEnabled',
+  'pushSessionName',
 ] as const
 
 /** One field of {@link RESTART_FIELDS}. */

package/src/share-ops.ts

@@ -32,11 +32,92 @@ export interface AgentStatusLike {
 
 /** The slice of a DSH session header the share decision reads. Field names
  * per `validateSessionHeader`: `id` (matches the session id), `origin`
- * (only legal value `'subagent'`), `parentSession` (a string when set). */
+ * (only legal value `'subagent'`), `parentSession` (a string when set),
+ * `isSeeded` (true on a fork). */
 export interface CreatedSessionHeaderLike {
   id?: unknown
   origin?: unknown
   parentSession?: unknown
+  isSeeded?: unknown
+}
+
+/** The slice of a DSH Session read to detect an unused blank placeholder
+ * reclaimed by `session/create` (`dsh-api-session-controller`'s `claim`
+ * resumes persisted blank sessions with `source: 'resume'`). */
+export interface CreatedSessionLike {
+  header?: CreatedSessionHeaderLike | null | undefined
+  snapshotEvents?: (() => readonly { type?: unknown }[]) | undefined
+}
+
+/** The slice of `ctx.agents.turnBoundaryOf(session)` (DSH 0.2+ projection
+ * reader, the non-deprecated replacement for `snapshotEvents()`). */
+export interface TurnBoundaryLike {
+  openTurnStartSeq?: unknown
+  lastTurn?: unknown
+}
+
+/**
+ * Whether `session` is an unseeded, non-subagent blank session (zero turns
+ * ever started). DSH's `createInWorkspace` reuses persisted blank sessions
+ * via `session/create` → `agents.resume` (`source: 'resume'`); judging
+ * blankness lets `agent/created` auto-share a reclaimed blank placeholder
+ * while keeping established conversations closed across reopens.
+ *
+ * Prefers `turnBoundaryOf(session)` (DSH's `sessionProjections`-backed
+ * `ctx.agents.turnBoundaryOf`, the predicate `dsh-api-session-controller`'s
+ * own `isBlank` uses: `openTurnStartSeq === null && lastTurn === 0`); falls
+ * back to `session.snapshotEvents()` when `turnBoundaryOf` is absent (DSH
+ * 0.1.7 compatibility or unit-test mocks; ponytail: remove `snapshotEvents`
+ * fallback once 0.1.7 support is dropped and `@deepseek-ai/dsh-session`
+ * retires synchronous event-log reads).
+ */
+export function isBlankSession(
+  session: CreatedSessionLike | undefined | null,
+  turnBoundaryOf?: ((session: CreatedSessionLike) => TurnBoundaryLike | undefined) | undefined,
+): boolean {
+  if (session === null || typeof session !== 'object') return false
+  const header = session.header
+  if (header === null || typeof header !== 'object') return false
+  if (header.origin === 'subagent' || header.isSeeded === true) return false
+  if (typeof header.id !== 'string' || header.id === '') return false
+  if (typeof turnBoundaryOf === 'function') {
+    try {
+      const boundary = turnBoundaryOf(session)
+      if (boundary !== null && typeof boundary === 'object') {
+        return boundary.openTurnStartSeq === null && boundary.lastTurn === 0
+      }
+    } catch {
+      // Fall through to snapshotEvents when the projection reader is unavailable.
+    }
+  }
+  if (typeof session.snapshotEvents !== 'function') return false
+  try {
+    const events = session.snapshotEvents()
+    if (!Array.isArray(events)) return false
+    return !events.some((event) => event !== null && typeof event === 'object' && event.type === 'turn/start')
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Whether `event` is the very first `turn/start` (`turn === 1`) of an
+ * unseeded non-subagent session. Covers the in-memory `reuseLive` path of
+ * `session/create`, where a live blank session (created before
+ * `autoShareNewSessions` was enabled, or after its idle window expired in
+ * memory) is reused without emitting `agent/created`.
+ */
+export function isFirstTurnStart(
+  session: { header?: CreatedSessionHeaderLike | null | undefined } | undefined | null,
+  event: { type?: unknown; data?: unknown } | undefined | null,
+): boolean {
+  if (event === null || typeof event !== 'object' || event.type !== 'turn/start') return false
+  const data = event.data as { turn?: unknown } | null | undefined
+  if (data === null || typeof data !== 'object' || data.turn !== 1) return false
+  const header = session?.header
+  if (header === null || typeof header !== 'object') return false
+  if (header.origin === 'subagent' || header.isSeeded === true) return false
+  return typeof header.id === 'string' && header.id !== ''
 }
 
 /**

package/src/share-store.ts

@@ -24,8 +24,10 @@
  * idle by definition until the caller says otherwise.
  */
 
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
-import { dirname } from 'node:path'
+import { readFileSync, renameSync } from 'node:fs'
+import { basename } from 'node:path'
+import { isVirtual } from './virtual-id.js'
+import { ensureSharesMigrated, readStateFile, STATE_FILE_NAME, writeStateFile } from './state-store.js'
 
 /** One row of the table, as `list()` reports it. */
 export interface ShareEntry {
@@ -154,37 +156,62 @@ export function createShareStore(options: ShareStoreOptions): ShareStore {
 
   // ---- startup load (synchronous, once) ----
   //
-  // Missing file = first run, empty table. Unreadable path (a directory,
-  // permissions) also starts empty but is NOT quarantined — renaming
-  // something we could not even read could eat a live directory.
-  let raw: string | null = null
-  try {
-    raw = readFileSync(file, 'utf8')
-  } catch {
-    raw = null
-  }
-  if (raw !== null) {
-    let parsed: unknown
+  // Two container shapes. When this store backs the MS-1 three-in-one state
+  // file (`zen-remote-state.json`), loading goes through state-store's
+  // reader: the legacy `zen-remote-shares.json` migrates in first (and is
+  // deleted), and a version:1 container without a sessions map is legal —
+  // the file also carries serverId/servers other writers may have filled.
+  // Any OTHER file name keeps the historical shares-file semantics verbatim:
+  // anything that is not `{version:1, sessions:{…}}` quarantines the whole
+  // file. Unreadable paths (a directory, permissions) start empty either way
+  // and are NOT quarantined — renaming something we could not even read
+  // could eat a live directory.
+  const isStateFile = basename(file) === STATE_FILE_NAME
+  if (isStateFile) {
     try {
-      parsed = JSON.parse(raw)
+      ensureSharesMigrated(file)
     } catch {
-      parsed = undefined
+      // Startup must not fail on a migration hiccup; the legacy file stays.
     }
-    // Container-level damage (unparseable JSON, wrong version, wrong shape)
-    // quarantines the whole file; row-level damage (one bad record) only
-    // skips that record — the rest of the table is worth keeping.
-    if (isPlainObject(parsed) && parsed.version === FILE_VERSION && isPlainObject(parsed.sessions)) {
-      for (const [id, value] of Object.entries(parsed.sessions)) {
+    const state = readStateFile(file)
+    if (state.sessions !== undefined) {
+      for (const [id, value] of Object.entries(state.sessions)) {
         if (!isValidId(id) || !isPlainObject(value)) continue
         const { sharedAt, lastActivityAt } = value
         if (!isFiniteNumber(sharedAt) || !isFiniteNumber(lastActivityAt)) continue
         sessions.set(id, { sharedAt, lastActivityAt, busy: false })
       }
-    } else {
+    }
+  } else {
+    let raw: string | null = null
+    try {
+      raw = readFileSync(file, 'utf8')
+    } catch {
+      raw = null
+    }
+    if (raw !== null) {
+      let parsed: unknown
       try {
-        renameSync(file, `${file}.corrupt-${now()}`)
+        parsed = JSON.parse(raw)
       } catch {
-        // Keep the empty table either way; startup must not fail here.
+        parsed = undefined
+      }
+      // Container-level damage (unparseable JSON, wrong version, wrong shape)
+      // quarantines the whole file; row-level damage (one bad record) only
+      // skips that record — the rest of the table is worth keeping.
+      if (isPlainObject(parsed) && parsed.version === FILE_VERSION && isPlainObject(parsed.sessions)) {
+        for (const [id, value] of Object.entries(parsed.sessions)) {
+          if (!isValidId(id) || !isPlainObject(value)) continue
+          const { sharedAt, lastActivityAt } = value
+          if (!isFiniteNumber(sharedAt) || !isFiniteNumber(lastActivityAt)) continue
+          sessions.set(id, { sharedAt, lastActivityAt, busy: false })
+        }
+      } else {
+        try {
+          renameSync(file, `${file}.corrupt-${now()}`)
+        } catch {
+          // Keep the empty table either way; startup must not fail here.
+        }
       }
     }
   }
@@ -212,9 +239,10 @@ export function createShareStore(options: ShareStoreOptions): ShareStore {
       fileSessions[id] = { sharedAt: row.sharedAt, lastActivityAt: row.lastActivityAt }
     }
     try {
-      mkdirSync(dirname(file), { recursive: true })
-      writeFileSync(`${file}.tmp`, JSON.stringify({ version: FILE_VERSION, sessions: fileSessions }))
-      renameSync(`${file}.tmp`, file)
+      // The merged write door: whatever ELSE the file carries (serverId and
+      // servers in the MS-1 state file, any extra top-level fields in a
+      // plain shares file) survives every table write.
+      writeStateFile(file, (current) => ({ ...current, version: FILE_VERSION, sessions: fileSessions }))
       lastWriteError = undefined
     } catch (error) {
       lastWriteError = error
@@ -237,6 +265,11 @@ export function createShareStore(options: ShareStoreOptions): ShareStore {
 
   const store: ShareStore = {
     share(sessionId) {
+      // A virtual id (`zr~<serverId>~…`) names a session that lives on a
+      // REMOTE server — this table is the local server's access control, and
+      // letting a virtual id in would make the local relay hand out access
+      // under an id it cannot resolve. Never enters the table.
+      if (isVirtual(sessionId)) return false
       if (!isValidId(sessionId)) return false
       const t = now()
       const existing = sessions.get(sessionId)