@agfpd/voicetalk-runtime 0.1.0 → 0.2.0

package/src/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// voicetalk-runtime — the voice presence-runtime router (Фаза 2: text caркас).
+// voicetalk-runtime — the voice presence-runtime router (Фаза 3: live voice pipeline).
 //
 // voicetalk is the third *-runtime after telegram and notifier: it makes the host's
 // microphone + speaker one more runtime through which the OWNER (a human, natural peer)
@@ -8,18 +8,19 @@
 // both directions through its stdio + a local inbound channel:
 //
 //   • OUTBOUND (fleet → owner): the supervisor writes <iap>…</iap> envelopes to this
-//     process's STDIN; the reader parses each and hands it to the AudioSink — which in
-//     Фаза 3 is TTS → the owner's speaker, and in Фаза 2 is a STUB that logs the spoken
-//     text (and appends it to spoken.log) so the path is exercised without audio.
-//   • INBOUND (owner → fleet): in Фаза 3 the mic + wake-word + STT turn the owner's
-//     speech into an utterance; in Фаза 2 that audio source is STUBBED by a local unix
-//     socket (the `say` subcommand is the mic+STT stand-in). Either way the utterance is
-//     framed for the spoken modality and delivered to the target peer through the daemon
-//     (`iapeer send`) FROM the owner's identity (PEER_RUNTIME=voicetalk).
+//     process's STDIN; the reader parses each and hands it to the AudioSink — TTS through
+//     voice-connect onto the owner's speaker (and a spoken.log line, always).
+//   • INBOUND (owner → fleet): the microphone runs always-on; endpointing cuts utterances,
+//     voice-connect transcribes them, and an utterance that opens by addressing a fleet
+//     peer («Борис, привет») is framed for the spoken modality and delivered to that peer
+//     through the daemon (`iapeer send`) FROM the owner's identity (PEER_RUNTIME=voicetalk).
+//     The `say` subcommand injects an utterance over the local socket without the mic —
+//     the Фаза-2 stand-in, kept as the debugging seam and the automated E2E's inbound.
 //
-// Speech ↔ text is NOT in this package — STT/TTS live in the shared voice-connect service
-// (a pure HTTP backend this runtime will CONSUME in Фаза 3). The two audio touchpoints
-// here (AudioSink + the socket inbound source) are the seams voice-connect plugs into.
+// Speech ↔ text is NOT in this package — STT/TTS live in the shared voice-connect service,
+// a pure HTTP backend this runtime CONSUMES (src/voiceConnect.ts is the only door to it).
+// Host audio mechanics (capture, endpointing, playback) are in src/audio.ts; turn-taking
+// and the address book in src/voiceSession.ts + src/wake.ts.
 //
 // NO sender-guard (decision: «Sender-guard: NO for the MVP»): the speaker is a single
 // local endpoint of the owner, so any fleet peer may answer by voice — there is no
@@ -41,8 +42,17 @@ import { randomUUID } from 'crypto'
 import { spawn } from 'child_process'
 import { BIN_NAME, IAPEER_DIR, NAME_RE, PACKAGE_NAME, PEER_PROFILE_FILE, RUNTIME, VERSION } from './constants.ts'
 import { selfInstall } from './selfInstall.ts'
-import { runSelfConfig } from './selfConfig.ts'
+import { parseWakeWords, runSelfConfig } from './selfConfig.ts'
 import { writeJsonAtomic } from './fsAtomic.ts'
+import { VoiceSession } from './voiceSession.ts'
+import { voiceHealth } from './voiceConnect.ts'
+import { listInputDevices, resolveInputDevice } from './audio.ts'
+import { buildAddressBook, unresolvedWakeWords, wakeEntries, type VoicetalkBinding } from './wake.ts'
+
+// Фаза 3: the audio half is LIVE by default (mic + wake-word + STT inbound, TTS outbound).
+// VOICETALK_AUDIO=0 falls back to the Фаза-2 text carcass — no microphone, no speaker —
+// which is what the automated E2E and any headless host run on.
+const VOICETALK_AUDIO_ENABLED = process.env.VOICETALK_AUDIO !== '0'
 
 // Inbound (owner → fleet) delivery is synchronous from the speaker's point of view: if
 // the core router refuses the send (ok=false/err) or our local waiter times out, the
@@ -73,6 +83,20 @@ function isIntelligence(value: unknown): value is Intelligence {
   return value === 'natural' || value === 'artificial' || value === 'absent'
 }
 
