@agfpd/iapeer 0.4.17 → 0.4.19

package/CHANGELOG.md

@@ -10,6 +10,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.19] - 2026-06-22
+
+### Added
+
+- **Voice provider slot** (`@agfpd/voice-connect`) — a second declarative provider slot
+  alongside memory, integrated into the host lifecycle:
+  - `iapeer onboard` now offers an optional **DEFAULT-YES** voice step (after memory) in
+    both the linear path (`--no-voice` / `--voice <pkg>`) and the interactive wizard. It
+    installs the voice provider's **HOST BACKEND only** (a self-managed launchd HTTP
+    TTS/STT service) via the provider's own `init` (inherited stdio) — per-peer voice
+    tooling stays the separate explicit `iapeer enable voice-connect <peer>`. Report-only
+    for the exit code (an empty slot is a valid state).
+  - `iapeer update` cascades to the voice provider (best-effort, version-gated) via its
+    own `npm exec --package=@agfpd/voice-connect@latest -- voice-connect update` verb —
+    after foundation + runtimes + memory.
+  - `iapeer status` shows a `voice:` line (`<provider> <version> @ <endpoint>` + heartbeat
+    freshness, or `none`). The voice slot is read-only to the core, fail-open; unlike
+    memory it carries no provision/unprovision (voice is opt-in per-peer, not at birth)
+    and adds an `endpoint` for HTTP-facade discovery (telegram-STT / voicetalk).
+
+## [0.4.18] - 2026-06-22
+
+### Changed
+
+- `iapeer rename <old> <new>` now performs a **full folder rename** (extends 0.4.17's
+  personality-only rename). The personality is a self-healed mirror of `normalize(basename(cwd))`,
+  so a rename that kept the cwd would be reverted by profile-standard self-heal — the folder
+  must move. The verb now atomically moves the cwd folder (the per-cwd profile, `.mcp.json`,
+  native-memory, `CLAUDE.md`, and the `.git` clone ride it), moves the claude transcript slug
+  dir (`~/.claude/projects/<slug>`, keyed by `realpath(cwd)` — so claude history is preserved),
+  and updates the registry cwd + personality + per-cwd profile, with rollback of the fs moves on
+  failure. Best-effort afterwards: re-trust the new cwd for codex + clean the old, rewrite the
+  claude `.mcp.json` identity, purge the old identity's lifecycle markers. Refuses a LIVE peer
+  unless `--force`. Memory (operativka folder + author/index attribution) re-key is the memory
+  provider's separate step; codex resume-history (keyed by the cwd recorded inside each session
+  file, not a path-dir) does not carry to the new cwd.
+
 ## [0.4.17] - 2026-06-21
 
 ### Added
@@ -257,7 +294,9 @@ Initial public release — the foundation core of the iapeer multi-agent ecosyst
 - **Heterogeneous peers** — AI agents (Claude, Codex), humans (Telegram), and services
   (timer = cron, watcher = event) are all first-class and addressed the same way.
 
