@agfpd/voicetalk-runtime 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to **@agfpd/voicetalk-runtime** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-26
+
+### Added
+
+- Native voice hand-off (pilot, `interfaces.voicetalk.native_voice` or
+  `VOICETALK_NATIVE_VOICE`): an accepted spoken wake for a listed target releases the
+  microphone (capture exit confirmed) and asks iapeer to open the peer's native Codex
+  `/voice` (`iapeer voice open|status|close <peer> --json`). The microphone returns to
+  wake mode only on a confirmed `closed`; failed/timed-out opens and unreadable receipts
+  keep it released. One wake → one open; outbound speech and earcons are held while the
+  peer owns the room; a restart adopts a still-open voice. Start-up preflight: if
+  `iapeer voice status` gives no readable answer, the target degrades to the STT path
+  (`native.unavailable`) instead of a listener that could never get its mic back.
+- `interface --native-voice <peers>`; `Microphone.pause()/resume()` (replay skips the
+  handed-off span); `scripts/replay-dialogue.sh` gains a fake `iapeer voice` and a
+  `native-voice.pcm` fixture.
+
+## [0.3.3] - 2026-10-18
+
+### Fixed
+
+- Self-install publishes the binary and manifest as one pair. 0.3.1 and the
+  unpublished 0.3.2 replaced the binary before writing the manifest, so a manifest
+  failure (reproduced with a real ENOTDIR) left the new binary next to the old
+  manifest. The manifest is now staged first; a manifest rename failure restores the
+  previous binary inode/signature/mode or removes a first-install binary, and a
+  failed rollback reports the retained recovery path.
+- Under `IAPEER_TEST_SANDBOX=1` self-install refuses to run unless both
+  `IAPEER_BIN_DIR` and `IAPEER_ROOT` are explicit.
+
+### Added
+
+- `scripts/verify-install.ts` (+ `verify-install-pair.ts`) shipped in the package:
+  a standalone native macOS proof run from the unpacked archive, including a live
+  headless router run of the installed binary.
+- `repository.url` and a dispatch-only `publish.yml` (npm trusted publishing, exact
+  accepted bytes: pack → sha256 check → native proof → publish → registry integrity).
+
+## [0.3.2] - 2026-10-06
+
+### Fixed
+
+- macOS self-install strictly verifies the staged executable after compile/copy and
+  chmod, before publishing the binary or manifest. Only an invalid signature is
+  repaired with ad-hoc signing, followed by another strict verification. Valid
+  signatures are preserved; verifier/repair failures leave the previous binary and
+  manifest untouched and remove staging files (including partial compiler output).
+
+### Added
+
+- Injectable command/platform seams, ordering and failure tests for both install
+  paths, and real macOS compile/execute/copy-self/repair/refusal acceptance in a
+  disposable sandbox. The acceptance test can target an unpacked npm artifact and
+  runs the installed binary's text router E2E without live audio or fleet delivery.
+
+## [0.3.1] - 2026-07-24
+
+### Fixed
+
+- Wake recognition is decoded without the configured names as a Whisper
+  `initial_prompt`. The prompt was generative context, not acoustic evidence: on
+  degraded but name-free speech it could manufacture an exact configured name and
+  wake an agent.
+- A closed dialogue now activates only from an exact leading address. Inexact
+  candidates, repeated-token decoder loops, and transcripts whose body merely echoes
+  configured names fail closed before `turn.open` and IAP delivery. Open-dialogue
+  continuation remains unchanged.
+
+### Added
+
+- A private bounded ring (`tmp/wake-captures`, 16 candidate segments by default)
+  retains the WAV plus the routing verdict, transcript, audio measurements, and PCM
+  hash for accepted and rejected wake candidates. This makes a disputed activation
+  replayable through `VOICETALK_MIC_FILE` without continuous room recording.
+
+## [0.1.0] - 2026-06-22
+
+### Added — Фаза 2 (runtime skeleton; text caркас, audio stubbed)
+
+- `run` — the bidirectional router loop. Outbound: an `<iap>…</iap>` reader on STDIN
+  (CDATA-aware) hands each envelope to an `AudioSink`; inbound: a per-owner unix socket
+  receives utterances and delivers them to the fleet. Audio touchpoints are stubbed —
+  the sink logs the spoken text (and appends to `spoken.log`), the socket stands in for
+  mic + wake-word + STT. The seams are the `voice-connect` plug-in points for Фаза 3.
+- `say --peer <personality> <text…>` — inject an utterance over the running router's
+  inbound socket (the Фаза-2 mic+STT stand-in). Frames the text for the spoken modality
+  and delivers it via the daemon (`iapeer send`) from the owner's identity
+  (`from-runtime=voicetalk`).
+- `src/manifest.ts` — `RuntimeManifest` self-deploy (operator-add: no `peers[]`),
+  IAPEER_ROOT-aware, atomic + idempotent.
+- `src/selfInstall.ts` + bare/`self-install` — npx self-deploy: compiled launcher on
+  PATH + manifest + on-host docs. `src/hostDocs.ts` mirrors the foundation scaffolder.
+- `src/selfConfig.ts` + `self-config` — the per-peer hook merging
+  `interfaces.voicetalk` (`{ wake_word, device? }`) from env, preserving the
+  foundation-provisioned identity (`intelligence=natural`).
+- `interface --wake-word <w> [--device <d>]` — manual binding setter; `doctor` reports
+  the binding + manifest health.
+- Tests: envelope parsing, the inbound `iapeer send` wrapper (verdicts/timeout),
+  manifest round-trip, the self-config hook, and a **live text E2E** that drives the
+  actual `run` process both directions with the daemon faked.
+- No sender-guard (decision: the speaker is a single local endpoint of the owner; any
+  fleet peer may answer by voice).
+
+## [0.0.1] - 2026-06-21
+
+### Added
+
+- Project scaffold: bun package skeleton mirroring the iapeer runtime contract
+  (`package.json`, `tsconfig.json`, `bin/voicetalk-runtime`, `.gitignore`, CI).
+- `src/constants.ts` — package-facing contract values (`RUNTIME` = `voicetalk`,
+  `BIN_NAME`, `PACKAGE_NAME`, `VERSION`, `NAME_RE`).
+- `src/cli.ts` — CLI skeleton: `run` (Фаза-0 stub), `doctor`, `--version`,
+  `--help`. The audio pipeline (wake-word / STT / TTS) is not implemented yet.
+- Smoke tests (`tests/cli.test.ts`) and the test + typecheck CI gate.
+
+[Unreleased]: https://github.com/agfpd/voicetalk-runtime/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/agfpd/voicetalk-runtime/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/agfpd/voicetalk-runtime/compare/v0.3.0...v0.3.1
+[0.1.0]: https://github.com/agfpd/voicetalk-runtime/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/agfpd/voicetalk-runtime/releases/tag/v0.0.1