+// Read-compat map for legacy intelligence values coming off the wire (mirrors the core
+// codec's normalizeIntelligenceValue): human → natural · scripted → absent. A genuinely
+// unknown value is dropped, not invented.
+const LEGACY_INTELLIGENCE: Readonly<Record<string, Intelligence>> = {
+  human: 'natural',
+  scripted: 'absent',
+}
+
+function normalizeIntelligenceValue(value: unknown): Intelligence | undefined {
+  if (typeof value !== 'string') return undefined
+  if (isIntelligence(value)) return value
+  return LEGACY_INTELLIGENCE[value]
+}
+
 const HUMAN_RUNTIMES = new Set(['telegram', 'voicetalk', 'discord', 'matrix', 'email', 'web'])
 const SCRIPTED_RUNTIMES = new Set(['webhook', 'api', 'cron'])
 
@@ -82,12 +106,12 @@ function defaultIntelligenceForRuntime(runtime: string): Intelligence {
   return 'artificial'
 }
 
-/** The voicetalk peer binding (narrowed schema, design dialog 21.06). STT/TTS/voice
- *  config is DELIBERATELY absent — it lives in voice-connect, not the passport. */
-type VoicetalkInterface = {
-  wake_word?: string
-  device?: string
-}
+/** The voicetalk peer binding. STT/TTS/voice config is DELIBERATELY absent — it lives in
+ *  voice-connect, not the passport (design dialog 21.06). Фаза 3 evolves the single
+ *  `wake_word` into the HYBRID wake map (22.07): a curated «word → target peer» set plus
+ *  a default agent for the neutral word. `wake_word` stays readable as the legacy
+ *  single-word form, so an already-provisioned peer keeps working untouched. */
+type VoicetalkInterface = VoicetalkBinding
 
 type PeerProfile = {
   personality: string
@@ -105,6 +129,9 @@ type IapEnvelope = {
   fromPersonality: string
   fromRuntime: string
   fromIntelligence?: Intelligence
+  /** Sender's dispatch instant (`ts` attribute, envelope-compaction F, core 0.4.86) —
+   *  full local ISO on the wire; absent on legacy envelopes. */
+  sentAt?: string
   topic?: string
   attachments: string[]
   message: string
@@ -136,10 +163,12 @@ function usage(): string {
   ${BIN_NAME}                                   # self-install (npx contract): bin on PATH + manifest
   ${BIN_NAME} self-install                      # explicit self-install (idempotent)
   ${BIN_NAME} self-config                       # per-peer self-config hook (foundation-invoked)
-  ${BIN_NAME} interface --wake-word <w> [--device <d>]   # set this peer's voicetalk binding
-  ${BIN_NAME} run                               # router loop (Фаза 2: text caркас, audio stubbed)
-  ${BIN_NAME} say --peer <personality> <text…>  # inject an utterance (Фаза-2 mic+STT stand-in)
-  ${BIN_NAME} doctor [--json]                   # health: binding + manifest
+  ${BIN_NAME} interface --wake-words «дарвин=darwin,борис=boris» [--default-target <peer>] [--device <d>]
+                                                # set this peer's voicetalk binding (wake map)
+  ${BIN_NAME} run                               # router loop: live mic ↔ speaker (VOICETALK_AUDIO=0 → text only)
+  ${BIN_NAME} say --peer <personality> <text…>  # inject an utterance without the mic (debug seam)
+  ${BIN_NAME} devices [--json]                  # list audio input devices (for --device)
+  ${BIN_NAME} doctor [--json]                   # health: binding, manifest, voice-connect, mic
   ${BIN_NAME} --version
   ${BIN_NAME} --help`
 }
@@ -230,6 +259,15 @@ function logEvt(evt: string, fields: Record<string, unknown>): void {
   process.stderr.write(`${BIN_NAME} ${JSON.stringify({ ts: nowIso(), evt, ...fields })}\n`)
 }
 
+/** Is an executable resolvable on PATH? (`doctor`'s host-tooling probe.) */
+function hasBinary(bin: string): Promise<boolean> {
+  return new Promise(resolve => {
+    const child = spawn('command', ['-v', bin], { stdio: 'ignore', shell: true })
+    child.on('error', () => resolve(false))
+    child.on('close', code => resolve(code === 0))
+  })
+}
+
 function oneLine(text: string, max = 200): string {
   const flat = text.replace(/\s+/g, ' ').trim()
   return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat
@@ -359,6 +397,8 @@ function setVoicetalkInterface(cwd: string, patch: VoicetalkInterface): Record<s
       ? { ...((interfaces as { voicetalk: Record<string, unknown> }).voicetalk) }
       : {}
   if (patch.wake_word !== undefined) voicetalk.wake_word = patch.wake_word
+  if (patch.wake_words !== undefined) voicetalk.wake_words = patch.wake_words
+  if (patch.default_target !== undefined) voicetalk.default_target = patch.default_target
   if (patch.device !== undefined) voicetalk.device = patch.device
   ;(interfaces as Record<string, unknown>).voicetalk = voicetalk
   const merged = { ...raw, interfaces }
@@ -367,80 +407,111 @@ function setVoicetalkInterface(cwd: string, patch: VoicetalkInterface): Record<s
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// IAP envelope parsing (CDATA-aware) — mirrors the foundation codec / telegram-runtime
+// IAP envelope parsing — port of the foundation codec (iapeer src/codec/index.ts,
+// envelope-compaction F, 0.4.86): CDATA-aware on BOTH tag sides (В37), В38
+// false-start resync, READ-BOTH attr/tag names (legacy wire + compact
+// presentation) and the additive `ts` attribute.
 // ─────────────────────────────────────────────────────────────────────────────
 
 function unescapeAttr(value: string): string {
+  // Reverse of the encoder's escapeAttr. Order matters: &amp; LAST so an escaped
+  // "&amp;lt;" in the source does not get double-decoded.
   return value.replace(/&quot;/g, '"').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
 }
 
+/** NAME-ANCHORED attribute lookup. The anchor `(?:^|\s)` is load-bearing: an unanchored
+ *  regex lets `runtime="` match the TAIL of `from-runtime="…"` (and `intelligence="` the
+ *  tail of `from-intelligence="…"`) — coincidentally right under today's attr order, a
+ *  mine under read-both (the short-name lookup must NOT be satisfied by a legacy long
+ *  name, or the fromRuntime modality cue reads the wrong value). */
 function attrValue(attrs: string, name: string): string | undefined {
-  const m = new RegExp(`${name}="([^"]*)"`).exec(attrs)
+  const m = new RegExp(`(?:^|\\s)${name}="([^"]*)"`).exec(attrs)
   return m ? unescapeAttr(m[1]) : undefined
 }
 
