@sidevoice/uplink 0.2.0 → 0.3.1

package/README.md

@@ -16,14 +16,18 @@ The client side. Three entry points behind one bin (`sidevoice`):
 - `pair` — redeems a pairing code from the room UI for this machine's
   credential (`~/.sidevoice/credentials.json`, mode 0600).
 
-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,9 @@
 #!/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 <mcp|pair|connector|hook|skill> …` — one bin, five entry points. */
+const [, , command] = process.argv;
+const entries = { mcp: './mcp.mjs', pair: './pair.mjs', connector: './connector.mjs', hook: './hook.mjs', skill: './skill.mjs' };
+if (!entries[command]) { console.error('usage: sidevoice <mcp|pair|connector|hook|skill> [args]'); process.exit(2); }
 process.argv.splice(2, 1);
+if (command === 'hook') process.env.SIDEVOICE_HOOK_MAIN = '1';
+if (command === 'skill') process.env.SIDEVOICE_SKILL_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, WORKING_POLL } 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');
@@ -46,10 +47,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 hook that fires 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 +64,44 @@ function saveOutbox() {
 }
 function send(frame) { if (ws?.readyState === WebSocket.OPEN) { ws.send(JSON.stringify(frame)); return true; } return false; }
 
+/* Whether a conversation is working is the harness's own state: each module answers in the way it can
+ * (a polled registry, a stream of lifecycle events), and 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
+ * happens, 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_POLL_MS = Number(process.env.SIDEVOICE_WORK_POLL_MS || 400);
+const WORK_ANNOUNCE_MS = Number(process.env.SIDEVOICE_WORK_ANNOUNCE_MS || 2000);
+let workTimer = 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 watchWork() {
+  if (workTimer) return;
+  workTimer = setInterval(() => {
+    if (!bindings.size) { clearInterval(workTimer); workTimer = null; return; }
+    for (const binding of bindings.values()) {
+      const harness = harnessFor(binding.harness);
+      if (capabilityState(harness, 'working') !== SUPPORTED) continue;
+      let working = binding.working;
+      if (harness.workingSource === WORKING_POLL) {
+        const polled = harness.working(binding.client_ref);
+        if (polled === null) continue;
+        working = polled;
+      } else if (typeof working !== 'boolean') continue;
+      const due = !binding.workingSentAt || Date.now() - binding.workingSentAt >= WORK_ANNOUNCE_MS;
+      if (working === binding.working && !due) continue;
+      announceWork(binding, working);
+    }
+  }, WORK_POLL_MS);
+  workTimer.unref?.();
+}
+
 function open() {
   if (closed || ws?.readyState === WebSocket.OPEN || ws?.readyState === WebSocket.CONNECTING) return;
   const socket = ws = new WebSocket(creds.url);
@@ -90,7 +131,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 +141,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;
@@ -113,7 +155,8 @@ async function receive(frame) {
       // One delivery at a time per binding keeps the user's turns in order.
       binding.chain = (binding.chain || Promise.resolve()).then(async () => {
         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) {
@@ -123,13 +166,23 @@ async function receive(frame) {
       });
       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);
+      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, 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 +200,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(); watchWork();
       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 */ }
+        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); 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();
@@ -176,6 +234,48 @@ async function command(client, input) {
       const { type, event_id, ...result } = reply;
       return result;
     }
+    case 'read': {
+      // A harness hook says the conversation admitted this voice message: the room learns it was read.
+      const { thread, message_id, session_id, revision, turn_id } = params;
+      if (!thread || !message_id) throw new Error('thread and message_id are required');
+      const binding = [...bindings.values()].find(b => b.thread === thread || b.client_ref === thread);
+      if (!binding) return { status: 'no_binding' };
+      if (readReported.has(message_id)) return { status: 'already_reported' };
+      readReported.add(message_id); if (readReported.size > 512) readReported.delete(readReported.values().next().value);
+      const sent = send({ type: 'input.read', binding_id: binding.binding_id, message_id, session_id, revision, turn_id: turn_id || null });
+      return { status: sent ? 'sent' : 'offline' };
+    }
+    case 'turn_end': {
+      const binding = [...bindings.values()].find(b => b.thread === params.thread || b.client_ref === params.thread);
+      if (!binding) return { status: 'no_binding' };
+      const sent = announceWork(binding, false, { turn_id: params.turn_id || null });
+      return { status: sent ? 'sent' : 'offline' };
+    }
+    case 'working': {
+      const { thread, turn_id, working } = params;
+      if (!thread || typeof working !== 'boolean' || !turn_id) throw new Error('thread, turn_id and working are required');
+      const binding = [...bindings.values()].find(b => b.thread === thread || b.client_ref === thread);
+      if (!binding) return { status: 'no_binding' };
+      binding.activeTurns ||= new Map();
+      binding.completedTurns ||= new Set();
+      if (working) {
+        if (binding.completedTurns.has(turn_id)) return { status: 'stale' };
+        if (binding.activeTurns.has(turn_id)) return { status: 'already_reported' };
+        const correlation = { turn_id,
+          ...(typeof params.session_id === 'string' ? { session_id: params.session_id } : {}),
+          ...(Number.isInteger(params.revision) ? { revision: params.revision } : {}) };
+        binding.activeTurns.set(turn_id, correlation);
+        const sent = announceWork(binding, true, { turn_phase: 'start', ...correlation });
+        return { status: sent ? 'sent' : 'offline' };
+      }
+      if (binding.completedTurns.has(turn_id)) return { status: 'already_reported' };
+      const correlation = binding.activeTurns.get(turn_id);
+      binding.completedTurns.add(turn_id);
+      if (!correlation) return { status: 'stale' };
+      binding.activeTurns.delete(turn_id);
+      const sent = announceWork(binding, binding.activeTurns.size > 0, { turn_phase: 'end', ...correlation });
+      return { status: sent ? 'sent' : 'offline' };
+    }
     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 }); }

