@sidevoice/uplink 0.4.2 → 0.4.3

package/README.md

@@ -3,8 +3,9 @@
 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.
+  version when an older one was registered) and removes a skill copy an earlier
+  version left. 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_pair`, `voice_say`, `voice_disconnect`, `voice_status`; carries the
   operational instructions in its `initialize` result. It never talks to the

package/cli.mjs

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

package/connector.mjs

@@ -5,8 +5,9 @@
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
-import { mkdirSync, openSync, closeSync, writeFileSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
+import { appendFileSync, mkdirSync, openSync, closeSync, statSync, writeFileSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
 import { capabilityState, SUPPORTED, voiceEnvelope } from './harness-contract.mjs';
 import { harnessFor } from './harnesses.mjs';
 import { privateNetwork } from './pair.mjs';
@@ -22,6 +23,21 @@ const outboxPath = path.join(dataDir, 'outbox.json');
 const credentialsPath = process.env.SIDEVOICE_CREDENTIALS || path.join(dataDir, 'credentials.json');
 const idleMs = Number(process.env.SIDEVOICE_CONNECTOR_IDLE_MS || 15_000);
 const hostId = process.env.SIDEVOICE_HOST_ID || os.hostname();
+const logPath = process.env.SIDEVOICE_CONNECTOR_LOG || path.join(dataDir, 'connector.log');
+const LOG_MAX = 1 << 20;
+
+/** One line per event, to stderr and to `connector.log` in the data dir: the façade starts this process
+ *  with its output discarded, so the file is the only record of a connector nobody ran by hand. Rolls
+ *  over once, at 1 MB. */
+function log(line) {
+  const stamped = `${new Date().toISOString()} [sidevoice] ${line}`;
+  console.error(stamped);
+  try {
+    let size = 0; try { size = statSync(logPath).size; } catch {}
+    if (size > LOG_MAX) renameSync(logPath, logPath + '.1');
+    appendFileSync(logPath, stamped + '\n', { mode: 0o600 });
+  } catch {}
+}
 
 function credentials() {
   let saved = {};
@@ -36,7 +52,16 @@ function credentials() {
   return { url, connector_id, token, room: room.origin };
 }
 
-function alive(pid) { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } }
+/** Whether the pid in the lock is a live Sidevoice connector — not merely a live pid. Pids are reused,
+ *  and on macOS a pid that now belongs to another user answers EPERM, which used to count as alive: a
+ *  stale lock then made every new connector exit at once, silently (a laptop, 2026-09-21). */
+function connectorAlive(pid) {
+  try { process.kill(pid, 0); } catch (error) { if (error.code !== 'EPERM') return false; }
+  try {
+    const args = execFileSync('ps', ['-o', 'args=', '-p', String(pid)], { encoding: 'utf8', timeout: 3000 }).trim();
+    return /(^|[\s/])connector(\.mjs)?(\s|$)/.test(args);   // `…/connector.mjs` from a checkout, `sidevoice connector` from a package; not test_connector.mjs
+  } catch { return true; }                          // No ps to ask: a live pid is taken at its word.
+}
 function acquireLock() {
   mkdirSync(dataDir, { recursive: true, mode: 0o700 });
   for (let attempt = 0; attempt < 2; attempt++) {
@@ -44,8 +69,12 @@ function acquireLock() {
     catch (error) {
       if (error.code !== 'EEXIST') throw error;
       let pid = 0; try { pid = Number(readFileSync(lockPath, 'utf8')); } catch {}
-      if (pid && alive(pid)) return false;          // A live connector holds it: we are redundant.
-      try { unlinkSync(lockPath); } catch {}         // Stale lock from a dead process.
+      if (pid && connectorAlive(pid)) {              // A live connector holds it: we are redundant, and we say so.
+        log(`a connector is already running (pid ${pid}, lock ${lockPath}); this one exits`);
+        return false;
+      }
+      log(`stale lock ${lockPath} (pid ${pid || '?'} is not a connector); taking over`);
+      try { unlinkSync(lockPath); } catch {}
     }
   }
   return false;
@@ -59,6 +88,7 @@ const closedByRoom = new Map();    // client_ref -> reason: the user closed that
 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 socketError = null;            // why the last attempt to reach the room failed, for whoever asks status
 let creds;
 
 function loadOutbox() { try { outbox = JSON.parse(readFileSync(outboxPath, 'utf8')); if (!Array.isArray(outbox)) outbox = []; } catch { outbox = []; } }
@@ -114,7 +144,7 @@ function watch(binding) {
       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}`);