-function decodeCdata(inner: string): string {
-  if (!inner.startsWith('<![CDATA[') || !inner.endsWith(']]>')) return inner
-  return inner.slice('<![CDATA['.length, -']]>'.length).replaceAll(']]]]><![CDATA[>', ']]>')
-}
-
-/** Find `needle` at/after `from`, ignoring any occurrence INSIDE a <![CDATA[ … ]]>
- *  section, so a message body that literally contains "</message>"/"</iap>" never
- *  truncates the envelope. With no CDATA present this behaves exactly like indexOf. */
-function indexOfOutsideCdata(s: string, needle: string, from = 0): number {
-  let i = from
-  let inCdata = false
-  while (i < s.length) {
-    if (inCdata) {
-      if (s.startsWith(']]>', i)) {
-        inCdata = false
-        i += 3
-        continue
-      }
-      i++
-      continue
-    }
-    if (s.startsWith('<![CDATA[', i)) {
-      inCdata = true
-      i += '<![CDATA['.length
+const CDATA_OPEN = '<![CDATA['
+const CDATA_CLOSE = ']]>'
+
+/** Find `needle` at/after `start`, skipping CDATA sections WHOLESALE — `]]>` inside a
+ *  section is its terminator, never a match — so a message body literally containing
+ *  "</message>"/"</iap>" never truncates the envelope. Returns -1 when not found OR when
+ *  an unterminated CDATA section is hit (incomplete buffer → the caller waits). */
+function indexOfOutsideCdata(buffer: string, needle: string, start = 0): number {
+  let i = start
+  while (i < buffer.length) {
+    if (buffer.startsWith(CDATA_OPEN, i)) {
+      const term = buffer.indexOf(CDATA_CLOSE, i + CDATA_OPEN.length)
+      if (term < 0) return -1 // unterminated CDATA → incomplete buffer
+      i = term + CDATA_CLOSE.length
       continue
     }
-    if (s.startsWith(needle, i)) return i
+    if (buffer.startsWith(needle, i)) return i
     i++
   }
   return -1
 }
 
+/** Extract and decode the content of `<tag>…</tag>`, treating the body as a sequence of
+ *  CDATA sections (and any stray raw text) and CONCATENATING them — which both ignores
+ *  quoted `</tag>`/`</iap>` inside CDATA and reverses the encoder's
+ *  `]]>` → `]]]]><![CDATA[>` split. В37: the OPEN tag is located CDATA-aware too (the
+ *  close side already was) — a message whose CDATA body QUOTES `<attachments>…</attachments>`
+ *  otherwise mints phantom attachments, and a quoted `<message>` hijacks the real body;
+ *  for this runtime the corrupted text would go straight to TTS. */
 function tagContent(xml: string, tag: string): string | undefined {
   const open = `<${tag}>`
-  const start = xml.indexOf(open)
-  if (start < 0) return undefined
-  const innerStart = start + open.length
-  const end = indexOfOutsideCdata(xml, `</${tag}>`, innerStart)
-  if (end < 0) return undefined
-  return decodeCdata(xml.slice(innerStart, end))
+  const close = `</${tag}>`
+  const openIdx = indexOfOutsideCdata(xml, open, 0)
+  if (openIdx < 0) return undefined
+  let i = openIdx + open.length
+  let out = ''
+  while (i < xml.length) {
+    if (xml.startsWith(CDATA_OPEN, i)) {
+      const term = xml.indexOf(CDATA_CLOSE, i + CDATA_OPEN.length)
+      if (term < 0) {
+        // Unterminated CDATA — malformed; treat the remainder as raw content.
+        return out + xml.slice(i + CDATA_OPEN.length)
+      }
+      out += xml.slice(i + CDATA_OPEN.length, term)
+      i = term + CDATA_CLOSE.length
+      continue
+    }
+    if (xml.startsWith(close, i)) return out
+    out += xml[i]
+    i++
+  }
+  return undefined // close tag never reached outside CDATA
 }
 
 export function parseIapEnvelope(xml: string): IapEnvelope {
   // Fold \r\n and lone \r → \n once (defensive: a raw-mode pty stdin can surface bare
-  // CRs), so multi-line messages and attachment splits are LF-terminated.
+  // CRs). DELIBERATE deviation from the core codec, which leaves the fold to the
+  // transport: here the parse boundary IS the transport boundary — this function is
+  // only ever fed envelopes sliced off this process's stdin.
   xml = xml.replace(/\r\n?/g, '\n')
   const open = /^<iap\s+([^>]*)>/.exec(xml.trim())
   if (!open) throw new VoicetalkRuntimeError('invalid IAP envelope: missing <iap ...>')
-  const fromPersonality = attrValue(open[1], 'from-personality')
-  const fromRuntime = attrValue(open[1], 'from-runtime')
+  // READ-BOTH (envelope-compaction F): the legacy wire names AND the compact
+  // presentation names (`from`/`runtime`/`intelligence`, `<msg>`, `ts`) both decode,
+  // short names winning when both are present — so a future wire flip to the compact
+  // form cannot blank fromRuntime (the spoken-modality cue) on this side.
+  const fromPersonality = attrValue(open[1], 'from') ?? attrValue(open[1], 'from-personality')
+  const fromRuntime = attrValue(open[1], 'runtime') ?? attrValue(open[1], 'from-runtime')
   if (!fromPersonality || !fromRuntime) {
     throw new VoicetalkRuntimeError('invalid IAP envelope: missing from-personality/from-runtime')
   }
-  const fromIntelligenceRaw = attrValue(open[1], 'from-intelligence')
-  const fromIntelligence = isIntelligence(fromIntelligenceRaw) ? fromIntelligenceRaw : undefined
-  const message = tagContent(xml, 'message')
+  const fromIntelligence = normalizeIntelligenceValue(
+    attrValue(open[1], 'intelligence') ?? attrValue(open[1], 'from-intelligence'),
+  )
+  const message = tagContent(xml, 'message') ?? tagContent(xml, 'msg')
   if (message === undefined) throw new VoicetalkRuntimeError('invalid IAP envelope: missing message')
   const attachmentsRaw = tagContent(xml, 'attachments')
+  const sentAt = attrValue(open[1], 'ts')
   return {
     fromPersonality,
     fromRuntime,
     ...(fromIntelligence ? { fromIntelligence } : {}),
+    ...(sentAt ? { sentAt } : {}),
     topic: attrValue(open[1], 'topic'),
     attachments: attachmentsRaw
       ? attachmentsRaw.split(/\r?\n/).map(item => item.trim()).filter(Boolean)
@@ -449,21 +520,64 @@ export function parseIapEnvelope(xml: string): IapEnvelope {
   }
 }
 
+// В38 — a real envelope's open tag is bounded: personality/runtime ≤32 chars each,
+// topic ≤200, intelligence one word, plus attr names and escaping. 1 KiB is far above
+// any legitimate open tag; a longer '>'-less run after `<iap ` is prose, not a tag.
+const MAX_OPEN_TAG_LEN = 1024
+
+/** Classify the text at a `<iap ` occurrence: a complete VALID open tag (required attrs
+ *  present under either naming — legacy wire or compact presentation), a
+ *  complete-but-INVALID one / overlong tagless run (prose that merely contains the
+ *  marker), or INCOMPLETE (no '>' yet within bounds — wait for the next chunk). */
+function openTagVerdict(candidate: string): 'valid' | 'invalid' | 'incomplete' {
+  const m = /^<iap\s+([^>]*)>/.exec(candidate)
+  if (!m) {
+    const unclosed = candidate.indexOf('>') < 0
+    return unclosed && candidate.length <= MAX_OPEN_TAG_LEN ? 'incomplete' : 'invalid'
+  }
+  if (m[0].length > MAX_OPEN_TAG_LEN) return 'invalid'
+  const hasPersonality = m[1].includes('from-personality="') || /(?:^|\s)from="/.test(m[1])
+  const hasRuntime = m[1].includes('from-runtime="') || /(?:^|\s)runtime="/.test(m[1])
+  return hasPersonality && hasRuntime ? 'valid' : 'invalid'
+}
+
 /** Slice complete <iap>…</iap> envelopes out of a streaming buffer, returning the leftover
- *  tail (a partial envelope still being written). CDATA-aware close matching. */
+ *  tail (a partial envelope still being written). CDATA-aware close matching.
+ *
+ *  В38 — a FALSE start (prose that merely contains `<iap `, e.g. a quoted tool
+ *  description) is never committed to: the open tag is validated first, and a candidate
+ *  whose decode fails RESYNCS one char forward instead of being kept (which used to
+ *  either swallow the NEXT real envelope into a mis-attributed blob, or park the buffer
+ *  forever waiting for a close that never comes). */
 export function extractIapEnvelopes(buffer: string): { envelopes: string[]; rest: string } {
   const envelopes: string[] = []
   let rest = buffer
   while (true) {
     const start = rest.indexOf('<iap ')
     if (start < 0) {
-      return { envelopes, rest: rest.slice(Math.max(0, rest.length - 8)) }
+      // Keep a small tail in case `<iap ` is split across chunk boundaries.
+      return { envelopes, rest: rest.slice(Math.max(0, rest.length - '<iap '.length)) }
     }
     if (start > 0) rest = rest.slice(start)
-    const end = indexOfOutsideCdata(rest, '</iap>')
-    if (end < 0) return { envelopes, rest }
+    const verdict = openTagVerdict(rest)
+    if (verdict === 'incomplete') return { envelopes, rest } // open tag split across chunks → wait
+    if (verdict === 'invalid') {
+      rest = rest.slice(1) // false start: skip past this '<' and rescan for the next '<iap '
+      continue
+    }
+    const end = indexOfOutsideCdata(rest, '</iap>', '<iap '.length)
+    if (end < 0) return { envelopes, rest } // incomplete (or mid-CDATA) → wait
     const envelopeEnd = end + '</iap>'.length
-    envelopes.push(rest.slice(0, envelopeEnd))
+    const candidate = rest.slice(0, envelopeEnd)
+    try {
+      parseIapEnvelope(candidate)
+    } catch {
+      // Structurally envelope-shaped but undecodable → a false start after all;
+      // resync so a REAL envelope inside/behind the candidate is still found.
+      rest = rest.slice(1)
+      continue
+    }
+    envelopes.push(candidate)
     rest = rest.slice(envelopeEnd)
   }
 }
@@ -622,9 +736,31 @@ export async function runIapSendCommand(args: {
 // outbound — the AudioSink (fleet → owner's speaker), Фаза-2 stub
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** Фаза-2 AudioSink: instead of TTS → speaker, log the spoken text (human stderr line +
- *  structured evt) and append the envelope to spoken.log so the path is observable and
- *  the E2E has a deterministic artifact. Фаза 3 replaces this with a voice-connect sink. */
+/** Append one spoken envelope to spoken.log — the durable, greppable record of everything
+ *  the runtime said out loud (and the deterministic assertion target of the text E2E).
+ *  Written in BOTH modes: the artifact does not depend on whether audio is live. */
+function appendSpokenLog(owner: string, envelope: IapEnvelope): void {
+  try {
+    appendFileSync(
+      spokenLogPath(),
+      `${JSON.stringify({
+        ts: nowIso(),
+        to: owner,
+        from: envelope.fromPersonality,
+        fromRuntime: envelope.fromRuntime,
+        message: envelope.message,
+        attachments: envelope.attachments,
+      })}\n`,
+      { mode: 0o600 },
+    )
+  } catch (err) {
+    // The artifact is best-effort observability; never let it break delivery.
+    logEvt('speak.log-error', { reason: formatError(err) })
+  }
+}
+
+/** Text-only AudioSink (VOICETALK_AUDIO=0 / no usable audio device): log the spoken text
+ *  instead of synthesizing it. This is the Фаза-2 carcass, kept as the headless floor. */
 function makeStubAudioSink(owner: string): AudioSink {
   return {
     async speak(envelope: IapEnvelope): Promise<void> {
@@ -638,22 +774,23 @@ function makeStubAudioSink(owner: string): AudioSink {
         chars: envelope.message.length,
         attachments: envelope.attachments.length,
       })
+      appendSpokenLog(owner, envelope)
+    },
+  }
+}
+
+/** Фаза-3 AudioSink: the agent's answer becomes speech on the owner's speaker through
+ *  voice-connect, and the session opens its follow-up window afterwards. A TTS or
+ *  playback failure degrades to the logged line — the answer is never silently lost. */
+function makeVoiceAudioSink(owner: string, session: VoiceSession): AudioSink {
+  return {
+    async speak(envelope: IapEnvelope): Promise<void> {
+      process.stderr.write(`🔊 ${BIN_NAME} ${envelope.fromPersonality} → ${owner}: ${oneLine(envelope.message)}\n`)
+      appendSpokenLog(owner, envelope)
       try {
-        appendFileSync(
-          spokenLogPath(),
-          `${JSON.stringify({
-            ts: nowIso(),
-            to: owner,
-            from: envelope.fromPersonality,
-            fromRuntime: envelope.fromRuntime,
-            message: envelope.message,
-            attachments: envelope.attachments,
-          })}\n`,
-          { mode: 0o600 },
-        )
+        await session.speak(envelope.fromPersonality, envelope.message)
       } catch (err) {
-        // The artifact is best-effort observability; never let it break delivery.
-        logEvt('speak.log-error', { reason: formatError(err) })
+        logEvt('speak.fallback', { from: envelope.fromPersonality, reason: formatError(err) })
       }
     },
   }
@@ -707,25 +844,18 @@ function installStdinEnvelopeReader(ctx: RuntimeContext): void {
   process.stdin.resume()
 }
 
-/** Frame + deliver one inbound utterance to the fleet through the daemon. Returns a small
- *  verdict the socket hands back to `say`. */
-async function handleInboundUtterance(
+/** Frame + deliver one inbound utterance to the fleet through the daemon. The single
+ *  delivery path for BOTH inbound sources — the live microphone (Фаза 3) and the `say`
+ *  socket injector (Фаза 2 stand-in, still the debugging seam). */
+async function deliverUtterance(
   ctx: RuntimeContext,
-  raw: string,
+  rawTarget: string,
+  text: string,
+  attachments: string[] = [],
 ): Promise<{ ok: boolean; target?: string; detail?: string }> {
-  let req: { target?: unknown; text?: unknown; attachments?: unknown }
-  try {
-    req = JSON.parse(raw)
-  } catch (err) {
-    return { ok: false, detail: `invalid utterance JSON: ${formatError(err)}` }
-  }
-  const target = normalizeName(String(req.target ?? ''))
+  const target = normalizeName(rawTarget)
   if (!NAME_RE.test(target)) return { ok: false, detail: `invalid target "${target}"` }
-  const text = typeof req.text === 'string' ? req.text : ''
   if (!text.trim()) return { ok: false, target, detail: 'empty utterance' }
-  const attachments = Array.isArray(req.attachments)
-    ? req.attachments.filter((s): s is string => typeof s === 'string')
-    : []
 
   logEvt('inbound.utterance', { target, chars: text.length, attachments: attachments.length })
   const result = await runIapSendCommand({
@@ -745,6 +875,28 @@ async function handleInboundUtterance(
   return { ok: false, target, detail }
 }
 
+/** The socket wire-form of one utterance: {target, text, attachments?} as a JSON line. */
+async function handleInboundUtterance(
+  ctx: RuntimeContext,
+  raw: string,
+): Promise<{ ok: boolean; target?: string; detail?: string }> {
+  let req: { target?: unknown; text?: unknown; attachments?: unknown }
+  try {
+    req = JSON.parse(raw)
+  } catch (err) {
+    return { ok: false, detail: `invalid utterance JSON: ${formatError(err)}` }
+  }
+  const attachments = Array.isArray(req.attachments)
+    ? req.attachments.filter((s): s is string => typeof s === 'string')
+    : []
+  return await deliverUtterance(
+    ctx,
+    String(req.target ?? ''),
+    typeof req.text === 'string' ? req.text : '',
+    attachments,
+  )
+}
+
 /** INBOUND source (Фаза-2 mic+STT stand-in): a unix socket the running router listens on.
  *  One connection = one utterance: the client writes a JSON line {target,text,attachments?}
  *  then half-closes; the router frames + delivers it and writes back a verdict line. */
@@ -808,10 +960,37 @@ async function runCommand(extraArgs: string[]): Promise<void> {
     sink: makeStubAudioSink(owner.personality),
   }
 
+  // Фаза 3 — bring the audio half up. A failure here is NOT fatal: the router keeps
+  // pumping envelopes in text mode (socket inbound + logged outbound) and says so, which
+  // beats a dead presence-runtime because a microphone was unplugged.
+  let session: VoiceSession | null = null
+  let audio: { device?: number; deviceName?: string; addresses?: number; error?: string } = {}
+  if (VOICETALK_AUDIO_ENABLED) {
+    const candidate = new VoiceSession({
+      owner: owner.personality,
+      binding,
+      deliver: (target, text) => deliverUtterance(ctx, target, text),
+      log: logEvt,
+      tmpDir: join(globalVoicetalkRoot(), 'tmp'),
+    })
+    try {
+      const started = await candidate.start()
+      session = candidate
+      ctx.sink = makeVoiceAudioSink(owner.personality, candidate)
+      audio = { device: started.deviceIndex, deviceName: started.deviceName, addresses: started.addresses }
+    } catch (err) {
+      audio = { error: formatError(err) }
+      logEvt('audio.unavailable', { reason: audio.error, note: 'router continues in text mode' })
+    }
+  }
+
   const server = startInboundServer(ctx)
   installStdinEnvelopeReader(ctx)
 
   const cleanup = () => {
+    try {
+      session?.stop()
+    } catch {}
     try {
       server.close()
     } catch {}
@@ -832,16 +1011,21 @@ async function runCommand(extraArgs: string[]): Promise<void> {
 
   logEvt('run', {
     owner: owner.personality,
-    wake_word: binding.wake_word ?? null,
+    wake_words: wakeEntries(binding).map(([w]) => w),
     device: binding.device ?? null,
     iapBin: ctx.iapBin,
     inbound_socket: inboundSocketPath(owner.personality),
-    note: 'Фаза 2 — text caркас; audio (mic/wake-word/STT/TTS) is stubbed, lands in Фаза 3',
+    audio: session ? { live: true, ...audio } : { live: false, ...audio },
   })
+  const audioNote = session
+    ? `mic [${audio.device}] ${audio.deviceName ?? '?'}, ${audio.addresses} addressable peers`
+    : VOICETALK_AUDIO_ENABLED
+      ? `audio UNAVAILABLE (${audio.error ?? 'unknown'}) — text mode`
+      : 'audio disabled (VOICETALK_AUDIO=0) — text mode'
   process.stderr.write(
     `${BIN_NAME}: running ${RUNTIME}-${owner.personality}` +
-      `${binding.wake_word ? ` (wake-word "${binding.wake_word}")` : ' (wake-word unset)'}; ` +
-      `audio stubbed — Фаза 2 text caркас\n`,
+      `${wakeEntries(binding).length ? ` (wake: ${wakeEntries(binding).map(([w]) => w).join('/')})` : ' (no wake words)'}; ` +
+      `${audioNote}\n`,
   )
 
   // Run forever — the supervisor (launchd KeepAlive) owns the lifecycle; we exit only on
@@ -928,13 +1112,19 @@ async function sayCommand(args: string[]): Promise<void> {
 async function interfaceCommand(args: string[]): Promise<void> {
   const { flags } = parseFlags(args)
   const wakeWord = stringFlag(flags, 'wake-word')
+  const wakeWords = parseWakeWords(stringFlag(flags, 'wake-words'))
+  const defaultTarget = stringFlag(flags, 'default-target')
   const device = stringFlag(flags, 'device')
-  if (wakeWord === undefined && device === undefined) {
-    throw new VoicetalkRuntimeError('interface requires --wake-word <w> and/or --device <d>')
+  if (wakeWord === undefined && wakeWords === undefined && defaultTarget === undefined && device === undefined) {
+    throw new VoicetalkRuntimeError(
+      'interface requires --wake-words <«слово=пир,…»>, --default-target <peer>, --wake-word <w> and/or --device <d>',
+    )
   }
   ensureCurrentProfile() // assert the profile exists before patching
   const merged = setVoicetalkInterface(process.cwd(), {
     ...(wakeWord !== undefined ? { wake_word: wakeWord } : {}),
+    ...(wakeWords !== undefined ? { wake_words: wakeWords } : {}),
+    ...(defaultTarget !== undefined ? { default_target: defaultTarget } : {}),
     ...(device !== undefined ? { device } : {}),
   })
   process.stdout.write(`${peerProfilePath(process.cwd())}\n`)
@@ -972,9 +1162,19 @@ async function selfConfigCommand(): Promise<void> {
   process.stdout.write(`${r.profilePath}\n`)
   process.stdout.write(
     `${BIN_NAME} self-config: configured peer "${r.personality}"` +
-      `${r.wakeWord ? ` wake_word="${r.wakeWord}"` : ''}${r.device ? ` device="${r.device}"` : ''}\n`,
+      `${r.wakeWord ? ` wake_word="${r.wakeWord}"` : ''}` +
+      `${r.wakeWords ? ` wake_words=${JSON.stringify(r.wakeWords)}` : ''}` +
+      `${r.defaultTarget ? ` default_target="${r.defaultTarget}"` : ''}` +
+      `${r.device ? ` device="${r.device}"` : ''}\n`,
   )
-  logEvt('self-config', { personality: r.personality, wake_word: r.wakeWord, device: r.device, profile: r.profilePath })
+  logEvt('self-config', {
+    personality: r.personality,
+    wake_word: r.wakeWord,
+    wake_words: r.wakeWords,
+    default_target: r.defaultTarget,
+    device: r.device,
+    profile: r.profilePath,
+  })
 }
 
 /** The contract self-description (runtime id / version / bin / package). Pure + exported
@@ -997,11 +1197,47 @@ async function doctorCommand(args: string[]): Promise<void> {
     problems.push(`peer intelligence is ${profile.intelligence}, voicetalk requires natural`)
   }
   const binding = profile ? voicetalkInterface(profile) : {}
-  if (profile && !binding.wake_word) {
-    // A warning, not a hard fail: Фаза-2 text routing does not need the wake-word, but a
-    // live voice session (Фаза 3) will.
-    problems.push('interfaces.voicetalk.wake_word is unset (needed for live voice in Фаза 3)')
+  if (profile && wakeEntries(binding).length === 0) {
+    // Without a wake word nothing the owner says can be addressed — text routing over the
+    // socket still works, but the microphone half is inert.
+    problems.push('interfaces.voicetalk has no wake words (set wake_words — live voice cannot route without one)')
+  }
+  // The Фаза-3 audio contour: the speech service, the two host binaries and the input
+  // device the passport points at. Reported always; only counted as a problem when audio
+  // is actually enabled — a headless run (VOICETALK_AUDIO=0) legitimately has none.
+  const voice = await voiceHealth()
+  if (VOICETALK_AUDIO_ENABLED && !voice.ok) {
+    problems.push(`voice-connect unreachable at ${voice.endpoint} (${voice.detail ?? 'no detail'}) — STT/TTS will fail`)
+  }
+  const tools: Record<string, boolean> = {}
+  for (const bin of ['ffmpeg', 'ffplay', 'afplay']) {
+    tools[bin] = await hasBinary(bin)
+    if (VOICETALK_AUDIO_ENABLED && !tools[bin]) {
+      problems.push(`${bin} not found on PATH (${bin === 'ffmpeg' ? 'microphone capture' : 'playback'})`)
+    }
+  }
+  let device: unknown = null
+  if (tools.ffmpeg) {
+    try {
+      const resolved = await resolveInputDevice(binding.device)
+      device = { index: resolved.index, name: resolved.name, matched: resolved.matched }
+      if (resolved.devices.length === 0 && VOICETALK_AUDIO_ENABLED) {
+        problems.push('no avfoundation audio input devices — is the microphone connected / TCC granted?')
+      }
+    } catch (err) {
+      device = { error: formatError(err) }
+      if (VOICETALK_AUDIO_ENABLED) problems.push(formatError(err))
+    }
+  }
+  const book = profile ? buildAddressBook({ owner: profile.personality, binding }) : []
+  const orphans = profile ? unresolvedWakeWords(binding) : []
+  if (orphans.length) {
+    problems.push(
+      `wake word(s) ${orphans.map(w => `"${w}"`).join(', ')} resolve to no peer — ` +
+        'name the target explicitly in interfaces.voicetalk.wake_words or set default_target',
+    )
   }
+
   const result = {
     ...doctorReport(),
     ok: problems.length === 0,
@@ -1010,17 +1246,46 @@ async function doctorCommand(args: string[]): Promise<void> {
     owner: profile ? { personality: profile.personality, intelligence: profile.intelligence } : null,
     binding,
     inbound_socket: profile ? inboundSocketPath(profile.personality) : null,
+    audio: { enabled: VOICETALK_AUDIO_ENABLED, tools, device },
+    voice_connect: voice,
+    wake_map: book.map(a => ({ target: a.personality, aliases: a.aliases })),
     problems,
   }
   if (flags.json) printJson(result)
   else {
     process.stdout.write(`runtime: ${result.runtime}\nversion: ${result.version}\nbin:     ${result.bin}\n`)
+    process.stdout.write(
+      `voice:   ${voice.ok ? `ok ${voice.endpoint} (${voice.source}${voice.version ? `, v${voice.version}` : ''})` : `DOWN ${voice.endpoint} — ${voice.detail ?? ''}`}\n`,
+    )
+    const dev = device as { index?: number; name?: string; error?: string } | null
+    process.stdout.write(
+      `mic:     ${dev?.error ? `ERROR ${dev.error}` : dev ? `[${dev.index}] ${dev.name ?? '?'}` : 'not probed'}\n`,
+    )
+    process.stdout.write(
+      `wake:    ${book.length ? book.map(a => `${a.aliases[0]} → ${a.personality}`).join(', ') : 'no wake words configured'}\n`,
+    )
     process.stdout.write(`${result.ok ? 'ok' : 'not ok'}\n`)
     for (const problem of problems) process.stdout.write(`- ${problem}\n`)
   }
   if (!result.ok) process.exitCode = 1
 }
 
+/** `devices` — list the host's audio inputs so an operator can pick one for
+ *  `interface --device`. Pure diagnostics. */
+async function devicesCommand(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args)
+  const devices = await listInputDevices()
+  if (flags.json) {
+    printJson(devices)
+    return
+  }
+  if (devices.length === 0) {
+    process.stdout.write('no audio input devices found (is the microphone connected / TCC granted?)\n')
+    return
+  }
+  for (const d of devices) process.stdout.write(`[${d.index}] ${d.name}\n`)
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // entry
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1058,6 +1323,9 @@ async function main(): Promise<void> {
     case 'say':
       await sayCommand(rest)
       return
+    case 'devices':
+      await devicesCommand(rest)
+      return
     case 'doctor':
       await doctorCommand(rest)
       return