@agfpd/voicetalk-runtime 0.1.0

package/src/cli.ts

@@ -0,0 +1,1076 @@
+#!/usr/bin/env bun
+// voicetalk-runtime — the voice presence-runtime router (Фаза 2: text caркас).
+//
+// 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)
+// talks to the fleet, exactly as telegram-runtime makes a person a peer through Telegram.
+// It is a long-running ROUTER (foundation adapter kind:'router'), pumping IAP envelopes
+// 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).
+//
+// 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.
+//
+// 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
+// separate "voicetalk-face" sender to distinguish, unlike telegram's bot_username.
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs'
+import { createConnection, createServer, type Server, type Socket } from 'net'
+import { homedir, tmpdir } from 'os'
+import { basename, dirname, join } from 'path'
+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 { writeJsonAtomic } from './fsAtomic.ts'
+
+// 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
+// utterance is reported as not-delivered — no auto-retry, no silent loss. Kept shorter
+// than the daemon wake-deadline so the channel never wedges behind a stuck CLI child.
+const IAP_SEND_TIMEOUT_MS = Number(process.env.VOICETALK_IAP_SEND_TIMEOUT_MS ?? '') || 60_000
+// `say` waits this long for the running router to ack a queued utterance over the socket.
+const SAY_TIMEOUT_MS = Number(process.env.VOICETALK_SAY_TIMEOUT_MS ?? '') || 65_000
+// Modality frame prepended to every inbound utterance so a naive agent answers in the
+// right modality (spoken, brief). Cheap to remove: one env (VOICETALK_FRAME=0), one
+// const, one call site. The daemon ALSO stamps from-runtime=voicetalk on the envelope;
+// the text frame is the belt-and-suspenders that survives an agent ignoring the runtime.
+const VOICETALK_FRAME_ENABLED = process.env.VOICETALK_FRAME !== '0'
+const VOICETALK_FRAME =
+  '[via voicetalk — the owner is speaking aloud, live, by voice. Reply briefly and ' +
+  'plainly for text-to-speech: short sentences, no markdown, code blocks, tables, or links.]'
+
+type Flags = Record<string, string | boolean | string[]>
+
+// IAP identity-contract vocabulary: natural (human peers) / artificial (LLM agents) /
+// absent (programmatic sources). The foundation normalizes any legacy value at its
+// boundary before an envelope or a provisioned profile reaches this runtime; values
+// round-trip verbatim through readPeerProfile/writePeerProfile (preserve, never
+// re-derive identity).
+type Intelligence = 'natural' | 'artificial' | 'absent'
+
+function isIntelligence(value: unknown): value is Intelligence {
+  return value === 'natural' || value === 'artificial' || value === 'absent'
+}
+
+const HUMAN_RUNTIMES = new Set(['telegram', 'voicetalk', 'discord', 'matrix', 'email', 'web'])
+const SCRIPTED_RUNTIMES = new Set(['webhook', 'api', 'cron'])
+
+function defaultIntelligenceForRuntime(runtime: string): Intelligence {
+  if (HUMAN_RUNTIMES.has(runtime)) return 'natural'
+  if (SCRIPTED_RUNTIMES.has(runtime)) return 'absent'
+  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
+}
+
+type PeerProfile = {
+  personality: string
+  runtime: string
+  runtimes: string[]
+  description: string
+  intelligence: Intelligence
+  interfaces?: {
+    voicetalk?: VoicetalkInterface
+    [key: string]: unknown
+  }
+}
+
+type IapEnvelope = {
+  fromPersonality: string
+  fromRuntime: string
+  fromIntelligence?: Intelligence
+  topic?: string
+  attachments: string[]
+  message: string
+}
+
+/** The outbound audio touchpoint (fleet → owner's speaker). Фаза 2 = stub (log + a
+ *  spoken.log artifact); Фаза 3 = TTS via voice-connect → the speaker device. The
+ *  interface IS the seam: swapping the sink is the whole Фаза-3 outbound change. */
+interface AudioSink {
+  speak(envelope: IapEnvelope): Promise<void>
+}
+
+type RuntimeContext = {
+  cwd: string
+  owner: PeerProfile
+  binding: VoicetalkInterface
+  iapBin: string
+  sink: AudioSink
+}
+
+class VoicetalkRuntimeError extends Error {}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// argv + small utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+function usage(): string {
+  return `Usage:
+  ${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} --version
+  ${BIN_NAME} --help`
+}
+
+function setFlag(flags: Flags, key: string, value: string | boolean): void {
+  const previous = flags[key]
+  if (previous === undefined) {
+    flags[key] = value
+    return
+  }
+  if (Array.isArray(previous)) {
+    previous.push(String(value))
+    return
+  }
+  flags[key] = [String(previous), String(value)]
+}
+
+/** Minimal argv parser: positionals + `--flag` / `--flag=value` / `--flag value`. Pure
+ *  and exported so dispatch is unit-testable without spawning a process. */
+export function parseFlags(argv: string[]): { positional: string[]; flags: Flags } {
+  const positional: string[] = []
+  const flags: Flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (!arg.startsWith('--')) {
+      positional.push(arg)
+      continue
+    }
+    const raw = arg.slice(2)
+    const eq = raw.indexOf('=')
+    if (eq >= 0) {
+      setFlag(flags, raw.slice(0, eq), raw.slice(eq + 1))
+      continue
+    }
+    const next = argv[i + 1]
+    if (!next || next.startsWith('--')) {
+      setFlag(flags, raw, true)
+      continue
+    }
+    i++
+    setFlag(flags, raw, next)
+  }
+  return { positional, flags }
+}
+
+function stringFlag(flags: Flags, key: string): string | undefined {
+  const value = flags[key]
+  if (Array.isArray(value)) return value.at(-1)
+  return typeof value === 'string' ? value : undefined
+}
+
+function arrayFlag(flags: Flags, key: string): string[] {
+  const value = flags[key]
+  if (Array.isArray(value)) return value
+  if (typeof value === 'string') return [value]
+  return []
+}
+
+function printJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+}
+
+function unique<T>(values: readonly T[]): T[] {
+  return [...new Set(values)]
+}
+
+function normalizeName(value: string): string {
+  return value.trim().toLowerCase()
+}
+
+function assertName(value: string, source: string): void {
+  if (!NAME_RE.test(value)) {
+    throw new VoicetalkRuntimeError(`${source} must match /^[a-z][a-z0-9-]{0,31}$/, got "${value}"`)
+  }
+}
+
+function formatError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+function nowIso(): string {
+  return new Date().toISOString()
+}
+
+/** Structured event line to stderr — the supervisor captures it into the pane-log, so a
+ *  forensic grep on `evt:` reconstructs every routing decision. */
+function logEvt(evt: string, fields: Record<string, unknown>): void {
+  process.stderr.write(`${BIN_NAME} ${JSON.stringify({ ts: nowIso(), evt, ...fields })}\n`)
+}
+
+function oneLine(text: string, max = 200): string {
+  const flat = text.replace(/\s+/g, ' ').trim()
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// root paths + scaffold
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** IAPEER_ROOT-aware (mirror of the foundation's resolveGlobalRoot): the env override
+ *  wins, else ~/.iapeer. In lockstep with manifest.ts resolveIapeerRoot. */
+function iapeerRoot(): string {
+  const override = process.env.IAPEER_ROOT?.trim()
+  if (override) return override
+  return join(homedir(), '.iapeer')
+}
+
+function globalVoicetalkRoot(): string {
+  return join(iapeerRoot(), 'runtimes', RUNTIME)
+}
+
+function inboxRoot(): string {
+  return join(globalVoicetalkRoot(), 'inbox')
+}
+
+/** The local inbound channel — a per-owner unix socket the running router listens on
+ *  for utterances (Фаза-2 stand-in for the mic+STT source). `say` connects here. Kept
+ *  short (sun_path is ~104 bytes on macOS); under the global root it stays well within. */
+function inboundSocketPath(personality: string): string {
+  return join(inboxRoot(), `${personality}.sock`)
+}
+
+/** Durable artifact the AudioSink stub appends spoken envelopes to — a deterministic
+ *  assertion target for the text E2E and a natural seam for Фаза-3 TTS. */
+function spokenLogPath(): string {
+  return join(globalVoicetalkRoot(), 'spoken.log')
+}
+
+function peerProfilePath(cwd = process.cwd()): string {
+  return join(cwd, IAPEER_DIR, PEER_PROFILE_FILE)
+}
+
+function ensureScaffold(cwd = process.cwd()): void {
+  mkdirSync(join(cwd, IAPEER_DIR, 'runtimes', RUNTIME), { recursive: true, mode: 0o700 })
+  mkdirSync(globalVoicetalkRoot(), { recursive: true, mode: 0o700 })
+  mkdirSync(inboxRoot(), { recursive: true, mode: 0o700 })
+  mkdirSync(join(globalVoicetalkRoot(), 'logs'), { recursive: true, mode: 0o700 })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// peer profile
+// ─────────────────────────────────────────────────────────────────────────────
+
+function readJsonFile<T>(path: string): T | null {
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T
+  } catch (err) {
+    throw new VoicetalkRuntimeError(`${path} is invalid JSON: ${formatError(err)}`)
+  }
+}
+
+/** Read the local peer profile, resolving identity defensively (prefer `default_runtime`,
+ *  fall back to the legacy `runtime` mirror) and preserving `interfaces` verbatim. */
+function readPeerProfile(cwd = process.cwd()): PeerProfile | null {
+  const raw = readJsonFile<Partial<PeerProfile> & { default_runtime?: string; runtime?: string }>(
+    peerProfilePath(cwd),
+  )
+  if (!raw) return null
+  if (typeof raw.personality !== 'string') {
+    throw new VoicetalkRuntimeError(`${peerProfilePath(cwd)} personality is required`)
+  }
+  const effectiveRuntime =
+    typeof raw.default_runtime === 'string' && raw.default_runtime
+      ? raw.default_runtime
+      : typeof raw.runtime === 'string' && raw.runtime
+        ? raw.runtime
+        : undefined
+  if (!effectiveRuntime) {
+    throw new VoicetalkRuntimeError(`${peerProfilePath(cwd)} default_runtime (or legacy runtime) is required`)
+  }
+  const personality = normalizeName(raw.personality)
+  assertName(personality, 'personality')
+  const runtimes = Array.isArray(raw.runtimes)
+    ? raw.runtimes.filter((item): item is string => typeof item === 'string')
+    : [effectiveRuntime]
+  const intelligence: Intelligence = isIntelligence(raw.intelligence)
+    ? raw.intelligence
+    : defaultIntelligenceForRuntime(effectiveRuntime)
+  return {
+    personality,
+    runtime: effectiveRuntime,
+    runtimes: unique([effectiveRuntime, ...runtimes]),
+    description: typeof raw.description === 'string' ? raw.description : '',
+    intelligence,
+    ...(raw.interfaces && typeof raw.interfaces === 'object' && !Array.isArray(raw.interfaces)
+      ? { interfaces: raw.interfaces }
+      : {}),
+  }
+}
+
+function voicetalkInterface(profile: PeerProfile): VoicetalkInterface {
+  const iface = profile.interfaces?.voicetalk
+  return iface && typeof iface === 'object' ? iface : {}
+}
+
+function ensureCurrentProfile(cwd = process.cwd()): PeerProfile {
+  const profile = readPeerProfile(cwd)
+  if (!profile) {
+    throw new VoicetalkRuntimeError(`missing ${peerProfilePath(cwd)} — provision the peer first`)
+  }
+  return profile
+}
+
+/** Set interfaces.voicetalk on the LOCAL profile, preserving every other field (RAW
+ *  read-merge-write so the foundation-provisioned identity round-trips untouched). */
+function setVoicetalkInterface(cwd: string, patch: VoicetalkInterface): Record<string, unknown> {
+  const path = peerProfilePath(cwd)
+  const raw = (readJsonFile<Record<string, unknown>>(path) ?? {}) as Record<string, unknown>
+  const interfaces =
+    raw.interfaces && typeof raw.interfaces === 'object' && !Array.isArray(raw.interfaces)
+      ? { ...(raw.interfaces as Record<string, unknown>) }
+      : {}
+  const voicetalk =
+    (interfaces as { voicetalk?: unknown }).voicetalk &&
+    typeof (interfaces as { voicetalk?: unknown }).voicetalk === 'object'
+      ? { ...((interfaces as { voicetalk: Record<string, unknown> }).voicetalk) }
+      : {}
+  if (patch.wake_word !== undefined) voicetalk.wake_word = patch.wake_word
+  if (patch.device !== undefined) voicetalk.device = patch.device
+  ;(interfaces as Record<string, unknown>).voicetalk = voicetalk
+  const merged = { ...raw, interfaces }
+  writeJsonAtomic(path, merged)
+  return merged
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IAP envelope parsing (CDATA-aware) — mirrors the foundation codec / telegram-runtime
+// ─────────────────────────────────────────────────────────────────────────────
+
+function unescapeAttr(value: string): string {
+  return value.replace(/&quot;/g, '"').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
+}
+
+function attrValue(attrs: string, name: string): string | undefined {
+  const m = new RegExp(`${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
+      continue
+    }
+    if (s.startsWith(needle, i)) return i
+    i++
+  }
+  return -1
+}
+
+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))
+}
+
+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.
+  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')
+  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')
+  if (message === undefined) throw new VoicetalkRuntimeError('invalid IAP envelope: missing message')
+  const attachmentsRaw = tagContent(xml, 'attachments')
+  return {
+    fromPersonality,
+    fromRuntime,
+    ...(fromIntelligence ? { fromIntelligence } : {}),
+    topic: attrValue(open[1], 'topic'),
+    attachments: attachmentsRaw
+      ? attachmentsRaw.split(/\r?\n/).map(item => item.trim()).filter(Boolean)
+      : [],
+    message,
+  }
+}
+
+/** Slice complete <iap>…</iap> envelopes out of a streaming buffer, returning the leftover
+ *  tail (a partial envelope still being written). CDATA-aware close matching. */
+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)) }
+    }
+    if (start > 0) rest = rest.slice(start)
+    const end = indexOfOutsideCdata(rest, '</iap>')
+    if (end < 0) return { envelopes, rest }
+    const envelopeEnd = end + '</iap>'.length
+    envelopes.push(rest.slice(0, envelopeEnd))
+    rest = rest.slice(envelopeEnd)
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// inbound delivery — the send_to_peer wrapper (owner → fleet, via the daemon CLI)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Namespaced env identifying the OWNER as the sender, so the daemon stamps the envelope
+ *  with from-runtime=voicetalk (the modality cue) and from-personality=<owner>. The three
+ *  must be coherent — the daemon enforces PEER_IDENTITY === PEER_RUNTIME-PEER_PERSONALITY. */
+function iapEnv(owner: PeerProfile): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    PEER_PERSONALITY: owner.personality,
+    PEER_RUNTIME: RUNTIME,
+    PEER_IDENTITY: `${RUNTIME}-${owner.personality}`,
+  }
+}
+
+/** Prepend the spoken-modality frame to an inbound utterance (env-gated, cheap to remove). */
+export function frameSpokenInbound(text: string): string {
+  return VOICETALK_FRAME_ENABLED ? `${VOICETALK_FRAME}\n\n${text}` : text
+}
+
+export type IapSendResult =
+  | { ok: true; stdout: string; stderr: string }
+  | { ok: false; detail: string; stdout: string; stderr: string; timedOut?: boolean; timeoutMs?: number }
+
+function cleanIapSendDetail(detail: string): string {
+  return detail
+    .replace(/^\s*iapeer\s+send:\s*/i, '')
+    .replace(/^\s*iap\s+send\s+failed:\s*/i, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function parseLogfmtValue(line: string, key: string): string | undefined {
+  const re = new RegExp(`(?:^|\\s)${key}=(?:"((?:\\\\.|[^"\\\\])*)"|(\\S+))`)
+  const m = re.exec(line)
+  if (!m) return undefined
+  if (m[1] !== undefined) return m[1].replace(/\\"/g, '"').replace(/\\\\/g, '\\')
+  return m[2]
+}
+
+/** Accept both the CLI shape (non-zero + stderr "iapeer send: <err>") and the lower-level
+ *  result vocabulary (ok=false err=…, or a JSON line with ok:false) so the bridge keys on
+ *  the contract word, not one concrete presentation. */
+function parseIapSendNotOk(stdout: string, stderr: string): string | null {
+  const combined = `${stdout}\n${stderr}`
+  for (const rawLine of combined.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line) continue
+    if (line.startsWith('{') && line.endsWith('}')) {
+      try {
+        const obj = JSON.parse(line) as Record<string, unknown>
+        if (obj.ok === false) {
+          const detail = obj.err ?? obj.error ?? obj.reason ?? obj.detail
+          return cleanIapSendDetail(typeof detail === 'string' && detail ? detail : 'delivery failed')
+        }
+      } catch {}
+    }
+    if (/\bok=false\b/.test(line)) {
+      const detail =
+        parseLogfmtValue(line, 'err') ??
+        parseLogfmtValue(line, 'error') ??
+        parseLogfmtValue(line, 'reason') ??
+        parseLogfmtValue(line, 'detail')
+      return cleanIapSendDetail(detail ?? 'delivery failed')
+    }
+  }
+  return null
+}
+
+function formatTimeoutSeconds(ms: number): number {
+  return Math.max(1, Math.ceil(ms / 1000))
+}
+
+export function iapDeliveryFailureVerdict(result: Extract<IapSendResult, { ok: false }>): string {
+  if (result.timedOut) {
+    return `not delivered: delivery timed out after ${formatTimeoutSeconds(result.timeoutMs ?? IAP_SEND_TIMEOUT_MS)}s — check the session`
+  }
+  return `not delivered: ${cleanIapSendDetail(result.detail) || 'delivery failed'}`
+}
+
+/** Shell out the daemon's `iapeer send <target> --message-file <tmp>` from the owner's
+ *  identity (the contract send_to_peer wrapper). Bounded by a timeout; never throws —
+ *  resolves a tagged result. Exported so a unit test drives it against a faked iap bin. */
+export async function runIapSendCommand(args: {
+  bin: string
+  cwd: string
+  env: NodeJS.ProcessEnv
+  targetPersonality: string
+  message: string
+  attachments: string[]
+  timeoutMs?: number
+}): Promise<IapSendResult> {
+  const timeoutMs = args.timeoutMs ?? IAP_SEND_TIMEOUT_MS
+  const tmp = join(tmpdir(), `${BIN_NAME}-${process.pid}-${Date.now()}-${randomUUID()}.txt`)
+  writeFileSync(tmp, args.message || '(message)', { mode: 0o600 })
+  try {
+    const argv = ['send', args.targetPersonality, '--message-file', tmp]
+    for (const attachment of args.attachments) argv.push('--attachment', attachment)
+    return await new Promise<IapSendResult>(resolve => {
+      let stdout = ''
+      let stderr = ''
+      let settled = false
+      let child: ReturnType<typeof spawn> | undefined
+      const finish = (result: IapSendResult) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        resolve(result)
+      }
+      const timer = setTimeout(() => {
+        try {
+          child?.kill('SIGKILL')
+        } catch {}
+        finish({
+          ok: false,
+          detail: `delivery timed out after ${formatTimeoutSeconds(timeoutMs)}s`,
+          stdout,
+          stderr,
+          timedOut: true,
+          timeoutMs,
+        })
+      }, timeoutMs)
+      try {
+        child = spawn(args.bin, argv, { cwd: args.cwd, env: args.env, stdio: ['ignore', 'pipe', 'pipe'] })
+      } catch (err) {
+        finish({ ok: false, detail: formatError(err), stdout, stderr })
+        return
+      }
+      child.stdout?.on('data', data => (stdout += String(data)))
+      child.stderr?.on('data', data => (stderr += String(data)))
+      child.on('error', err => finish({ ok: false, detail: err.message, stdout, stderr }))
+      child.on('close', status => {
+        const notOk = parseIapSendNotOk(stdout, stderr)
+        if (notOk) {
+          finish({ ok: false, detail: notOk, stdout, stderr })
+          return
+        }
+        if (status === 0) {
+          finish({ ok: true, stdout, stderr })
+          return
+        }
+        finish({ ok: false, detail: cleanIapSendDetail((stderr || stdout || `exit ${status}`).trim()), stdout, stderr })
+      })
+    })
+  } finally {
+    rmSync(tmp, { force: true })
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 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. */
+function makeStubAudioSink(owner: string): AudioSink {
+  return {
+    async speak(envelope: IapEnvelope): Promise<void> {
+      process.stderr.write(
+        `🔊 ${BIN_NAME}[tts-stub] ${envelope.fromPersonality} → ${owner}: ${oneLine(envelope.message)}\n`,
+      )
+      logEvt('speak.stub', {
+        to: owner,
+        from: envelope.fromPersonality,
+        fromRuntime: envelope.fromRuntime,
+        chars: envelope.message.length,
+        attachments: envelope.attachments.length,
+      })
+      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) })
+      }
+    },
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// run — the bidirectional router loop
+// ─────────────────────────────────────────────────────────────────────────────
+
+// A serial queue so outbound envelopes are spoken one at a time, in order (Фаза-3 TTS is
+// async and must not overlap on the speaker). A failed task logs and is dropped — the
+// next envelope still gets its turn.
+let outboundChain: Promise<void> = Promise.resolve()
+function enqueueOutbound(task: () => Promise<void> | void): void {
+  outboundChain = outboundChain.then(task).catch(err => {
+    process.stderr.write(`${BIN_NAME}: outbound task failed: ${formatError(err)}\n`)
+  })
+}
+
+/** OUTBOUND reader: parse <iap>…</iap> envelopes off STDIN (the supervisor writes them
+ *  here) and hand each to the AudioSink, serialized. */
+function installStdinEnvelopeReader(ctx: RuntimeContext): void {
+  let buffer = ''
+  const onChunk = (chunk: unknown) => {
+    buffer += String(chunk)
+    const extracted = extractIapEnvelopes(buffer)
+    buffer = extracted.rest
+    for (const raw of extracted.envelopes) {
+      enqueueOutbound(async () => {
+        let envelope: IapEnvelope
+        try {
+          envelope = parseIapEnvelope(raw)
+        } catch (err) {
+          logEvt('envelope.drop', { stage: 'parse', reason: formatError(err) })
+          throw err
+        }
+        try {
+          await ctx.sink.speak(envelope)
+        } catch (err) {
+          logEvt('envelope.drop', { stage: 'speak', from: envelope.fromPersonality, reason: formatError(err) })
+          throw err
+        }
+      })
+    }
+  }
+  // Raw mode disables the pty line-discipline cap (MAX_CANON ~1024B) that would truncate
+  // a long single-line envelope. Guard on isTTY: setRawMode throws on a piped stdin.
+  if (process.stdin.isTTY) process.stdin.setRawMode(true)
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', onChunk)
+  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(
+  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 target = normalizeName(String(req.target ?? ''))
+  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({
+    bin: ctx.iapBin,
+    cwd: ctx.cwd,
+    env: iapEnv(ctx.owner),
+    targetPersonality: target,
+    message: frameSpokenInbound(text),
+    attachments,
+  })
+  if (result.ok) {
+    logEvt('inbound.delivered', { target })
+    return { ok: true, target }
+  }
+  const detail = iapDeliveryFailureVerdict(result)
+  logEvt('inbound.drop', { target, reason: detail })
+  return { ok: false, target, detail }
+}
+
+/** 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. */
+function startInboundServer(ctx: RuntimeContext): Server {
+  const sockPath = inboundSocketPath(ctx.owner.personality)
+  // Clear a stale socket from a prior (crashed) run; listen() fails on EADDRINUSE otherwise.
+  try {
+    if (existsSync(sockPath)) unlinkSync(sockPath)
+  } catch {}
+  mkdirSync(dirname(sockPath), { recursive: true, mode: 0o700 })
+  const server = createServer((conn: Socket) => {
+    // One newline-terminated JSON utterance per connection. We frame on '\n' rather than
+    // the client's half-close so we never depend on half-open socket semantics (a server
+    // socket with allowHalfOpen:false would auto-close its writable side on the client's
+    // FIN, losing the async verdict). reply() writes the verdict + closes.
+    let buf = ''
+    let handled = false
+    conn.setEncoding('utf8')
+    const reply = (result: { ok: boolean; target?: string; detail?: string }) => {
+      try {
+        conn.end(`${JSON.stringify(result)}\n`)
+      } catch {}
+    }
+    conn.on('data', d => {
+      if (handled) return
+      buf += String(d)
+      const nl = buf.indexOf('\n')
+      if (nl < 0) return
+      handled = true
+      handleInboundUtterance(ctx, buf.slice(0, nl))
+        .then(reply)
+        .catch(err => reply({ ok: false, detail: formatError(err) }))
+    })
+    conn.on('error', () => {
+      try {
+        conn.destroy()
+      } catch {}
+    })
+  })
+  server.listen(sockPath)
+  return server
+}
+
+async function runCommand(extraArgs: string[]): Promise<void> {
+  parseFlags(extraArgs) // tolerate (ignore) extra flags the supervisor may pass through
+  ensureScaffold()
+  const owner = ensureCurrentProfile()
+  if (owner.intelligence !== 'natural') {
+    // voicetalk is a HUMAN channel (foundation adapter requiresIntelligence:'natural').
+    // Fail loud rather than route the owner's voice endpoint to an agent/script.
+    throw new VoicetalkRuntimeError(
+      `voicetalk is a human channel — peer "${owner.personality}" has intelligence=${owner.intelligence}, expected natural`,
+    )
+  }
+  const binding = voicetalkInterface(owner)
+  const ctx: RuntimeContext = {
+    cwd: process.cwd(),
+    owner,
+    binding,
+    iapBin: process.env.VOICETALK_RUNTIME_IAP_BIN ?? process.env.IAP_BIN ?? 'iapeer',
+    sink: makeStubAudioSink(owner.personality),
+  }
+
+  const server = startInboundServer(ctx)
+  installStdinEnvelopeReader(ctx)
+
+  const cleanup = () => {
+    try {
+      server.close()
+    } catch {}
+    try {
+      const p = inboundSocketPath(owner.personality)
+      if (existsSync(p)) unlinkSync(p)
+    } catch {}
+  }
+  process.once('exit', cleanup)
+  process.once('SIGINT', () => {
+    cleanup()
+    process.exit(130)
+  })
+  process.once('SIGTERM', () => {
+    cleanup()
+    process.exit(143)
+  })
+
+  logEvt('run', {
+    owner: owner.personality,
+    wake_word: binding.wake_word ?? null,
+    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',
+  })
+  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`,
+  )
+
+  // Run forever — the supervisor (launchd KeepAlive) owns the lifecycle; we exit only on
+  // a signal. Never resolves.
+  await new Promise<never>(() => {})
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// say — the Фаза-2 inbound injector (mic + wake-word + STT stand-in)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Connect to a running router's inbound socket, write one utterance, read the verdict. */
+async function sendUtteranceOverSocket(
+  sockPath: string,
+  payload: { target: string; text: string; attachments: string[] },
+  timeoutMs = SAY_TIMEOUT_MS,
+): Promise<{ ok: boolean; target?: string; detail?: string }> {
+  return await new Promise(resolve => {
+    let buf = ''
+    let settled = false
+    const finish = (r: { ok: boolean; target?: string; detail?: string }) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try {
+        conn.destroy()
+      } catch {}
+      resolve(r)
+    }
+    const conn = createConnection(sockPath)
+    const timer = setTimeout(() => finish({ ok: false, detail: `no ack from router after ${timeoutMs}ms` }), timeoutMs)
+    conn.setEncoding('utf8')
+    // Write the utterance and KEEP the writable side open (no half-close) — we frame the
+    // verdict on the router's '\n', then tear the connection down in finish().
+    conn.on('connect', () => conn.write(`${JSON.stringify(payload)}\n`))
+    const tryParse = () => {
+      const nl = buf.indexOf('\n')
+      if (nl < 0) return
+      const line = buf.slice(0, nl).trim()
+      try {
+        finish(JSON.parse(line))
+      } catch {
+        finish({ ok: false, detail: `bad router response: ${line}` })
+      }
+    }
+    conn.on('data', d => {
+      buf += String(d)
+      tryParse()
+    })
+    conn.on('end', () => {
+      if (!buf.trim()) finish({ ok: false, detail: 'router closed without a verdict' })
+      else tryParse()
+    })
+    conn.on('error', err =>
+      finish({
+        ok: false,
+        detail: `cannot reach the voicetalk router at ${sockPath}: ${err.message} — is "voicetalk-runtime run" up?`,
+      }),
+    )
+  })
+}
+
+async function sayCommand(args: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(args)
+  const target = stringFlag(flags, 'peer')
+  if (!target) throw new VoicetalkRuntimeError('say requires --peer <personality>')
+  const normalized = normalizeName(target)
+  assertName(normalized, 'peer')
+  const text = positional.join(' ').trim()
+  if (!text) throw new VoicetalkRuntimeError('say requires utterance text (positional)')
+  const attachments = arrayFlag(flags, 'attachment')
+
+  const owner = ensureCurrentProfile()
+  const sockPath = inboundSocketPath(owner.personality)
+  const verdict = await sendUtteranceOverSocket(sockPath, { target: normalized, text, attachments })
+  printJson(verdict)
+  if (!verdict.ok) process.exitCode = 1
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// interface / self-install / self-config / doctor
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function interfaceCommand(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args)
+  const wakeWord = stringFlag(flags, 'wake-word')
+  const device = stringFlag(flags, 'device')
+  if (wakeWord === undefined && device === undefined) {
+    throw new VoicetalkRuntimeError('interface requires --wake-word <w> and/or --device <d>')
+  }
+  ensureCurrentProfile() // assert the profile exists before patching
+  const merged = setVoicetalkInterface(process.cwd(), {
+    ...(wakeWord !== undefined ? { wake_word: wakeWord } : {}),
+    ...(device !== undefined ? { device } : {}),
+  })
+  process.stdout.write(`${peerProfilePath(process.cwd())}\n`)
+  printJson(merged)
+}
+
+// `voicetalk-runtime` (bare) / `self-install`: the npx self-deploy contract. Place the
+// launcher on PATH (a self-contained compiled snapshot, overwriting any legacy symlink) +
+// write the runtime manifest at <IAPEER_ROOT>/runtimes/voicetalk/runtime.json (NO peers[]
+// — operator-add). IDEMPOTENT. After it, `iapeer create <owner> --runtime voicetalk`
+// resolves the launcher, bakes it into the always-on plist (VOICETALK_RUNTIME_BIN), and
+// runs the per-peer self-config hook.
+async function selfInstallCommand(): Promise<void> {
+  const r = selfInstall({ env: process.env, sourceEntry: import.meta.path })
+  process.stdout.write(`${BIN_NAME} self-install (idempotent)\n`)
+  process.stdout.write(`  bin:      ${r.binPath}  (${r.binMode})\n`)
+  process.stdout.write(`  manifest: ${r.manifestPath}\n`)
+  process.stdout.write(`  root:     ${r.root}\n`)
+  process.stdout.write(`  docs:     ${r.docs.copied ? r.docs.dest : `skipped (${r.docs.reason ?? 'unknown'})`}\n`)
+  logEvt('self-install', {
+    bin: r.binPath,
+    manifest: r.manifestPath,
+    binMode: r.binMode,
+    root: r.root,
+    docs: r.docs,
+  })
+}
+
+// `voicetalk-runtime self-config`: the PER-PEER hook the foundation invokes inside
+// createPeer→initPeer (cwd = peer cwd, IAPEER_PEER_* in env). Merges this owner's voice
+// binding (wake_word + device, from env) into the local peer profile, PRESERVING the
+// foundation-provisioned identity (intelligence=natural). exit 0 = configured.
+async function selfConfigCommand(): Promise<void> {
+  const r = runSelfConfig({ env: process.env, cwd: process.cwd() })
+  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`,
+  )
+  logEvt('self-config', { personality: r.personality, wake_word: r.wakeWord, device: r.device, profile: r.profilePath })
+}
+
+/** The contract self-description (runtime id / version / bin / package). Pure + exported
+ *  so a test asserts the contract values without running the CLI. */
+export function doctorReport(): { runtime: string; version: string; bin: string; package: string } {
+  return { runtime: RUNTIME, version: VERSION, bin: BIN_NAME, package: PACKAGE_NAME }
+}
+
+async function doctorCommand(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args)
+  const problems: string[] = []
+  let profile: PeerProfile | null = null
+  try {
+    profile = readPeerProfile(process.cwd())
+  } catch (err) {
+    problems.push(formatError(err))
+  }
+  if (!profile) problems.push(`${peerProfilePath(process.cwd())} missing`)
+  if (profile && profile.intelligence !== 'natural') {
+    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)')
+  }
+  const result = {
+    ...doctorReport(),
+    ok: problems.length === 0,
+    cwd: process.cwd(),
+    profile_path: peerProfilePath(process.cwd()),
+    owner: profile ? { personality: profile.personality, intelligence: profile.intelligence } : null,
+    binding,
+    inbound_socket: profile ? inboundSocketPath(profile.personality) : null,
+    problems,
+  }
+  if (flags.json) printJson(result)
+  else {
+    process.stdout.write(`runtime: ${result.runtime}\nversion: ${result.version}\nbin:     ${result.bin}\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
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// entry
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const [cmd, ...rest] = process.argv.slice(2)
+  const { flags } = parseFlags(process.argv.slice(2))
+  if (flags.version === true || flags.v === true) {
+    process.stdout.write(`${VERSION}\n`)
+    return
+  }
+  if (cmd === '--help' || cmd === '-h' || cmd === 'help' || (flags.help === true && !cmd)) {
+    process.stdout.write(`${usage()}\n`)
+    return
+  }
+  if (!cmd) {
+    // Bare invocation = the npx self-install contract (the foundation's defaultNpxRunner
+    // runs `npx -y <package>` with NO args).
+    await selfInstallCommand()
+    return
+  }
+  switch (cmd) {
+    case 'self-install':
+      await selfInstallCommand()
+      return
+    case 'self-config':
+      await selfConfigCommand()
+      return
+    case 'interface':
+      await interfaceCommand(rest)
+      return
+    case 'run':
+      await runCommand(rest)
+      return
+    case 'say':
+      await sayCommand(rest)
+      return
+    case 'doctor':
+      await doctorCommand(rest)
+      return
+    default:
+      process.stderr.write(`unknown command: ${cmd}\n\n${usage()}\n`)
+      process.exitCode = 2
+      return
+  }
+}
+
+if (import.meta.main) {
+  main().catch(err => {
+    process.stderr.write(`${BIN_NAME}: ${formatError(err)}\n`)
+    process.exit(1)
+  })
+}