@sidevoice/uplink 0.2.0 → 0.4.0

package/README.md

@@ -1,9 +1,12 @@
 # Sidevoice uplink — the client side (`@sidevoice/uplink`)
 
-The client side. Three entry points behind one bin (`sidevoice`):
+The client side. One bin (`sidevoice`), these entry points:
 
+- `install` — registers the MCP server with the harness (re-pinned to this
+  version when an older one was registered) and installs the skill. Pairs with
+  nothing; reports whether the machine is paired and with which room.
 - `mcp` — the stdio MCP server a harness starts. One per conversation. Exposes
-  `voice_connect`, `voice_say`, `voice_disconnect`, `voice_status`; carries the
+  `voice_connect`, `voice_pair`, `voice_say`, `voice_disconnect`, `voice_status`; carries the
   operational instructions in its `initialize` result. It never talks to the
   room: it keeps one local connection to the connector for as long as the
   session lives, and the binding it registered dies with that connection.
@@ -13,17 +16,23 @@ The client side. Three entry points behind one bin (`sidevoice`):
   durable outbox for speech published while offline, answers the room's
   heartbeat, and delivers one input event at a time per binding through the
   adapter that binding was registered with. A file lock makes it a singleton.
-- `pair` — redeems a pairing code from the room UI for this machine's
-  credential (`~/.sidevoice/credentials.json`, mode 0600).
+- `pair` — redeems, by hand, a pairing code from the room UI for this machine's
+  credential (`~/.sidevoice/credentials.json`, mode 0600). The usual path is the
+  conversation's `voice_pair`, with the code the user read from the room; nothing
+  on the client side ever asks the room for a code.
 
-Adapters (`adapters.mjs`): `claude-uds` writes the voice envelope as a user
-message to the Claude Code session's inbox socket; `codex-queue` runs
-`codex queue --thread <id>`; `http` posts to any local receiver that accepts the
-room's message shape (for harnesses that have neither).
+Harness modules implement one contract (`harness-contract.mjs`): delivery,
+inbound inspection, mechanical working state (polled or lifecycle-backed), end-of-turn reporting and session
+identity. Every capability is explicitly `supported` or `unsupported`; an old
+or malformed declaration becomes `unknown`, never false. Claude Code, Codex and
+generic HTTP each have one module. See the repository's
+[`docs/HARNESS_CONTRACT.md`](../../docs/HARNESS_CONTRACT.md).
 
 Protocol (newline-free JSON over the WebSocket): `connector.hello` ->
-`connector.welcome`; `binding.register` -> `binding.registered|rejected`;
-`binding.unregister`; `input.deliver` -> `input.ack`; `speech.publish` ->
+`connector.welcome`; `binding.register` (including declared harness capabilities)
+-> `binding.registered|rejected`;
+`binding.unregister`; `input.deliver` -> `input.ack`; `input.working`;
+`speech.publish` ->
 `speech.published`; `heartbeat` <-> `heartbeat.ack`. Protocol version 1.
 
 Node 22+, no dependencies. Tests: `node --test test/test_connector.mjs`.

package/cli.mjs

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
-/** `sidevoice <mcp|pair|connector> …` — one bin, three entry points. */
-const [, , command, ...rest] = process.argv;
-const entries = { mcp: './mcp.mjs', pair: './pair.mjs', connector: './connector.mjs' };
-if (!entries[command]) { console.error('usage: sidevoice <mcp|pair|connector> [args]'); process.exit(2); }
+/** `sidevoice <install|mcp|pair|connector|skill> …` — one bin, five entry points. */
+const [, , command] = process.argv;
+const entries = { install: './install.mjs', mcp: './mcp.mjs', pair: './pair.mjs', connector: './connector.mjs', skill: './skill.mjs' };
+if (!entries[command]) { console.error('usage: sidevoice <install|mcp|pair|connector|skill> [args]'); process.exit(2); }
 process.argv.splice(2, 1);
+if (command === 'skill') process.env.SIDEVOICE_SKILL_MAIN = '1';
+if (command === 'pair') process.env.SIDEVOICE_PAIR_MAIN = '1';
+if (command === 'install') process.env.SIDEVOICE_INSTALL_MAIN = '1';
 await import(entries[command]);