package/harness-claude.mjs

@@ -8,8 +8,10 @@
  *  Documented at https://code.claude.com/docs/en/cross-session-messaging */
 import { execFileSync } from 'node:child_process';
 import { readFileSync, readdirSync } from 'node:fs';
+import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
+import { defineHarness, envelope, SUPPORTED, WORKING_POLL } 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,70 @@ 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. A prompt-admitted hook supplies the
+ *  separate read receipt; 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'));
+  });
+}
+
+/** A configured Stop hook is a direct end-of-turn signal, independent of session polling. */
+export function endOfTurn(payload, env = process.env) {
+  if (!payload || !/^stop$/i.test(String(payload.hook_event_name || payload.hookEventName || ''))) return null;
+  const identity = sessionIdentity({ env });
+  return identity ? { thread: identity.thread, turn_id: payload.turn_id || null } : null;
+}
+
+export const claudeHarness = defineHarness({
+  name: 'claude',
+  workingSource: WORKING_POLL,
+  capabilities: {
+    deliver: SUPPORTED,
+    inspectInbound: SUPPORTED,
+    working: SUPPORTED,
+    endOfTurn: SUPPORTED,
+    sessionIdentity: SUPPORTED,
+  },
+  deliver,
+  inspectInbound,
+  engine: sessionEngine,
+  working: sessionWorking,
+  endOfTurn,
+  sessionIdentity,
+});
+
+export default claudeHarness;

package/harness-codex.mjs

@@ -0,0 +1,95 @@
+/** Codex harness implementation.
+ *
+ * Delivery and identity are available to the stdio MCP façade. Configured UserPromptSubmit and
+ * Stop hooks report the mechanical start and end of every interactive turn. */
+import { execFile } from 'node:child_process';
+import { defineHarness, envelope, SUPPORTED, UNSUPPORTED, WORKING_EVENT } 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;
+}
+
+function endOfTurn(payload, env = process.env) {
+  if (!payload || !/^stop$/i.test(String(payload.hook_event_name || payload.hookEventName || ''))) return null;
+  const identity = sessionIdentity({ payload, env });
+  return identity ? { thread: identity.thread, turn_id: payload.turn_id || null } : null;
+}
+
+/** A Codex lifecycle hook, normalized as a per-thread working transition. */
+function working(payload, env = process.env) {
+  const event = String(payload?.hook_event_name || payload?.hookEventName || '');
+  if (!/^(userpromptsubmit|stop)$/i.test(event)) return null;
+  const identity = sessionIdentity({ payload, env });
+  if (!identity || typeof identity.thread !== 'string' || !identity.thread
+      || typeof payload.turn_id !== 'string' || !payload.turn_id) return null;
+  return {
+    thread: identity.thread,
+    turn_id: payload.turn_id || null,
+    working: /^userpromptsubmit$/i.test(event),
+  };
+}
+
+export const codexHarness = defineHarness({
+  name: 'codex',
+  workingSource: WORKING_EVENT,
+  capabilities: {
+    deliver: SUPPORTED,
+    inspectInbound: UNSUPPORTED,
+    working: SUPPORTED,
+    endOfTurn: SUPPORTED,
+    sessionIdentity: SUPPORTED,
+  },
+  deliver,
+  engine,
+  working,
+  endOfTurn,
+  sessionIdentity,
+});
+
+export default codexHarness;

package/harness-contract.mjs

