@sidevoice/uplink 0.3.1 → 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,8 +16,10 @@ 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.
 
 Harness modules implement one contract (`harness-contract.mjs`): delivery,
 inbound inspection, mechanical working state (polled or lifecycle-backed), end-of-turn reporting and session

package/cli.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-/** `sidevoice <mcp|pair|connector|hook|skill> …` — one bin, five entry points. */
+/** `sidevoice <install|mcp|pair|connector|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); }
+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 === 'hook') process.env.SIDEVOICE_HOOK_MAIN = '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,7 @@ 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 { capabilityState, SUPPORTED, WORKING_POLL } from './harness-contract.mjs';
+import { capabilityState, SUPPORTED, voiceEnvelope } from './harness-contract.mjs';
 import { harnessFor } from './harnesses.mjs';
 
 export const PROTOCOL = 1;
@@ -25,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'; } }
@@ -52,7 +53,7 @@ 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
+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;
@@ -64,43 +65,73 @@ 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.
+/* 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
- * happens, and the same state is said again every few seconds regardless: a room that restarted, or a
+ * 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_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;
+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 watchWork() {
-  if (workTimer) return;
-  workTimer = setInterval(() => {
-    if (!bindings.size) { clearInterval(workTimer); workTimer = null; return; }
+function keepAnnouncing() {
+  if (announceTimer) return;
+  announceTimer = setInterval(() => {
+    if (!bindings.size) { clearInterval(announceTimer); announceTimer = 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);
+      if (typeof binding.working !== 'boolean') continue;
+      if (Date.now() - (binding.workingSentAt || 0) >= WORK_ANNOUNCE_MS) announceWork(binding, binding.working);
     }
-  }, WORK_POLL_MS);
-  workTimer.unref?.();
+  }, 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;
@@ -154,12 +185,20 @@ 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 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) });
         }
@@ -170,7 +209,7 @@ async function receive(frame) {
       // 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);
+      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;
@@ -180,7 +219,7 @@ async function receive(frame) {
 }
 
 function snapshot() {
-  return { host: hostId, connected, protocol: PROTOCOL, outbox: outbox.length, room_error: lastError, closed_by_room: [...closedByRoom.keys()],
+  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 })) };
 }
@@ -211,12 +250,12 @@ async function command(client, input) {
       }
       const local_id = 'local-' + randomUUID();
       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();
+      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, capabilities, engine })) { /* sent on welcome */ }
-      }).catch(error => { if (!connected) return null; bindings.delete(binding.binding_id); client.bindings.delete(binding); throw error; });
+      }).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': {
@@ -234,51 +273,9 @@ 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 }); }
+      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();
@@ -306,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,11 +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, WORKING_POLL } from './harness-contract.mjs';
+import { defineHarness, envelope, SUPPORTED, tailJsonl } from './harness-contract.mjs';
 
 const configDir = () => process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 
@@ -135,8 +135,8 @@ export function sessionIdentity({ env = process.env } = {}) {
   };
 }
 
-/** 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. */
+/** 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) => {
@@ -161,16 +161,55 @@ export function deliver(delivery, event) {
   });
 }
 
-/** 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;
+/** 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',
-  workingSource: WORKING_POLL,
   capabilities: {
     deliver: SUPPORTED,
     inspectInbound: SUPPORTED,
@@ -181,8 +220,7 @@ export const claudeHarness = defineHarness({
   deliver,
   inspectInbound,
   engine: sessionEngine,
-  working: sessionWorking,
-  endOfTurn,
+  observe,
   sessionIdentity,
 });
 

package/harness-codex.mjs

@@ -1,9 +1,12 @@
 /** 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. */
+ * 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 { defineHarness, envelope, SUPPORTED, UNSUPPORTED, WORKING_EVENT } from './harness-contract.mjs';
+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'] || {};
@@ -55,29 +58,58 @@ function engine(thread, env = process.env) {
   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;
+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;
 }
 