package/connector.mjs

@@ -7,7 +7,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { mkdirSync, openSync, closeSync, writeFileSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { deliver } from './adapters.mjs';
+import { capabilityState, SUPPORTED, voiceEnvelope } from './harness-contract.mjs';
+import { harnessFor } from './harnesses.mjs';
 
 export const PROTOCOL = 1;
 const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
@@ -24,11 +25,12 @@ function credentials() {
   const url = process.env.SIDEVOICE_URL || saved.url;
   const connector_id = process.env.SIDEVOICE_CONNECTOR_ID || saved.connector_id;
   const token = process.env.SIDEVOICE_CONNECTOR_TOKEN || saved.token;
-  if (!url || !connector_id || !token) throw new Error(`Not paired: run pair.mjs first (looked in ${credentialsPath})`);
+  if (!url || !connector_id || !token) throw new Error(`Not paired with any room (looked in ${credentialsPath}): the conversation's voice_pair, or sidevoice pair <room-url> <code>, with the code the room shows`);
   const parsed = new URL(url);
   const loopback = ['127.0.0.1', 'localhost', '::1'].includes(parsed.hostname);
   if (parsed.protocol !== 'wss:' && !loopback) throw new Error('The room URL must be wss:// unless it is loopback');
-  return { url, connector_id, token };
+  const room = new URL(url); room.protocol = room.protocol === 'wss:' ? 'https:' : 'http:';
+  return { url, connector_id, token, room: room.origin };
 }
 
 function alive(pid) { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } }
@@ -46,10 +48,12 @@ function acquireLock() {
   return false;
 }
 
-const bindings = new Map();        // binding_id -> { binding_id, client_ref, harness, thread, title, delivery, owner, chain }
+const bindings = new Map();        // binding_id -> { binding_id, client_ref, harness, thread, title, delivery, capabilities, owner, chain }
 const registering = new Map();     // client_ref -> { resolve, reject, timer }
 const publishing = new Map();      // event_id -> { resolve, timer }
 const clients = new Set();         // façade IPC connections
+const closedByRoom = new Map();    // client_ref -> reason: the user closed that conversation's voice from the room
+const readReported = new Set();    // message ids already reported as read, so a transcript read twice is harmless
 let outbox = [];                   // speech frames not yet confirmed by the room
 let ws = null, connected = false, closed = false, reconnectTimer = null, idleTimer = null, reconnectAttempt = 0, lastError = null;
 let creds;
@@ -61,6 +65,74 @@ function saveOutbox() {
 }
 function send(frame) { if (ws?.readyState === WebSocket.OPEN) { ws.send(JSON.stringify(frame)); return true; } return false; }
 
