@volter/supercode-teams 0.3.172 → 0.3.174

package/machine.mjs

@@ -39,6 +39,7 @@ import { checkRemoteClose } from './remote-close.mjs';
 import { SqliteMailStore } from './mail/sqlite-store.mjs';
 import { SessionIndexOwner, requireSessionIndexRuntime } from './session-index-owner.mjs';
 import { SessionIndexViews, SESSION_INDEX_METHODS, SESSION_INDEX_CAPABILITY } from './session-index-views.mjs';
+import { SessionReadClient, SESSION_READ_METHODS, SESSION_READ_EVENT, SESSION_READ_CAPABILITY, parseSessionWire, stringifySessionWire } from './session-read-client.mjs';
 import { projectLiveDescriptors, addDiscoveryActivities, displayRecordLive } from './session-index-live.mjs';
 import { MailReads, panePrompt } from './mail/reads.mjs';
 import { render } from './mail/envelope.mjs';
@@ -1271,7 +1272,8 @@ export class TeamsMachine extends MachineCore {
     this.#stopMailWorkers();
     const closingViews = this.indexViews?.close();
     const closingIndex = this.sessionIndex?.close();
-    await Promise.all([closingViews, closingIndex]);
+    const closingReads = [...(this.sessionReadClients ?? [])].map((client) => client.close());
+    await Promise.all([closingViews, closingIndex, ...closingReads]);
     this.mailStore?.stop();
     this.stoppingServe = true;
     clearTimeout(this.serveRestart);
@@ -1380,6 +1382,15 @@ export class TeamsMachine extends MachineCore {
   /** One `harness.v1` request of the daemon's own, to its `harness serve`: the
    *  connection id INTERNAL_CONNECTION marks the answer as ours. */
   #serveRequest(method, params, timeoutMs = 3000) {
+    if (SESSION_READ_METHODS.includes(method)) {
+      if (this.stopping) return Promise.reject(new Error('this machine daemon is stopping'));
+      if (!this.sessionReads) {
+        const client = this.#newSessionReads(); this.sessionReads = client;
+        client.on('notification', (frame) => this.emit('internal-notification', frame));
+        client.on('ended', (error) => { if (this.sessionReads === client) this.sessionReads = null; this.emit('serve-stderr', `session read service ended: ${error.message}\n`); });
+      }
+      return this.sessionReads.call(method, params, { timeoutMs });
+    }
     if (SESSION_INDEX_METHODS.includes(method)) return new Promise((resolve, reject) => {
       let ended = false;
       const timer = setTimeout(() => { ended = true; reject(new Error(`${method} timed out`)); }, timeoutMs);
@@ -1447,9 +1458,9 @@ export class TeamsMachine extends MachineCore {
       const method = entry.harnessRequests?.get(original);
       entry.harnessRequests?.delete(original);
       if (method === 'harness.v1.capabilities' && message.result) message.result = { ...message.result,
-        methods: [...new Set([...(message.result.methods ?? []), ...SESSION_INDEX_METHODS])],
-        notifications: [...new Set([...(message.result.notifications ?? []), 'harness.v1.sessions.index_event'])],
-        session_index: SESSION_INDEX_CAPABILITY };
+        methods: [...new Set([...(message.result.methods ?? []), ...SESSION_INDEX_METHODS, ...SESSION_READ_METHODS])],
+        notifications: [...new Set([...(message.result.notifications ?? []), 'harness.v1.sessions.index_event', SESSION_READ_EVENT])],
+        session_index: SESSION_INDEX_CAPABILITY, session_read: SESSION_READ_CAPABILITY };
       // Learn routing keys from results so later notifications find their owner.
       if (message.result && typeof message.result === 'object') {
         for (const key of ['subscription', 'connection', 'runtime_id', 'subscription_id']) {
@@ -1527,7 +1538,7 @@ export class TeamsMachine extends MachineCore {
           }
           if (stream.closed) return;
           let message;
-          try { message = JSON.parse(line); } catch { return; }
+          try { message = parseSessionWire(line); } catch { return; }
           const asked = message.id !== undefined && message.id !== null ? message.id : null;
           if (SESSION_INDEX_METHODS.includes(message.method)) {
             // A cold read on one owner source cannot hold this stream's
@@ -1535,6 +1546,10 @@ export class TeamsMachine extends MachineCore {
             void this.#answerIndex(entry, stream, message);
             return;
           }
+          if (SESSION_READ_METHODS.includes(message.method)) {
+            void this.#answerRead(entry, stream, message);
+            return;
+          }
           if (asked !== null) message.id = joinId(index, message.id);
           if (asked !== null && message.method === 'harness.v1.runtimes.close' && !message.params?.connection && typeof message.params?.runtime_id === 'string' && this.closeOwnedRuntime) {
             try {
@@ -1560,7 +1575,60 @@ export class TeamsMachine extends MachineCore {
         }).catch(() => { if (!stream.closed) stream.close('machine authority could not be verified'); });
       }
     });
-    stream.on('close', () => { this.indexViews?.releaseConnection(stream); entry.harness = null; entry.harnessRequests.clear(); entry.harnessNative = false; });
+    stream.on('close', () => {
+      this.indexViews?.releaseConnection(stream);
+      void entry.sessionReads?.close().catch((error) => this.emit('serve-stderr', `${error.message}\n`)); entry.sessionReads = null;
+      entry.harness = null; entry.harnessRequests.clear(); entry.harnessNative = false;
+    });
+  }
+
+  #newSessionReads() {
+    const client = new SessionReadClient({ env: this.env, cwd: process.cwd() });
+    (this.sessionReadClients ??= new Set()).add(client);
+    client.on('closed', () => this.sessionReadClients.delete(client));
+    client.on('shutdown-error', (error) => this.emit('serve-stderr', `${error.message}\n`));
+    return client;
+  }
+  #readOutput(entry, stream, frame) {
+    if (stream.closed || this.stopping) return Promise.resolve(false);
+    const line = stringifySessionWire(frame), bytes = Buffer.byteLength(line);
+    entry.sessionReadBuffered = (entry.sessionReadBuffered ?? 0) + bytes;
+    if (entry.sessionReadBuffered > 16 * 1024 * 1024 && frame.method === SESSION_READ_EVENT) {
+      entry.sessionReadBuffered -= bytes; stream.close('session read notifications exceeded the stream buffer'); return Promise.resolve(false);
+    }
+    entry.sessionReadOutput = (entry.sessionReadOutput ?? Promise.resolve()).then(async () => {
+      if (stream.closed || this.stopping) return false;
+      if (entry.verify) {
+        const fresh = await entry.verify();
+        if (fresh?.class !== 'operator') { stream.close('no live operator grant'); return false; }
+        entry.admitted = fresh;
+      }
+      if (stream.closed || entry.admitted?.class !== 'operator') return false;
+      writeLine(stream, line); return true;
+    }).catch(() => { if (!stream.closed) stream.close('machine authority could not be verified'); return false; })
+      .finally(() => { entry.sessionReadBuffered -= bytes; });
+    return entry.sessionReadOutput;
+  }
+  async #answerRead(entry, stream, message) {
+    const asked = message.id !== undefined && message.id !== null ? message.id : null;
+    if (message.jsonrpc !== '2.0' || asked !== null && typeof asked !== 'string' && !Number.isFinite(asked)) {
+      if (!stream.closed) writeLine(stream, JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'invalid JSON-RPC request' } }));
+      return;
+    }
+    try {
+      if (stream.closed || this.stopping) return;
+      if (!entry.sessionReads) {
+        const client = this.#newSessionReads(); entry.sessionReads = client;
+        client.on('notification', (frame) => { void this.#readOutput(entry, stream, frame); });
+        client.on('ended', (error) => { if (!stream.closed) stream.close(`session read service ended: ${error.message}`); });
+      }
+      const client = entry.sessionReads, answer = await client.submit(message);
+      if (asked !== null && await this.#readOutput(entry, stream, answer)
+        && message.method === 'harness.v1.sessions.follow' && answer.result?.subscription) client.activate(answer.result.subscription);
+    } catch (error) {
+      if (asked !== null && !stream.closed) await this.#readOutput(entry, stream, { jsonrpc: '2.0', id: asked,
+        error: { code: error.code ?? -32000, message: error.message } });
+    }
   }
 
   async #indexClaudeName(query, name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-teams",