@@ -0,0 +1,53 @@
+/** The harness boundary. A known harness declares every capability; callers never infer support
+ *  from a missing method. Missing or malformed declarations remain unknown, never false. */
+
+export const CAPABILITIES = Object.freeze([
+  'deliver',
+  'inspectInbound',
+  'working',
+  'endOfTurn',
+  'sessionIdentity',
+]);
+
+export const SUPPORTED = 'supported';
+export const UNSUPPORTED = 'unsupported';
+export const UNKNOWN = 'unknown';
+export const WORKING_POLL = 'poll';
+export const WORKING_EVENT = 'event';
+const DECLARED_STATES = new Set([SUPPORTED, UNSUPPORTED]);
+const WORKING_SOURCES = new Set([WORKING_POLL, WORKING_EVENT]);
+
+export function capabilityState(harness, capability) {
+  const state = harness?.capabilities?.[capability];
+  return DECLARED_STATES.has(state) ? state : UNKNOWN;
+}
+
+export function advertisedCapabilities(harness) {
+  return Object.fromEntries(CAPABILITIES.map(capability => [capability, capabilityState(harness, capability)]));
+}
+
+export function defineHarness(definition) {
+  if (!definition?.name) throw new Error('A harness needs a name');
+  for (const capability of CAPABILITIES) {
+    const state = definition.capabilities?.[capability];
+    if (!DECLARED_STATES.has(state)) throw new Error(`${definition.name} must declare ${capability}`);
+    if (state === SUPPORTED && typeof definition[capability] !== 'function') {
+      throw new Error(`${definition.name} declares ${capability} supported but does not implement it`);
+    }
+  }
+  if (definition.capabilities.working === SUPPORTED && !WORKING_SOURCES.has(definition.workingSource)) {
+    throw new Error(`${definition.name} declares working supported but does not declare a working source`);
+  }
+  return Object.freeze({ ...definition, capabilities: Object.freeze({ ...definition.capabilities }) });
+}
+
+/** The header the voice skill expects before the user's literal words. */
+export function envelope(event) {
+  const header = {
+    channel: event.channel === 'room-control' ? 'room-control' : 'voice',
+    session_id: event.session_id,
+    revision: event.revision,
+    message_id: event.message_id,
+  };
+  return JSON.stringify(header) + '\n\n' + event.text;
+}

package/harness-http.mjs

@@ -0,0 +1,39 @@
+/** Generic HTTP harness used by explicitly configured external receivers. */
+import { defineHarness, SUPPORTED, UNSUPPORTED } from './harness-contract.mjs';
+
+async function deliver(delivery, event) {
+  if (delivery?.kind !== 'http') throw new Error(`Unsupported HTTP delivery kind: ${delivery?.kind}`);
+  const response = await 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),
+  });
+  if (!response.ok) throw new Error(`Harness delivery failed (${response.status})`);
+  return { status: 'accepted', detail: `receiver answered ${response.status}` };
+}
+
+function sessionIdentity({ env = process.env } = {}) {
+  if (!env.SIDEVOICE_THREAD || !env.SIDEVOICE_DELIVERY_URL) return null;
+  return {
+    harness: env.SIDEVOICE_HARNESS || 'http',
+    thread: env.SIDEVOICE_THREAD,
+    delivery: { kind: 'http', url: env.SIDEVOICE_DELIVERY_URL, thread: env.SIDEVOICE_THREAD },
+  };
+}
+
+export const httpHarness = defineHarness({
+  name: 'http',
+  capabilities: {
+    deliver: SUPPORTED,
+    inspectInbound: UNSUPPORTED,
+    working: UNSUPPORTED,
+    endOfTurn: UNSUPPORTED,
+    sessionIdentity: SUPPORTED,
+  },
+  deliver,
+  sessionIdentity,
+});
+
+export default httpHarness;

package/harnesses.mjs

@@ -0,0 +1,36 @@
+/** Registry and selection for the harness modules. The façade and connector ask this registry;
+ *  neither contains harness-name branches. */
+import { claudeHarness } from './harness-claude.mjs';
+import { codexHarness } from './harness-codex.mjs';
+import { httpHarness } from './harness-http.mjs';
+
+export const harnesses = Object.freeze({ claude: claudeHarness, codex: codexHarness, http: httpHarness });
+
+export function harnessFor(name) {
+  return harnesses[name] || httpHarness;
+}
+
+export function identifyHarness(meta, env = process.env) {
+  for (const harness of [claudeHarness, codexHarness, httpHarness]) {
+    const identity = harness.sessionIdentity({ meta, env });
+    if (identity?.delivery) return { ...identity, module: harness };
+  }
+  throw new Error('Cannot tell which conversation this is: not launched by Claude Code or Codex, and no SIDEVOICE_THREAD/SIDEVOICE_DELIVERY_URL set');
+}
+
+/** Which harness a hook invocation belongs to.
+ *
+ *  The installed hook command names it (`sidevoice hook --harness <name>`, or SIDEVOICE_HOOK_HARNESS):
+ *  a harness started from another harness's terminal inherits that one's environment variables, and both
+ *  hook payloads carry a `session_id`, so neither the environment nor the payload can tell them apart on
+ *  its own. Naming it at the point of install is mechanical; guessing is not. Without a declaration the
+ *  modules are asked in order, which only holds when a single harness runs on the machine. */
+export function identifyHookHarness(payload, env = process.env) {
+  const declared = env.SIDEVOICE_HOOK_HARNESS;
+  const candidates = declared ? [harnesses[declared]].filter(Boolean) : [claudeHarness, codexHarness, httpHarness];
+  for (const harness of candidates) {
+    const identity = harness.sessionIdentity({ payload, env });
+    if (identity) return { ...identity, module: harness };
+  }
+  return null;
+}