+/* Whether a conversation is working, and whether it has read what the room sent, are the harness's own
+ * state — and every harness writes that state down somewhere of its own: Claude Code in a session registry
+ * and a transcript, Codex in the thread's rollout. Each module watches what its harness writes (`observe`)
+ * and calls back; nothing is installed in the harness for it. Unknown or unsupported is skipped rather
+ * than rendered as false.
+ *
+ * The connector does not assume the room still knows what it was told. A transition is sent the moment it
+ * is seen, and the same state is said again every few seconds regardless: a room that restarted, or a
+ * socket that dropped, learns what is true within one interval instead of waiting for the next change that
+ * may never come (a conversation that was already working when the room came back showed nothing at all,
+ * 2026-09-20). Saying it again is one small frame; not saying it is a light that never comes on. */
+const WORK_ANNOUNCE_MS = Number(process.env.SIDEVOICE_WORK_ANNOUNCE_MS || 2000);
+const PENDING_MAX = 64;
+let announceTimer = null;
+function announceWork(binding, working, extra = {}) {
+  binding.working = working;
+  binding.workingSentAt = Date.now();
+  return send({ type: 'input.working', binding_id: binding.binding_id, working, ...extra });
+}
+function keepAnnouncing() {
+  if (announceTimer) return;
+  announceTimer = setInterval(() => {
+    if (!bindings.size) { clearInterval(announceTimer); announceTimer = null; return; }
+    for (const binding of bindings.values()) {
+      if (typeof binding.working !== 'boolean') continue;
+      if (Date.now() - (binding.workingSentAt || 0) >= WORK_ANNOUNCE_MS) announceWork(binding, binding.working);
+    }
+  }, Math.max(50, WORK_ANNOUNCE_MS / 4));
+  announceTimer.unref?.();
+}
+/** Start watching a binding's conversation through its harness. What we delivered and it has not yet taken
+ *  waits in `pending`; the moment its transcript shows the message, the room gets the second tick and a
+ *  correlated start of turn; the end of that turn carries the same correlation. */
+function watch(binding) {
+  const harness = harnessFor(binding.harness);
+  if (binding.stop || capabilityState(harness, 'working') !== SUPPORTED || typeof harness.observe !== 'function') return;
+  binding.pending ||= new Map();
+  const correlation = () => binding.turn ? { turn_id: binding.turn.turn_id, session_id: binding.turn.session_id, revision: binding.turn.revision } : {};
+  binding.stop = harness.observe(binding.thread, {
+    userMessage({ text, turn_id }) {
+      const header = voiceEnvelope(text);
+      if (!header || !binding.pending.has(header.message_id)) return;
+      binding.pending.delete(header.message_id);
+      if (!readReported.has(header.message_id)) {
+        readReported.add(header.message_id); if (readReported.size > 512) readReported.delete(readReported.values().next().value);
+        send({ type: 'input.read', binding_id: binding.binding_id, message_id: header.message_id, session_id: header.session_id, revision: header.revision, turn_id: turn_id || null });
+        console.error(`[sidevoice] ${binding.thread} read ${header.message_id}`);
+      }
+      if (header.channel !== 'voice') return;
+      binding.turn = { turn_id: turn_id || null, session_id: header.session_id, revision: header.revision };
+      announceWork(binding, true, turn_id ? { turn_phase: 'start', ...correlation() } : {});
+    },
+    working(working, { turn_id } = {}) {
+      if (working) {
+        // A start we can name is said with its name; the correlated start, if any, comes with the message itself.
+        if (binding.turn && turn_id && binding.turn.turn_id === turn_id) return announceWork(binding, true, { turn_phase: 'start', ...correlation() });
+        return announceWork(binding, true, {});
+      }
+      const ours = binding.turn && (!turn_id || !binding.turn.turn_id || binding.turn.turn_id === turn_id);
+      if (ours) { const extra = binding.turn.turn_id ? { turn_phase: 'end', ...correlation() } : {}; binding.turn = null; return announceWork(binding, false, extra); }
+      if (turn_id && binding.turn) return;     // some other turn ended: ours is still running
+      return announceWork(binding, false, {});
+    },
+  });
+  keepAnnouncing();
+}
+function unwatch(binding) { try { binding.stop?.(); } catch {} binding.stop = null; }
+
 function open() {
   if (closed || ws?.readyState === WebSocket.OPEN || ws?.readyState === WebSocket.CONNECTING) return;
   const socket = ws = new WebSocket(creds.url);
@@ -90,7 +162,7 @@ async function receive(frame) {
         // Sending it back makes the room correctly reject it as foreign.
         const frame = { type: 'binding.register', client_ref: binding.client_ref,
           harness: binding.harness, thread: binding.thread, title: binding.title,
-          inbound: binding.inbound, focus: false };
+          inbound: binding.inbound, capabilities: binding.capabilities, focus: false };
         if (!binding.binding_id.startsWith('local-')) frame.binding_id = binding.binding_id;
         send(frame);
       }
