@agfpd/voicetalk-runtime 0.3.3 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-26
+
+### Added
+
+- `native.ready {target, state}` on start when the `iapeer voice status` preflight
+  answers and the target stays in native mode — a positive receipt, so a healthy start
+  is distinguishable from one that never ran the preflight.
+
+## [0.4.0] - 2026-10-26
+
+### Added
+
+- Native voice hand-off (pilot, `interfaces.voicetalk.native_voice` or
+  `VOICETALK_NATIVE_VOICE`): an accepted spoken wake for a listed target releases the
+  microphone (capture exit confirmed) and asks iapeer to open the peer's native Codex
+  `/voice` (`iapeer voice open|status|close <peer> --json`). The microphone returns to
+  wake mode only on a confirmed `closed`; failed/timed-out opens and unreadable receipts
+  keep it released. One wake → one open; outbound speech and earcons are held while the
+  peer owns the room; a restart adopts a still-open voice. Start-up preflight: if
+  `iapeer voice status` gives no readable answer, the target degrades to the STT path
+  (`native.unavailable`) instead of a listener that could never get its mic back.
+- `interface --native-voice <peers>`; `Microphone.pause()/resume()` (replay skips the
+  handed-off span); `scripts/replay-dialogue.sh` gains a fake `iapeer voice` and a
+  `native-voice.pcm` fixture.
+
 ## [0.3.3] - 2026-10-18
 
 ### Fixed

package/docs/README.md

@@ -46,6 +46,37 @@ decoder prompt, because prompt text can be generated back on unrelated audio. A
 dialogue opens only on an exact leading address in the unprimed transcript; repeated
 token loops and name-only echoes are rejected before an IAP envelope exists.
 
+## Native voice — `native_voice` (pilot)
+
+```jsonc
+{ "native_voice": ["darwin"] }     // or env VOICETALK_NATIVE_VOICE=darwin ("" disables)
+```
+
+For a target listed here an accepted wake word does NOT start STT → envelope → TTS. It
+hands the conversation to the peer's own realtime voice (Codex CLI `/voice`) inside its
+live session, which iapeer opens and closes:
+
+1. The wake word must pass every fail-closed check above — native voice changes only
+   what an accepted activation does, never what counts as one.
+2. voicetalk kills its capture process and waits until it has actually exited (no
+   CoreAudio client left), plays the short "heard you" earcon while nobody is
+   listening, then runs `iapeer voice open <peer> --json`.
+3. While the peer holds the room voicetalk stays silent: no earcons, and any agent
+   answer that arrives is spoken only after the hand-off ends.
+4. voicetalk polls `iapeer voice status <peer> --json` (1 s) and takes the microphone
+   back ONLY on `state: closed`. A failed or timed-out open, an unreadable answer, and
+   `opening`/`closing` all keep the microphone released — a timeout is not evidence
+   that the peer stopped listening. Idle-close is iapeer's; after a 30-minute ceiling
+   (`VOICETALK_NATIVE_MAX_MS`) voicetalk asks `iapeer voice close`, and still waits for
+   the confirmed `closed`.
+5. Back in wake mode a soft "door closed" tone plays; the next turn needs a name again.
+   A runtime restart adopts a voice that is still open instead of grabbing the mic.
+   If at start iapeer does not answer `voice status` at all, the target falls back to
+   the STT path (`native.unavailable` in the log).
+
+The words spoken after the name in the activating phrase are not forwarded; the
+conversation itself happens in the peer's native voice. Other targets keep the STT path.
+
 ## How a turn works
 
 1. The microphone runs always-on; energy endpointing cuts an utterance when the

package/docs/ru/README.md

@@ -46,6 +46,37 @@ prompt: такой контекст способен сам породить и
 открывает только точное имя в начале непримированного транскрипта; циклы повторяющихся
 токенов и тело из одних настроенных имён отбрасываются до появления IAP-конверта.
 