package/hook.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/** Harness hook: `sidevoice hook` on stdin reports lifecycle events for event-backed harnesses. When an admitted
+ *  prompt is a Sidevoice voice message it also reports the read receipt and hands the harness context so the model
+ *  speaks first. It never blocks the harness: any failure exits 0. */
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { capabilityState, SUPPORTED, WORKING_EVENT } from './harness-contract.mjs';
+import { harnesses, identifyHookHarness } from './harnesses.mjs';
+
+const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
+const socketPath = process.env.SIDEVOICE_CONNECTOR_SOCKET || path.join(dataDir, 'connector.sock');
+
+/** The envelope a harness delivery module puts before the user's words. Anything else is not ours. */
+export function voiceEnvelope(prompt) {
+  if (typeof prompt !== 'string' || !prompt.startsWith('{')) return null;
+  const end = prompt.indexOf('}');
+  if (end < 0) return null;
+  let header;
+  try { header = JSON.parse(prompt.slice(0, end + 1)); } catch { return null; }
+  if (!header || header.channel !== 'voice' || !header.message_id || !header.session_id || !Number.isInteger(header.revision)) return null;
+  return { message_id: header.message_id, session_id: header.session_id, revision: header.revision, text: prompt.slice(end + 1).trim() };
+}
+
+/** What this hook invocation means, or null when it is not a Sidevoice voice message being admitted. */
+export function interpret(payload, env = process.env) {
+  if (!payload || typeof payload !== 'object') return null;
+  const event = payload.hook_event_name || payload.hookEventName;
+  if (event && !/^userpromptsubmit$/i.test(String(event))) return null;
+  const envelope = voiceEnvelope(payload.prompt);
+  if (!envelope) return null;
+  const identity = identifyHookHarness(payload, env);
+  return identity ? { thread: identity.thread, turn_id: payload.turn_id || null, ...envelope } : null;
+}
+
+/** A harness-native end-of-turn signal, normalized by that harness's module. */
+export function interpretTurnEnd(payload, env = process.env) {
+  const identity = identifyHookHarness(payload, env);
+  if (!identity || identity.module.workingSource === WORKING_EVENT
+      || capabilityState(identity.module, 'endOfTurn') !== SUPPORTED) return null;
+  return identity.module.endOfTurn(payload, env);
+}
+
+/** A lifecycle-backed harness working transition, plus Sidevoice correlation when this is our prompt. */
+export function interpretWorking(payload, env = process.env) {
+  const identity = identifyHookHarness(payload, env);
+  if (!identity || capabilityState(identity.module, 'working') !== SUPPORTED
+      || identity.module.workingSource !== WORKING_EVENT) return null;
+  const transition = identity.module.working(payload, env);
+  if (!transition) return null;
+  const reading = transition.working ? voiceEnvelope(payload.prompt) : null;
+  return reading
+    ? { ...transition, session_id: reading.session_id, revision: reading.revision, message_id: reading.message_id }
+    : transition;
+}
+
+/** The harness this hook was installed for, as the hook command itself names it. Nothing is inferred
+ *  from the environment: one harness's variables survive into another harness launched from its terminal. */
+export function declaredHarness(argv = process.argv, env = process.env) {
+  const flag = argv.indexOf('--harness');
+  const named = flag >= 0 ? argv[flag + 1] : argv.find(arg => arg.startsWith('--harness='))?.slice('--harness='.length);
+  return named || env.SIDEVOICE_HOOK_HARNESS || null;
+}
+
+/** The context handed back to the harness: the acknowledgement is asked for at the moment the message is read. */
+export function nudge(reading) {
+  return `A voice message just arrived from the room (session ${reading.session_id}, revision ${reading.revision}). `
+    + 'Before any other tool, publish a short spoken acknowledgement with voice_say that says what you understood and what you will do next, '
+    + 'using that session_id and revision; then continue the work and publish the result by voice as well.';
+}
+
+function report(method, params, timeoutMs = 1500) {
+  return new Promise(resolve => {
+    const socket = net.createConnection(socketPath);
+    const done = value => { clearTimeout(timer); socket.destroy(); resolve(value); };
+    const timer = setTimeout(() => done({ ok: false, error: 'timeout' }), timeoutMs);
+    let buffer = '';
+    socket.on('error', error => done({ ok: false, error: error.code || error.message }));
+    socket.on('connect', () => socket.write(JSON.stringify({ id: 1, method, params }) + '\n'));
+    socket.on('data', chunk => {
+      buffer += chunk; const index = buffer.indexOf('\n');
+      if (index < 0) return;
+      try { done(JSON.parse(buffer.slice(0, index))); } catch { done({ ok: false, error: 'bad reply' }); }
+    });
+  });
+}
+
+async function main() {
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  let payload = null;
+  try { payload = JSON.parse(raw); } catch {}
+  const named = declaredHarness();
+  if (named && !harnesses[named]) return console.error('[sidevoice hook] unknown harness: ' + named);
+  const env = named ? { ...process.env, SIDEVOICE_HOOK_HARNESS: named } : process.env;
+  const transition = interpretWorking(payload, env);
+  if (transition) {
+    const outcome = await report('working', transition);
+    if (!outcome.ok) console.error('[sidevoice hook] working report not sent: ' + (outcome.error || 'unknown'));
+    if (!transition.working) return;
+  }
+  const ended = interpretTurnEnd(payload, env);
+  if (ended) {
+    const outcome = await report('turn_end', ended);
+    if (!outcome.ok) console.error('[sidevoice hook] end-of-turn report not sent: ' + (outcome.error || 'unknown'));
+    return;
+  }
+  const reading = interpret(payload, env);
+  if (!reading) return;
+  const outcome = await report('read', reading);
+  if (!outcome.ok) console.error('[sidevoice hook] read receipt not sent: ' + (outcome.error || 'unknown'));
+  if (process.env.SIDEVOICE_HOOK_NUDGE !== '0') {
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: nudge(reading) } }) + '\n');
+  }
+}
+
+if (process.argv[1] && /hook\.mjs$/.test(process.argv[1]) || process.env.SIDEVOICE_HOOK_MAIN === '1') {
+  main().catch(error => { console.error('[sidevoice hook] ' + (error?.message || error)); }).finally(() => process.exit(0));
+}

