@agfpd/voicetalk-runtime 0.3.0 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# 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.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/README.md

@@ -61,11 +61,17 @@ runs the same router text-only, with no microphone at all. Configuration details
 - **Modality framing for a naive agent.** An agent has no senses — only envelope text. voicetalk marks the inbound envelope so a peer with no knowledge of the system answers in the right modality ("spoken, live — reply by voice, briefly").
 - **Voice stays out of the core.** Speech-to-text and text-to-speech live in the shared `voice-connect` service (multi-provider, one place to configure), not inside this runtime and not inside the iapeer foundation.
 - **Conversational turn-taking.** A wake-word only opens a conversation; after a reply, an open-mic window lets the next utterance continue without re-triggering. Endpointing and earcons are owned here, inside the audio session — the agent only sees the next message.
+- **Wake evidence fails closed.** Configured names are never injected into Whisper's
+  decoder prompt: only an exact leading name heard in the unprimed transcript can open
+  a dialogue, and repeated-name decoder loops are discarded before IAP delivery.
 
 ## What it does not do (yet)
 
 - No barge-in: the owner cannot interrupt a spoken answer by talking over it (that needs acoustic echo cancellation plus a neural VAD). While the runtime speaks, it does not listen.
-- Wake detection runs on the transcript, not on an acoustic wake-word model — so a wake word costs one line of config and no training, at the price of transcribing every voiced segment. An acoustic pre-gate is the Фаза-4 latency upgrade.
+- Wake detection runs on an unprimed transcript, not on an acoustic wake-word model —
+  so a wake word costs one line of config and no training, at the price of transcribing
+  every voiced segment. A bounded private ring retains wake-candidate segments for
+  replayable diagnostics; an acoustic pre-gate remains the stronger future upgrade.
 - Single host, single owner, local microphone and speaker. Multi-device and multi-owner are out of scope for the MVP.
 
 ## Roadmap

package/docs/README.md

@@ -41,6 +41,11 @@ self-config hook. `voicetalk-runtime devices` lists the host's inputs;
 `voicetalk-runtime doctor` reports the whole contour (binding, wake map,
 voice-connect, microphone).
 
+Wake evidence is fail-closed. The configured vocabulary is never passed as a Whisper
+decoder prompt, because prompt text can be generated back on unrelated audio. A closed
+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.
+
 ## How a turn works
 
 1. The microphone runs always-on; energy endpointing cuts an utterance when the
@@ -69,7 +74,14 @@ Everything is tunable by env: `VOICETALK_AUDIO=0` (text-only, no microphone),
 `VOICETALK_FOLLOWUP_MS`, `VOICETALK_HANGOVER_MS`, `VOICETALK_VAD_MIN_RMS`,
 `VOICETALK_VAD_RATIO`, `VOICETALK_STT_LANG`, `VOICETALK_STT_ENGINE`,
 `VOICETALK_TTS_MAX_CHARS`, `VOICETALK_EARCONS=0`, `VOICETALK_COMPOSE_MS`,
-`VOICETALK_COMPOSE_UNFINISHED_MS`, `VOICETALK_TURN_MAX_MS`.
+`VOICETALK_COMPOSE_UNFINISHED_MS`, `VOICETALK_TURN_MAX_MS`,
+`VOICETALK_WAKE_CAPTURE=0` (disable the default diagnostic ring), and
+`VOICETALK_WAKE_CAPTURE_MAX` (default 16).
+
+Every transcript that resembles a configured wake is retained as a mode-0600 WAV plus
+JSON verdict under `<IAPEER_ROOT>/runtimes/voicetalk/tmp/wake-captures`. The ring is
+bounded and contains candidate utterances only, not continuous room audio. Replay a
+disputed segment through the same paced microphone path described below.
 
 Two seams exist for testing turn-taking without touching a live channel:
 `VOICETALK_MIC_FILE=<pcm>` replays a recording through the microphone path (paced in
@@ -85,6 +97,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

@@ -41,6 +41,11 @@ self-config-хука (`VOICETALK_WAKE_WORDS`, `VOICETALK_DEFAULT_TARGET`,
 `voicetalk-runtime doctor` — весь контур целиком (привязка, карта, voice-connect,
 микрофон).
 
+Wake-сигнал работает fail-closed. Настроенные имена не передаются Whisper как decoder
+prompt: такой контекст способен сам породить имя на постороннем аудио. Закрытый диалог
+открывает только точное имя в начале непримированного транскрипта; циклы повторяющихся
+токенов и тело из одних настроенных имён отбрасываются до появления IAP-конверта.
+
 ## Как устроен ход разговора
 
 1. Микрофон слушает постоянно; энергетический эндпойнтер закрывает реплику по паузе
@@ -68,7 +73,14 @@ Earcon'ы размечают состояния: восходящий — мик
 `VOICETALK_FOLLOWUP_MS`, `VOICETALK_HANGOVER_MS`, `VOICETALK_VAD_MIN_RMS`,
 `VOICETALK_VAD_RATIO`, `VOICETALK_STT_LANG`, `VOICETALK_STT_ENGINE`,
 `VOICETALK_TTS_MAX_CHARS`, `VOICETALK_EARCONS=0`, `VOICETALK_COMPOSE_MS`,
-`VOICETALK_COMPOSE_UNFINISHED_MS`, `VOICETALK_TURN_MAX_MS`.
+`VOICETALK_COMPOSE_UNFINISHED_MS`, `VOICETALK_TURN_MAX_MS`,
+`VOICETALK_WAKE_CAPTURE=0` (отключить диагностическое кольцо) и
+`VOICETALK_WAKE_CAPTURE_MAX` (по умолчанию 16).
+
+Каждый транскрипт, похожий на настроенный wake, сохраняется как WAV с правами 0600 и
+JSON-вердикт в `<IAPEER_ROOT>/runtimes/voicetalk/tmp/wake-captures`. Кольцо ограничено
+и хранит только сегменты-кандидаты, не непрерывную запись комнаты. Спорный сегмент
+можно прогнать через тот же микрофонный путь способом ниже.
 
 Для проверки turn-taking, не трогая живой канал, есть два шва: `VOICETALK_MIC_FILE=<pcm>`
 проигрывает запись через тот же путь, что и микрофон (в реальном темпе), а
@@ -84,6 +96,55 @@ Earcon'ы размечают состояния: восходящий — мик
   (переопределяется `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.0",
+  "version": "0.3.3",
   "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`)
+}