-/** 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),
-  };
+/** 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',
-  workingSource: WORKING_EVENT,
   capabilities: {
     deliver: SUPPORTED,
     inspectInbound: UNSUPPORTED,
@@ -87,8 +119,7 @@ export const codexHarness = defineHarness({
   },
   deliver,
   engine,
-  working,
-  endOfTurn,
+  observe,
   sessionIdentity,
 });
 

package/harness-contract.mjs

@@ -12,10 +12,7 @@ export const CAPABILITIES = Object.freeze([
 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];
@@ -26,22 +23,27 @@ export function advertisedCapabilities(harness) {
   return Object.fromEntries(CAPABILITIES.map(capability => [capability, capabilityState(harness, capability)]));
 }
 
+/** `working` and `endOfTurn` are both answered by observation: a harness that supports either
+ *  implements `observe(thread, handlers)`, which watches what the harness itself writes about that
+ *  conversation and calls back — `working(bool, { turn_id })` on every transition it can see, and
+ *  `userMessage({ text, turn_id })` for every user message the conversation admits. It returns a
+ *  function that stops watching. Nothing is installed in the harness for this to work. */
 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') {
+    const implemented = capability === 'working' || capability === 'endOfTurn' ? definition.observe : definition[capability];
+    if (state === SUPPORTED && typeof implemented !== '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. */
+/** The header before the user's literal words, and — for a voice message — the note after them that
+ *  asks the conversation to speak first. The note travels inside the message because it is the only
+ *  thing every harness delivers without anything installed; the instructions name it as not the user's. */
 export function envelope(event) {
   const header = {
     channel: event.channel === 'room-control' ? 'room-control' : 'voice',
@@ -49,5 +51,66 @@ export function envelope(event) {
     revision: event.revision,
     message_id: event.message_id,
   };
-  return JSON.stringify(header) + '\n\n' + event.text;
+  const note = header.channel === 'voice' ? '\n\n' + nudge(header) : '';
+  return JSON.stringify(header) + '\n\n' + event.text + note;
+}
+
+/** What the conversation is asked at the moment it reads a voice message. */
+export function nudge(header) {
+  return `[Sidevoice] A voice message from the room (session_id "${header.session_id}", revision ${header.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.';
+}
+
+/** The header at the front of a delivered message, or null when the text is not one of ours. Works on
+ *  the text as a harness stores it, which may put its own line before the header. */
+export function voiceEnvelope(text) {
+  if (typeof text !== 'string') return null;
+  const start = text.indexOf('{"channel":');
+  if (start < 0) return null;
+  const end = text.indexOf('}', start);
+  if (end < 0) return null;
+  let header;
+  try { header = JSON.parse(text.slice(start, end + 1)); } catch { return null; }
+  if (!header || (header.channel !== 'voice' && header.channel !== 'room-control') || !header.message_id || !header.session_id || !Number.isInteger(header.revision)) return null;
+  return { channel: header.channel, message_id: header.message_id, session_id: header.session_id, revision: header.revision };
+}
+
+/** Follows a JSON-lines file the harness appends to: each complete new line is handed to `onLine` as
+ *  parsed JSON. From where the file is now, unless `catchUp` is set — then what is already there is
+ *  read first, with `replayed = true`, so a watcher can learn the current state without mistaking old
+ *  lines for news. The file may not exist yet — `locate` is asked again until it does. */
+export function tailJsonl(locate, onLine, { intervalMs = 400, catchUp = false, caughtUp = () => {} } = {}) {
+  let file = null, offset = null, remainder = '', replaying = false;
+  const poll = async () => {
+    const { statSync, openSync, readSync, closeSync } = await import('node:fs');
+    if (!file) { file = locate(); if (!file) return; }
+    let size;
+    try { size = statSync(file).size; } catch { file = null; offset = null; return; }
+    if (offset === null) {
+      if (!catchUp) { offset = size; return; }                // start at the end: only what happens from now on
+      offset = 0; replaying = true;
+    }
+    if (size < offset) { offset = 0; remainder = ''; }        // rewritten: read it again from the top
+    if (size === offset) return;
+    const fd = openSync(file, 'r');
+    try {
+      const buffer = Buffer.alloc(size - offset);
+      readSync(fd, buffer, 0, buffer.length, offset);
+      offset = size;
+      remainder += buffer.toString('utf8');
+    } finally { closeSync(fd); }
+    let index;
+    while ((index = remainder.indexOf('\n')) >= 0) {
+      const line = remainder.slice(0, index); remainder = remainder.slice(index + 1);
+      if (!line.trim()) continue;
+      let parsed; try { parsed = JSON.parse(line); } catch { continue; }
+      try { onLine(parsed, replaying); } catch {}
+    }
+    if (replaying) { replaying = false; try { caughtUp(); } catch {} }
+  };
+  const timer = setInterval(() => { poll().catch(() => {}); }, intervalMs);
+  timer.unref?.();
+  poll().catch(() => {});
+  return () => clearInterval(timer);
 }

package/harnesses.mjs

@@ -17,20 +17,3 @@ export function identifyHarness(meta, env = process.env) {
   }
   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/install.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/** `sidevoice install` — put this version of Sidevoice in front of the harnesses on this machine.
+ *
+ *  It registers the MCP server (re-pinned to this version when an older one was registered), installs
+ *  the skill, says what it changed, and is safe to run twice: run it again after an upgrade and the
+ *  harness points at the new version. It pairs with nothing. Pairing is a person's act — the room shows
+ *  a one-time code to whoever is in it, and a conversation asks for it the first time it joins — so
+ *  the installer only reports whether this machine is paired, and with which room.
+ *
+ *  What it does not do is decide for the person: it never edits a machine-wide Codex configuration it
+ *  does not own, and it never relaxes Claude Code's inbound safeguard — those it prints, with the reason. */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pairedRoom } from './pair.mjs';
+import { install as installSkill, skillsDir } from './skill.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(path.join(here, 'package.json'), 'utf8')).version;
+/** What a harness should run to start the server. From a checkout it names this copy, so a machine that
+ *  installed from source keeps working when the published version moves; otherwise the pinned package. */
+export function serverCommand(env = process.env) {
+  const fromSource = env.SIDEVOICE_INSTALL_FROM_SOURCE === '1' || existsSync(path.join(here, '..', '..', '.git'));
+  return fromSource
+    ? { command: 'node', args: [path.join(here, 'cli.mjs'), 'mcp'] }
+    : { command: 'npx', args: ['-y', `@sidevoice/uplink@${VERSION}`, 'mcp'] };
+}
+
+export function flag(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+
+/** Which harnesses this machine has, by what they leave behind. */
+export function harnessesPresent(env = process.env) {
+  const found = [];
+  if (existsSync(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'))) found.push('claude');
+  if (existsSync(env.CODEX_HOME || path.join(os.homedir(), '.codex'))) found.push('codex');
+  return found;
+}
+
+function claude(args, env) {
+  return execFileSync(env.SIDEVOICE_CLAUDE_BIN || 'claude', args, { encoding: 'utf8', timeout: 30_000, env, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/** What Claude Code currently runs for `sidevoice`, read from its own `mcp get`: null when nothing is
+ *  registered or there is no `claude` to ask. The scope matters — only a user-scope entry is ours to move. */
+export function claudeRegistration(env = process.env) {
+  let output;
+  try { output = claude(['mcp', 'get', 'sidevoice'], env); } catch { return null; }
+  const field = name => (output.match(new RegExp(`^\\s*${name}:\\s*(.*)$`, 'm')) || [])[1]?.trim() ?? '';
+  const command = field('Command'), args = field('Args');
+  if (!command) return null;
+  return { scope: /user/i.test(field('Scope')) ? 'user' : 'other', line: [command, args].filter(Boolean).join(' ') };
+}
+
+function registerWithClaude(done, env) {
+  const { command, args } = serverCommand(env);
+  const wanted = [command, ...args].join(' ');
+  const manual = `claude mcp add --scope user sidevoice -- ${wanted}`;
+  const current = claudeRegistration(env);
+  if (current?.line === wanted) { done.push('Claude Code already runs this version of the MCP server.'); return; }
+  if (current && current.scope !== 'user') {
+    done.push(`Claude Code has a sidevoice MCP server registered outside user scope (${current.line}); not touched. To move it:\n    ${manual}`);
+    return;
+  }
+  try {
+    if (current) claude(['mcp', 'remove', '--scope', 'user', 'sidevoice'], env);
+    claude(['mcp', 'add', '--scope', 'user', 'sidevoice', '--', command, ...args], env);
+    done.push(current ? `Re-pointed Claude Code's MCP server to this version (was: ${current.line}).`
+                      : 'Registered the MCP server with Claude Code (user scope).');
+  } catch (error) {
+    done.push(`Could not register with Claude Code automatically (${(error.message || '').split('\n')[0]}). Run:\n    ${manual}`);
+  }
+}
+
+/** Codex keeps one machine-wide file that may hold anything its user put there: we never rewrite it. */
+export function codexInstructions(env = process.env) {
+  const { command, args } = serverCommand(env);
+  return [
+    `Add to ${env.CODEX_HOME || path.join(os.homedir(), '.codex')}/config.toml — it is machine-wide and`,
+    'this package does not rewrite it:',
+    '',
+    '  [mcp_servers.sidevoice]',
+    `  command = "${command}"`,
+    `  args = [${args.map(a => `"${a}"`).join(', ')}]`,
+    '',
+    'Then restart Codex. That is all: read receipts and working state come from what Codex records about the thread.',
+  ].join('\n');
+}
+
+/** Claude Code holds messages from other local processes when a session bypasses permission prompts. */
+export function inboundWarning(env = process.env) {
+  const settings = path.join(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'settings.json');
+  let parsed = {};
+  try { parsed = JSON.parse(readFileSync(settings, 'utf8')); } catch { return null; }
+  if (parsed.crossSessionInbound) return null;
+  if (parsed.permissions?.defaultMode !== 'bypassPermissions') return null;
+  return [
+    'This machine runs Claude Code sessions in bypassPermissions, and those hold what the room sends',
+    'instead of delivering it — voice looks sent and never arrives. Either start a session with',
+    `  --settings '{"crossSessionInbound":"accept"}'`,
+    `or add "crossSessionInbound": "accept" to ${settings}. That second one lets any local process post`,
+    'into every Claude session on this machine, which is the safeguard it removes: your call, not ours.',
+  ].join('\n');
+}
+
+export async function install(argv = process.argv.slice(2), env = process.env) {
+  const stray = argv.find(item => !item.startsWith('-') && argv[argv.indexOf(item) - 1] !== '--harness');
+  if (stray) throw new Error(`usage: sidevoice install [--harness claude|codex]\n` +
+    `Pairing is not part of installing: a conversation asks for the room's code the first time it joins, ` +
+    `or run  sidevoice pair <room-url> <code>  with the code the room shows under "Emparejar conector".`);
+  const wanted = flag(argv, '--harness');
+  const harnesses = wanted ? [wanted] : harnessesPresent(env);
+  const done = [], next = [];
+
+  done.push(`Sidevoice ${VERSION}.`);
+  if (harnesses.includes('claude')) {
+    registerWithClaude(done, env);
+    const outcome = installSkill(skillsDir([], env));
+    done.push(`Skill ${outcome.action} at ${outcome.target}.`);
+  }
+
+  const paired = pairedRoom(env);
+  done.push(paired ? `This machine is paired with ${paired.origin} (connector ${paired.connector_id}).`
+                   : 'This machine is not paired with any room yet.');
+
+  if (harnesses.includes('claude')) {
+    next.push('In a conversation, run /voice-room to join the room.' +
+              (paired ? '' : ' The first time, the conversation asks you for the room\'s address and the one-time code the room shows under "Emparejar conector".'));
+    next.push('Sessions already open need a restart before they can see the skill.');
+    const warning = inboundWarning(env);
+    if (warning) next.push(warning);
+  }
+  if (harnesses.includes('codex')) next.push(codexInstructions(env));
+  if (!harnesses.length) next.push('No harness found on this machine. Pass --harness claude or --harness codex.');
+  return { done, next };
+}
+
+if (process.env.SIDEVOICE_INSTALL_MAIN === '1') {
+  try {
+    const { done, next } = await install();
+    for (const line of done) console.log('· ' + line);
+    if (next.length) {
+      console.log('\nLeft for you:');
+      for (const line of next) console.log('\n' + line);
+    }
+  } catch (error) { console.error(error.message); process.exit(1); }
+}