-[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.17...HEAD
+[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.19...HEAD
+[0.4.19]: https://github.com/agfpd/iapeer/compare/v0.4.18...v0.4.19
+[0.4.18]: https://github.com/agfpd/iapeer/compare/v0.4.17...v0.4.18
 [0.4.17]: https://github.com/agfpd/iapeer/compare/v0.4.16...v0.4.17
 [0.4.16]: https://github.com/agfpd/iapeer/compare/v0.4.15...v0.4.16
 [0.4.15]: https://github.com/agfpd/iapeer/compare/v0.4.14...v0.4.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -11,7 +11,7 @@
 // sentinel-marked always-on plist) are stop/start-able.
 
 import { spawnSync } from 'child_process'
-import { existsSync, readFileSync } from 'fs'
+import { existsSync, readFileSync, renameSync } from 'fs'
 import { fileURLToPath } from 'url'
 import { dirname, join } from 'path'
 import {
@@ -54,6 +54,7 @@ import { hostRunDir } from '../launch/ptyHost.ts' // pty-only: attach via the su
 import { runSupervisorClient } from '../supervisor/client.ts' // @xterm-free attach client (both reattach port-deps baked in)
 import { cycleDaemon, isFoundationOwnedPlist, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
 import { readPeerProfile, renamePeer, resolveCallerIdentity, resolveIdentity, writePeerProfileAtomic } from '../identity/index.ts'
+import { claudeProjectsRoot, transcriptSlug } from '../launch/adapters/claude.ts'
 import { peerProfilePath } from '../storage/index.ts'
 import {
   isConformant,
@@ -836,27 +837,37 @@ export async function removePeerCli(
 export interface RenameOutcome {
   oldPersonality: string
   newPersonality: string
-  action: 'renamed' | 'absent' | 'target-exists' | 'refused-live'
+  action: 'renamed' | 'absent' | 'target-exists' | 'target-cwd-exists' | 'refused-live'
   reason?: string
-  cwd?: string
+  oldCwd?: string
+  newCwd?: string
+  transcriptMoved?: boolean
   purgedState?: string[]
+  sideEffects?: string[]
 }
 
 /**
- * Rename a peer's personality through renamePeer (registry + per-cwd profile, atomic;
- * cwd KEPT — the transcript history keyed by slug=realpath(cwd) survives). Refuses a LIVE
- * peer unless --force: a running session carries the OLD identity in its env
- * (PEER_PERSONALITY, set at launch), so renaming under it desyncs the registry from the
- * live process — stop it first, it respawns under the new identity. Purges the OLD
- * identity-keyed lifecycle markers (remove-parity) so a future namesake can't inherit
- * them. Does NOT move memory: the operativka folder + author/index attribution are
- * personality-keyed (the memory provider re-keys them separately); native-memory is
- * cwd-keyed and rides the kept cwd unchanged.
+ * FULL folder rename of a peer (Arthur's invariant: personality == normalize(basename(cwd)),
+ * a self-healed mirror — so a rename MUST move the folder, or profile-standard self-heal
+ * reverts the personality back to the basename). Atomic core, best-effort side-effects:
+ *  1. mv the cwd folder oldCwd → dirname(oldCwd)/<new> (the per-cwd profile, .mcp.json,
+ *     native-memory, CLAUDE.md, .git all ride it).
+ *  2. mv the claude transcript slug dir (~/.claude/projects/<oldSlug> → <newSlug>) — keyed
+ *     by realpath(cwd), so this is how the claude history is NOT orphaned. (codex history
+ *     is keyed by the cwd recorded INSIDE each ~/.codex/sessions jsonl, not a path-dir, so
+ *     it does NOT carry — a documented limitation; codex starts fresh sessions at the new cwd.)
+ *  3. renamePeer(…, newCwd): atomic registry personality+cwd + per-cwd profile personality.
+ * On any failure in 1-3 the fs moves are rolled back (folder + transcript back). Then
+ * best-effort: codex re-trust the new cwd + clean the old, re-write the claude .mcp.json
+ * identity fallback, purge the old identity's lifecycle markers. Refuses a LIVE peer unless
+ * --force. Does NOT touch memory (operativka/author/index) — the provider re-keys that
+ * separately AFTER this rename; deliberately NO `remove`/unprovision (which would risk a
+ * memory purge). `claudeProjectsDir` is a test seam (default ~/.claude/projects).
  */
 export async function renamePeerCli(
   oldPersonality: string,
   newPersonality: string,
-  opts: CliEnvOptions & { force?: boolean } = {},
+  opts: CliEnvOptions & { force?: boolean; claudeProjectsDir?: string } = {},
 ): Promise<RenameOutcome> {
   const env = opts.env ?? process.env
   const index = readPeersIndex({ env })
@@ -865,6 +876,11 @@ export async function renamePeerCli(
   if (findPeer(index, newPersonality)) {
     return { oldPersonality, newPersonality, action: 'target-exists', reason: `"${newPersonality}" already exists` }
   }
+  const oldCwd = peer.cwd
+  const newCwd = join(dirname(oldCwd), newPersonality)
+  if (existsSync(newCwd)) {
+    return { oldPersonality, newPersonality, action: 'target-cwd-exists', reason: `${newCwd} already exists — move or remove it first` }
+  }
   const cfg = loadLifecycleConfig(env)
   if (!opts.force) {
     const liveRt = peer.runtimes.find(rt => isPeerLive(rt, oldPersonality, cfg.sockDir))
@@ -873,13 +889,57 @@ export async function renamePeerCli(
         oldPersonality,
         newPersonality,
         action: 'refused-live',
-        reason: `"${oldPersonality}" is LIVE on ${liveRt} — its running session carries the old identity in its env; stop it first (\`iapeer stop ${oldPersonality}\`) or pass --force`,
+        reason: `"${oldPersonality}" is LIVE on ${liveRt} — its session + folder must be quiescent for the move; stop it first (\`iapeer stop ${oldPersonality}\`) or pass --force`,
       }
     }
   }
-  await renamePeer(oldPersonality, newPersonality, { env })
+  // ── atomic core (1-3) with rollback ──────────────────────────────────────────
+  const projectsDir = opts.claudeProjectsDir ?? claudeProjectsRoot()
+  const oldSlug = transcriptSlug(oldCwd) // BEFORE the mv — realpath needs the live dir
+  const oldTx = join(projectsDir, oldSlug)
+  renameSync(oldCwd, newCwd) // 1. folder (atomic on one filesystem)
+  let transcriptMoved = false
+  let newTx: string | undefined
+  try {
+    const newSlug = transcriptSlug(newCwd) // AFTER the mv — realpath(newCwd) resolves
+    newTx = join(projectsDir, newSlug)
+    if (oldSlug !== newSlug && existsSync(oldTx) && !existsSync(newTx)) {
+      renameSync(oldTx, newTx) // 2. claude transcript slug dir
+      transcriptMoved = true
+    }
+    await renamePeer(oldPersonality, newPersonality, { env }, newCwd) // 3. atomic registry+profile
+  } catch (e) {
+    if (transcriptMoved && newTx) {
+      try { renameSync(newTx, oldTx) } catch { /* best-effort rollback */ }
+    }
+    try { renameSync(newCwd, oldCwd) } catch { /* best-effort rollback */ }
+    throw e
+  }
+  // ── best-effort side-effects (the core rename already committed) ──────────────
+  const sideEffects: string[] = []
+  if (peer.runtimes.includes('codex')) {
+    try {
+      const { preTrustCodexCwd, removeCodexCwdTrust } = await import('../launch/nativeMemory.ts')
+      preTrustCodexCwd(newCwd, env)
+      removeCodexCwdTrust(oldCwd, env)
+      const { removeCodexHooksTrustUnder } = await import('../launch/codexHooksTrust.ts')
+      removeCodexHooksTrustUnder(oldCwd, env)
+      sideEffects.push('codex-trust: re-trusted new cwd + cleaned old')
+    } catch (e) {
+      sideEffects.push(`codex-trust: failed (${e instanceof Error ? e.message : String(e)})`)
+    }
+  }
+  if (peer.runtimes.includes('claude')) {
+    try {
+      const { writeClaudeMcpConfig, resolveDaemonMcpUrl } = await import('../init/index.ts')
+      writeClaudeMcpConfig(newCwd, newPersonality, resolveDaemonMcpUrl({ env }))
+      sideEffects.push('claude .mcp.json: identity rewritten')
+    } catch (e) {
+      sideEffects.push(`claude .mcp.json: failed (${e instanceof Error ? e.message : String(e)})`)
+    }
+  }
   const purgedState = peer.runtimes.flatMap(rt => purgeIdentityState(cfg, buildProcessAddress(rt, oldPersonality)))
-  return { oldPersonality, newPersonality, action: 'renamed', cwd: peer.cwd, purgedState }
+  return { oldPersonality, newPersonality, action: 'renamed', oldCwd, newCwd, transcriptMoved, purgedState, sideEffects }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1028,10 +1088,10 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
   { sig: 'help | --help | -h', desc: 'print this usage (works appended to any verb; executes nothing)' },
   { sig: 'daemon [--install-plist]', desc: 'run the host-wide HTTP-MCP router (launchd-held)' },
   {
-    sig: 'onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--infra <csv>]',
-    desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
+    sig: 'onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--no-voice] [--voice <pkg>] [--infra <csv>]',
+    desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory → voice (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
   },
-  { sig: 'status', desc: 'host snapshot: version, daemon health, memory slot (<provider> | none)' },
+  { sig: 'status', desc: 'host snapshot: version, daemon health, memory + voice slots (<provider> | none)' },
   { sig: 'install-runtime <runtime> [--package pkg] [--npx]', desc: 'npx-install a runtime package + deploy its declared peer-set' },
   { sig: 'update-runtime <runtime> | --all [--force]', desc: "version-gate → re-install + re-provision declared set → restart the runtime's peers" },
   { sig: 'init [cwd] [--runtime r] [--description d]', desc: 'onboard the CURRENT folder as a peer (name = folder name; identity + MCP + doctrine)' },
@@ -1054,7 +1114,7 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     desc: 'LAZY soft-reload: agentic peer comes up FRESH (re-reads doctrine) on its NEXT natural wake — no kill, no burst-wake; non-agentic runtimes skipped. --all = whole fleet. (eager: `new`/self-fresh)',
   },
   { sig: 'remove <peer> [--force]', desc: 'delete a peer\'s registry record (locked writer); refuses a LIVE peer unless --force' },
-  { sig: 'rename <old> <new> [--force]', desc: 'rename a peer\'s personality (registry + per-cwd profile, atomic; cwd/transcript-history kept); refuses a LIVE peer unless --force. Memory re-key is the provider\'s separate step.' },
+  { sig: 'rename <old> <new> [--force]', desc: 'rename a peer — moves the cwd folder + claude transcript + atomic registry/profile (personality = folder name); refuses a LIVE peer unless --force. Memory re-key is the provider\'s separate step.' },
   {
     sig: 'send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]',
     desc: 'manual IAP send (fallback)',
@@ -1171,7 +1231,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // Interactive TUI wizard (Фаза TUI-редизайн) — the DEFAULT for an
         // interactive `iapeer onboard`. Routed ONLY in a real interactive terminal
         // and never for an automation path (--accept-risk / --dry-run / --no-memory
-        // / --infra), which stay on the deterministic linear flow below. Escape
+        // / --no-voice / --infra), which stay on the deterministic linear flow below. Escape
         // hatch: IAPEER_ONBOARD_WIZARD=0 forces the linear path (recovery / scripts
         // that want the old flow). The wizard owns its own gate screen, so we route
         // BEFORE the readline gate. It fails closed: no real TTY →
@@ -1181,6 +1241,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           flags['accept-risk'] === true ||
           flags['dry-run'] === true ||
           flags['no-memory'] === true ||
+          flags['no-voice'] === true ||
           typeof flags.infra === 'string'
         if (!wizardOptOut && !automationFlag && process.stdin.isTTY === true && process.stdout.isTTY === true) {
           const { runOnboardWizard, WIZARD_NOT_INTERACTIVE } = await import('../tui/onboard/run.tsx')
@@ -1282,6 +1343,19 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         })
         const memLabel = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
         out(`memory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${memLabel})\n`)
+        // Voice slot (host backend only — per-peer voice tooling is the separate
+        // `iapeer enable voice-connect <peer>`): optional DEFAULT-YES install of the
+        // voice provider; its own init runs with INHERITED stdio (it owns the TTS-key
+        // prompts). REPORT-ONLY for the exit code — an empty slot is a valid state.
+        const { onboardVoiceProvider } = await import('../onboard/voice.ts')
+        const voice = await onboardVoiceProvider({
+          skip: flags['no-voice'] === true,
+          package: typeof flags.voice === 'string' ? flags.voice : undefined,
+          dryRun: flags['dry-run'] === true,
+          env,
+        })
+        const voiceLabel = voice.provider ? `${voice.provider.provider} ${voice.provider.version}` : 'none'
+        out(`voice: ${voice.state}${voice.detail ? ` — ${voice.detail}` : ''} (slot: ${voiceLabel})\n`)
         // Runtime auth readiness (clean-host prerequisite): a peer runs the runtime's
         // interactive TUI; the launcher auto-clears first-run modals (theme/trust) but
         // CANNOT complete a login OAuth flow. Warn for every INSTALLED runtime (marketplace
@@ -1759,19 +1833,23 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return o.action === 'refused-live' ? 1 : 0
       }
       case 'rename': {
-        // Rename a peer's personality (registry + per-cwd profile, atomic; cwd KEPT so
-        // the transcript history survives). Refuses a LIVE peer unless --force. Memory
-        // (operativka folder + author/index) is personality-keyed and re-keyed separately
-        // by the provider — say so, or it reads as a silent data loss.
+        // FULL folder rename (Arthur's invariant: personality == basename(cwd)): mv the
+        // folder + the claude transcript slug dir + atomic registry cwd+personality, with
+        // rollback; best-effort codex re-trust + .mcp.json rewrite + old-marker purge.
+        // Refuses a LIVE peer unless --force. Memory + codex-history caveats are stated —
+        // a silent data move reads as loss otherwise.
         if (!positionals[0] || !positionals[1]) {
           return argErr(errOut, 'rename needs old and new names — usage: iapeer rename <old> <new> [--force]')
         }
         const o = await renamePeerCli(positionals[0], positionals[1], { force: flags.force === true, env })
         if (o.action === 'renamed') {
-          out(`renamed "${o.oldPersonality}" → "${o.newPersonality}" (registry + per-cwd profile; cwd kept: ${o.cwd})\n`)
-          if (o.purgedState?.length) out(`lifecycle state purged (old identity): ${o.purgedState.join(', ')}\n`)
+          out(`renamed "${o.oldPersonality}" → "${o.newPersonality}"\n`)
+          out(`  folder: ${o.oldCwd} → ${o.newCwd}\n`)
+          out(`  claude transcript: ${o.transcriptMoved ? 'moved (history preserved)' : 'no slug dir to move'}\n`)
+          if (o.sideEffects?.length) out(`  ${o.sideEffects.join('\n  ')}\n`)
+          if (o.purgedState?.length) out(`  lifecycle state purged (old identity): ${o.purgedState.join(', ')}\n`)
           out(
-            `NOTE: memory is NOT moved by rename — re-key the operativka folder + author/index attribution under "${o.newPersonality}" via the memory provider (native-memory rides the kept cwd, unchanged). Wake "${o.newPersonality}" to verify identity + history.\n`,
+            `NOTE: memory (operativka folder + author/index) is personality-keyed — re-key it under "${o.newPersonality}" via the memory provider separately. codex resume-history for the old cwd does NOT carry (codex keys sessions on the in-file cwd). Wake "${o.newPersonality}" to verify identity + history.\n`,
           )
         } else if (o.action === 'absent') errOut(`rename: "${o.oldPersonality}" not registered\n`)
         else errOut(`rename: ${o.reason}\n`)
@@ -1881,9 +1959,11 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // ── Cascade tail: runtimes + memory provider (best-effort) ──
         const { updateAllRuntimes } = await import('../runtime/update.ts')
         const { updateMemoryProvider } = await import('../onboard/memory.ts')
+        const { updateVoiceProvider } = await import('../onboard/voice.ts')
         const tail = await cascadeTail({
           runtimes: () => updateAllRuntimes({ force: flags.force === true, env, warn: m => errOut(`warn: ${m}\n`) }),
           memory: () => updateMemoryProvider({ env }),
+          voice: () => updateVoiceProvider({ env }),
           out,
         })
         return foundationExit === 0 && !tail.failed ? 0 : 1

package/src/identity/index.ts

@@ -634,6 +634,7 @@ export async function renamePeer(
   oldPersonality: string,
   newPersonality: string,
   options: PeersUpdateOptions = {},
+  newCwd?: string,
 ): Promise<PeersIndex> {
   if (!isValidName(oldPersonality) || !isValidName(newPersonality)) {
     throw new IapError('peers rename requires valid personalities')
@@ -647,22 +648,30 @@ export async function renamePeer(
     if (index.peers.some(peer => peer.personality === newPersonality)) {
       throw new IapError(`peer "${newPersonality}" already exists`)
     }
-    const sourceProfile = readPeerProfile(target.cwd)
+    // newCwd: the FOLDER was already moved by the caller (the cwd-move rename), so the
+    // profile now lives at newCwd; read/rewrite it THERE and update the registry cwd
+    // pointer atomically with the personality. Omitted → keep-cwd rename (profile at the
+    // registry's current cwd). The folder mv + transcript mv are the caller's side (cli),
+    // done BEFORE this atomic registry write (with rollback on failure).
+    const profileCwd = newCwd ?? target.cwd
+    const sourceProfile = readPeerProfile(profileCwd)
     if (!sourceProfile) {
       throw new IapError(
-        `peer "${oldPersonality}" cwd ${target.cwd} has no ${IAPEER_DIR}/${PEER_PROFILE_FILE}; restore the cwd or remove the registry entry`,
+        `peer "${oldPersonality}" cwd ${profileCwd} has no ${IAPEER_DIR}/${PEER_PROFILE_FILE}; restore the cwd or remove the registry entry`,
       )
     }
     if (sourceProfile.personality !== oldPersonality) {
       throw new IapError(
-        `peer "${oldPersonality}" cwd ${target.cwd} profile has personality "${sourceProfile.personality}", not "${oldPersonality}"; registry out of sync`,
+        `peer "${oldPersonality}" cwd ${profileCwd} profile has personality "${sourceProfile.personality}", not "${oldPersonality}"; registry out of sync`,
       )
     }
-    writePeerProfileAtomic(target.cwd, { ...sourceProfile, personality: newPersonality })
+    writePeerProfileAtomic(profileCwd, { ...sourceProfile, personality: newPersonality })
     return {
       ...index,
       peers: index.peers.map(peer =>
-        peer.personality === oldPersonality ? { ...peer, personality: newPersonality } : peer,
+        peer.personality === oldPersonality
+          ? { ...peer, personality: newPersonality, ...(newCwd ? { cwd: newCwd } : {}) }
+          : peer,
       ),
     }
   }, options)

package/src/launch/adapters/claude.ts

@@ -89,7 +89,7 @@ function anyBootDialog(pane: string): boolean {
  * mkdtemp temp cwd. realpath first so a symlinked cwd maps to the dir claude
  * actually wrote (a stale path falls through to the original string).
  */
-function transcriptSlug(workDir: string): string {
+export function transcriptSlug(workDir: string): string {
   let phys = workDir
   try {
     phys = realpathSync(workDir)
@@ -99,8 +99,15 @@ function transcriptSlug(workDir: string): string {
   return phys.replace(/[^a-zA-Z0-9]/g, '-')
 }
 
-function transcriptDir(workDir: string): string {
-  return join(homedir(), '.claude', 'projects', transcriptSlug(workDir))
+/** The base dir holding all claude project transcript slugs (~/.claude/projects).
+ *  Exported so a cwd-move (peer folder rename) can relocate the slug dir from the
+ *  SINGLE source of the slug encoding, never a re-implementation that could drift. */
+export function claudeProjectsRoot(): string {
+  return join(homedir(), '.claude', 'projects')
+}
+
+export function transcriptDir(workDir: string): string {
+  return join(claudeProjectsRoot(), transcriptSlug(workDir))
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/onboard/voice.ts

@@ -0,0 +1,204 @@
+// Voice-slot onboard step (the voice provider = @agfpd/voice-connect).
+// Host-phase, optional, DEFAULT-YES: install the voice provider package and run ITS
+// OWN init-verb — the provider deploys its HOST BACKEND (a self-managed launchd HTTP
+// service), writes the slot declaration, and prompts for any TTS keys over our
+// inherited tty. The core never writes the slot itself.
+//
+// SCOPE — host backend ONLY (the PIN, confirmed with voice-connect): init wires NO
+// host MCP server. Per-peer voice tooling (the voice_create / tts MCP surface) is the
+// SEPARATE explicit `iapeer enable voice-connect <peer>` (a marketplace capability
+// plugin whose per-peer identity resolves from the MCP stdio child's cwd — a single
+// host-wide server cannot resolve per-peer voices). So onboard ≠ per-peer wiring; the
+// backend it installs is independently valuable (telegram-STT / voicetalk consume the
+// HTTP facade with no MCP at all). Unlike memory there is therefore NO per-peer birth
+// hook and the slot carries NO provision/unprovision.
+//
+// Outcome semantics: this step NEVER fails the onboard exit code — an empty slot is a
+// fully valid state regardless of why (skipped / not yet published / non-tty refusal).
+// Outcomes are reported, not enforced. Mirrors onboard/memory.ts deliberately (same
+// vocabulary), minus memory's --human/--runtime init args (voice init takes none).
+
+import { spawnSync } from 'child_process'
+import { readVoiceProvider, type VoiceProvider } from '../status/index.ts'
+
+/** The distribution default voice provider. */
+export const DEFAULT_VOICE_PACKAGE = '@agfpd/voice-connect'
+
+export interface VoiceOnboardOptions {
+  /** --no-voice: skip the step entirely. */
+  skip?: boolean
+  /** --voice <pkg>: override the provider package (default @agfpd/voice-connect). */
+  package?: string
+  dryRun?: boolean
+  env?: NodeJS.ProcessEnv
+  /** Wall-clock backstop (ms) for the provider-init subprocess — a hung provider must
+   *  NEVER wedge onboard (voice is optional). The interactive wizard passes a generous
+   *  value; the linear path leaves it unset (no timeout). */
+  timeoutMs?: number
+  /** Injectable runner (tests). Default: availability probe + `npx -y <pkg> init`
+   *  with inherited stdio. */
+  runInit?: (
+    pkg: string,
+    args: string[],
+    env: NodeJS.ProcessEnv,
+    timeoutMs?: number,
+  ) => { status: number | null; unavailable: boolean }
+}
+
+export interface VoiceOnboardResult {
+  state:
+    | 'installed' // provider init succeeded and declared the slot
+    | 'already' // slot already occupied by the SAME package — idempotent no-op
+    | 'skipped-flag' // --no-voice
+    | 'skipped-unavailable' // package not published / no network — soft skip (contract)
+    | 'refused-foreign' // slot occupied by ANOTHER provider — explicit refusal
+    | 'provider-init-failed' // provider init ran and exited non-zero / declared nothing
+    | 'dry-run'
+  provider: VoiceProvider | null
+  detail?: string
+}
+
+function defaultRunInit(
+  pkg: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+  timeoutMs?: number,
+): { status: number | null; unavailable: boolean } {
+  // Availability probe FIRST (cheap, side-effect-free, bounded): an unpublished package
+  // / no network → soft-skip per the contract (the provider's release order must never
+  // block the core's onboard).
+  const probe = spawnSync('npm', ['view', `${pkg}@latest`, 'version'], { encoding: 'utf8', env, timeout: 60_000 })
+  if (probe.status !== 0) return { status: probe.status, unavailable: true }
+  // INHERITED stdio — the provider owns its install questions (TTS-key prompts happen
+  // here, once). The provider bin (`voice-connect`) is an ARG-DISPATCHER: a subcommand
+  // (`init`) routes to its lifecycle path, NOT the backward-compatible MCP-stdio path
+  // (no-subcommand) — so `npx -y <pkg> init` correctly hits init.
+  const r = spawnSync('npx', ['-y', pkg, ...args], {
+    stdio: 'inherit',
+    env,
+    ...(timeoutMs ? { timeout: timeoutMs } : {}),
+  })
+  return { status: r.status, unavailable: false }
+}
+
+export async function onboardVoiceProvider(opts: VoiceOnboardOptions = {}): Promise<VoiceOnboardResult> {
+  const env = opts.env ?? process.env
+  const pkg = opts.package?.trim() || DEFAULT_VOICE_PACKAGE
+  const existing = readVoiceProvider(env)
+  if (opts.skip) return { state: 'skipped-flag', provider: existing }
+  if (existing) {
+    if (existing.package === pkg) return { state: 'already', provider: existing }
+    // Never silently install over an occupied slot (contract: FORBIDDEN).
+    return {
+      state: 'refused-foreign',
+      provider: existing,
+      detail: `slot is occupied by "${existing.provider}" (${existing.package}) — uninstall it first`,
+    }
+  }
+  // voice init takes NO core-known facts (no --human/--runtime — the host backend is
+  // peer-agnostic; per-peer voice is a separate `iapeer enable`).
+  const args = ['init']
+  if (opts.dryRun) {
+    return { state: 'dry-run', provider: null, detail: `would run: npx -y ${pkg} ${args.join(' ')}` }
+  }
+  const run = opts.runInit ?? defaultRunInit
+  const r = run(pkg, args, env, opts.timeoutMs)
+  if (r.unavailable) {
+    return {
+      state: 'skipped-unavailable',
+      provider: null,
+      detail: `${pkg} is not available (not published yet / no network) — install later: npx ${pkg} init`,
+    }
+  }
+  if (r.status !== 0) {
+    return {
+      state: 'provider-init-failed',
+      provider: readVoiceProvider(env),
+      detail: `provider init exited ${r.status ?? 'null'}`,
+    }
+  }
+  // The PROVIDER declares the slot; verify it actually did (its contract duty).
+  const after = readVoiceProvider(env)
+  if (!after) {
+    return {
+      state: 'provider-init-failed',
+      provider: null,
+      detail: 'provider init succeeded but did not declare the slot (voice-provider.json missing)',
+    }
+  }
+  return { state: 'installed', provider: after }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// updateVoiceProvider — the voice leg of the cascade `iapeer update` (FU12)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface VoiceUpdateResult {
+  state:
+    | 'updated' // provider update ran and the slot version advanced
+    | 'already-latest' // ran but the slot version is unchanged
+    | 'no-slot' // no provider claimed — nothing to update
+    | 'skipped-unavailable' // package not published / no network — soft skip
+    | 'failed' // provider update exited non-zero
+  package?: string
+  from?: string
+  to?: string
+  detail?: string
+}
+
+/** The provider's CLI bin name = the unscoped package name (`@agfpd/voice-connect` →
+ *  `voice-connect`). That bin is the arg-dispatcher; `<bin> update` routes to its
+ *  lifecycle update path. */
+function voiceBinName(pkg: string): string {
+  return pkg.replace(/^@[^/]+\//, '')
+}
+
+function defaultRunVoiceUpdate(pkg: string, env: NodeJS.ProcessEnv): { status: number | null; unavailable: boolean } {
+  // Availability probe FIRST (cheap, bounded): unpublished / no network → soft-skip.
+  const probe = spawnSync('npm', ['view', `${pkg}@latest`, 'version'], { encoding: 'utf8', env, timeout: 60_000 })
+  if (probe.status !== 0) return { status: probe.status, unavailable: true }
+  // `npm exec --package=<pkg>@latest -- <bin> update` fetches the latest published
+  // package into a fresh temp and runs ITS update verb from there — bypassing any
+  // PATH name-shadow (the 0.2.9 pitfall: a bare `npx <bin>` could re-run a stale
+  // installed binary). voice-connect's update then re-copies its runtime tree into the
+  // STABLE provider home (~/.iapeer/providers/voice-connect/, never the GC'd npx cache),
+  // bootout→bootstraps its HTTP service, and bumps slot.version — so the before/after
+  // version-gate this leg reads is real. The provider OWNS update + slot-write + its own
+  // service restart.
+  const r = spawnSync(
+    'npm',
+    ['exec', '--yes', `--package=${pkg}@latest`, '--', voiceBinName(pkg), 'update'],
+    { stdio: 'inherit', env },
+  )
+  return { status: r.status, unavailable: false }
+}
+
+/**
+ * Update the CLAIMED voice provider via ITS OWN update verb (slot contract: the
+ * provider owns install/update + slot-write + service restart; the core only invokes +
+ * reads the slot). No slot → nothing to update. Reports from→to by reading the slot
+ * version before/after. BEST-EFFORT by the caller (the cascade never aborts on it).
+ */
+export function updateVoiceProvider(opts: {
+  env?: NodeJS.ProcessEnv
+  dryRun?: boolean
+  runUpdate?: (pkg: string, env: NodeJS.ProcessEnv) => { status: number | null; unavailable: boolean }
+} = {}): VoiceUpdateResult {
+  const env = opts.env ?? process.env
+  const slot = readVoiceProvider(env)
+  if (!slot) return { state: 'no-slot', detail: 'no voice provider claimed — nothing to update' }
+  const pkg = slot.package
+  const from = slot.version
+  if (opts.dryRun) {
+    return { state: 'updated', package: pkg, from, detail: `would run: npm exec --package=${pkg}@latest -- ${voiceBinName(pkg)} update` }
+  }
+  const run = opts.runUpdate ?? defaultRunVoiceUpdate
+  const r = run(pkg, env)
+  if (r.unavailable) {
+    return { state: 'skipped-unavailable', package: pkg, from, detail: `${pkg}@latest not reachable (no network / unpublished)` }
+  }
+  if (r.status !== 0) return { state: 'failed', package: pkg, from, detail: `provider update exited ${r.status ?? 'null'}` }
+  const to = readVoiceProvider(env)?.version
+  if (from && to && from === to) return { state: 'already-latest', package: pkg, from, to }
+  return { state: 'updated', package: pkg, from, to }
+}

package/src/status/index.ts

@@ -1,10 +1,14 @@
 // Status — the host-snapshot verb: installed-binary version, daemon health, and
-// the MEMORY SLOT line (docs/Слот памяти — контракт memory provider.md). The slot
-// is DECLARATIVE: a root file `~/.iapeer/memory-provider.json` written (atomically)
-// by the PROVIDER's own init/uninstall — the core only ever READS it. An absent or
-// unreadable file is the EMPTY slot — a fully valid state (bare core), never an
-// error (fail-open). The core never acts on heartbeat staleness — it only REPORTS
-// it (healing the provider's daemon is the provider's job).
+// the provider-SLOT lines (docs/Слот памяти — контракт memory provider.md). A slot
+// is DECLARATIVE: a root file (`~/.iapeer/memory-provider.json`, `voice-provider.json`)
+// written (atomically) by the PROVIDER's own init/uninstall — the core only ever
+// READS it. An absent or unreadable file is the EMPTY slot — a fully valid state
+// (bare core), never an error (fail-open). The core never acts on heartbeat
+// staleness — it only REPORTS it (healing the provider's daemon is the provider's
+// job). Two slots share the same declarative contract: MEMORY (auto-at-birth, carries
+// provision/unprovision) and VOICE (host-level backend only; per-peer voice tooling is
+// the separate `iapeer enable voice-connect <peer>` — the voice slot carries NO
+// provision/unprovision, and adds an `endpoint` for HTTP-facade discovery).
 
 import { closeSync, openSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
@@ -97,8 +101,9 @@ export function readMemoryProvider(env: NodeJS.ProcessEnv = process.env): Memory
   }
 }
 
-/** Age (s) of the provider's heartbeat file, or null (none declared / unreadable). */
-export function heartbeatAgeSecs(provider: MemoryProvider, nowMs: number = Date.now()): number | null {
+/** Age (s) of a provider's heartbeat file, or null (none declared / unreadable).
+ *  Generic over any slot carrying an optional `heartbeat` path (memory + voice). */
+export function heartbeatAgeSecs(provider: { heartbeat?: string }, nowMs: number = Date.now()): number | null {
   if (!provider.heartbeat) return null
   try {
     return Math.max(0, Math.floor((nowMs - statSync(provider.heartbeat).mtimeMs) / 1000))
@@ -107,6 +112,63 @@ export function heartbeatAgeSecs(provider: MemoryProvider, nowMs: number = Date.
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// VOICE slot — the voice-connect provider declaration (the same declarative
+// contract as memory, two differences by design: NO provision/unprovision (voice
+// is opt-in PER-PEER via `iapeer enable`, not auto-at-birth), and an `endpoint`
+// (+ a named `routes` object the core does NOT parse) for the HTTP-facade that
+// telegram-STT / voicetalk consume with no MCP at all). The core only READS it.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The voice-slot declaration filename in the storage root. */
+export const VOICE_PROVIDER_FILE = 'voice-provider.json'
+
+export interface VoiceProvider {
+  /** Provider name occupying the slot (e.g. "voice-connect"). */
+  provider: string
+  /** npm package of the provider (e.g. "@agfpd/voice-connect"). */
+  package: string
+  version: string
+  registeredAt: string
+  /** Optional liveness proxy: an absolute path whose mtime the provider's HTTP
+   *  daemon refreshes. status reports its age; the core takes NO action on staleness. */
+  heartbeat?: string
+  /** Base URL of the provider's HTTP facade (e.g. "http://127.0.0.1:PORT") — shown
+   *  in status for discovery. Opaque to the core. */
+  endpoint?: string
+}
+
+export function voiceProviderPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveGlobalRoot(env), VOICE_PROVIDER_FILE)
+}
+
+/**
+ * Read the voice-slot declaration. null = EMPTY slot (absent / unreadable /
+ * schema-invalid file) — a valid state, so this NEVER throws (fail-open to bare).
+ * Self-management extras the provider may add (label/managed/host/port/routes) are
+ * ignored — the core reads only the contract fields it acts/reports on.
+ */
+export function readVoiceProvider(env: NodeJS.ProcessEnv = process.env): VoiceProvider | null {
+  try {
+    const raw = JSON.parse(readFileSync(voiceProviderPath(env), 'utf8')) as unknown
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+    const o = raw as Record<string, unknown>
+    if (typeof o.provider !== 'string' || !o.provider.trim()) return null
+    if (typeof o.package !== 'string' || !o.package.trim()) return null
+    if (typeof o.version !== 'string' || !o.version.trim()) return null
+    return {
+      provider: o.provider.trim(),
+      package: o.package.trim(),
+      version: o.version.trim(),
+      registeredAt: typeof o.registeredAt === 'string' ? o.registeredAt : '',
+      ...(typeof o.heartbeat === 'string' && o.heartbeat.trim() ? { heartbeat: o.heartbeat.trim() } : {}),
+      ...(typeof o.endpoint === 'string' && o.endpoint.trim() ? { endpoint: o.endpoint.trim() } : {}),
+    }
+  } catch {
+    return null // empty slot — bare core is valid
+  }
+}
+
 /**
  * Probe whether the iapeer binary holds Full Disk Access (macOS TCC). Reads the
  * user TCC.db — a canonical FDA-gated resource that is NEVER promptable (silent
@@ -137,6 +199,7 @@ export interface HostStatus {
   version: string
   daemon: { healthy: boolean; url: string | null; sock: string | null }
   memory: { provider: MemoryProvider | null; heartbeatAgeSecs: number | null }
+  voice: { provider: VoiceProvider | null; heartbeatAgeSecs: number | null }
   /** Full Disk Access of the iapeer binary: true granted / false not-granted /
    *  null undeterminable (non-macOS or TCC.db unreadable for a non-TCC reason). */
   fda: boolean | null
@@ -165,11 +228,13 @@ export async function hostStatus(opts: HostStatusOptions = {}): Promise<HostStat
   }
   const health = await waitForDaemonHealthy({ env, timeoutMs: 2500, needConsecutive: 1, probe: opts.probe })
   const provider = readMemoryProvider(env)
+  const voice = readVoiceProvider(env)
   const fda = (opts.fdaProbe ?? (() => probeFullDiskAccess(env)))()
   return {
     version: IAPEER_VERSION,
     daemon: { healthy: health.healthy, url, sock },
     memory: { provider, heartbeatAgeSecs: provider ? heartbeatAgeSecs(provider) : null },
+    voice: { provider: voice, heartbeatAgeSecs: voice ? heartbeatAgeSecs(voice) : null },
     fda,
   }
 }
@@ -190,6 +255,17 @@ export function formatHostStatus(s: HostStatus): string {
       : ' (daemon not running — no heartbeat file)'
   }
   const memory = s.memory.provider ? `${s.memory.provider.provider} ${s.memory.provider.version}${hb}` : 'none'
+  // Voice slot — same heartbeat semantics as memory; also show the HTTP endpoint
+  // (discovery target for telegram-STT / voicetalk). 'none' when the slot is empty.
+  let vhb = ''
+  if (s.voice.provider?.heartbeat) {
+    vhb = s.voice.heartbeatAgeSecs !== null
+      ? ` (heartbeat ${s.voice.heartbeatAgeSecs}s ago)`
+      : ' (daemon not running — no heartbeat file)'
+  }
+  const voice = s.voice.provider
+    ? `${s.voice.provider.provider} ${s.voice.provider.version}${s.voice.provider.endpoint ? ` @ ${s.voice.provider.endpoint}` : ''}${vhb}`
+    : 'none'
   // FDA line: granted → terse OK; NOT granted → the actionable hint (a fresh host
   // without FDA silently meets TCC prompts on every new protected class — peers
   // read protected folders + foreign app containers, attributed to this binary;
@@ -204,5 +280,5 @@ export function formatHostStatus(s: HostStatus): string {
   } else {
     fda = 'fda: unknown (not macOS / undeterminable)'
   }
-  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\n${fda}\n`
+  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\nvoice: ${voice}\n${fda}\n`
 }

package/src/tui/onboard/app.tsx

@@ -18,6 +18,7 @@ import { iapeerBinPath } from '../../install/index.ts'
 export interface WizardResult {
   code: number
   memoryConsent: boolean
+  voiceConsent: boolean
   advisories: string[]
   summary: string[]
   telegramConsent: boolean
@@ -27,7 +28,7 @@ export interface WizardResult {
   hostRuntime?: OnboardRuntime
 }
 
-type Phase = 'gate' | 'running' | 'telegram' | 'memory' | 'declined' | 'finishing'
+type Phase = 'gate' | 'running' | 'telegram' | 'memory' | 'voice' | 'declined' | 'finishing'
 type StepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'fail'
 interface Step {
   key: string
@@ -96,16 +97,17 @@ export function OnboardApp({
   const [advisories, setAdvisories] = useState<string[]>([])
   const [hostRuntime, setHostRuntime] = useState<OnboardRuntime | undefined>(undefined)
   const [telegramConsent, setTelegramConsent] = useState(false)
+  const [memoryConsent, setMemoryConsent] = useState(false)
   const spin = useSpinnerFrame(phase === 'running')
 
-  const finish = (memoryConsent: boolean): void => {
+  const finish = (voiceConsent: boolean): void => {
     const failed = steps.some(s => s.status === 'fail')
     const summary = steps.map(s => {
       const mark = s.status === 'ok' ? '✓' : s.status === 'warn' ? '!' : s.status === 'fail' ? '✗' : '·'
       return `  ${mark} ${s.label}${s.detail ? ` — ${s.detail}` : ''}`
     })
     summary.unshift(failed ? 'Onboard finished with errors:' : 'Onboard complete:')
-    onResult({ code: failed ? 1 : 0, memoryConsent, telegramConsent, advisories, summary, hostRuntime })
+    onResult({ code: failed ? 1 : 0, memoryConsent, voiceConsent, telegramConsent, advisories, summary, hostRuntime })
     setPhase('finishing')
     setTimeout(() => exit(), 30)
   }
@@ -135,19 +137,34 @@ export function OnboardApp({
     { isActive: phase === 'telegram' },
   )
 
-  // Memory consent — DEFAULT-YES ([Y/n]: Enter or y → install).
+  // Memory consent — DEFAULT-YES ([Y/n]: Enter or y → install). Records the decision
+  // and advances to the voice consent (the install itself runs post-Ink). Then → voice.
+  useInput(
+    (input, key) => {
+      if (input === 'n' || input === 'N') {
+        setMemoryConsent(false)
+        setPhase('voice')
+      } else if (input === 'y' || input === 'Y' || key.return) {
+        setMemoryConsent(true)
+        setPhase('voice')
+      }
+    },
+    { isActive: phase === 'memory' },
+  )
+
+  // Voice consent — DEFAULT-YES ([Y/n]: Enter or y → install). The LAST consent → finish.
   useInput(
     (input, key) => {
       if (input === 'n' || input === 'N') finish(false)
       else if (input === 'y' || input === 'Y' || key.return) finish(true)
     },
-    { isActive: phase === 'memory' },
+    { isActive: phase === 'voice' },
   )
 
   // Declined → exit 1 (no host mutation).
   useEffect(() => {
     if (phase !== 'declined') return
-    onResult({ code: 1, memoryConsent: false, telegramConsent: false, advisories: [], summary: ['onboard aborted — risk not accepted.'] })
+    onResult({ code: 1, memoryConsent: false, voiceConsent: false, telegramConsent: false, advisories: [], summary: ['onboard aborted — risk not accepted.'] })
     const t = setTimeout(() => exit(), 30)
     return () => clearTimeout(t)
   }, [phase, onResult, exit])
@@ -305,7 +322,7 @@ export function OnboardApp({
     return <Text color="red">onboard aborted — risk not accepted.</Text>
   }
 
-  // running | telegram | memory | finishing
+  // running | telegram | memory | voice | finishing
   return (
     <Box flexDirection="column">
       <Box marginBottom={1}>
@@ -352,6 +369,14 @@ export function OnboardApp({
           <Text dimColor> Gives your agents a shared knowledge vault. [Y/n]</Text>
         </Box>
       ) : null}
+      {phase === 'voice' ? (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold color="cyan">
+            ? Install the voice provider backend (@agfpd/voice-connect)?
+          </Text>
+          <Text dimColor> A local text-to-speech / speech-to-text HTTP service. Per-agent voice tools are a separate `iapeer enable`. [Y/n]</Text>
+        </Box>
+      ) : null}
     </Box>
   )
 }

package/src/tui/onboard/run.tsx

@@ -71,7 +71,7 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
   // wizard only runs on one), off under NO_COLOR.
   const a = makeAnsi(colorEnabled(env, process.stdout))
 
-  let result: WizardResult = { code: 0, memoryConsent: false, telegramConsent: false, advisories: [], summary: [] }
+  let result: WizardResult = { code: 0, memoryConsent: false, voiceConsent: false, telegramConsent: false, advisories: [], summary: [] }
   try {
     const app = render(<OnboardApp env={env} onResult={r => (result = r)} />)
     await app.waitUntilExit()
@@ -79,9 +79,10 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
     return WIZARD_NOT_INTERACTIVE
   }
 
-  // Post-Ink interactive provisioning — telegram THEN memory (the canonical order:
-  // telegram creates the human peer that memory's --human resolves from). These own
-  // the terminal (inherited stdio / readline), so they run AFTER Ink unmounts (no
+  // Post-Ink interactive provisioning — telegram THEN memory THEN voice (the canonical
+  // order: telegram creates the human peer that memory's --human resolves from; voice is
+  // an independent host backend). These own the terminal (inherited stdio / readline),
+  // so they run AFTER Ink unmounts (no
   // contention). NON-WEDGE: ignore SIGINT in the parent so Ctrl-C kills only the
   // CURRENT step's child/readline and onboard continues to the summary, instead of
   // the whole flow dying. The no-op handler is queued past the blocking spawnSync.
@@ -136,6 +137,33 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
         '\n' + paintResult('memory', 'skipped', ' — set it up later with `npx @agfpd/iapeer-memory init`', a) + '\n',
       )
     }
+
+    if (result.voiceConsent) {
+      const { onboardVoiceProvider } = await import('../../onboard/voice.ts')
+      process.stdout.write(
+        '\n' +
+          a.bold('Installing the voice provider backend (@agfpd/voice-connect)…') +
+          '\n' +
+          a.dim(
+            'A local TTS/STT HTTP service. Voice is OPTIONAL: press Ctrl-C to skip it\n' +
+              '(set it up later with `npx @agfpd/voice-connect init`).',
+          ) +
+          '\n\n',
+      )
+      try {
+        const v = await onboardVoiceProvider({ env, timeoutMs: 12 * 60_000 })
+        const label = v.provider ? `${v.provider.provider} ${v.provider.version}` : 'none'
+        const rest = `${v.detail ? ` — ${v.detail}` : ''} ${a.dim(`(slot: ${label})`)}`
+        process.stdout.write('\n' + paintResult('voice', v.state, rest, a) + '\n')
+      } catch (e) {
+        const rest = ` — ${e instanceof Error ? e.message : String(e)} ${a.dim('(set up later: `npx @agfpd/voice-connect init`)')}`
+        process.stdout.write('\n' + paintResult('voice', 'step skipped', rest, a) + '\n')
+      }
+    } else {
+      process.stdout.write(
+        '\n' + paintResult('voice', 'skipped', ' — set it up later with `npx @agfpd/voice-connect init`', a) + '\n',
+      )
+    }
   } finally {
     process.removeListener('SIGINT', ignore)
     for (const h of prevInt) process.on('SIGINT', h as NodeJS.SignalsListener)

package/src/update/index.ts

@@ -51,6 +51,7 @@ import { defaultDaemonSocketPath } from '../daemon/index.ts'
 // shapes but receives the component-updaters as injected deps.
 import type { UpdateRuntimeResult } from '../runtime/update.ts'
 import type { MemoryUpdateResult } from '../onboard/memory.ts'
+import type { VoiceUpdateResult } from '../onboard/voice.ts'
 
 /** The npm package the foundation publishes / updates from. */
 export const IAPEER_PACKAGE = '@agfpd/iapeer'
@@ -320,10 +321,10 @@ export function updateIapeer(deps: UpdateDeps = {}): UpdateResult {
 // ─────────────────────────────────────────────────────────────────────────────
 // cascadeTail — the runtimes + memory legs of the cascade `iapeer update` (FU12).
 // Runs AFTER a healthy foundation update (the CLI owns that, abort-on-hard-fail);
-// here we update every installed runtime then the memory provider, BEST-EFFORT — a
-// component failure is reported, never aborts the rest. Pure orchestration over
-// injected component-updaters (no value-import of runtime/onboard → no cycle), so it
-// is hermetically testable. Returns whether anything failed (→ exit≠0).
+// here we update every installed runtime, then the memory provider, then the voice
+// provider, BEST-EFFORT — a component failure is reported, never aborts the rest. Pure
+// orchestration over injected component-updaters (no value-import of runtime/onboard →
+// no cycle), so it is hermetically testable. Returns whether anything failed (→ exit≠0).
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface CascadeTailDeps {
@@ -331,6 +332,8 @@ export interface CascadeTailDeps {
   runtimes: () => Promise<UpdateRuntimeResult[]>
   /** = updateMemoryProvider (onboard/memory.ts). */
   memory: () => MemoryUpdateResult | Promise<MemoryUpdateResult>
+  /** = updateVoiceProvider (onboard/voice.ts). */
+  voice: () => VoiceUpdateResult | Promise<VoiceUpdateResult>
   out: (s: string) => void
 }
 
@@ -353,5 +356,10 @@ export async function cascadeTail(deps: CascadeTailDeps): Promise<{ failed: bool
   deps.out(`memory: ${m.state}${m.package ? ` (${m.package}${mver})` : ''}${m.detail ? ` — ${m.detail}` : ''}\n`)
   if (m.state === 'failed') failed = true
 
+  const v = await deps.voice()
+  const vver = v.from || v.to ? ` ${v.from ?? '?'} → ${v.to ?? '?'}` : ''
+  deps.out(`voice: ${v.state}${v.package ? ` (${v.package}${vver})` : ''}${v.detail ? ` — ${v.detail}` : ''}\n`)
+  if (v.state === 'failed') failed = true
+
   return { failed }
 }