+## Нативный голос — `native_voice` (пилот)
+
+```jsonc
+{ "native_voice": ["darwin"] }     // или env VOICETALK_NATIVE_VOICE=darwin ("" выключает)
+```
+
+Для перечисленного адресата принятое wake-слово НЕ запускает STT → конверт → TTS, а
+передаёт разговор в собственный realtime-голос пира (Codex CLI `/voice`) в его живой
+сессии; открывает и закрывает голос iapeer.
+
+1. Wake-слово проходит все fail-closed проверки выше: режим меняет только то, что делает
+   принятая активация, но не то, что ею считается.
+2. voicetalk гасит процесс захвата и ждёт его фактического выхода (CoreAudio-клиента
+   нет), играет короткий earcon «услышал», пока никто не слушает, и вызывает
+   `iapeer voice open <peer> --json`.
+3. Пока комната у пира, voicetalk молчит: ни earcon'ов, а пришедший ответ агента
+   озвучивается только после возврата микрофона.
+4. voicetalk опрашивает `iapeer voice status <peer> --json` (1 с) и забирает микрофон
+   ТОЛЬКО по `state: closed`. Неудачный или просроченный open, нечитаемый ответ,
+   `opening`/`closing` — микрофон остаётся отпущенным: таймаут не доказывает, что пир
+   перестал слушать. Закрытие по простою — у iapeer; по потолку 30 минут
+   (`VOICETALK_NATIVE_MAX_MS`) voicetalk просит `iapeer voice close` и всё равно ждёт
+   подтверждённого `closed`.
+5. По возврату в wake-режим звучит мягкий тон «дверь закрыта»; следующий ход снова
+   требует имени. Рестарт рантайма принимает ещё открытый голос, а не хватает микрофон.
+   Если на старте iapeer вообще не отвечает на `voice status`, адресат уходит на прежний
+   STT-путь (`native.unavailable` в логе).
+
+Слова после имени в активирующей фразе не пересылаются — разговор идёт уже нативным
+голосом пира. Остальные адресаты — прежним STT-путём.
+
 ## Как устроен ход разговора
 
 1. Микрофон слушает постоянно; энергетический эндпойнтер закрывает реплику по паузе

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/voicetalk-runtime",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Voice runtime-router for IAP peers.",
   "repository": {
     "type": "git",

package/src/audio.ts

@@ -320,6 +320,9 @@ export class Microphone {
   private stopped = false
   private attempt = 0
   private timer: ReturnType<typeof setTimeout> | null = null
+  /** Replay position, kept across pause/resume (test seam only). */
+  private replayOffset = 0
+  private pausedAt = 0
 
   constructor(private readonly opts: MicOptions) {}
 
@@ -342,6 +345,37 @@ export class Microphone {
     return this.child !== null
   }
 
+  /** Release the input device and resolve only once the capture child has actually
+   *  EXITED — a killed-but-not-yet-reaped ffmpeg still holds the CoreAudio client. This is
+   *  the hand-off to a second listener (native voice): the other side may open the same
+   *  physical microphone only after this resolves, or both would hear the room. */
+  async pause(capMs = 3_000): Promise<{ released: boolean }> {
+    const child = this.child
+    this.stop()
+    if (this.opts.filePath) this.pausedAt = Date.now()
+    if (!child || child.exitCode !== null || child.signalCode !== null) return { released: true }
+    return await new Promise(resolve => {
+      const timer = setTimeout(() => resolve({ released: false }), capMs)
+      child.once('close', () => {
+        clearTimeout(timer)
+        resolve({ released: true })
+      })
+    })
+  }
+
+  /** Take the device back after a pause. A replayed recording does not rewind: the audio
+   *  that "played" while the device was handed off belongs to the other listener, so the
+   *  replay skips ahead by the paused wall-clock time — exactly what a real microphone
+   *  would have missed. */
+  resume(): void {
+    if (this.opts.filePath && this.pausedAt) {
+      const frames = Math.floor((Date.now() - this.pausedAt) / FRAME_MS)
+      this.replayOffset += frames * FRAME_BYTES
+      this.pausedAt = 0
+    }
+    this.start()
+  }
+
   private spawnChild(): void {
     if (this.stopped) return
     this.attempt += 1
@@ -397,9 +431,9 @@ export class Microphone {
       return
     }
     this.opts.onStart?.(this.attempt)
-    let offset = 0
     const tick = () => {
       if (this.stopped) return
+      const offset = this.replayOffset
       if (offset >= pcm.length) {
         // Keep the stream alive with silence so compose/window timers still fire.
         this.opts.onData(Buffer.alloc(FRAME_BYTES))
@@ -407,7 +441,7 @@ export class Microphone {
         return
       }
       this.opts.onData(Buffer.from(pcm.subarray(offset, offset + FRAME_BYTES)))
-      offset += FRAME_BYTES
+      this.replayOffset = offset + FRAME_BYTES
       this.timer = setTimeout(tick, FRAME_MS)
     }
     tick()

package/src/cli.ts

@@ -45,6 +45,7 @@ import { selfInstall } from './selfInstall.ts'
 import { parseWakeWords, runSelfConfig } from './selfConfig.ts'
 import { writeJsonAtomic } from './fsAtomic.ts'
 import { VoiceSession } from './voiceSession.ts'
+import { cliNativeVoice, nativeVoiceTargets } from './nativeVoice.ts'
 import { voiceHealth } from './voiceConnect.ts'
 import { listInputDevices, resolveInputDevice } from './audio.ts'
 import { buildAddressBook, unresolvedWakeWords, wakeEntries, type VoicetalkBinding } from './wake.ts'
@@ -163,7 +164,7 @@ 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-words «дарвин=darwin,борис=boris» [--default-target <peer>] [--device <d>]
+  ${BIN_NAME} interface --wake-words «дарвин=darwin,борис=boris» [--default-target <peer>] [--device <d>] [--native-voice darwin]
                                                 # 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)
@@ -400,6 +401,7 @@ function setVoicetalkInterface(cwd: string, patch: VoicetalkInterface): Record<s
   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
+  if (patch.native_voice !== undefined) voicetalk.native_voice = patch.native_voice
   ;(interfaces as Record<string, unknown>).voicetalk = voicetalk
   const merged = { ...raw, interfaces }
   writeJsonAtomic(path, merged)
@@ -972,6 +974,11 @@ async function runCommand(extraArgs: string[]): Promise<void> {
       deliver: (target, text) => deliverUtterance(ctx, target, text),
       log: logEvt,
       tmpDir: join(globalVoicetalkRoot(), 'tmp'),
+      // Native voice is opt-in per target; with no target configured the door is not
+      // even built, so the STT path is untouched for everyone.
+      ...(nativeVoiceTargets(binding).size
+        ? { nativeVoice: cliNativeVoice({ bin: ctx.iapBin, env: iapEnv(owner), cwd: ctx.cwd }) }
+        : {}),
     })
     try {
       const started = await candidate.start()
@@ -1013,6 +1020,7 @@ async function runCommand(extraArgs: string[]): Promise<void> {
     owner: owner.personality,
     wake_words: wakeEntries(binding).map(([w]) => w),
     device: binding.device ?? null,
+    native_voice: [...nativeVoiceTargets(binding)],
     iapBin: ctx.iapBin,
     inbound_socket: inboundSocketPath(owner.personality),
     audio: session ? { live: true, ...audio } : { live: false, ...audio },
@@ -1115,9 +1123,17 @@ async function interfaceCommand(args: string[]): Promise<void> {
   const wakeWords = parseWakeWords(stringFlag(flags, 'wake-words'))
   const defaultTarget = stringFlag(flags, 'default-target')
   const device = stringFlag(flags, 'device')
-  if (wakeWord === undefined && wakeWords === undefined && defaultTarget === undefined && device === undefined) {
+  const nativeFlag = stringFlag(flags, 'native-voice')
+  const nativeVoice = nativeFlag === undefined ? undefined : nativeFlag.split(',').map(v => v.trim()).filter(Boolean)
+  if (
+    wakeWord === undefined &&
+    wakeWords === undefined &&
+    defaultTarget === undefined &&
+    device === undefined &&
+    nativeVoice === undefined
+  ) {
     throw new VoicetalkRuntimeError(
-      'interface requires --wake-words <«слово=пир,…»>, --default-target <peer>, --wake-word <w> and/or --device <d>',
+      'interface requires --wake-words <«слово=пир,…»>, --default-target <peer>, --wake-word <w>, --device <d> and/or --native-voice <peers>',
     )
   }
   ensureCurrentProfile() // assert the profile exists before patching
@@ -1126,6 +1142,7 @@ async function interfaceCommand(args: string[]): Promise<void> {
     ...(wakeWords !== undefined ? { wake_words: wakeWords } : {}),
     ...(defaultTarget !== undefined ? { default_target: defaultTarget } : {}),
     ...(device !== undefined ? { device } : {}),
+    ...(nativeVoice !== undefined ? { native_voice: nativeVoice } : {}),
   })
   process.stdout.write(`${peerProfilePath(process.cwd())}\n`)
   printJson(merged)

package/src/nativeVoice.ts

@@ -0,0 +1,119 @@
+// nativeVoice.ts — the door to a peer's NATIVE voice mode (Codex CLI `/voice`).
+//
+// For a configured target the spoken wake word does not start STT → envelope → TTS; it
+// hands the conversation to the peer's own realtime voice inside its live session. The
+// session belongs to iapeer (the pty supervisor), so voicetalk only REQUESTS and OBSERVES
+// over a small CLI contract agreed with the iapeer Implementer (topic codex-voice-wake):
+//
+//   iapeer voice open   <peer> --json → {"ok":true,"state":"open","session":"…","already":bool}
+//   iapeer voice status <peer> --json → {"state":"open|opening|closing|closed","session":…,"reason"?:…}
+//   iapeer voice close  <peer> --json → {"ok":true,"state":"closed"}
+//
+// open returns only once the realtime session is confirmed started, close once it is
+// confirmed closed; status is what the listener polls before it takes the microphone back.
+// Idle-close lives in iapeer — voicetalk never decides a conversation is over, it only
+// waits for the confirmation that it is.
+
+import { spawn } from 'child_process'
+
+export type NativeVoiceState = 'open' | 'opening' | 'closing' | 'closed' | 'unknown'
+
+export type NativeVoiceReceipt = {
+  ok: boolean
+  state: NativeVoiceState
+  session?: string | null
+  already?: boolean
+  reason?: string
+  error?: string
+  /** Raw stdout/stderr tail for the log when the answer did not parse. */
+  raw?: string
+}
+
+export type NativeVoiceControl = {
+  open(peer: string): Promise<NativeVoiceReceipt>
+  status(peer: string): Promise<NativeVoiceReceipt>
+  close(peer: string): Promise<NativeVoiceReceipt>
+}
+
+const STATES = new Set(['open', 'opening', 'closing', 'closed'])
+
+/** Parse the LAST JSON object line of a contract answer. Anything else is not a receipt:
+ *  a confirmation that cannot be read is treated as no confirmation. */
+export function parseVoiceReceipt(stdout: string, stderr: string, exitCode: number | null): NativeVoiceReceipt {
+  const lines = `${stdout}`.split(/\r?\n/).map(l => l.trim()).filter(l => l.startsWith('{') && l.endsWith('}'))
+  for (const line of lines.reverse()) {
+    try {
+      const obj = JSON.parse(line) as Record<string, unknown>
+      const state = typeof obj.state === 'string' && STATES.has(obj.state) ? (obj.state as NativeVoiceState) : 'unknown'
+      const errorText = [obj.error, obj.err, obj.detail].find(v => typeof v === 'string') as string | undefined
+      return {
+        ok: obj.ok === false ? false : exitCode === 0,
+        state,
+        session: typeof obj.session === 'string' ? obj.session : null,
+        already: obj.already === true,
+        reason: typeof obj.reason === 'string' ? obj.reason : undefined,
+        error: exitCode === 0 && obj.ok !== false ? undefined : (errorText ?? `exit ${exitCode}`),
+      }
+    } catch {}
+  }
+  const raw = `${stdout}\n${stderr}`.trim().slice(-300)
+  return { ok: false, state: 'unknown', error: raw || `exit ${exitCode}`, raw }
+}
+
+/** The CLI implementation of the contract. Never throws; a timeout is a failed receipt. */
+export function cliNativeVoice(opts: {
+  bin: string
+  env?: NodeJS.ProcessEnv
+  cwd?: string
+  openTimeoutMs?: number
+  statusTimeoutMs?: number
+  closeTimeoutMs?: number
+}): NativeVoiceControl {
+  const run = (verb: string, peer: string, timeoutMs: number) =>
+    new Promise<NativeVoiceReceipt>(resolve => {
+      let stdout = ''
+      let stderr = ''
+      let settled = false
+      const finish = (r: NativeVoiceReceipt) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        resolve(r)
+      }
+      let child: ReturnType<typeof spawn>
+      try {
+        child = spawn(opts.bin, ['voice', verb, peer, '--json'], {
+          cwd: opts.cwd,
+          env: opts.env ?? process.env,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        })
+      } catch (err) {
+        resolve({ ok: false, state: 'unknown', error: err instanceof Error ? err.message : String(err) })
+        return
+      }
+      const timer = setTimeout(() => {
+        try {
+          child.kill('SIGKILL')
+        } catch {}
+        finish({ ok: false, state: 'unknown', error: `voice ${verb} timed out after ${Math.ceil(timeoutMs / 1000)}s` })
+      }, timeoutMs)
+      child.stdout?.on('data', d => (stdout += String(d)))
+      child.stderr?.on('data', d => (stderr += String(d)))
+      child.on('error', err => finish({ ok: false, state: 'unknown', error: err.message }))
+      child.on('close', code => finish(parseVoiceReceipt(stdout, stderr, code)))
+    })
+  return {
+    open: peer => run('open', peer, opts.openTimeoutMs ?? 20_000),
+    status: peer => run('status', peer, opts.statusTimeoutMs ?? 5_000),
+    close: peer => run('close', peer, opts.closeTimeoutMs ?? 15_000),
+  }
+}
+
+/** Which targets are answered in native voice: the passport's `native_voice` list, or the
+ *  `VOICETALK_NATIVE_VOICE` override (comma list; empty string disables). */
+export function nativeVoiceTargets(binding: { native_voice?: unknown }, env = process.env): Set<string> {
+  const override = env.VOICETALK_NATIVE_VOICE
+  const source: unknown = override !== undefined ? override.split(',') : binding.native_voice
+  const list = Array.isArray(source) ? source : typeof source === 'string' ? source.split(',') : []
+  return new Set(list.map(v => String(v).trim()).filter(Boolean))
+}

package/src/voiceSession.ts

@@ -43,6 +43,7 @@ import {
   type Segment,
 } from './audio.ts'
 import { synthesize, transcribe } from './voiceConnect.ts'
+import { nativeVoiceTargets, type NativeVoiceControl } from './nativeVoice.ts'
 import {
   buildAddressBook,
   hallucinationReason,
@@ -104,6 +105,11 @@ const PLAYBACK_ENABLED = process.env.VOICETALK_PLAYBACK !== '0'
  *  are mode 0600 under the runtime scratch dir and the oldest pair is evicted. */
 const WAKE_CAPTURE_ENABLED = process.env.VOICETALK_WAKE_CAPTURE !== '0'
 const WAKE_CAPTURE_MAX = Math.min(100, num(process.env.VOICETALK_WAKE_CAPTURE_MAX, 16))
+/** Native voice hand-off: how often the listener asks whether the peer's voice is closed,
+ *  and the hard ceiling after which it asks iapeer to close it. Idle-close itself belongs
+ *  to iapeer; the ceiling only bounds a hand-off whose closing was never confirmed. */
+const NATIVE_POLL_MS = num(process.env.VOICETALK_NATIVE_POLL_MS, 1_000)
+const NATIVE_MAX_MS = num(process.env.VOICETALK_NATIVE_MAX_MS, 30 * 60_000)
 
 export type DeliverFn = (target: string, text: string) => Promise<{ ok: boolean; detail?: string }>
 export type LogFn = (evt: string, fields: Record<string, unknown>) => void
@@ -116,6 +122,21 @@ export type VoiceSessionOptions = {
   /** Scratch dir for captured WAVs and synthesized OGGs. */
   tmpDir: string
   peers?: FleetPeer[]
+  /** The door to a peer's native voice mode; absent = every target goes through STT. */
+  nativeVoice?: NativeVoiceControl
+  /** Override the hand-off poll / hold ceiling (tests); defaults come from the env. */
+  nativePollMs?: number
+  nativeMaxMs?: number
+}
+
+/** The microphone is lent to a peer's native voice. `releasing` and `reclaiming` are the
+ *  edges where nobody listens (earcons are allowed there); during `opening` and `open`
+ *  the room belongs to the peer and voicetalk stays silent. */
+type NativeHandOff = {
+  target: string
+  phase: 'releasing' | 'opening' | 'open' | 'reclaiming'
+  since: number
+  session?: string | null
 }
 
 type WakeRoutingDecision = {
@@ -153,8 +174,18 @@ export class VoiceSession {
   /** When the current turn was handed to the fleet — the clock for «ответ за N с». */
   private deliveredAt = new Map<string, number>()
   private stopped = false
+  private nativeTargets: Set<string>
+  private native: NativeHandOff | null = null
+  private nativeWaiters: Array<() => void> = []
+
+  constructor(private readonly opts: VoiceSessionOptions) {
+    this.nativeTargets = opts.nativeVoice ? nativeVoiceTargets(opts.binding) : new Set()
+  }
 
-  constructor(private readonly opts: VoiceSessionOptions) {}
+  /** Who currently holds the microphone instead of the wake listener (null = we do). */
+  get nativeHolder(): { target: string; phase: string } | null {
+    return this.native ? { target: this.native.target, phase: this.native.phase } : null
+  }
 
   /** Resolve the input device, prime the address book, open the mic. Throws if the mic
    *  cannot be resolved — the caller decides whether that is fatal (it is not: the
@@ -173,7 +204,10 @@ export class VoiceSession {
       onStart: attempt => this.opts.log('mic.start', { device: device.index, name: device.name, attempt }),
       onError: detail => this.opts.log('mic.error', { detail }),
     })
-    this.mic.start()
+    // A restart must not grab a microphone a peer is still talking on: adopt an open
+    // native voice and wait for its close before listening.
+    const adopted = await this.adoptOpenNativeVoice()
+    if (!adopted) this.mic.start()
     return { deviceIndex: device.index, deviceName: device.name, addresses: this.book.length }
   }
 
@@ -216,6 +250,9 @@ export class VoiceSession {
 
   private async earcon(kind: keyof Earcons): Promise<void> {
     if (!this.earcons || process.env.VOICETALK_EARCONS === '0' || !PLAYBACK_ENABLED) return
+    // The peer's own voice session is listening to the room — a beep from us would be
+    // heard (and possibly answered) by it.
+    if (this.native && (this.native.phase === 'opening' || this.native.phase === 'open')) return
     try {
       this.muteUntil = Math.max(this.muteUntil, Date.now() + 600)
       await playFile(this.earcons[kind], { timeoutMs: 5_000 })
@@ -229,7 +266,7 @@ export class VoiceSession {
   }
 
   private onAudio(chunk: Buffer): void {
-    if (this.stopped) return
+    if (this.stopped || this.native) return
     if (this.muted()) {
       // Our own speech (or an earcon) is in the room — throw the audio away rather than
       // letting the endpointer build an utterance out of it.
@@ -439,10 +476,18 @@ export class VoiceSession {
       // goes out before the new one starts.
       this.opts.log('wake.switch', { from: active, to: match!.target })
       this.flush('switch')
-      this.append(match!.target, match!.body)
+      if (this.nativeTargets.has(match!.target)) this.handOff(match!)
+      else this.append(match!.target, match!.body)
       return { candidate: match!, accepted: true }
     }
 
+    if (match && this.nativeTargets.has(match.target)) {
+      // An accepted, spoken, exact address to a native-voice peer: the conversation moves
+      // to the peer's own realtime voice. Nothing is transcribed onward or sent as text.
+      this.handOff(match)
+      return { candidate: match, accepted: true }
+    }
+
     if (match) {
       if (!match.body) {
         // Addressed with nothing to say yet («Борис?») — acknowledge and hold the mic
@@ -569,6 +614,155 @@ export class VoiceSession {
     this.followTimer = null
   }
 
+  // ── native voice hand-off ─────────────────────────────────────────────────────
+
+  /** One accepted wake → one hand-off. Synchronously marks the microphone as lent (so no
+   *  second wake can be formed from audio already captured), then runs the hand-off. */
+  private handOff(match: WakeMatch): void {
+    if (this.native) {
+      this.opts.log('native.ignored', { target: match.target, holder: this.native.target, phase: this.native.phase })
+      return
+    }
+    this.native = { target: match.target, phase: 'releasing', since: Date.now() }
+    // Audio captured before the wake was handled belongs to no one now: the owner is
+    // about to talk to the peer directly. A thought in flight to someone ELSE still goes.
+    const dropped = this.queue.length
+    this.queue = []
+    if (this.pending) this.flush('native-voice')
+    this.clearWindow()
+    this.followTarget = null
+    this.opts.log('native.wake', { target: match.target, alias: match.alias, body: match.body || null, droppedSegments: dropped })
+    void this.runHandOff(match.target)
+  }
+
+  private async runHandOff(target: string): Promise<void> {
+    const control = this.opts.nativeVoice!
+    const released = this.mic ? await this.mic.pause() : { released: true }
+    this.segmenter.reset()
+    this.opts.log('mic.released', { to: target, confirmed: released.released })
+    if (!released.released) {
+      // Our capture has not provably let go of the device; opening the peer's voice now
+      // could put two listeners on one microphone. Abort this activation instead.
+      this.native!.phase = 'reclaiming'
+      await this.earcon('error')
+      this.reclaim(target, 'release-unconfirmed')
+      return
+    }
+    // "Heard you" — played while NOBODY is listening: our capture is gone and the peer's
+    // voice is not open yet.
+    await this.earcon('end')
+    if (this.stopped) return
+    this.native!.phase = 'opening'
+    this.opts.log('native.open-requested', { target })
+    const started = Date.now()
+    const receipt = await control.open(target)
+    if (!receipt.ok || receipt.state !== 'open') {
+      // A failed open is NOT evidence that the peer is off the microphone: the realtime
+      // session may still start late, and a timeout or an unreadable answer says nothing
+      // at all. The microphone comes back only on a confirmed `closed` (contract with
+      // iapeer, 26.10) — until then we hold exactly as if the voice were open.
+      this.opts.log('native.open-failed', { target, state: receipt.state, error: receipt.error, openMs: Date.now() - started })
+      this.native!.phase = 'open'
+      await this.holdUntilClosed(target, { failedOpen: true })
+      return
+    }
+    this.native!.phase = 'open'
+    this.native!.session = receipt.session ?? null
+    this.opts.log('native.opened', { target, session: receipt.session ?? null, already: !!receipt.already, openMs: Date.now() - started })
+    await this.holdUntilClosed(target)
+  }
+
+  /** Poll the peer's voice state until iapeer confirms it is closed, then give the
+   *  microphone back to the wake listener. */
+  private async holdUntilClosed(target: string, opts: { failedOpen?: boolean } = {}): Promise<void> {
+    const control = this.opts.nativeVoice!
+    const openedAt = Date.now()
+    let closeRequested = false
+    let lastAlarm = Date.now()
+    let lastState = ''
+    while (!this.stopped) {
+      await new Promise(r => setTimeout(r, this.opts.nativePollMs ?? NATIVE_POLL_MS))
+      if (this.stopped) return
+      const st = await control.status(target)
+      if (st.state !== lastState) {
+        this.opts.log('native.status', { target, state: st.state, reason: st.reason ?? null, error: st.error ?? null })
+        lastState = st.state
+      }
+      if (st.state === 'closed') {
+        this.opts.log('native.closed', { target, session: st.session ?? this.native?.session ?? null, reason: st.reason ?? null, heldMs: Date.now() - openedAt })
+        break
+      }
+      if (!closeRequested && Date.now() - openedAt >= (this.opts.nativeMaxMs ?? NATIVE_MAX_MS)) {
+        closeRequested = true
+        this.opts.log('native.close-requested', { target, reason: 'hold ceiling', heldMs: Date.now() - openedAt })
+        const closed = await control.close(target)
+        this.opts.log('native.close-receipt', { target, ok: closed.ok, state: closed.state, error: closed.error ?? null })
+      }
+      if (closeRequested && Date.now() - lastAlarm >= 60_000) {
+        // Past the ceiling and still no confirmed close. Taking the microphone back
+        // unconfirmed would put two listeners on one device; staying deaf is the
+        // recoverable failure, so it is reported loudly instead of resolved by guess.
+        lastAlarm = Date.now()
+        this.opts.log('native.stuck', { target, lastState, heldMs: Date.now() - openedAt })
+        const closed = await control.close(target)
+        this.opts.log('native.close-receipt', { target, ok: closed.ok, state: closed.state, error: closed.error ?? null })
+      }
+    }
+    if (this.stopped) return
+    this.native!.phase = 'reclaiming'
+    if (opts.failedOpen) await this.earcon('error')
+    this.reclaim(target, opts.failedOpen ? 'open-failed' : 'closed')
+    if (!opts.failedOpen) void this.earcon('close')
+  }
+
+  private reclaim(target: string, reason: string): void {
+    this.segmenter.reset()
+    this.native = null
+    // Back to wake mode proper: after a native conversation the next turn needs a name.
+    this.clearWindow()
+    this.followTarget = null
+    this.mic?.resume()
+    this.opts.log('wake.listening', { after: target, reason })
+    const waiters = this.nativeWaiters
+    this.nativeWaiters = []
+    for (const w of waiters) w()
+  }
+
+  /** On start: if a native voice is already open (the runtime restarted mid-conversation),
+   *  stay off the microphone until it closes. */
+  private async adoptOpenNativeVoice(): Promise<boolean> {
+    const control = this.opts.nativeVoice
+    if (!control) return false
+    for (const target of [...this.nativeTargets]) {
+      const st = await control.status(target)
+      if (st.state === 'unknown') {
+        // Preflight: the contract does not answer at all (an iapeer without `voice`, a
+        // broken CLI). Nothing can have been opened by THIS process yet, so the safe
+        // degradation is the STT path for this target — not a listener that goes deaf
+        // forever on the first wake because no `closed` can ever be confirmed.
+        this.nativeTargets.delete(target)
+        this.opts.log('native.unavailable', { target, error: st.error ?? null, fallback: 'stt' })
+        continue
+      }
+      if (st.state === 'open' || st.state === 'opening' || st.state === 'closing') {
+        this.native = { target, phase: 'open', since: Date.now(), session: st.session ?? null }
+        this.opts.log('native.adopted', { target, state: st.state, session: st.session ?? null })
+        void this.holdUntilClosed(target)
+        return true
+      }
+      // Positive preflight receipt: the contract answered and the target is live in
+      // native mode. Without this line a healthy start is indistinguishable from one that
+      // never ran the preflight.
+      this.opts.log('native.ready', { target, state: st.state })
+    }
+    return false
+  }
+
+  private waitNativeIdle(): Promise<void> {
+    if (!this.native) return Promise.resolve()
+    return new Promise(resolve => this.nativeWaiters.push(resolve))
+  }
+
   /** Speak an agent's answer on the owner's speaker, then hold the follow-up window
    *  open — the conversational turn passes back to the human. */
   async speak(from: string, message: string): Promise<void> {
@@ -596,6 +790,11 @@ export class VoiceSession {
   }
 
   private async say(text: string, opts: { from?: string } = {}): Promise<void> {
+    if (this.native) {
+      // The room belongs to a peer's native voice; speaking now would be heard by it.
+      this.opts.log('tts.deferred', { from: opts.from ?? null, holder: this.native.target })
+      await this.waitNativeIdle()
+    }
     const out = join(this.opts.tmpDir, `say-${randomUUID()}.ogg`)
     const started = Date.now()
     try {

package/src/wake.ts

@@ -120,6 +120,10 @@ export type VoicetalkBinding = {
   wake_words?: Record<string, string> | string[]
   default_target?: string
   device?: string
+  /** Targets answered in their own NATIVE voice mode (Codex `/voice`) instead of
+   *  STT → envelope → TTS. The wake word still has to be spoken and pass every activation
+   *  check — this only changes what an accepted activation does. */
+  native_voice?: string[]
 }
 
 export type AddressBookOptions = {