@agfpd/voicetalk-runtime 0.1.1 → 0.2.1

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
@@ -96,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
@@ -153,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`
 }
@@ -247,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
@@ -376,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 }
@@ -713,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> {
@@ -729,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) })
       }
     },
   }
@@ -798,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({
@@ -836,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. */
@@ -899,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 {}
@@ -923,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
@@ -1019,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`)
@@ -1063,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
@@ -1088,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,
@@ -1101,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
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1149,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

package/src/selfConfig.ts

@@ -46,9 +46,34 @@ export interface SelfConfigOutcome {
   profilePath: string
   /** What was written into interfaces.voicetalk this run (for the CLI summary/log). */
   wakeWord?: string
+  wakeWords?: Record<string, string> | string[]
+  defaultTarget?: string
   device?: string
 }
 
+/** Parse the operator's wake map from one env string: "дарвин=darwin,борис=boris".
+ *  A bare word ("борис") inherits its target from the peer it names / default_target,
+ *  and is written as a bare list entry. Mixed forms collapse into the map form. */
+export function parseWakeWords(spec: string | undefined): Record<string, string> | string[] | undefined {
+  const raw = spec?.trim()
+  if (!raw) return undefined
+  const pairs: Array<[string, string | undefined]> = []
+  for (const part of raw.split(/[,;\n]/)) {
+    const item = part.trim()
+    if (!item) continue
+    const eq = item.indexOf('=')
+    if (eq < 0) pairs.push([item, undefined])
+    else {
+      const word = item.slice(0, eq).trim()
+      const target = item.slice(eq + 1).trim()
+      if (word) pairs.push([word, target || undefined])
+    }
+  }
+  if (pairs.length === 0) return undefined
+  if (pairs.every(([, target]) => target === undefined)) return pairs.map(([word]) => word)
+  return Object.fromEntries(pairs.map(([word, target]) => [word, target ?? word]))
+}
+
 function trimmed(value: string | undefined): string | undefined {
   const v = value?.trim()
   return v && v.length > 0 ? v : undefined
@@ -102,6 +127,10 @@ export function runSelfConfig(opts: SelfConfigOptions = {}): SelfConfigOutcome {
   // Operator-supplied voice binding (env, forwarded by the foundation).
   const wakeWord = trimmed(env.VOICETALK_WAKE_WORD)
   const device = trimmed(env.VOICETALK_DEVICE)
+  // Hybrid wake map (Фаза 3): "борис=boris,линус=linus" — a bare word inherits the
+  // default target. Written only when the operator supplies it.
+  const wakeWords = parseWakeWords(trimmed(env.VOICETALK_WAKE_WORDS))
+  const defaultTarget = trimmed(env.VOICETALK_DEFAULT_TARGET)
 
   // Merge interfaces.voicetalk (preserve any existing voicetalk fields). Only set
   // wake_word/device when provided — never blank out a value the operator set earlier.
@@ -115,6 +144,8 @@ export function runSelfConfig(opts: SelfConfigOptions = {}): SelfConfigOutcome {
       ? { ...((interfaces as { voicetalk: Record<string, unknown> }).voicetalk) }
       : {}
   if (wakeWord) voicetalk.wake_word = wakeWord
+  if (wakeWords) voicetalk.wake_words = wakeWords
+  if (defaultTarget) voicetalk.default_target = defaultTarget
   if (device) voicetalk.device = device
   ;(interfaces as Record<string, unknown>).voicetalk = voicetalk
 
@@ -125,5 +156,5 @@ export function runSelfConfig(opts: SelfConfigOptions = {}): SelfConfigOutcome {
 
   writeJsonAtomic(profilePath, merged)
 
-  return { personality, profilePath, wakeWord, device }
+  return { personality, profilePath, wakeWord, wakeWords, defaultTarget, device }
 }