package/mcp.mjs

@@ -9,6 +9,7 @@ import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { advertisedCapabilities, capabilityState, SUPPORTED } from './harness-contract.mjs';
 import { harnessFor, identifyHarness } from './harnesses.mjs';
+import { pair, pairedRoom } from './pair.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');
@@ -16,14 +17,15 @@ const connectorPath = fileURLToPath(new URL('./connector.mjs', import.meta.url))
 
 const INSTRUCTIONS = `Sidevoice connects this conversation to the user's voice room.
 - Call voice_connect only when the user asks to join the voice room or enable voice for this conversation; never as a side effect.
-- Voice input arrives as a user message that starts with a JSON header ({"channel":"voice","session_id":...,"revision":...,"message_id":...}) followed by the user's literal words. Treat the header as opaque reply metadata; if the same message_id arrives twice, it is a redelivery: do not act on it again.
+- Voice input arrives as a user message that starts with a JSON header ({"channel":"voice","session_id":...,"revision":...,"message_id":...}) followed by the user's literal words, and ends with a line marked [Sidevoice] that is not the user's words: it asks you to acknowledge by voice first. Treat the header as opaque reply metadata; if the same message_id arrives twice, it is a redelivery: do not act on it again.
 - For substantive work, one incoming voice message may receive multiple voice_say publications: an immediate acknowledgement that states what was understood and the next action, meaningful progress checkpoints while work continues, and a final result. Use the same original session_id and revision for every publication, with distinct utterances; do not manufacture filler or narrate every tool call.
 - 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.
 - 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.
+- voice_status reports whether the room can currently reach this conversation, and which room this machine is paired with.
+- Pairing is the user's act, never yours. If voice_connect answers that this machine is not paired with the room (or is paired with a different one), ask the user for the room's address and the one-time pairing code the room shows them under "Emparejar conector" (it expires in ten minutes), then call voice_pair with both and voice_connect again. Never try to obtain a code from the room yourself, and do not offer to: the room only shows it to the person in it.
+- On Claude Code, /voice-room is a shortcut for the same joining steps. Read receipts and working state need nothing from you: the room learns them from what the harness records about this conversation.
 - 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.`;
 
 // ----- one persistent connection to the connector -----