@@ -100,6 +172,7 @@ async function receive(frame) {
     case 'binding.registered': {
       const binding = [...bindings.values()].find(b => b.client_ref === frame.client_ref);
       if (binding && binding.binding_id !== frame.binding_id) { bindings.delete(binding.binding_id); binding.binding_id = frame.binding_id; bindings.set(frame.binding_id, binding); }
+      if (binding && typeof binding.working === 'boolean') announceWork(binding, binding.working);
       registering.get(frame.client_ref)?.resolve(frame); return;
     }
     case 'binding.rejected': registering.get(frame.client_ref)?.reject(new Error(frame.error || 'Binding rejected')); return;
@@ -112,24 +185,43 @@ async function receive(frame) {
       if (!binding) { send({ type: 'input.ack', event_id: frame.event_id, status: 'unknown_binding' }); return; }
       // One delivery at a time per binding keeps the user's turns in order.
       binding.chain = (binding.chain || Promise.resolve()).then(async () => {
+        // Expected before it is sent: the harness can take the message, and its transcript show it, before the
+        // delivery call has even settled (Claude Code admitted one 9 ms after the write; the socket answered
+        // 1.5 s later, 2026-09-21). A message expected and never taken costs a map entry.
+        if (binding.pending && frame.message_id) {
+          binding.pending.set(frame.message_id, { session_id: frame.session_id, revision: frame.revision, at: Date.now() });
+          while (binding.pending.size > PENDING_MAX) binding.pending.delete(binding.pending.keys().next().value);
+        }
         try {
-          const outcome = await deliver(binding.delivery, frame);
+          const harness = harnessFor(binding.harness);
+          const outcome = await harness.deliver(binding.delivery, frame);
           console.error(`[sidevoice] delivered ${frame.event_id} to ${binding.thread} via ${binding.delivery.kind}: ${outcome.status} (${outcome.detail})`);
           send({ type: 'input.ack', event_id: frame.event_id, status: outcome.status, detail: outcome.detail });
         } catch (error) {
+          binding.pending?.delete(frame.message_id);
           console.error(`[sidevoice] delivery of ${frame.event_id} failed: ${error.message}`);
           send({ type: 'input.ack', event_id: frame.event_id, status: 'failed', error: String(error.message || error).slice(0, 400) });
         }
       });
       return;
     }
+    case 'binding.close': {
+      // The user closed this conversation's voice in the room. Forget the binding; the façade learns it on its next call.
+      const binding = bindings.get(frame.binding_id);
+      if (!binding) return;
+      bindings.delete(binding.binding_id); binding.owner?.bindings.delete(binding); unwatch(binding);
+      closedByRoom.set(binding.client_ref, frame.reason || 'closed_from_room');
+      console.error(`[sidevoice] room closed voice for ${binding.thread}`);
+      scheduleExit(); return;
+    }
     case 'connector.error': lastError = frame.error; console.error('[sidevoice] room: ' + frame.error); return;
   }
 }
 
 function snapshot() {
-  return { host: hostId, connected, protocol: PROTOCOL, outbox: outbox.length, room_error: lastError,
-    bindings: [...bindings.values()].map(({ binding_id, client_ref, harness, thread, title, delivery }) => ({ binding_id, client_ref, harness, thread, title, delivery: delivery.kind })) };
+  return { host: hostId, room: creds.room, connected, protocol: PROTOCOL, outbox: outbox.length, room_error: lastError, closed_by_room: [...closedByRoom.keys()],
+    bindings: [...bindings.values()].map(({ binding_id, client_ref, harness, thread, title, delivery, capabilities }) =>
+      ({ binding_id, client_ref, harness, thread, title, delivery: delivery.kind, capabilities })) };
 }
 function scheduleExit() {
   if (idleTimer) clearTimeout(idleTimer);
@@ -147,23 +239,28 @@ async function command(client, input) {
   const params = input.params || {};
   switch (input.method) {
     case 'register': {
-      const { client_ref, harness, thread, title, delivery, inbound } = params;
+      const { client_ref, harness, thread, title, delivery, inbound, capabilities, engine } = params;
       if (!client_ref || !thread || !delivery?.kind) throw new Error('client_ref, thread and delivery are required');
+      closedByRoom.delete(client_ref);   // joining again is the user's explicit request
       const existing = [...bindings.values()].find(b => b.client_ref === client_ref);
-      if (existing) { existing.owner = client; existing.delivery = delivery; client.bindings.add(existing); return { binding_id: existing.binding_id, thread, connected }; }
+      if (existing) {
+        Object.assign(existing, { owner: client, delivery, inbound, capabilities });
+        client.bindings.add(existing);
+        return { binding_id: existing.binding_id, thread, connected };
+      }
       const local_id = 'local-' + randomUUID();
-      const binding = { binding_id: local_id, client_ref, harness, thread, title, delivery, inbound, owner: client };
-      bindings.set(local_id, binding); client.bindings.add(binding); clearTimeout(idleTimer); open();
+      const binding = { binding_id: local_id, client_ref, harness, thread, title, delivery, inbound, capabilities, owner: client };
+      bindings.set(local_id, binding); client.bindings.add(binding); clearTimeout(idleTimer); open(); watch(binding);
       const frame = await new Promise((resolve, reject) => {
         const timer = setTimeout(() => { registering.delete(client_ref); reject(new Error(connected ? 'The room did not confirm the binding' : 'The room is unreachable; retrying in the background')); }, 10_000);
         registering.set(client_ref, { resolve: f => { clearTimeout(timer); registering.delete(client_ref); resolve(f); }, reject: e => { clearTimeout(timer); registering.delete(client_ref); reject(e); } });
-        if (!send({ type: 'binding.register', client_ref, harness, thread, title, inbound })) { /* sent on welcome */ }
-      }).catch(error => { if (!connected) return null; bindings.delete(binding.binding_id); client.bindings.delete(binding); throw error; });
+        if (!send({ type: 'binding.register', client_ref, harness, thread, title, inbound, capabilities, engine })) { /* sent on welcome */ }
+      }).catch(error => { if (!connected) return null; bindings.delete(binding.binding_id); client.bindings.delete(binding); unwatch(binding); throw error; });
       return { binding_id: frame?.binding_id || binding.binding_id, thread, connected, pending: !frame };
     }
     case 'publish': {
       const binding = bindings.get(params.binding_id) || [...bindings.values()].find(b => b.client_ref === params.client_ref);
-      if (!binding) throw new Error('Unknown binding');
+      if (!binding) throw new Error(closedByRoom.has(params.client_ref) ? 'CLOSED_BY_ROOM' : 'Unknown binding');
       const speech = { type: 'speech.publish', event_id: params.event_id || randomUUID(), binding_id: binding.binding_id,
         session_id: params.session_id, revision: params.revision, utterance_id: params.utterance_id || randomUUID(), text: params.text, language: params.language };
       outbox.push(speech); saveOutbox();
@@ -178,7 +275,7 @@ async function command(client, input) {
     }
     case 'unregister': {
       const binding = bindings.get(params.binding_id);
-      if (binding) { bindings.delete(binding.binding_id); binding.owner?.bindings.delete(binding); if (!binding.binding_id.startsWith('local-')) send({ type: 'binding.unregister', binding_id: binding.binding_id }); }
+      if (binding) { bindings.delete(binding.binding_id); binding.owner?.bindings.delete(binding); unwatch(binding); if (!binding.binding_id.startsWith('local-')) send({ type: 'binding.unregister', binding_id: binding.binding_id }); }
       scheduleExit(); return snapshot();
     }
     case 'status': return snapshot();
@@ -206,7 +303,7 @@ function serve(socket) {
   socket.on('close', () => {
     clients.delete(client);
     // The façade is gone: so is every conversation it spoke for.
-    for (const binding of client.bindings) { bindings.delete(binding.binding_id); if (!binding.binding_id.startsWith('local-')) send({ type: 'binding.unregister', binding_id: binding.binding_id }); }
+    for (const binding of client.bindings) { bindings.delete(binding.binding_id); unwatch(binding); if (!binding.binding_id.startsWith('local-')) send({ type: 'binding.unregister', binding_id: binding.binding_id }); }
     scheduleExit();
   });
 }

package/harness-claude.mjs

@@ -7,9 +7,11 @@
  *  cannot read could tighten this further, and the result says so rather than pretending.
  *  Documented at https://code.claude.com/docs/en/cross-session-messaging */
 import { execFileSync } from 'node:child_process';
-import { readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
+import { defineHarness, envelope, SUPPORTED, tailJsonl } from './harness-contract.mjs';
 
 const configDir = () => process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 
@@ -17,6 +19,28 @@ function readJson(file) {
   try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
 }
 
+/** The record Claude Code keeps for a session, or null. It publishes `status` there and keeps it current. */
+export function sessionRecord(sessionId) {
+  const registry = path.join(configDir(), 'sessions');
+  let entries = [];
+  try { entries = readdirSync(registry).filter(name => name.endsWith('.json')); } catch { return null; }
+  for (const name of entries) {
+    const record = readJson(path.join(registry, name));
+    if (record?.sessionId === sessionId) return record;
+  }
+  return null;
+}
+
+/** Whether that session is working on something right now: true, false, or null when it cannot be told.
+ *  This is Claude Code's own bookkeeping, not a published interface: an unknown value answers null rather
+ *  than guessing, and the room falls back to what the conversation says about its own replies. */
+export function sessionWorking(sessionId) {
+  const status = sessionRecord(sessionId)?.status;
+  if (status === 'busy') return true;
+  if (status === 'idle' || status === 'ready' || status === 'waiting') return false;
+  return null;
+}
+
 /** The pid of the session with this id, from Claude Code's own session registry. */
 function sessionPid(sessionId) {
   const registry = path.join(configDir(), 'sessions');
@@ -52,6 +76,16 @@ function settingsFromFlag(args) {
 
 const BYPASS_MODES = new Set(['bypassPermissions']);
 
+/** Which model this conversation runs, read from the session's own launch line — no model is asked to
+ *  say what it is. Absent rather than guessed when the launcher did not name one (the CLI's default). */
+export function sessionEngine(sessionId) {
+  const args = launchArgs(sessionPid(sessionId));
+  if (!args) return null;
+  const model = flag(args, '--model'), effort = flag(args, '--effort'), thinking = flag(args, '--thinking');
+  if (!model && !effort) return null;
+  return { model: model || null, effort: effort || null, thinking: thinking || null };
+}
+
 /** Will an injected message be delivered to this Claude session, or held for its user? */
 export function inspectInbound(sessionId) {
   const pid = sessionPid(sessionId);
@@ -86,3 +120,108 @@ export function inspectInbound(sessionId) {
     confidence: pid ? 'read from the session launch flags and settings' : 'settings only; the session process was not found',
   };
 }
+
+/** Identity and private inbox inherited by the MCP façade Claude Code spawned. */
+export function sessionIdentity({ env = process.env } = {}) {
+  if (!env.CLAUDE_CODE_SESSION_ID) return null;
+  return {
+    harness: 'claude',
+    thread: env.CLAUDE_CODE_SESSION_ID,
+    ...(env.CLAUDE_CODE_MESSAGING_SOCKET ? { delivery: {
+      kind: 'claude-uds',
+      socket: env.CLAUDE_CODE_MESSAGING_SOCKET,
+      token: env.CLAUDE_CODE_MESSAGING_TOKEN || '',
+    } } : {}),
+  };
+}
+
+/** Claude Code's session inbox sends no acknowledgement. The read receipt comes from watching the
+ *  session's own transcript (see observe); this method reports only what the socket itself proves. */
+export function deliver(delivery, event) {
+  if (delivery?.kind !== 'claude-uds') throw new Error(`Unsupported Claude delivery kind: ${delivery?.kind}`);
+  return new Promise((resolve, reject) => {
+    const started = Date.now();
+    const socket = net.createConnection(delivery.socket);
+    let settled = false, wrote = 0, replied = '';
+    const finish = (error, status, detail) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); socket.destroy();
+      if (error) return reject(error);
+      resolve({ status, detail: `${detail} after ${Date.now() - started}ms${replied ? ', peer said ' + replied.slice(0, 120) : ''}` });
+    };
+    const timer = setTimeout(() => finish(null, 'unknown', 'connection still open, no acknowledgement'), 1500);
+    socket.on('error', error => finish(error));
+    socket.on('data', chunk => { replied += chunk; });
+    socket.on('connect', () => {
+      socket.write(JSON.stringify({ type: 'auth', token: delivery.token }) + '\n');
+      socket.write(JSON.stringify({ type: 'user', message: { role: 'user', content: envelope(event) } }) + '\n');
+      wrote = Date.now();
+    });
+    socket.on('close', () => finish(null, 'rejected', wrote ? 'peer closed the connection' : 'peer closed before the frames were written'));
+  });
+}
+
+/** The transcript Claude Code writes for a session: one JSON-lines file named after the session id, under
+ *  the project directory it derives from the launch cwd. Found by name rather than derived, so a renamed
+ *  or moved cwd changes nothing. */
+export function transcriptPath(sessionId) {
+  const projects = path.join(configDir(), 'projects');
+  let dirs = [];
+  try { dirs = readdirSync(projects); } catch { return null; }
+  for (const dir of dirs) {
+    const candidate = path.join(projects, dir, sessionId + '.jsonl');
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** The text of a transcript entry that is a user message, or null for anything else (tool results,
+ *  attachments, the session's own bookkeeping). */
+export function userMessageText(entry) {
+  if (entry?.type !== 'user' || entry.message?.role !== 'user') return null;
+  const content = entry.message.content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return null;
+  const parts = content.filter(part => part?.type === 'text').map(part => part.text);
+  return parts.length ? parts.join('\n') : null;
+}
+
+const POLL_MS = Number(process.env.SIDEVOICE_WORK_POLL_MS || 400);
+
+/** Watch one session through what Claude Code itself writes about it, and nothing installed in it:
+ *  its registry record says whether it is busy, and its transcript records every user message the
+ *  moment the session admits it (a message from the inbox is appended as the turn takes it, not when
+ *  the socket accepted it — the difference is what the second tick shows). */
+export function observe(sessionId, handlers) {
+  let lastStatus = null;
+  const stopTranscript = tailJsonl(() => transcriptPath(sessionId), entry => {
+    const text = userMessageText(entry);
+    if (text !== null) handlers.userMessage({ text, turn_id: entry.promptId || null });
+  }, { intervalMs: POLL_MS });
+  const timer = setInterval(() => {
+    const working = sessionWorking(sessionId);
+    if (working === null || working === lastStatus) return;
+    lastStatus = working;
+    handlers.working(working, {});
+  }, POLL_MS);
+  timer.unref?.();
+  return () => { clearInterval(timer); stopTranscript(); };
+}
+
+export const claudeHarness = defineHarness({
+  name: 'claude',
+  capabilities: {
+    deliver: SUPPORTED,
+    inspectInbound: SUPPORTED,
+    working: SUPPORTED,
+    endOfTurn: SUPPORTED,
+    sessionIdentity: SUPPORTED,
+  },
+  deliver,
+  inspectInbound,
+  engine: sessionEngine,
+  observe,
+  sessionIdentity,
+});
+
+export default claudeHarness;

package/harness-codex.mjs

@@ -0,0 +1,126 @@
+/** Codex harness implementation.
+ *
+ * Delivery and identity are available to the stdio MCP façade. Working state and read receipts come
+ * from the thread's own rollout file, which Codex appends as the turn runs; nothing is configured in Codex. */
+import { execFile } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { defineHarness, envelope, SUPPORTED, UNSUPPORTED, tailJsonl } from './harness-contract.mjs';
+
+function turnMetadata(meta) {
+  let turn = meta?.['x-codex-turn-metadata'] || {};
+  if (typeof turn === 'string') {
+    try { turn = JSON.parse(turn); } catch { turn = {}; }
+  }
+  return turn;
+}
+
+function sessionIdentity({ meta, env = process.env, payload } = {}) {
+  const turn = turnMetadata(meta);
+  const thread = meta?.['openai/threadId'] || meta?.['openai/thread_id'] || meta?.codexThreadId
+    || meta?.codex_thread_id || turn.thread_id || payload?.session_id || payload?.thread_id
+    || env.CODEX_THREAD_ID;
+  if (!thread) return null;
+  const delivery = env.SIDEVOICE_DELIVERY_URL
+    ? { kind: 'http', url: env.SIDEVOICE_DELIVERY_URL, thread }
+    : { kind: 'codex-queue', thread };
+  return { harness: 'codex', thread, delivery };
+}
+
+function deliver(delivery, event) {
+  if (delivery?.kind === 'http') {
+    return fetch(delivery.url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ thread_id: delivery.thread, text: event.text, message_id: event.message_id,
+        session_id: event.session_id, revision: event.revision, channel: event.channel || 'voice' }),
+      signal: AbortSignal.timeout(30_000),
+    }).then(async response => {
+      if (!response.ok) throw new Error(`Harness delivery failed (${response.status})`);
+      return { status: 'accepted', detail: `receiver answered ${response.status}` };
+    });
+  }
+  if (delivery?.kind !== 'codex-queue') throw new Error(`Unsupported Codex delivery kind: ${delivery?.kind}`);
+  return new Promise((resolve, reject) => {
+    const binary = process.env.SIDEVOICE_CODEX_BIN || 'codex';
+    const args = ['queue', '--thread', delivery.thread, '--message', envelope(event)];
+    execFile(binary, args, { timeout: 30_000, maxBuffer: 1 << 20 }, (error, stdout, stderr) => {
+      if (error) return reject(new Error((stderr || stdout || error.message).toString().trim().slice(0, 400)));
+      resolve({ status: 'accepted', detail: 'codex queue confirmed the thread' });
+    });
+  });
+}
+
+/** Which model this thread runs, from the launch line of the process that owns it, when it says. */
+function engine(thread, env = process.env) {
+  const named = env.CODEX_MODEL || null;
+  return named ? { model: named, effort: env.CODEX_REASONING_EFFORT || null, thinking: null } : null;
+}
+
+const codexHome = () => process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+
+/** The rollout Codex writes for a thread: `sessions/YYYY/MM/DD/rollout-<stamp>-<thread id>.jsonl`. Found by
+ *  its name, newest day first, so nothing has to be asked of Codex's database. */
+export function rolloutPath(threadId) {
+  const root = path.join(codexHome(), 'sessions');
+  const list = dir => { try { return readdirSync(dir).sort().reverse(); } catch { return []; } };
+  for (const year of list(root)) for (const month of list(path.join(root, year))) for (const day of list(path.join(root, year, month))) {
+    const dir = path.join(root, year, month, day);
+    const file = list(dir).find(name => name.endsWith('-' + threadId + '.jsonl'));
+    if (file) return path.join(dir, file);
+  }
+  return null;
+}
+
+/** What one rollout line says, in the terms of the contract: a working transition, a user message, or nothing. */
+export function interpretRollout(entry, state = {}) {
+  const payload = entry?.payload || {};
+  if (entry?.type === 'event_msg') {
+    if (payload.type === 'task_started' && payload.turn_id) { state.turn_id = payload.turn_id; return { working: true, turn_id: payload.turn_id }; }
+    if ((payload.type === 'task_complete' || payload.type === 'turn_aborted') && payload.turn_id) {
+      if (state.turn_id === payload.turn_id) state.turn_id = null;
+      return { working: false, turn_id: payload.turn_id };
+    }
+    return null;
+  }
+  if (entry?.type === 'response_item' && payload.type === 'message' && payload.role === 'user') {
+    const text = (payload.content || []).filter(part => part?.type === 'input_text').map(part => part.text).join('\n');
+    return text ? { text, turn_id: state.turn_id || null } : null;
+  }
+  return null;
+}
+
+const POLL_MS = Number(process.env.SIDEVOICE_WORK_POLL_MS || 400);
+
+/** Watch one thread through its rollout: task_started/task_complete are the turn, a user message is the
+ *  moment the thread took it (a queued message is written when the turn starts on it). What the rollout
+ *  already holds is read first, silently, so a turn that was running before we looked is reported as
+ *  running — old messages are not re-read. */
+export function observe(threadId, handlers) {
+  const state = {};
+  let working = null;
+  return tailJsonl(() => rolloutPath(threadId), (entry, replayed) => {
+    const seen = interpretRollout(entry, state);
+    if (!seen) return;
+    if (typeof seen.working === 'boolean') { working = seen.working; if (!replayed) handlers.working(seen.working, { turn_id: seen.turn_id }); }
+    else if (!replayed) handlers.userMessage({ text: seen.text, turn_id: seen.turn_id });
+  }, { intervalMs: POLL_MS, catchUp: true, caughtUp: () => { if (working !== null) handlers.working(working, { turn_id: working ? state.turn_id : null }); } });
+}
+
+export const codexHarness = defineHarness({
+  name: 'codex',
+  capabilities: {
+    deliver: SUPPORTED,
+    inspectInbound: UNSUPPORTED,
+    working: SUPPORTED,
+    endOfTurn: SUPPORTED,
+    sessionIdentity: SUPPORTED,
+  },
+  deliver,
+  engine,
+  observe,
+  sessionIdentity,
+});
+
+export default codexHarness;