package/docs/README.md

@@ -46,6 +46,37 @@ decoder prompt, because prompt text can be generated back on unrelated audio. A
 dialogue opens only on an exact leading address in the unprimed transcript; repeated
 token loops and name-only echoes are rejected before an IAP envelope exists.
 
+## Native voice — `native_voice` (pilot)
+
+```jsonc
+{ "native_voice": ["darwin"] }     // or env VOICETALK_NATIVE_VOICE=darwin ("" disables)
+```
+
+For a target listed here an accepted wake word does NOT start STT → envelope → TTS. It
+hands the conversation to the peer's own realtime voice (Codex CLI `/voice`) inside its
+live session, which iapeer opens and closes:
+
+1. The wake word must pass every fail-closed check above — native voice changes only
+   what an accepted activation does, never what counts as one.
+2. voicetalk kills its capture process and waits until it has actually exited (no
+   CoreAudio client left), plays the short "heard you" earcon while nobody is
+   listening, then runs `iapeer voice open <peer> --json`.
+3. While the peer holds the room voicetalk stays silent: no earcons, and any agent
+   answer that arrives is spoken only after the hand-off ends.
+4. voicetalk polls `iapeer voice status <peer> --json` (1 s) and takes the microphone
+   back ONLY on `state: closed`. A failed or timed-out open, an unreadable answer, and
+   `opening`/`closing` all keep the microphone released — a timeout is not evidence
+   that the peer stopped listening. Idle-close is iapeer's; after a 30-minute ceiling
+   (`VOICETALK_NATIVE_MAX_MS`) voicetalk asks `iapeer voice close`, and still waits for
+   the confirmed `closed`.
+5. Back in wake mode a soft "door closed" tone plays; the next turn needs a name again.
+   A runtime restart adopts a voice that is still open instead of grabbing the mic.
+   If at start iapeer does not answer `voice status` at all, the target falls back to
+   the STT path (`native.unavailable` in the log).
+
+The words spoken after the name in the activating phrase are not forwarded; the
+conversation itself happens in the peer's native voice. Other targets keep the STT path.
+
 ## How a turn works
 
 1. The microphone runs always-on; energy endpointing cuts an utterance when the