package/mcp.mjs

@@ -7,7 +7,8 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { inspectInbound } from './harness-claude.mjs';
+import { advertisedCapabilities, capabilityState, SUPPORTED } from './harness-contract.mjs';
+import { harnessFor, identifyHarness } from './harnesses.mjs';
 
 const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
 const socketPath = process.env.SIDEVOICE_CONNECTOR_SOCKET || path.join(dataDir, 'connector.sock');
@@ -20,29 +21,11 @@ const INSTRUCTIONS = `Sidevoice connects this conversation to the user's voice r
 - A progress publication is not itself a listening point. Divide substantive execution into bounded steps and, after each tool result or operational boundary, process newly arrived user input before starting the next step. Do not add artificial sleeps or fixed pauses.
 - If a new user message arrives during active work, treat it as an addition, refinement, or replacement according to its meaning. Stop not-yet-started obsolete work, preserve completed work that remains useful, acknowledge the new interpretation before continuing, and do not later answer a stale request. A tool already running may finish before the correction takes effect; delegation is not a substitute for listening.
 - A "published" voice_say result means the room stored it, not that the user heard it. If publication fails, continue in writing.
-- A message with "channel":"room-control" is an instruction from the room (for example: continue in writing); it is not a voice turn to answer aloud.
+- If the user closes this conversation's voice channel from the room, the connection is removed: voice_say then fails saying so. Continue in writing and do not try to speak again; call voice_connect only when the user asks for voice again.
 - voice_status reports whether the room can currently reach this conversation.
+- On Claude Code, if a skill named voice-room is available, joining through it (/voice-room) is preferred: it registers, for this session only, the hook that gives the room read receipts and asks you to speak first.
 - If voice_connect returns inbound.ok false, voice will look sent and never arrive: this harness holds or refuses messages posted by other local processes. Tell the user what inbound.reason says, offer inbound.remedy in your own words including what safeguard the machine-wide option removes, and let them choose. Do not change their settings without being asked to.`;
 