@@ -69,14 +71,26 @@ async function rpc(method, params) {
 
 // ----- tools -----
 const tools = [
-  { name: 'voice_connect', description: 'Connect this conversation to the voice room. Only on an explicit request to join or enable voice.',
-    inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'Short label for this conversation in the room' } }, additionalProperties: false } },
+  { name: 'voice_connect', description: 'Connect this conversation to the voice room. Only on an explicit request to join or enable voice. Fails, saying what to ask the user, when this machine is not paired with the room.',
+    inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'Short label for this conversation in the room' }, room: { type: 'string', description: 'The room\'s address (https://…) when the user names one; omitted, the room this machine is paired with' } }, additionalProperties: false } },
+  { name: 'voice_pair', description: 'Pair this machine with a room using the one-time code the user read from the room\'s interface ("Emparejar conector"). Only with a code the user gave you; one room per machine, a new pairing replaces the previous one.',
+    inputSchema: { type: 'object', properties: { room: { type: 'string', description: 'The room\'s address (https://…)' }, code: { type: 'string', description: 'The one-time pairing code shown by the room' } }, required: ['room', 'code'], additionalProperties: false } },
   { name: 'voice_say', description: 'Publish a concise spoken version of your reply to the room, with the session_id and revision from the voice message header.',
     inputSchema: { type: 'object', properties: { text: { type: 'string' }, session_id: { type: 'string' }, revision: { type: 'integer', minimum: 0 }, utterance_id: { type: 'string' }, language: { type: 'string', enum: ['es', 'en', 'fr', 'it', 'pt', 'hi'] } }, required: ['text', 'session_id', 'revision'], additionalProperties: false } },
   { name: 'voice_disconnect', description: 'Leave the voice room. The conversation and its work continue in writing.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
   { name: 'voice_status', description: 'Whether the room can currently reach this conversation.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
 ];
 let binding = null;
+function originOf(room) {
+  try { return new URL(room).origin; } catch { throw new Error(`"${room}" is not a room address; expected something like https://voice.example`); }
+}
+/** Ask the user, do not guess: the code exists only on the room's screen. */
+function pairingNeeded(room, paired) {
+  const target = room ? originOf(room) : null;
+  if (!paired) return `This machine is not paired with ${target ? 'the room at ' + target : 'any room'}. Ask the user for the room's address${target ? ' (confirm ' + target + ')' : ''} and the one-time pairing code the room shows under "Emparejar conector", then call voice_pair with both. Do not fetch a code yourself.`;
+  if (target && target !== paired.origin) return `This machine is paired with ${paired.origin}, not ${target}. One room per machine: to switch, ask the user for the pairing code that ${target} shows under "Emparejar conector" and call voice_pair (it replaces the current pairing); to stay, call voice_connect without a room.`;
+  return null;
+}
 function inboundFor(harness, thread) {
   return capabilityState(harness, 'inspectInbound') === SUPPORTED ? harness.inspectInbound(thread) : null;
 }
@@ -88,12 +102,28 @@ async function invoke(name, args, meta) {
     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,
+    return { joined: !!binding, room: status.room || pairedRoom()?.origin || null, room_reachable: status.connected, room_error: status.room_error || null,
              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_pair') {
+    if (!args.room || !args.code) throw new Error('voice_pair needs the room\'s address and the code the user read from it.');
+    const previous = pairedRoom();
+    // The room shows the code in upper case and compares it that way; a dictated one arrives however it was heard.
+    const result = await pair(originOf(args.room), String(args.code).trim().toUpperCase());
+    // The connector that is up, if any, was started for the previous credential: let go of it so it can
+    // exit, and the next voice_connect starts one for this room. Other conversations still bound to the
+    // previous room keep that connector alive until they leave; they are not moved.
+    if (binding) { try { await rpc('unregister', { binding_id: binding.binding_id }); } catch {} binding = null; }
+    if (ipc) { ipc.end(); ipc = null; }
+    return { status: 'paired', room: result.origin, connector_id: result.connector_id,
+             ...(previous && previous.origin !== result.origin ? { replaced: previous.origin, note: 'Conversations on this machine still joined to the previous room keep it until they leave.' } : {}),
+             next: 'Call voice_connect to join.' };
+  }
   if (name === 'voice_connect') {
+    const needed = pairingNeeded(args.room, pairedRoom());
+    if (needed) { const error = new Error(needed); error.data = { pairing_needed: true, room: args.room ? originOf(args.room) : null }; throw error; }
     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
@@ -115,6 +145,7 @@ async function invoke(name, args, meta) {
              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') {
     let result;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidevoice/uplink",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",
@@ -12,6 +12,7 @@
   },
   "files": [
     "cli.mjs",
+    "install.mjs",
     "mcp.mjs",
     "connector.mjs",
     "harness-contract.mjs",
@@ -20,7 +21,6 @@
     "harness-codex.mjs",
     "harness-http.mjs",
     "pair.mjs",
-    "hook.mjs",
     "skill.mjs",
     "skill/",
     "README.md"

package/pair.mjs

@@ -1,21 +1,53 @@
 #!/usr/bin/env node
-/** One-time pairing: redeem the code shown by the room for this host's connector credential. */
+/** One-time pairing: redeem the code shown by the room for this host's connector credential.
+ *
+ *  The code is the room's to give and the person's to carry: the room shows it to whoever is in it
+ *  ("Emparejar conector"), and only that person can hand it to this machine. Nothing here asks the
+ *  room for one — a caller that could would turn "you can reach the address" into "you are in the room". */
 import os from 'node:os';
 import path from 'node:path';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 
-const [room, code] = process.argv.slice(2);
-if (!room || !code) { console.error('usage: pair.mjs <room-url> <pairing-code>'); process.exit(2); }
-const base = new URL(room);
-const response = await fetch(new URL('/api/connectors/pair', base), {
-  method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ code, host: os.hostname() }),
-  signal: AbortSignal.timeout(15_000),
-});
-const body = await response.json().catch(() => ({}));
-if (!response.ok) { console.error('Pairing failed: ' + (body.detail || response.status)); process.exit(1); }
-const ws = new URL('/api/connectors/ws', base); ws.protocol = base.protocol === 'https:' ? 'wss:' : 'ws:';
-const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
-mkdirSync(dataDir, { recursive: true, mode: 0o700 });
-const file = path.join(dataDir, 'credentials.json');
-writeFileSync(file, JSON.stringify({ url: ws.toString(), connector_id: body.connector_id, token: body.token, protocol: body.protocol }, null, 2), { mode: 0o600 });
-console.log(`Paired with ${base.origin} as connector ${body.connector_id}; credential saved to ${file}`);
+export function dataDir(env = process.env) {
+  return env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
+}
+
+/** The room's http(s) origin from the socket address the credential stores. */
+export function roomOrigin(wsUrl) {
+  const url = new URL(wsUrl); url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:'; return url.origin;
+}
+
+/** Which room this machine is paired with, or null. */
+export function pairedRoom(env = process.env) {
+  try {
+    const saved = JSON.parse(readFileSync(path.join(dataDir(env), 'credentials.json'), 'utf8'));
+    if (!saved.url || !saved.connector_id || !saved.token) return null;
+    return { origin: roomOrigin(saved.url), connector_id: saved.connector_id };
+  } catch { return null; }
+}
+
+/** Redeem a code for this host's credential. Returns where it was written. */
+export async function pair(room, code, env = process.env) {
+  const base = new URL(room);
+  const response = await fetch(new URL('/api/connectors/pair', base), {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ code, host: os.hostname() }), signal: AbortSignal.timeout(15_000),
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error('Pairing failed: ' + (body.detail || response.status));
+  const ws = new URL('/api/connectors/ws', base); ws.protocol = base.protocol === 'https:' ? 'wss:' : 'ws:';
+  const directory = dataDir(env);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, 'credentials.json');
+  writeFileSync(file, JSON.stringify({ url: ws.toString(), connector_id: body.connector_id, token: body.token, protocol: body.protocol }, null, 2), { mode: 0o600 });
+  return { file, connector_id: body.connector_id, origin: base.origin };
+}
+
+if (process.env.SIDEVOICE_PAIR_MAIN === '1') {
+  const [room, code] = process.argv.slice(2);
+  if (!room || !code) { console.error('usage: sidevoice pair <room-url> <pairing-code>   (the code is shown in the room under "Emparejar conector")'); process.exit(2); }
+  try {
+    const result = await pair(room, code);
+    console.log(`Paired with ${result.origin} as connector ${result.connector_id}; credential saved to ${result.file}`);
+  } catch (error) { console.error(error.message); process.exit(1); }
+}

package/skill/voice-room/SKILL.md

@@ -2,22 +2,6 @@
 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`
 ---
@@ -25,7 +9,8 @@ metadata:
 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.
+2. Call `voice_connect` with the title `$ARGUMENTS` when given, otherwise a short label of what this conversation is about. If the user named a room, pass its address as `room`.
+   If it fails saying this machine is not paired with the room (or is paired with a different one), ask the user for the room's address and the one-time code the room shows them under **Emparejar conector**; call `voice_pair` with both, then `voice_connect` again. Never try to get a code from the room yourself.
 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.
+Nothing else is registered: the room learns that a message was read and whether this conversation is working from what Claude Code itself records about the session. How to behave once joined is in the Sidevoice MCP server's own instructions.

package/skill.mjs

@@ -1,7 +1,7 @@
-/** `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';
+/** `sidevoice skill install|remove|status [--dir <skills dir>]`: the Claude Code skill that joins the room
+ *  (`/voice-room`). One file; running install again repairs it. A directory of the same name that is not
+ *  ours is never touched. */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -9,7 +9,6 @@ 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');
@@ -23,16 +22,17 @@ export function status(dir) {
   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')) };
+  return { state: ours ? 'installed' : 'foreign', target };
 }
 
 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));
+  writeFileSync(path.join(current.target, 'SKILL.md'), readFileSync(path.join(here, 'skill', SKILL_NAME, 'SKILL.md'), 'utf8'));
+  for (const stale of ['hook.mjs', 'harness-contract.mjs', 'harnesses.mjs', 'harness-claude.mjs', 'harness-codex.mjs', 'harness-http.mjs']) {
+    rmSync(path.join(current.target, stale), { force: true });   // an older copy carried a hook runtime; it is gone
+  }
   return { ...status(dir), action: current.state === 'installed' ? 'updated' : 'installed' };
 }
 
@@ -51,7 +51,7 @@ if (process.env.SIDEVOICE_SKILL_MAIN === '1') {
     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.');
+      console.log('In Claude Code, /voice-room joins the room for that conversation. New sessions see the skill; a session already open needs a restart.');
     }
   } catch (error) { console.error(error.message); process.exit(1); }
 }

package/hook.mjs

@@ -1,119 +0,0 @@
-#!/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));
-}