+        log(`${binding.thread} read ${header.message_id} (session ${header.session_id} rev ${header.revision}, turn ${turn_id || '?'})`);
       }
       if (header.channel !== 'voice') return;
       binding.turn = { turn_id: turn_id || null, session_id: header.session_id, revision: header.revision };
@@ -143,22 +173,25 @@ function open() {
     send({ type: 'connector.hello', protocol: PROTOCOL, connector_id: creds.connector_id, token: creds.token, host: hostId });
   });
   socket.addEventListener('message', event => { receive(JSON.parse(String(event.data))).catch(error => send({ type: 'connector.error', error: error.message })); });
-  const lost = () => { if (ws === socket) { ws = null; connected = false; } reconnect(); };
+  const lost = why => { if (ws === socket) { ws = null; connected = false; } if (why) { socketError = { ...why, at: new Date().toISOString(), attempt: reconnectAttempt }; log('room unreachable: ' + JSON.stringify(why)); } reconnect(); };
   // A refused connection surfaces as 'error' with no 'close', and the dead socket stays
-  // CONNECTING forever: forget it, or open() would never make another one.
-  socket.addEventListener('close', lost);
-  socket.addEventListener('error', lost);
+  // CONNECTING forever: forget it, or open() would never make another one. Whatever the runtime
+  // says about it is kept: "not reachable" alone told a person nothing (2026-09-21).
+  socket.addEventListener('close', event => lost(connected ? null : { close_code: event.code, reason: event.reason || null }));
+  socket.addEventListener('error', event => lost({ error: event.error?.message || event.message || 'connection failed' }));
 }
 function reconnect() {
   if (closed || reconnectTimer) return;
   const delay = Math.min(10_000, 250 * 2 ** Math.min(reconnectAttempt++, 6));
+  if (reconnectAttempt <= 3 || reconnectAttempt % 10 === 0) log(`room not connected; retrying in ${delay} ms (attempt ${reconnectAttempt})`);
   reconnectTimer = setTimeout(() => { reconnectTimer = null; open(); }, delay);
 }
 
 async function receive(frame) {
   switch (frame.type) {
     case 'connector.welcome':
-      connected = true; reconnectAttempt = 0; lastError = null;
+      connected = true; reconnectAttempt = 0; lastError = null; socketError = null;
+      log(`connected to ${creds.room} as ${creds.connector_id} (protocol ${frame.protocol ?? PROTOCOL}); ${bindings.size} binding(s) to re-register, ${outbox.length} queued speech`);
       for (const binding of bindings.values()) {
         // `local-*` is only a connector-side placeholder while the first
         // registration waits for the room to mint its durable binding id.
@@ -176,10 +209,12 @@ async function receive(frame) {
       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);
+      if (binding) log(`room registered ${binding.thread} as ${frame.binding_id} ("${binding.title || ''}")`);
       registering.get(frame.client_ref)?.resolve(frame); return;
     }
-    case 'binding.rejected': registering.get(frame.client_ref)?.reject(new Error(frame.error || 'Binding rejected')); return;
+    case 'binding.rejected': log(`room rejected ${frame.client_ref}: ${frame.error || 'no reason'}`); registering.get(frame.client_ref)?.reject(new Error(frame.error || 'Binding rejected')); return;
     case 'speech.published': {
+      log(`speech ${frame.utterance_id || frame.event_id} ${frame.status || 'published'}${frame.reason ? ' (' + frame.reason + ')' : ''}`);
       outbox = outbox.filter(speech => speech.event_id !== frame.event_id); saveOutbox();
       publishing.get(frame.event_id)?.resolve(frame); return;
     }
@@ -198,11 +233,11 @@ async function receive(frame) {
         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})`);
+          log(`delivered ${frame.event_id} (${frame.message_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}`);
+          log(`delivery of ${frame.event_id} to ${binding.thread} failed: ${error.message}`);
           send({ type: 'input.ack', event_id: frame.event_id, status: 'failed', error: String(error.message || error).slice(0, 400) });
         }
       });
@@ -214,23 +249,24 @@ async function receive(frame) {
       if (!binding) return;
       bindings.delete(binding.binding_id); binding.owner?.bindings.delete(binding); unwatch(binding);
       closedByRoom.set(binding.client_ref, frame.reason || 'closed_from_room');
-      console.error(`[sidevoice] room closed voice for ${binding.thread}`);
+      log(`room closed voice for ${binding.thread} (${frame.reason || 'closed_from_room'})`);
       scheduleExit(); return;
     }
-    case 'connector.error': lastError = frame.error; console.error('[sidevoice] room: ' + frame.error); return;
+    case 'connector.error': lastError = frame.error; log('room says: ' + frame.error); return;
   }
 }
 
 function snapshot() {
-  return { host: hostId, version: VERSION, room: creds.room, connected, protocol: PROTOCOL, outbox: outbox.length, room_error: lastError, closed_by_room: [...closedByRoom.keys()],
+  return { host: hostId, version: VERSION, room: creds.room, connected, protocol: PROTOCOL, outbox: outbox.length, room_error: lastError, socket_error: socketError, 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);
-  idleTimer = setTimeout(() => { if (clients.size === 0 && bindings.size === 0) shutdown(); }, idleMs);
+  idleTimer = setTimeout(() => { if (clients.size === 0 && bindings.size === 0) { log(`idle for ${idleMs} ms with no conversation; exiting`); shutdown(); } }, idleMs);
 }
 function shutdown() {
+  if (!closed) log(`shutting down (${bindings.size} binding(s), ${clients.size} façade(s))`);
   closed = true; clearTimeout(reconnectTimer); clearTimeout(idleTimer);
   try { ws?.close(); } catch {}
   server.close();
@@ -252,6 +288,7 @@ async function command(client, input) {
         return { binding_id: existing.binding_id, thread, connected };
       }
       const local_id = 'local-' + randomUUID();
+      log(`${harness} ${thread} joins ("${title || ''}", delivery ${delivery.kind}, inbound ${inbound ? (inbound.ok ? 'ok' : 'held') : 'n/a'})`);
       const binding = { binding_id: local_id, client_ref, harness, thread, title, delivery, inbound, capabilities, owner: client };
       bindings.set(local_id, binding); client.bindings.add(binding); clearTimeout(idleTimer); open(); watch(binding);
       const frame = await new Promise((resolve, reject) => {
@@ -278,7 +315,7 @@ async function command(client, input) {
     }
     case 'unregister': {
       const binding = bindings.get(params.binding_id);
-      if (binding) { bindings.delete(binding.binding_id); binding.owner?.bindings.delete(binding); unwatch(binding); if (!binding.binding_id.startsWith('local-')) send({ type: 'binding.unregister', binding_id: binding.binding_id }); }
+      if (binding) { log(`${binding.thread} leaves`); 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();
@@ -289,6 +326,7 @@ async function command(client, input) {
 function serve(socket) {
   const client = { socket, bindings: new Set() };
   clients.add(client); clearTimeout(idleTimer);
+  log(`façade attached (${clients.size} now)`);
   let buffer = '';
   socket.on('data', chunk => {
     buffer += chunk;
@@ -305,6 +343,7 @@ function serve(socket) {
   socket.on('error', () => {});
   socket.on('close', () => {
     clients.delete(client);
+    log(`façade detached (${clients.size} left); dropping ${client.bindings.size} binding(s)`);
     // The façade is gone: so is every conversation it spoke for.
     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();
@@ -313,7 +352,9 @@ function serve(socket) {
 
 creds = credentials();
 if (!acquireLock()) process.exit(0);
+log(`connector ${VERSION} starting: pid ${process.pid}, host ${hostId}, room ${creds.room}, socket ${socketPath}, log ${logPath}`);
 loadOutbox();
+if (outbox.length) log(`${outbox.length} speech frame(s) waiting in the outbox`);
 try { unlinkSync(socketPath); } catch {}
 const server = net.createServer(serve);
 await new Promise((resolve, reject) => server.once('error', reject).listen(socketPath, resolve));

package/harness-contract.mjs

@@ -55,11 +55,11 @@ export function envelope(event) {
   return JSON.stringify(header) + '\n\n' + event.text + note;
 }
 
-/** What the conversation is asked at the moment it reads a voice message. */
+/** What the conversation is asked at the moment it reads a voice message: one line that points at the
+ *  server's instructions, which are already in context — not a copy of them. The harness adds its own
+ *  wrapper around a cross-session message; ours stays small. */
 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.';
+  return `[Sidevoice] Voice from the room: acknowledge with voice_say (session_id "${header.session_id}", revision ${header.revision}) before any other tool, then work and reply by voice, as the sidevoice server's instructions say.`;
 }
 
 /** The header at the front of a delivered message, or null when the text is not one of ours. Works on

package/install.mjs

@@ -16,7 +16,7 @@ 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';
+import { remove as removeSkill, skillsDir, status as skillStatus } from './skill.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(path.join(here, 'package.json'), 'utf8')).version;
@@ -175,8 +175,8 @@ export async function install(argv = process.argv.slice(2), env = process.env) {
   if (copy.action === 'copied') done.push(`Copied this version to ${copy.target}${copy.removed.length ? ` (removed: ${copy.removed.join(', ')})` : ''}.`);
   if (harnesses.includes('claude')) {
     registerWithClaude(done, env);
-    const outcome = installSkill(skillsDir([], env));
-    done.push(`Skill ${outcome.action} at ${outcome.target}.`);
+    // The join shortcut is a prompt the server offers; a skill copy from an earlier version is taken away.
+    if (skillStatus(skillsDir([], env)).state === 'installed') done.push(`Removed the voice-room skill copy at ${removeSkill(skillsDir([], env)).target}: the server offers it as the prompt /mcp__sidevoice__voice-room.`);
   }
 
   const paired = pairedRoom(env);
@@ -189,9 +189,9 @@ export async function install(argv = process.argv.slice(2), env = process.env) {
   }
 
   if (harnesses.includes('claude')) {
-    next.push('In a conversation, run /voice-room to join the room.' +
+    next.push('In a conversation, ask to join the voice room (or run /mcp__sidevoice__voice-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.');
+    next.push('Sessions already open need a restart before they see the server.');
     const warning = inboundWarning(env);
     if (warning) next.push(warning);
   }
@@ -200,6 +200,50 @@ export async function install(argv = process.argv.slice(2), env = process.env) {
   return { done, next };
 }
 
+/** `sidevoice uninstall`: the reverse of install, for this machine. Unregisters the MCP server from Claude
+ *  Code, stops the connector, removes the installed copies, the skill copy an older version left, and the
+ *  pairing credential. The room keeps this machine's pairing until it is revoked from the room's page —
+ *  say so. Codex's machine-wide file is, as always, printed and not touched. */
+export async function uninstall(argv = process.argv.slice(2), env = process.env) {
+  const wanted = flag(argv, '--harness');
+  const harnesses = wanted ? [wanted] : harnessesPresent(env);
+  const done = [], next = [];
+  if (harnesses.includes('claude')) {
+    const current = claudeRegistration(env);
+    if (current?.scope === 'user') {
+      try { claude(['mcp', 'remove', '--scope', 'user', 'sidevoice'], env); done.push('Unregistered the MCP server from Claude Code.'); }
+      catch (error) { done.push(`Could not unregister from Claude Code (${(error.message || '').split('\n')[0]}). Run:\n    claude mcp remove --scope user sidevoice`); }
+    } else if (current) {
+      next.push(`Claude Code has a sidevoice MCP server registered outside user scope (${current.line}); remove it where it was added.`);
+    } else done.push('Claude Code had no sidevoice MCP server registered.');
+    if (skillStatus(skillsDir([], env)).state === 'installed') done.push(`Removed the voice-room skill copy at ${removeSkill(skillsDir([], env)).target}.`);
+  }
+  const running = await runningConnector(env);
+  if (running?.pid) {
+    try { process.kill(running.pid, 'SIGTERM'); done.push(`Stopped the connector (pid ${running.pid}${running.version ? ', version ' + running.version : ''}).`); }
+    catch (error) { next.push(`A connector is running (pid ${running.pid}) and could not be stopped (${error.code || error.message}); stop it yourself.`); }
+  }
+  if (!fromSource(env) && existsSync(copiesDir(env))) { rmSync(copiesDir(env), { recursive: true, force: true }); done.push(`Removed the installed copies under ${copiesDir(env)}.`); }
+  const dataDir = env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.sidevoice');
+  const paired = pairedRoom(env);
+  if (existsSync(dataDir)) {
+    rmSync(dataDir, { recursive: true, force: true });
+    done.push(`Removed ${dataDir} (credential, socket, outbox, log).`);
+    if (paired) next.push(`The room at ${paired.origin} still lists this machine as paired (connector ${paired.connector_id}) until you revoke it from the room's page.`);
+  }
+  if (harnesses.includes('codex')) next.push(`Remove the [mcp_servers.sidevoice] table from ${env.CODEX_HOME || path.join(os.homedir(), '.codex')}/config.toml — it is machine-wide and this package does not rewrite it.`);
+  next.push('Sessions already open keep their MCP server until they end.');
+  return { done, next };
+}
+
+if (process.env.SIDEVOICE_UNINSTALL_MAIN === '1') {
+  try {
+    const { done, next } = await uninstall();
+    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); }
+}
+
 if (process.env.SIDEVOICE_INSTALL_MAIN === '1') {
   try {
     const { done, next } = await install();

package/mcp.mjs

@@ -18,18 +18,17 @@ const dataDir = process.env.SIDEVOICE_DATA_DIR || path.join(os.homedir(), '.side
 const socketPath = process.env.SIDEVOICE_CONNECTOR_SOCKET || path.join(dataDir, 'connector.sock');
 const connectorPath = fileURLToPath(new URL('./connector.mjs', import.meta.url));
 
+// Claude Code keeps at most 2048 characters of these; the rest is cut (measured 2026-09-21).
 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, 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, 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.`;
+- Call voice_connect only when the user asks to join the room or enable voice; never as a side effect.
+- Voice input is a user message: a JSON header ({"channel":"voice","session_id","revision","message_id"}), the user's literal words, then a [Sidevoice] line that is not the user's. The header is opaque reply metadata. A repeated message_id is a redelivery: do not act on it again.
+- Reply by voice with voice_say, using that message's session_id and revision for every publication. For substantive work: first a short acknowledgement (what you understood, what you will do next), then meaningful checkpoints, then the result. No filler, no narrating tool calls. Publish questions too, and wait.
+- Between steps, at each tool result, take in newly arrived user input before starting the next step: an addition, a refinement or a replacement, by its meaning. Drop obsolete work not yet started; keep what remains useful; say what you now understand. No artificial pauses.
+- "published" means the room stored it, not that the user heard it. If publishing fails, continue in writing.
+- If the user closes this conversation's voice from the room, voice_say fails saying so: continue in writing, do not retry, and call voice_connect again only if asked.
+- Pairing is the user's act. If voice_connect says this machine is not paired with the room, ask the user for the room's address and the one-time code the room shows under "Emparejar conector", then call voice_pair and voice_connect again. Never try to obtain a code from the room yourself.
+- If voice_connect returns inbound.ok false, voice will look sent and never arrive: tell the user inbound.reason, offer inbound.remedy in your own words including the safeguard the machine-wide option removes, and change no settings unasked.
+- Read receipts and working state need nothing from you: the room observes what the harness records.`;
 
 // ----- one persistent connection to the connector -----
 let ipc = null, ipcBuffer = '', ipcSerial = 0;
@@ -83,6 +82,26 @@ const tools = [
   { 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 } },
 ];
+/** The joining steps as a prompt: what the voice-room skill used to be, now carried by the server itself so
+ *  nothing is copied into any harness and the steps move with the version. */
+const PROMPTS = [{
+  name: 'voice-room',
+  description: 'Join the user\'s Sidevoice voice room with this conversation.',
+  arguments: [{ name: 'title', description: 'Title for this conversation in the room', required: false }],
+}];
+function promptText(args = {}) {
+  const title = (args.title || '').trim();
+  return [
+    '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 ${title ? JSON.stringify(title) : '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.',
+    '',
+    'Nothing else is registered: the room learns that a message was read and whether this conversation is working from what the harness itself records about it. How to behave once joined is in this server\'s instructions.',
+  ].join('\n');
+}
 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`); }
@@ -110,7 +129,7 @@ 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: status.room || pairedRoom()?.origin || null, 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, socket_error: status.socket_error || null,
              version: VERSION, connector_version: status.version || null, ...versionNote(status.version),
              binding_id: binding?.binding_id || null, harness: binding?.harness || null,
              capabilities: binding?.capabilities || null, inbound,
@@ -186,7 +205,12 @@ process.stdin.on('data', async chunk => {
     if (request.id === undefined) continue; // notifications need no answer
     let result, error;
     try {
-      if (request.method === 'initialize') result = { protocolVersion: request.params?.protocolVersion || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'sidevoice', version: VERSION }, instructions: INSTRUCTIONS };
+      if (request.method === 'initialize') result = { protocolVersion: request.params?.protocolVersion || '2025-06-18', capabilities: { tools: {}, prompts: {} }, serverInfo: { name: 'sidevoice', version: VERSION }, instructions: INSTRUCTIONS };
+      else if (request.method === 'prompts/list') result = { prompts: PROMPTS };
+      else if (request.method === 'prompts/get') {
+        if (request.params?.name !== 'voice-room') throw Object.assign(new Error('Unknown prompt'), { code: -32602 });
+        result = { description: PROMPTS[0].description, messages: [{ role: 'user', content: { type: 'text', text: promptText(request.params?.arguments) } }] };
+      }
       else if (request.method === 'tools/list') result = { tools };
       else if (request.method === 'tools/call') { const value = await invoke(request.params.name, request.params.arguments || {}, request.params._meta); result = { content: [{ type: 'text', text: JSON.stringify(value) }] }; }
       else if (request.method === 'ping') result = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidevoice/uplink",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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",
@@ -22,7 +22,6 @@
     "harness-http.mjs",
     "pair.mjs",
     "skill.mjs",
-    "skill/",
     "README.md"
   ],
   "scripts": {

package/skill.mjs

@@ -1,12 +1,10 @@
-/** `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';
+/** `sidevoice skill remove|status [--dir <skills dir>]`: the voice-room skill is no longer installed — the
+ *  server carries the same steps as an MCP prompt — but copies from earlier versions are still on disk, and
+ *  this takes ours away. A directory of the same name that is not ours is never touched. */
+import { existsSync, readFileSync, rmSync } 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';
 
@@ -25,17 +23,6 @@ export function status(dir) {
   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 });
-  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' };
-}
-
 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.`);
@@ -47,11 +34,8 @@ 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); }
+    const result = command === 'remove' ? remove(dir) : command === 'status' ? status(dir) : null;
+    if (!result) { console.error('usage: sidevoice skill <remove|status> [--dir <skills dir>]   (the skill is no longer installed: the MCP server offers the voice-room prompt)'); 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. New sessions see the skill; a session already open needs a restart.');
-    }
   } catch (error) { console.error(error.message); process.exit(1); }
 }

package/skill/voice-room/SKILL.md

@@ -1,16 +0,0 @@
----
-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]"
-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. 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.
-
-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.