-/** Who this façade speaks for, decided by what spawned it — never by the model. */
-function identity(meta) {
-  if (process.env.CLAUDE_CODE_SESSION_ID && process.env.CLAUDE_CODE_MESSAGING_SOCKET) {
-    return { harness: 'claude', thread: process.env.CLAUDE_CODE_SESSION_ID,
-      delivery: { kind: 'claude-uds', socket: process.env.CLAUDE_CODE_MESSAGING_SOCKET, token: process.env.CLAUDE_CODE_MESSAGING_TOKEN || '' } };
-  }
-  let turn = meta?.['x-codex-turn-metadata'] || {};
-  if (typeof turn === 'string') { try { turn = JSON.parse(turn); } catch { turn = {}; } }
-  const codexThread = meta?.['openai/threadId'] || meta?.['openai/thread_id'] || meta?.codexThreadId || meta?.codex_thread_id || turn.thread_id || process.env.CODEX_THREAD_ID;
-  if (codexThread) {
-    const delivery = process.env.SIDEVOICE_DELIVERY_URL ? { kind: 'http', url: process.env.SIDEVOICE_DELIVERY_URL, thread: codexThread } : { kind: 'codex-queue', thread: codexThread };
-    return { harness: 'codex', thread: codexThread, delivery };
-  }
-  if (process.env.SIDEVOICE_THREAD && process.env.SIDEVOICE_DELIVERY_URL) {
-    return { harness: process.env.SIDEVOICE_HARNESS || 'http', thread: process.env.SIDEVOICE_THREAD, delivery: { kind: 'http', url: process.env.SIDEVOICE_DELIVERY_URL, thread: process.env.SIDEVOICE_THREAD } };
-  }
-  throw new Error('Cannot tell which conversation this is: not launched by Claude Code or Codex, and no SIDEVOICE_THREAD/SIDEVOICE_DELIVERY_URL set');
-}
-
 // ----- one persistent connection to the connector -----
 let ipc = null, ipcBuffer = '', ipcSerial = 0;
 const ipcWaiting = new Map();