@@ -97,6 +128,55 @@ still performed and timed. `scripts/replay-dialogue.sh` wires both into a sandbo
   `VOICETALK_VOICE_ENDPOINT`).
 - Microphone permission (TCC) granted once to the process that runs the runtime.
 
+## Install integrity on macOS
+
+Bare invocation (`npx -y @agfpd/voicetalk-runtime@<version>`) and `self-install`
+stage the compiled or copied executable beside its destination. After chmod, before
+binary rename and manifest publication, `/usr/bin/codesign --verify --deep --strict`
+must pass. If the signature is invalid, the installer runs `--force --sign -` on
+that staging file, then strictly verifies again. Verification-tool failures or an
+unsuccessful repair abort installation, retain the previous binary and manifest,
+and remove the staging file. No core/helper package dependency is required.
+
+A valid signature is never replaced. Repair may change the TCC identity and require
+permission to be granted again; this gate checks local signature integrity, not
+notarization or code provenance. See Apple's
+[code-signing verification guidance](https://developer.apple.com/library/archive/technotes/tn2206/).
+
+The binary and manifest are published as one pair. The manifest is staged before
+the binary is published, and the previous binary is kept as a hard link until the
+manifest rename succeeds. If any catchable I/O error happens after the binary is in
+place (for example ENOTDIR or EACCES), the previous binary inode, signature and mode
+are restored, or a first-install binary is removed. If that rollback also fails, the
+error names the path that still holds the previous binary. This is not atomic across
+power loss, SIGKILL or concurrent installers.
+
+Artifact proof shipped in the package (macOS, Bun, system tools; no checkout,
+daemon, microphone, speaker or voice service):
+
+```sh
+mkdir /tmp/vt-proof && tar -xzf /absolute/agfpd-voicetalk-runtime-<version>.tgz -C /tmp/vt-proof
+bun /tmp/vt-proof/package/scripts/verify-install.ts \
+  [/tmp/vt-proof/package] [/absolute/previous-package-dir] [/absolute/recovery-backup-dir]
+```
+
+It compiles through the shipped CLI under strict codesign, runs the installed router
+headless (doctor, outbound envelope to the audio sink, inbound `say` to a stub
+daemon), checks copy-self, unsigned repair, real ENOTDIR and late EACCES with the
+previous pair preserved, rejection of a truncated Mach-O and of a strict-invalid
+minimal compile, and exact recovery of the previous pair. All writes go to a
+temporary `/tmp/vtp-*` sandbox that is removed afterwards. Passing an unpacked
+previous package also reproduces that installer's ENOTDIR defect as a
+before-and-after contrast. It does not prove live audio or delivery to a real fleet.
+
+Developer acceptance (macOS, no live channel mutation):
+
+```sh
+bun test tests/installSignature.test.ts tests/selfInstall.test.ts tests/selfInstall-macos.test.ts
+# To repeat real acceptance against an unpacked npm tarball:
+VOICETALK_INSTALL_PACKAGE_ROOT=/absolute/path/to/package bun test tests/selfInstall-macos.test.ts
+```
+
 These pages are written as each phase lands. Russian translation lives in
 [`ru/`](ru/README.md).
 

package/docs/ru/README.md

@@ -46,6 +46,37 @@ prompt: такой контекст способен сам породить и
 открывает только точное имя в начале непримированного транскрипта; циклы повторяющихся
 токенов и тело из одних настроенных имён отбрасываются до появления IAP-конверта.
 
+## Нативный голос — `native_voice` (пилот)
+
+```jsonc
+{ "native_voice": ["darwin"] }     // или env VOICETALK_NATIVE_VOICE=darwin ("" выключает)
+```
+
+Для перечисленного адресата принятое wake-слово НЕ запускает STT → конверт → TTS, а
+передаёт разговор в собственный realtime-голос пира (Codex CLI `/voice`) в его живой
+сессии; открывает и закрывает голос iapeer.
+
+1. Wake-слово проходит все fail-closed проверки выше: режим меняет только то, что делает
+   принятая активация, но не то, что ею считается.
+2. voicetalk гасит процесс захвата и ждёт его фактического выхода (CoreAudio-клиента
+   нет), играет короткий earcon «услышал», пока никто не слушает, и вызывает
+   `iapeer voice open <peer> --json`.
+3. Пока комната у пира, voicetalk молчит: ни earcon'ов, а пришедший ответ агента
+   озвучивается только после возврата микрофона.
+4. voicetalk опрашивает `iapeer voice status <peer> --json` (1 с) и забирает микрофон
+   ТОЛЬКО по `state: closed`. Неудачный или просроченный open, нечитаемый ответ,
+   `opening`/`closing` — микрофон остаётся отпущенным: таймаут не доказывает, что пир
+   перестал слушать. Закрытие по простою — у iapeer; по потолку 30 минут
+   (`VOICETALK_NATIVE_MAX_MS`) voicetalk просит `iapeer voice close` и всё равно ждёт
+   подтверждённого `closed`.
+5. По возврату в wake-режим звучит мягкий тон «дверь закрыта»; следующий ход снова
+   требует имени. Рестарт рантайма принимает ещё открытый голос, а не хватает микрофон.
+   Если на старте iapeer вообще не отвечает на `voice status`, адресат уходит на прежний
+   STT-путь (`native.unavailable` в логе).
+
+Слова после имени в активирующей фразе не пересылаются — разговор идёт уже нативным
+голосом пира. Остальные адресаты — прежним STT-путём.
+
 ## Как устроен ход разговора
 
 1. Микрофон слушает постоянно; энергетический эндпойнтер закрывает реплику по паузе
@@ -96,6 +127,55 @@ JSON-вердикт в `<IAPEER_ROOT>/runtimes/voicetalk/tmp/wake-captures`. К
   (переопределяется `VOICETALK_VOICE_ENDPOINT`).
 - Разрешение на микрофон (TCC), выданное один раз процессу рантайма.
 
+## Целостность установки на macOS
+
+Запуск без подкоманды (`npx -y @agfpd/voicetalk-runtime@<версия>`) и `self-install`
+собирают или копируют исполняемый файл во временный файл рядом с целевым бинарником.
+После chmod, до rename бинарника и публикации манифеста, обязательна проверка
+`/usr/bin/codesign --verify --deep --strict`. Невалидная подпись исправляется
+`--force --sign -` только на этом временном файле, затем повторяется строгая проверка.
+Отказ средства проверки или неуспешное исправление прерывает установку: прежние
+бинарник и манифест не изменяются, временный файл удаляется. Зависимость от пакета
+ядра или его helper-модуля не требуется.
+
+Валидная подпись не переписывается. Исправление может изменить идентичность TCC и
+потребовать повторной выдачи разрешения; проверка подтверждает целостность локальной
+подписи, не нотариализацию или происхождение кода. См.
+[руководство Apple по проверке подписи](https://developer.apple.com/library/archive/technotes/tn2206/).
+
+Бинарник и манифест публикуются парой. Манифест готовится до публикации бинарника,
+а прежний бинарник сохраняется жёсткой ссылкой, пока rename манифеста не завершится.
+При перехватываемой ошибке ввода-вывода после замены бинарника (например, ENOTDIR или
+EACCES) восстанавливаются прежние inode, подпись и права бинарника, а бинарник первой
+установки удаляется. Если откат тоже не удался, ошибка называет путь к сохранённой
+копии. Атомарности при потере питания, SIGKILL и параллельных установщиках нет.
+
+Проверка артефакта поставляется в пакете (macOS, Bun, системные утилиты; без
+репозитория, демона, микрофона, динамика и голосового сервиса):
+
+```sh
+mkdir /tmp/vt-proof && tar -xzf /absolute/agfpd-voicetalk-runtime-<версия>.tgz -C /tmp/vt-proof
+bun /tmp/vt-proof/package/scripts/verify-install.ts \
+  [/tmp/vt-proof/package] [/absolute/previous-package-dir] [/absolute/recovery-backup-dir]
+```
+
+Скрипт собирает бинарник через поставляемый CLI со строгой проверкой подписи, запускает
+установленный роутер без аудио (doctor, исходящий конверт в аудиоприёмник, входящий
+`say` в подставной демон), проверяет copy-self, исправление неподписанной копии,
+реальные ENOTDIR и поздний EACCES с сохранением прежней пары, отказ усечённому Mach-O
+и строго невалидной минимальной сборке, точное восстановление прежней пары. Все записи
+идут во временную песочницу `/tmp/vtp-*`, которая затем удаляется. С распакованным
+предыдущим пакетом дополнительно воспроизводится дефект ENOTDIR его установщика как
+контраст «до/после». Живой звук и доставка реальному флоту не проверяются.
+
+Проверка разработчика на macOS без изменения живого канала:
+
+```sh
+bun test tests/installSignature.test.ts tests/selfInstall.test.ts tests/selfInstall-macos.test.ts
+# Повтор настоящей приёмки на распакованном npm-артефакте:
+VOICETALK_INSTALL_PACKAGE_ROOT=/absolute/path/to/package bun test tests/selfInstall-macos.test.ts
+```
+
 Страницы пишутся по мере прохождения фаз.
 
 ## Источники дизайна

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "@agfpd/voicetalk-runtime",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Voice runtime-router for IAP peers.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agfpd/voicetalk-runtime.git"
+  },
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
     "voicetalk-runtime": "bin/voicetalk-runtime"
   },
   "files": [
+    "CHANGELOG.md",
     "bin/",
     "src/",
     "docs/*.md",
     "docs/ru/",
+    "scripts/verify-install.ts",
+    "scripts/verify-install-pair.ts",
     "tsconfig.json"
   ],
   "scripts": {

package/scripts/verify-install-pair.ts

@@ -0,0 +1,145 @@
+// Real filesystem regression, imported by the shipped standalone proof.
+import { strict as assert } from 'assert'
+import { execFileSync } from 'child_process'
+import { createHash } from 'crypto'
+import { chmodSync, copyFileSync, cpSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs'
+import { dirname, join, relative } from 'path'
+import type { selfInstall as Install } from '../src/selfInstall.ts'
+
+type Tree = Record<string, { mode: number; kind: string; sha256?: string }>
+const hash = (path: string) => createHash('sha256').update(readFileSync(path)).digest('hex')
+function tree(path: string): Tree {
+  const result: Tree = {}
+  const walk = (p: string) => {
+    const s = lstatSync(p)
+    assert.ok(s.isDirectory() || s.isFile(), `proof fixture must not contain symlinks: ${p}`)
+    result[relative(path, p) || '.'] = { mode: s.mode & 0o7777, kind: s.isDirectory() ? 'dir' : 'file',
+      ...(s.isFile() ? { sha256: hash(p) } : {}) }
+    if (s.isDirectory()) for (const name of readdirSync(p).sort()) walk(join(p, name))
+  }
+  walk(path)
+  return result
+}
+function copyExact(source: string, dest: string): void {
+  mkdirSync(dirname(dest), { recursive: true })
+  if (lstatSync(source).isDirectory()) cpSync(source, dest, { recursive: true })
+  else copyFileSync(source, dest)
+  for (const [name, node] of Object.entries(tree(source))) chmodSync(name === '.' ? dest : join(dest, name), node.mode)
+  assert.deepEqual(tree(dest), tree(source))
+}
+
+export async function proveInstallPair(options: {
+  pkg: string; tmp: string; env: NodeJS.ProcessEnv; candidateBin: string; selfInstall: typeof Install
+  run: (bin: string, version: string, env: NodeJS.ProcessEnv) => Promise<void>
+  previousPkg?: string; recoveryBackup?: string
+}): Promise<void> {
+  const { pkg, tmp, candidateBin, selfInstall, run } = options
+  const version = JSON.parse(readFileSync(join(pkg, 'package.json'), 'utf8')).version as string
+  const env = { ...options.env, IAPEER_ROOT: join(tmp, 'pair-root'), IAPEER_BIN_DIR: join(tmp, 'pair-bin') }
+  const bin = join(env.IAPEER_BIN_DIR, 'voicetalk-runtime')
+  const manifest = join(env.IAPEER_ROOT, 'runtimes/voicetalk/runtime.json')
+  const docs = join(env.IAPEER_ROOT, 'docs/voicetalk-runtime')
+  const strict = (path: string) => execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', path], { env })
+  const runningVersion = () => execFileSync(bin, ['--version'], { env, encoding: 'utf8' }).trim()
+  const targets = { bin, manifest, docs }
+  const saved = join(tmp, 'pair-backup')
+  if (options.recoveryBackup) {
+    // Optional readonly accepted host backup. It is NEVER a destination.
+    const baseline = JSON.parse(readFileSync(join(options.recoveryBackup, 'baseline.json'), 'utf8'))
+    for (const [key, dest] of Object.entries(targets)) {
+      const entry = baseline.paths[key === 'bin' ? 'binary' : key]
+      const source = join(options.recoveryBackup, entry.backup)
+      const inventory = tree(source)
+      for (const [name, node] of Object.entries(inventory)) {
+        assert.equal(node.mode, entry.tree[name].mode)
+        assert.equal(node.kind, entry.tree[name].kind)
+        if (node.kind === 'file') assert.equal(node.sha256, entry.tree[name].sha256)
+      }
+      assert.equal(Object.keys(inventory).length, Object.keys(entry.tree).length)
+      copyExact(source, dest)
+    }
+  } else {
+    // Self-contained old native fixture: same working application, deliberately
+    // distinct valid ad-hoc signature. No host binary/backup is required.
+    mkdirSync(dirname(bin), { recursive: true })
+    copyFileSync(candidateBin, bin)
+    execFileSync('/usr/bin/codesign', ['--force', '--sign', '-', '--identifier', 'voicetalk-runtime.proof.previous', bin], { env })
+    mkdirSync(dirname(manifest), { recursive: true })
+    writeFileSync(manifest, `${JSON.stringify({ runtime: 'voicetalk', version, selfConfig: { command: bin, args: ['self-config'] } }, null, 4)}\n\n`)
+    mkdirSync(docs, { recursive: true })
+    for (const name of readdirSync(join(pkg, 'docs')).filter(n => n.endsWith('.md'))) copyExact(join(pkg, 'docs', name), join(docs, name))
+  }
+  strict(bin)
+  const oldVersion = runningVersion()
+  assert.equal(JSON.parse(readFileSync(manifest, 'utf8')).version, oldVersion)
+  assert.notEqual(hash(bin), hash(candidateBin), 'old native must differ, otherwise replacement is invisible')
+  for (const [key, path] of Object.entries(targets)) copyExact(path, join(saved, key))
+  const before = () => Object.fromEntries(Object.entries(targets).map(([key, path]) => [key, tree(path)]))
+  const original = before()
+  await run(bin, oldVersion, env)
+  const manifestDirEntries = readdirSync(dirname(manifest)).sort() // the router creates its inbox/spoken.log here
+  const blocked = join(tmp, 'not-a-root')
+  writeFileSync(blocked, 'ordinary file occupying IAPEER_ROOT')
+  const copyOptions = { env, sourceEntry: join(tmp, 'missing-pair-entry.ts'), execPath: candidateBin, docsSource: join(pkg, 'docs') }
+
+  if (options.previousPkg) {
+    const { selfInstall: previousInstall } = await import(join(options.previousPkg, 'src/selfInstall.ts')) as { selfInstall: typeof Install }
+    assert.throws(() => previousInstall({ ...copyOptions, env: { ...env, IAPEER_ROOT: blocked } }), /ENOTDIR/)
+    assert.equal(hash(bin), hash(candidateBin), 'previous installer must reproduce the binary replacement defect')
+    assert.deepEqual(tree(manifest), original.manifest)
+    console.log('BEFORE reproduced: published previous installer ENOTDIR leaves NEW binary + OLD manifest')
+    copyExact(join(saved, 'bin'), bin + '.restore.tmp')
+    strict(bin + '.restore.tmp'); renameSync(bin + '.restore.tmp', bin)
+    assert.deepEqual(before(), original)
+  }
+
+  assert.throws(() => selfInstall({ ...copyOptions, env: { ...env, IAPEER_ROOT: blocked } }), /ENOTDIR/)
+  assert.deepEqual(before(), original)
+  assert.equal(readFileSync(blocked, 'utf8'), 'ordinary file occupying IAPEER_ROOT')
+  assert.deepEqual(readdirSync(env.IAPEER_BIN_DIR), ['voicetalk-runtime'])
+  console.log(`AFTER real ENOTDIR: old pair unchanged, bin=${hash(bin)} manifest=${hash(manifest)}`)
+
+  const inode = lstatSync(bin).ino
+  let attempts = 0
+  let failure: unknown
+  try {
+    selfInstall({ ...copyOptions, publishRename: (from, to) => {
+      attempts++
+      if (to !== manifest) return renameSync(from, to)
+      assert.equal(hash(bin), hash(candidateBin), 'late failure must happen AFTER binary publication')
+      assert.deepEqual(tree(manifest), original.manifest)
+      const mode = lstatSync(dirname(manifest)).mode & 0o7777
+      chmodSync(dirname(manifest), 0o555)
+      try { renameSync(from, to) } // real OS error, not a mocked rename result
+      finally { chmodSync(dirname(manifest), mode) }
+    } })
+  } catch (e) { failure = e }
+  assert.equal((failure as NodeJS.ErrnoException)?.code, 'EACCES', `expected real unprivileged EACCES, got ${failure}`)
+  assert.equal(attempts, 3, 'binary rename, failed manifest rename, old inode rollback')
+  assert.equal(lstatSync(bin).ino, inode)
+  assert.deepEqual(before(), original)
+  strict(bin)
+  assert.deepEqual(readdirSync(env.IAPEER_BIN_DIR), ['voicetalk-runtime'])
+  assert.deepEqual(readdirSync(dirname(manifest)).sort(), manifestDirEntries)
+  console.log(`AFTER real late EACCES: binary inode/signature/mode restored, manifest unchanged; version=${oldVersion}`)
+  await run(bin, oldVersion, env)
+
+  // Successful native install, then verify-only recovery of all three surfaces.
+  selfInstall(copyOptions)
+  strict(bin); assert.equal(runningVersion(), version)
+  assert.equal(JSON.parse(readFileSync(manifest, 'utf8')).version, version)
+  await run(bin, version, env)
+  const installed = before()
+  for (const [key, path] of Object.entries(targets)) copyExact(join(saved, key), path + '.restore.tmp')
+  strict(bin + '.restore.tmp')
+  assert.deepEqual(before(), installed, 'stage ALL recovery surfaces before replacing ANY')
+  renameSync(bin + '.restore.tmp', bin)
+  renameSync(manifest + '.restore.tmp', manifest)
+  renameSync(docs, docs + '.candidate.saved')
+  try { renameSync(docs + '.restore.tmp', docs) }
+  catch (e) { renameSync(docs + '.candidate.saved', docs); throw e }
+  assert.deepEqual(before(), original)
+  strict(bin); assert.equal(runningVersion(), oldVersion)
+  await run(bin, oldVersion, env)
+  console.log(`PASS native recovery ${oldVersion} -> ${version} -> ${oldVersion}: exact binary/manifest/docs bytes+modes, original signature`)
+}