-  "version": "0.3.172",
+  "version": "0.3.174",
   "type": "module",
   "description": "A machine daemon serving this machine's doors, and a local or remote Teams server for shared session discovery, OpenTelemetry ingestion and access to enrolled machines.",
   "license": "MIT",
@@ -12,6 +12,10 @@
       "types": "./session-index-client.d.ts",
       "default": "./session-index-client.mjs"
     },
+    "./session-read-client": {
+      "types": "./session-read-client.d.ts",
+      "default": "./session-read-client.mjs"
+    },
     "./live-sessions": "./live-sessions.mjs",
     "./codex-hooks": {
       "types": "./codex-hooks.d.ts",
@@ -57,6 +61,7 @@
     "workspace-client.d.ts",
     "codex-hooks.d.ts",
     "session-index-client.d.ts",
+    "session-read-client.d.ts",
     "porthole-hook.cjs",
     "bin",
     "server",
@@ -79,7 +84,7 @@
     "@volter/supercode-frontend": "^0.2.2",
     "@volter/supercode-harness-sdk": "^0.3.58",
     "@volter/supercode-health": "^0.1.0",
-    "@volter/supercode-interchange": "0.1.1",
+    "@volter/supercode-interchange": "0.1.3",
     "@volter/supercode-terminal": "^0.2.54",
     "@volter/supercode-trace": "^0.1.0",
     "@volter/teams": "0.2.45",

package/session-read-client.d.ts

@@ -0,0 +1,11 @@
+import { EventEmitter } from 'node:events';
+import type { IndexRpcFrame } from './session-index-client.js';
+export { parseSessionWire, stringifySessionWire, SESSION_READ_METHODS, SESSION_READ_EVENT, SESSION_READ_CAPABILITY } from '@volter/supercode-interchange/session-read';
+/** Caller-owned worker lanes; never forwards a read to native or to a daemon. */
+export class SessionReadClient extends EventEmitter {
+  constructor(options?: { env?: Record<string, string | undefined>; cwd?: string; pollMs?: number | string });
+  submit(request: IndexRpcFrame, onAnswer?: ((answer: IndexRpcFrame) => void) | null): Promise<IndexRpcFrame>;
+  call(method: string, params?: unknown, options?: { timeoutMs?: number | null }): Promise<unknown>;
+  activate(subscription: string): void;
+  close(): Promise<void>;
+}

package/session-read-client.mjs

@@ -0,0 +1,109 @@
+import { EventEmitter } from 'node:events';
+import { Worker } from 'node:worker_threads';
+import { parseSessionWire, stringifySessionWire, SESSION_READ_METHODS, SESSION_READ_EVENT, SESSION_READ_CAPABILITY } from '@volter/supercode-interchange/session-read';
+import { SessionRuntimeStates } from './session-runtime-state.mjs';
+
+export { parseSessionWire, stringifySessionWire, SESSION_READ_METHODS, SESSION_READ_EVENT, SESSION_READ_CAPABILITY };
+const hasId = (request) => request.id !== undefined && request.id !== null;
+
+export class SessionReadClient extends EventEmitter {
+  #env; #cwd; #pollMs; #workers = new Map(); #pending = new Map(); #sources = new Map();
+  #next = 1; #subscription = 1; #states; #timer; #statePolling = false; #closed = false; #stopping = null;
+  constructor({ env = process.env, cwd = process.cwd(), pollMs = 500 } = {}) {
+    super(); this.#env = { ...env }; this.#cwd = cwd;
+    this.#pollMs = Math.min(0x7fffffff, Math.max(1, Number(pollMs)));
+    this.#states = new SessionRuntimeStates(this.#env);
+    this.#timer = setInterval(() => { void this.#pollStates(); }, this.#pollMs); this.#timer.unref();
+  }
+  #worker(lane) {
+    if (this.#closed) throw new Error('session-read client is closed');
+    let worker = this.#workers.get(lane); if (worker) return worker;
+    worker = new Worker(new URL('./session-read-worker.mjs', import.meta.url), { name: `supercode-session-${lane}`, env: this.#env,
+      workerData: { lane, env: this.#env, cwd: this.#cwd, pollMs: this.#pollMs } });
+    this.#workers.set(lane, worker);
+    worker.on('message', (frame) => {
+      if (this.#closed) return;
+      try {
+        if (frame.fatal) throw new Error(frame.fatal);
+        if (frame.notification) {
+          const notification = parseSessionWire(frame.notification);
+          if (this.#sources.get(notification.params?.subscription)?.active) this.emit('notification', notification);
+          return;
+        }
+        const held = this.#pending.get(frame.id); if (!held || held.worker !== worker) return;
+        const answer = frame.error ? { jsonrpc: '2.0', id: held.request.id, error: frame.error }
+          : { jsonrpc: '2.0', id: held.request.id, result: parseSessionWire(frame.result) };
+        this.#pending.delete(frame.id);
+        if (answer.result && hasId(held.request) && held.request.method === 'harness.v1.sessions.follow') {
+          const locator = held.request.params.locator;
+          this.#sources.set(answer.result.subscription, { harness: locator.harness, session_id: locator.session_id, reported: null, active: false });
+        }
+        if (answer.result?.removed && held.request.method === 'harness.v1.sessions.unfollow') this.#sources.delete(held.request.params.subscription);
+        try {
+          held.onAnswer?.(answer);
+          if (held.onAnswer && held.request.method === 'harness.v1.sessions.follow' && answer.result?.subscription && hasId(held.request)) this.activate(answer.result.subscription);
+          held.resolve(answer);
+        } catch (error) { held.reject(error); }
+      } catch (error) { this.#failed(error); }
+    });
+    worker.on('error', (error) => this.#failed(error));
+    worker.on('exit', (code) => { if (!this.#closed) this.#failed(new Error(`session ${lane} worker exited (${code})`)); });
+    return worker;
+  }
+  activate(subscription) {
+    const source = this.#sources.get(subscription); if (!source || this.#closed || source.active) return;
+    source.active = true; this.#worker('follow').postMessage({ activate: subscription });
+  }
+  async call(method, params = {}, { timeoutMs = null } = {}) {
+    let timer;
+    try {
+      const work = this.submit({ jsonrpc: '2.0', id: 1, method, params });
+      const answer = timeoutMs == null ? await work : await Promise.race([work, new Promise((_, reject) => {
+        timer = setTimeout(() => { this.#failed(new Error(`${method} did not answer within ${timeoutMs} ms`)); reject(new Error(`${method} timed out`)); }, timeoutMs);
+      })]);
+      if (answer.error) throw Object.assign(new Error(answer.error.message), { code: answer.error.code, answered: true });
+      if (method === 'harness.v1.sessions.follow' && answer.result?.subscription) this.activate(answer.result.subscription);
+      return answer.result;
+    } finally { clearTimeout(timer); }
+  }
+  #failed(error) { if (this.#closed) return; void this.close().catch((failure) => this.emit('shutdown-error', failure)); this.emit('ended', error); }
+  submit(request, onAnswer) {
+    if (this.#closed) return Promise.reject(new Error('session-read client is closed'));
+    if (!SESSION_READ_METHODS.includes(request.method)) return Promise.reject(new Error(`unknown session-read method: ${request.method}`));
+    const worker = this.#worker(request.method === 'harness.v1.sessions.load' ? 'load' : 'follow'), id = this.#next++;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { worker, request, onAnswer, resolve, reject });
+      try { worker.postMessage({ id, method: request.method, params: stringifySessionWire(request.params ?? {}), retain: hasId(request),
+        subscription: `read-sub-${this.#subscription++}` }); }
+      catch (error) { this.#pending.delete(id); reject(error); }
+    });
+  }
+  async #pollStates() {
+    if (this.#closed || this.#statePolling || !this.#sources.size) return;
+    this.#statePolling = true;
+    try {
+      const selected = new Map([...this.#sources].filter(([, source]) => source.active)), states = await this.#states.read([...selected.values()]);
+      if (this.#closed) return;
+      for (const [subscription, source] of selected) {
+        if (this.#sources.get(subscription) !== source) continue;
+        const state = states.get(JSON.stringify([source.harness, source.session_id]));
+        if (state == null || state === source.reported) continue;
+        source.reported = state;
+        this.emit('notification', { jsonrpc: '2.0', method: SESSION_READ_EVENT, params: { subscription, event: { type: 'runtime_state', state } } });
+      }
+    } catch { /* a registry read failure establishes no transition */ }
+    finally { this.#statePolling = false; }
+  }
+  close() {
+    if (this.#stopping) return this.#stopping;
+    this.#closed = true; clearInterval(this.#timer); this.#states.close(); this.#sources.clear();
+    for (const held of this.#pending.values()) held.reject(new Error('session-read client closed'));
+    this.#pending.clear();
+    this.#stopping = Promise.all([...this.#workers.values()].map(async (worker) => {
+      let timer;
+      try { await Promise.race([worker.terminate(), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`session-read worker ${worker.threadId} did not end after shutdown`)), 1500); })]); }
+      finally { clearTimeout(timer); }
+    })).then(() => { this.#workers.clear(); this.emit('closed'); });
+    return this.#stopping;
+  }
+}

package/session-read-worker.mjs

@@ -0,0 +1,51 @@
+// One caller-owned worker per read lane; no binary, daemon, or credentials
+// outside that caller's process. A long load cannot hold the stdio router.
+import { parentPort, workerData } from 'node:worker_threads';
+import { loadSessionRead, openSessionReadFollower, parseSessionWire, stringifySessionWire, SESSION_READ_EVENT } from '@volter/supercode-interchange/session-read';
+
+const followers = new Map(), context = { env: workerData.env, cwd: workerData.cwd };
+let closing = false, queue = Promise.resolve(), polling = false;
+const post = (frame) => { if (!closing) parentPort.postMessage(frame); };
+const enqueue = (work) => { queue = queue.then(work).catch((error) => post({ fatal: error.message })); };
+const timer = workerData.lane === 'follow' ? setInterval(() => {
+  if (closing || polling || !followers.size) return;
+  polling = true;
+  enqueue(async () => {
+    try {
+      for (const [subscription, { follower, active }] of followers) {
+        if (closing) return;
+        if (!active) continue;
+        let event;
+        try { event = await follower.poll(); }
+        catch (error) { event = { type: 'watch_error', recoverable: true, message: error.message }; }
+        if (event) post({ notification: stringifySessionWire({ jsonrpc: '2.0', method: SESSION_READ_EVENT, params: { subscription, event } }) });
+      }
+    } finally { polling = false; }
+  });
+}, workerData.pollMs) : null;
+
+parentPort.on('message', (request) => {
+  if (closing) return;
+  enqueue(async () => {
+    if (closing) return;
+    try {
+      if (request.activate) { const held = followers.get(request.activate); if (held) held.active = true; return; }
+      const params = parseSessionWire(request.params);
+      let result;
+      if (request.method === 'harness.v1.sessions.load') result = await loadSessionRead(params, context);
+      else if (request.method === 'harness.v1.sessions.follow') {
+        const follower = await openSessionReadFollower(params, context);
+        if (closing) { follower.close(); return; }
+        const initial = await follower.poll();
+        if (request.retain) followers.set(request.subscription, { follower, active: false }); else follower.close();
+        result = { subscription: request.subscription, initial };
+      } else if (request.method === 'harness.v1.sessions.unfollow') {
+        if (typeof params?.subscription !== 'string') throw Object.assign(new Error('subscription must be a string'), { rpcCode: -32602 });
+        const held = followers.get(params.subscription);
+        held?.follower.close(); result = { removed: followers.delete(params.subscription) };
+      } else throw Object.assign(new Error(`unknown session-read method: ${request.method}`), { rpcCode: -32601 });
+      post({ id: request.id, result: stringifySessionWire(result) });
+    } catch (error) { post({ id: request.id, error: { code: error.rpcCode ?? -32000, message: error.message } }); }
+  });
+});
+parentPort.on('close', () => { closing = true; clearInterval(timer); for (const { follower } of followers.values()) follower.close(); followers.clear(); });

package/session-runtime-state.mjs

@@ -0,0 +1,110 @@
+// Read-only source lifecycle projection for sessions.follow. The retained
+// registry still owns receipt retirement; this reader never removes a receipt
+// or touches the runtime's controller, observer lease, or event stream.
+import { readdir, readFile, realpath } from 'node:fs/promises';
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+import { request, Agent } from 'node:http';
+import { lookup } from 'node:dns';
+import { parseSessionWire } from '@volter/supercode-interchange/session-read';
+
+const loopback = (address) => address === '127.0.0.1' || address === '::1';
+function receiptHome(env) {
+  if (env.SUPERCODE_HOME) return env.SUPERCODE_HOME;
+  if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, 'supercode');
+  let accountHome; try { accountHome = userInfo().homedir; } catch { accountHome = '.'; }
+  return join(env.HOME || (process.platform === 'win32' && env.USERPROFILE) || accountHome || '.', '.config', 'supercode');
+}
+const canonical = async (path) => { try { return await realpath(path); } catch { return path; } };
+function live(pid) {
+  if (!Number.isInteger(pid) || pid < 1 || pid > 0xffffffff) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return process.platform !== 'win32' && error.code === 'EPERM'; }
+}
+function address(value) {
+  let url; try { url = new URL(value); } catch { return null; }
+  return url.protocol === 'http:' && !url.username && !url.password && !url.search && !url.hash
+    && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) ? url : null;
+}
+function localLookup(host, options, callback) {
+  lookup(host, options, (error, resolved, family) => {
+    if (error) return callback(error);
+    if (options.all) {
+      const local = resolved.filter((item) => loopback(item.address));
+      return local.length ? callback(null, local) : callback(new Error('runtime receipt hostname did not resolve to loopback'));
+    }
+    return loopback(resolved) ? callback(null, resolved, family) : callback(new Error('runtime receipt hostname did not resolve to loopback'));
+  });
+}
+
+export class SessionRuntimeStates {
+  #directory; #agent = new Agent({ keepAlive: true, maxSockets: 8, lookup: localLookup });
+  #requests = new Set(); #closed = false; #nextId = 1;
+  constructor(env) { this.#directory = join(receiptHome(env), 'live-runtimes'); }
+  async #receipt(path) {
+    const receipt = parseSessionWire(await readFile(path, 'utf8'));
+    if (receipt?.schema !== 'supercode.live-runtime.v1' || !address(receipt.base_url) || !live(receipt.pid)
+      || !/^[0-9a-f]{32}$/.test(receipt.receipt_id) || typeof receipt.runtime_session_id !== 'string'
+      || typeof receipt.token !== 'string' || !receipt.token || typeof receipt.source?.harness !== 'string'
+      || typeof receipt.source?.session_id !== 'string' || typeof receipt.source?.workspace !== 'string'
+      || !Number.isFinite(receipt.created_at_ms) || receipt.created_at_ms < 0) throw new Error('not a live runtime receipt');
+    return receipt;
+  }
+  async #describe(receipt) {
+    if (this.#closed) throw new Error('runtime-state reader closed');
+    const url = address(`${receipt.base_url.replace(/\/+$/, '')}/rpc`); if (!url) throw new Error('invalid local runtime endpoint');
+    const id = this.#nextId++, body = JSON.stringify({ id, method: 'frontend.v2.describe', params: {} });
+    return new Promise((resolveResult, reject) => {
+      const req = request(url, { agent: this.#agent, method: 'POST', headers: {
+        authorization: `Bearer ${receipt.token}`, 'content-type': 'application/json', 'content-length': Buffer.byteLength(body),
+        'x-supercode-client-id': `registry-${receipt.receipt_id}`, 'x-supercode-permissions': 'observe',
+      } }, (res) => {
+        // A receipt is authority only for its loopback endpoint. Never follow
+        // redirects or give its bearer to a different host.
+        if (res.statusCode < 200 || res.statusCode >= 300) { res.resume(); reject(new Error('local runtime refused its state probe')); return; }
+        let bytes = 0; const chunks = [];
+        res.on('data', (chunk) => { bytes += chunk.length; if (bytes > 1024 * 1024) req.destroy(new Error('runtime descriptor exceeds its read limit')); else chunks.push(chunk); });
+        res.on('error', reject);
+        res.on('end', () => {
+          try {
+            const frame = JSON.parse(Buffer.concat(chunks).toString('utf8')), descriptor = frame.result;
+            if (frame.id !== id || frame.error || descriptor?.schema_version !== 2 || typeof descriptor.session_id !== 'string'
+              || !['connected', 'shutting_down'].includes(descriptor.connection_state)
+              || !['idle', 'busy'].includes(descriptor.turn_state)) throw new Error('invalid runtime descriptor');
+            resolveResult(descriptor.connection_state === 'shutting_down' ? 'shutting_down' : descriptor.turn_state === 'busy' ? 'busy' : 'idle');
+          } catch (error) { reject(error); }
+        });
+      });
+      this.#requests.add(req);
+      const timer = setTimeout(() => req.destroy(new Error('local runtime state probe did not answer')), 2000);
+      req.once('close', () => { clearTimeout(timer); this.#requests.delete(req); });
+      req.once('error', reject); req.end(body);
+    });
+  }
+  /** One receipt scan per poll, probing only followed source identities. */
+  async read(sources) {
+    if (this.#closed) throw new Error('runtime-state reader closed');
+    const keys = new Map(sources.map((source) => [JSON.stringify([source.harness, source.session_id]), 'persisted']));
+    if (!keys.size) return keys;
+    let names; try { names = await readdir(this.#directory); } catch { names = []; }
+    const receipts = [];
+    for (const name of names) {
+      if (!name.endsWith('.json')) continue;
+      try { const receipt = await this.#receipt(join(this.#directory, name)); receipts.push(receipt); } catch { /* native registry discovery skips malformed/stale receipts */ }
+    }
+    receipts.sort((a, b) => b.created_at_ms - a.created_at_ms || Buffer.compare(Buffer.from(a.runtime_session_id), Buffer.from(b.runtime_session_id)));
+    for (const receipt of receipts) {
+      if (this.#closed) throw new Error('runtime-state reader closed');
+      const key = JSON.stringify([receipt.source.harness, receipt.source.session_id]);
+      if (keys.get(key) !== 'persisted') continue;
+      try {
+        const selected = await this.#receipt(join(this.#directory, `${receipt.receipt_id}.json`));
+        if (selected.receipt_id !== receipt.receipt_id || selected.source.harness !== receipt.source.harness
+          || selected.source.session_id !== receipt.source.session_id
+          || await canonical(selected.source.workspace) !== await canonical(receipt.source.workspace)) continue;
+        keys.set(key, await this.#describe(selected));
+      } catch { /* a failed probe is not a live runtime; try another matching registration */ }
+    }
+    return keys;
+  }
+  close() { this.#closed = true; for (const req of this.#requests) req.destroy(new Error('runtime-state reader closed')); this.#agent.destroy(); }
+}