@@ -94,32 +77,55 @@ const tools = [
   { name: 'voice_status', description: 'Whether the room can currently reach this conversation.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
 ];
 let binding = null;
+function inboundFor(harness, thread) {
+  return capabilityState(harness, 'inspectInbound') === SUPPORTED ? harness.inspectInbound(thread) : null;
+}
 async function invoke(name, args, meta) {
   if (name === 'voice_status') {
-    const status = ipc ? await rpc('status', {}) : { connected: false, bindings: [] };
-    const inbound = binding?.harness === 'claude' ? inspectInbound(binding.client_ref) : { ok: true };
+    const status = ipc ? await rpc('status', {}) : { connected: false, bindings: [], closed_by_room: [] };
+    // The room may have closed this conversation's voice since we joined: the connector is the truth.
+    const closed = !!binding && (status.closed_by_room || []).includes(binding.client_ref);
+    if (closed) binding = null;
+    const module = binding ? harnessFor(binding.harness) : null;
+    const inbound = binding ? inboundFor(module, binding.client_ref) : null;
     return { joined: !!binding, room_reachable: status.connected, room_error: status.room_error || null,
-             binding_id: binding?.binding_id || null, harness: binding?.harness || null, inbound };
+             binding_id: binding?.binding_id || null, harness: binding?.harness || null,
+             capabilities: binding?.capabilities || null, inbound,
+             ...(closed ? { closed_by_room: true, note: 'The user closed this conversation\'s voice channel from the room. Continue in writing; call voice_connect again only if they ask for voice.' } : {}) };
   }
   if (name === 'voice_connect') {
-    const who = identity(meta);
+    const who = identifyHarness(meta);
     const title = (args.title || process.env.SIDEVOICE_TITLE || path.basename(process.cwd())).slice(0, 200);
     // Refuse rather than join a room we cannot hear from: a conversation whose harness holds
     // what the room posts would sit in the list looking present while the user talks to nobody.
-    const inbound = who.harness === 'claude' ? inspectInbound(who.thread) : { ok: true };
-    if (inbound.ok === false) {
+    const inbound = inboundFor(who.module, who.thread);
+    if (inbound?.ok === false) {
       const error = new Error(`No se conecta esta conversación: ${inbound.reason} ${inbound.remedy}`);
       error.data = { inbound };
       throw error;
     }
-    const result = await rpc('register', { client_ref: who.thread, harness: who.harness, thread: who.thread, title, delivery: who.delivery, inbound });
-    binding = { ...result, harness: who.harness, client_ref: who.thread };
+    const capabilities = advertisedCapabilities(who.module);
+    // Which model is answering, read from the session's own launch line rather than asked of the model.
+    let engine = null;
+    try { engine = who.module.engine?.(who.thread) || null; } catch { engine = null; }
+    const result = await rpc('register', { client_ref: who.thread, harness: who.harness, thread: who.thread,
+      title, delivery: who.delivery, inbound, capabilities, engine });
+    binding = { ...result, harness: who.harness, client_ref: who.thread, capabilities };
     return { status: result.pending ? 'joining' : 'joined', harness: who.harness, conversation: who.thread,
-             binding_id: result.binding_id, delivery: 'push', room_reachable: result.connected, inbound };
+             binding_id: result.binding_id, delivery: 'push', room_reachable: result.connected, capabilities, inbound };
   }
   if (!binding) throw new Error('Not connected to the voice room: call voice_connect first (only if the user asked).');
   if (name === 'voice_say') {
-    const result = await rpc('publish', { binding_id: binding.binding_id, client_ref: binding.client_ref, text: args.text, session_id: args.session_id, revision: args.revision, utterance_id: args.utterance_id, language: args.language });
+    let result;
+    try {
+      result = await rpc('publish', { binding_id: binding.binding_id, client_ref: binding.client_ref, text: args.text, session_id: args.session_id, revision: args.revision, utterance_id: args.utterance_id, language: args.language });
+    } catch (error) {
+      if (error.message === 'CLOSED_BY_ROOM') {
+        binding = null;
+        throw new Error('The user closed this conversation\'s voice channel from the room. Continue in writing and do not publish speech; call voice_connect again only if the user asks for voice.');
+      }
+      throw error;
+    }
     return result.text_saved ? { status: 'published', text_saved: true, audio: result.status, reason: result.reason } : result;
   }
   if (name === 'voice_disconnect') { const result = await rpc('unregister', { binding_id: binding.binding_id }); binding = null; return { status: 'left', room_reachable: result.connected }; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidevoice/uplink",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Sidevoice client side: the stdio MCP server your agent uses, one outbound uplink per machine to the room, one-time pairing.",
   "type": "module",
   "license": "MIT",
@@ -14,9 +14,15 @@
     "cli.mjs",
     "mcp.mjs",
     "connector.mjs",
-    "adapters.mjs",
+    "harness-contract.mjs",
+    "harnesses.mjs",
     "harness-claude.mjs",
+    "harness-codex.mjs",
+    "harness-http.mjs",
     "pair.mjs",
+    "hook.mjs",
+    "skill.mjs",
+    "skill/",
     "README.md"
   ],
   "scripts": {

package/skill/voice-room/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: voice-room
+description: Join the user's Sidevoice voice room with this conversation. Use when the user asks to enable voice, join the room or talk by voice; never as a side effect of other work.
+argument-hint: "[title for this conversation in the room]"
+# Same shape as settings.json hooks (a list of groups): Claude Code 2.1.x registers nothing for a map here.
+# The command names its harness: a Codex session started from this terminal inherits CLAUDE_CODE_SESSION_ID,
+# so the hook cannot tell the two apart from the environment alone.
+# The installer replaces __SIDEVOICE_SKILL_DIR__ with the directory it copies this file into: the hook must
+# resolve without any variable, since ${CLAUDE_SKILL_DIR} is not expanded in a user skill's hook command.
+hooks:
+  UserPromptSubmit:
+    - hooks:
+        - type: command
+          command: node "__SIDEVOICE_SKILL_DIR__/hook.mjs" --harness claude
+          timeout: 5
+  Stop:
+    - hooks:
+        - type: command
+          command: node "__SIDEVOICE_SKILL_DIR__/hook.mjs" --harness claude
+          timeout: 5
+metadata:
+  sidevoice: installed copy; the source is skill/voice-room in @sidevoice/uplink, reinstall with `sidevoice skill install`
+---
+
+Join the voice room for this conversation and keep it reachable.
+
+1. Call `voice_status`. If it reports `joined` and `room_reachable`, say so in one line and stop.
+2. Call `voice_connect` with the title `$ARGUMENTS` when given, otherwise a short label of what this conversation is about.
+3. Tell the user in one line whether the room can reach this conversation. If `inbound.ok` is false, relay `inbound.reason` and offer `inbound.remedy` in your own words, including what safeguard it removes; change nothing yourself.
+
+From now on this conversation has read receipts and mechanical working-state reporting: invoking this skill registered hooks that tell the room when a voice message is admitted and when the turn stops. Voice messages arrive as user messages that begin with a JSON header (`channel`, `session_id`, `revision`, `message_id`) followed by the user's words. For each one, publish a short `voice_say` with that `session_id` and `revision` before any other tool, then do the work and publish the result by voice as well. A repeated `message_id` is a redelivery: do not act on it twice.

package/skill.mjs

@@ -0,0 +1,57 @@
+/** `sidevoice skill install|remove|status [--dir <skills dir>]`: the Claude Code skill that joins the room and,
+ *  for that session only, registers the lifecycle hook. It installs the skill plus the hook's harness runtime;
+ *  running install again repairs it. A directory of the same name that is not ours is never touched. */
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const SKILL_NAME = 'voice-room';
+const MARKER = 'sidevoice: installed copy';
+const HOOK_FILES = ['hook.mjs', 'harness-contract.mjs', 'harnesses.mjs', 'harness-claude.mjs', 'harness-codex.mjs', 'harness-http.mjs'];
+
+export function skillsDir(argv = process.argv.slice(2), env = process.env) {
+  const index = argv.indexOf('--dir');
+  if (index >= 0 && argv[index + 1]) return path.resolve(argv[index + 1]);
+  return path.join(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'skills');
+}
+
+export function status(dir) {
+  const target = path.join(dir, SKILL_NAME);
+  const manifest = path.join(target, 'SKILL.md');
+  if (!existsSync(target)) return { state: 'absent', target };
+  let ours = false;
+  try { ours = readFileSync(manifest, 'utf8').includes(MARKER); } catch {}
+  return { state: ours ? 'installed' : 'foreign', target, hook: existsSync(path.join(target, 'hook.mjs')) };
+}
+
+export function install(dir) {
+  const current = status(dir);
+  if (current.state === 'foreign') throw new Error(`${current.target} already holds a skill that is not Sidevoice's; remove or rename it first.`);
+  mkdirSync(current.target, { recursive: true });
+  const manifest = readFileSync(path.join(here, 'skill', SKILL_NAME, 'SKILL.md'), 'utf8').replaceAll('__SIDEVOICE_SKILL_DIR__', current.target);
+  writeFileSync(path.join(current.target, 'SKILL.md'), manifest);
+  for (const file of HOOK_FILES) cpSync(path.join(here, file), path.join(current.target, file));
+  return { ...status(dir), action: current.state === 'installed' ? 'updated' : 'installed' };
+}
+
+export function remove(dir) {
+  const current = status(dir);
+  if (current.state === 'foreign') throw new Error(`${current.target} is not Sidevoice's skill; left as it is.`);
+  if (current.state === 'installed') rmSync(current.target, { recursive: true, force: true });
+  return { state: 'absent', target: current.target, action: current.state === 'installed' ? 'removed' : 'nothing to remove' };
+}
+
+if (process.env.SIDEVOICE_SKILL_MAIN === '1') {
+  const [command] = process.argv.slice(2);
+  const dir = skillsDir();
+  try {
+    const result = command === 'install' ? install(dir) : command === 'remove' ? remove(dir) : command === 'status' ? status(dir) : null;
+    if (!result) { console.error('usage: sidevoice skill <install|remove|status> [--dir <skills dir>]'); process.exit(2); }
+    console.log(`${result.action || result.state}: ${result.target}`);
+    if (result.action === 'installed' || result.action === 'updated') {
+      console.log('In Claude Code, /voice-room joins the room for that conversation and gives it read receipts. New sessions see the skill; a session already open needs a restart.');
+    }
+  } catch (error) { console.error(error.message); process.exit(1); }
+}

package/adapters.mjs

@@ -1,69 +0,0 @@
-/** The last mile, one function per harness. Each takes a binding's delivery target and a room event. */
-import net from 'node:net';
-import { execFile } from 'node:child_process';
-
-/** The header the skill expects before the user's literal words. */
-export function envelope(event) {
-  const header = { channel: event.channel === 'room-control' ? 'room-control' : 'voice',
-    session_id: event.session_id, revision: event.revision, message_id: event.message_id };
-  return JSON.stringify(header) + '\n\n' + event.text;
-}
-
-/** Claude Code: the session's own inbox socket, inherited by the façade that registered the binding.
- *  The inbox sends no acknowledgement, so this can never report more than what the wire showed:
- *  the peer hanging up right after the frames is the one observable sign of a refusal. */
-function deliverClaude(delivery, event) {
-  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();
-    });
-    // A hang-up right after the frames is how a refused auth or a closed inbox looks from here.
-    socket.on('close', () => finish(null, 'rejected', wrote ? 'peer closed the connection' : 'peer closed before the frames were written'));
-  });
-}
-
-/** Codex: `codex queue` enqueues the next user turn on the local app-server daemon. */
-function deliverCodex(delivery, event) {
-  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' });
-    });
-  });
-}
-
-/** Fallback: an HTTP receiver next to the harness (the slimmed Codex Desktop bridge speaks this). */
-async function deliverHttp(delivery, event) {
-  const response = await 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),
-  });
-  if (!response.ok) throw new Error(`Harness delivery failed (${response.status})`);
-  return { status: 'accepted', detail: `receiver answered ${response.status}` };
-}
-
-export const adapters = { 'claude-uds': deliverClaude, 'codex-queue': deliverCodex, http: deliverHttp };
-
-export function deliver(delivery, event) {
-  const adapter = adapters[delivery?.kind];
-  if (!adapter) throw new Error(`Unknown delivery kind: ${delivery?.kind}`);
-  return adapter(delivery, event);
-}