@agfpd/voicetalk-runtime 0.3.1 → 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/docs/README.md

@@ -97,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

@@ -96,6 +96,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.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`)
+}

package/scripts/verify-install.ts

@@ -0,0 +1,202 @@
+// Standalone real macOS install proof shipped IN the package. No dependencies,
+// daemon, keychain identities, lifecycle commands, microphone, speaker, voice
+// service or repository checkout required.
+// Usage after unpacking:
+//   bun package/scripts/verify-install.ts [package-dir] [previous-package-dir] [recovery-backup-dir]
+import { strict as assert } from 'assert'
+import { execFileSync, spawn, spawnSync, type ChildProcess } from 'child_process'
+import { createHash, randomUUID } from 'crypto'
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs'
+import { join, resolve } from 'path'
+import { proveInstallPair } from './verify-install-pair.ts'
+
+assert.equal(process.platform, 'darwin', 'real codesign proof requires macOS')
+const pkg = resolve(process.argv[2] ?? join(import.meta.dir, '..'))
+const { selfInstall } = await import(join(pkg, 'src/selfInstall.ts')) as typeof import('../src/selfInstall.ts')
+const version = JSON.parse(readFileSync(join(pkg, 'package.json'), 'utf8')).version as string
+// SHORT root on purpose: the router's inbound unix socket lives under IAPEER_ROOT and
+// macOS sun_path is ~104 bytes; $TMPDIR (/var/folders/…) would overflow it.
+const tmp = mkdtempSync('/tmp/vtp-')
+const fakeIap = join(tmp, 'fake-iapeer')
+// Do not inherit host credentials, daemon discovery, identity, audio or voice knobs.
+const env: NodeJS.ProcessEnv = {
+  PATH: process.env.PATH ?? '/usr/bin:/bin',
+  HOME: join(tmp, 'home'), TMPDIR: tmp,
+  IAPEER_TEST_SANDBOX: '1', IAPEER_ROOT: join(tmp, 'root'), IAPEER_BIN_DIR: join(tmp, 'bin'),
+  IAP_BIN: fakeIap, VOICETALK_AUDIO: '0', VOICETALK_PLAYBACK: '0',
+  VOICETALK_VOICE_ENDPOINT: 'http://127.0.0.1:1',
+}
+mkdirSync(env.HOME!, { recursive: true })
+const bin = join(env.IAPEER_BIN_DIR!, 'voicetalk-runtime')
+const manifest = join(env.IAPEER_ROOT!, 'runtimes/voicetalk/runtime.json')
+const hash = (path: string) => createHash('sha256').update(readFileSync(path)).digest('hex')
+const verify = () => execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', bin], { env })
+const runningVersion = () => execFileSync(bin, ['--version'], { env, encoding: 'utf8' }).trim()
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+let router: ChildProcess | undefined
+let routerExit: Promise<void> | undefined
+
+// Stand-in for the iapeer daemon: records argv + message body, never contacts a fleet.
+const argvFile = join(tmp, 'daemon-argv.txt')
+const bodyFile = join(tmp, 'daemon-body.txt')
+writeFileSync(fakeIap,
+  `#!/bin/sh\nprintf '%s\\n' "$*" > ${JSON.stringify(argvFile)}\n` +
+  `while [ "$#" -gt 0 ]; do\n  if [ "$1" = "--message-file" ]; then shift; cat "$1" > ${JSON.stringify(bodyFile)}; fi\n  shift || true\ndone\n` +
+  `printf '%s\\n' 'delivered to proof-target (claude)'\nexit 0\n`)
+chmodSync(fakeIap, 0o755)
+
+async function stopRouter(): Promise<void> {
+  if (!router || router.exitCode !== null || router.signalCode !== null) return
+  router.kill('SIGTERM') // ONLY the proof's own child, never a host runtime
+  await Promise.race([routerExit, sleep(3000)])
+  if (router.exitCode === null && router.signalCode === null) {
+    router.kill('SIGKILL')
+    await routerExit
+  }
+}
+
+async function waitFor(predicate: () => boolean, ms = 8000): Promise<boolean> {
+  const deadline = Date.now() + ms
+  while (Date.now() < deadline) {
+    if (predicate()) return true
+    await sleep(50)
+  }
+  return predicate()
+}
+
+/** The installed binary RUNS as a router: headless `run` (audio off) in a bound
+ *  natural peer, an outbound envelope reaches the audio sink, an inbound `say`
+ *  reaches the (fake) daemon framed for the spoken modality. */
+async function proveRunningRouter(executable = bin, expectedVersion = version, runEnv = env): Promise<void> {
+  assert.equal(execFileSync(executable, ['--version'], { env: runEnv, encoding: 'utf8' }).trim(), expectedVersion)
+  const peer = join(tmp, 'proof-owner')
+  mkdirSync(join(peer, '.iapeer'), { recursive: true })
+  writeFileSync(join(peer, '.iapeer/peer-profile.json'), JSON.stringify({
+    personality: 'proof-owner', default_runtime: 'voicetalk', runtimes: ['voicetalk'], intelligence: 'natural',
+    interfaces: { voicetalk: { wake_words: { 'проба': 'proof-target' }, default_target: 'proof-target' } },
+  }))
+  const doctor = spawnSync(executable, ['doctor', '--json'], { cwd: peer, env: runEnv, encoding: 'utf8' })
+  assert.equal(doctor.status, 0, `doctor: ${doctor.stdout}${doctor.stderr}`)
+  assert.equal(JSON.parse(doctor.stdout).ok, true)
+  rmSync(argvFile, { force: true }); rmSync(bodyFile, { force: true })
+  const root = runEnv.IAPEER_ROOT!
+  const sock = join(root, 'runtimes/voicetalk/inbox/proof-owner.sock')
+  assert.ok(Buffer.byteLength(sock) < 104, `socket path too long for sun_path: ${sock}`)
+  router = spawn(executable, ['run'], { cwd: peer, env: runEnv, stdio: ['pipe', 'pipe', 'pipe'] })
+  routerExit = new Promise<void>(resolve => router!.once('close', () => resolve()))
+  let stderr = ''
+  let spawnError: Error | undefined
+  router.once('error', error => { spawnError = error })
+  router.stdout!.resume()
+  router.stderr!.on('data', chunk => { stderr += String(chunk) })
+  try {
+    const up = await waitFor(() => { assert.ifError(spawnError); return existsSync(sock) })
+    assert.ok(up, `router never opened its inbound socket: ${stderr}`)
+    const outbound = `исходящее ${randomUUID()}`
+    router.stdin!.write('<iap from-personality="proof-target" from-runtime="claude" from-intelligence="artificial">' +
+      `<message><![CDATA[${outbound}]]></message></iap>`)
+    const spokenLog = join(root, 'runtimes/voicetalk/spoken.log')
+    assert.ok(await waitFor(() => existsSync(spokenLog) && readFileSync(spokenLog, 'utf8').includes(outbound)),
+      `outbound envelope did not reach the audio sink: ${stderr}`)
+    const inbound = `входящее ${randomUUID()}`
+    const say = spawnSync(executable, ['say', '--peer', 'proof-target', inbound], { cwd: peer, env: runEnv, encoding: 'utf8' })
+    assert.equal(say.status, 0, `say: ${say.stdout}${say.stderr}\nrouter: ${stderr}`)
+    assert.equal(JSON.parse(say.stdout.trim()).ok, true)
+    assert.match(readFileSync(argvFile, 'utf8').trim(), /^send proof-target --message-file /)
+    const body = readFileSync(bodyFile, 'utf8')
+    assert.ok(body.includes('via voicetalk') && body.includes(inbound), body)
+    assert.equal(router.exitCode, null, stderr)
+    console.log(`PASS installed router run: version ${expectedVersion}, doctor ok, outbound→sink, inbound say→daemon (fake), audio off`)
+  } finally {
+    await stopRouter()
+  }
+}
+
+try {
+  // Exercise the actual shipped CLI + default compile/signature runner.
+  const compiled = execFileSync(process.execPath, [join(pkg, 'src/cli.ts'), 'self-install'], { env, encoding: 'utf8', timeout: 120_000 })
+  assert.match(compiled, /\(compiled\)/)
+  verify()
+  assert.equal(runningVersion(), version)
+  assert.equal(JSON.parse(readFileSync(manifest, 'utf8')).version, version)
+  console.log(`PASS package CLI compile: strict signature + executable version ${version}`)
+  await proveRunningRouter()
+
+  const validHash = hash(bin)
+  const copied = execFileSync(bin, ['self-install'], { env, encoding: 'utf8', timeout: 120_000 })
+  assert.match(copied, /\(copied-self\)/)
+  verify()
+  assert.equal(hash(bin), validHash, 'valid copy-self must retain the exact signature/bytes')
+  console.log('PASS package CLI copy-self: strict signature, bytes/signature unchanged')
+
+  // Feed an unsigned native input through the shipped copy-self implementation.
+  const unsigned = join(tmp, 'unsigned-voicetalk-runtime')
+  copyFileSync(bin, unsigned)
+  execFileSync('/usr/bin/codesign', ['--remove-signature', unsigned], { env })
+  const repaired = selfInstall({ env, sourceEntry: join(tmp, 'missing.ts'), execPath: unsigned })
+  assert.equal(repaired.binMode, 'copied-self')
+  assert.equal(repaired.signature, 'repaired')
+  verify()
+  assert.equal(runningVersion(), version)
+  console.log('PASS unsigned native copy: ad-hoc repaired, strict verify + executable')
+
+  await proveInstallPair({ pkg, tmp, env, candidateBin: bin, selfInstall, run: proveRunningRouter,
+    previousPkg: process.argv[3] ? resolve(process.argv[3]) : undefined,
+    recoveryBackup: process.argv[4] ? resolve(process.argv[4]) : undefined,
+  })
+
+  // Impossible-to-sign input: real codesign failure must preserve BOTH old surfaces.
+  const bad = join(tmp, 'truncated-mach-o')
+  writeFileSync(bad, readFileSync(bin).subarray(0, 1024))
+  const invalid = spawnSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', bad], { env, encoding: 'utf8' })
+  assert.ifError(invalid.error)
+  assert.notEqual(invalid.status, 0, 'negative fixture must really be strict-invalid')
+  console.log(`REAL truncated Mach-O strict verify: status=${invalid.status}, SHA256=${hash(bad)}`)
+  const before = [hash(bin), hash(manifest)]
+  assert.throws(() => selfInstall({ env, sourceEntry: join(tmp, 'missing.ts'), execPath: bad,
+    runner: (cmd, args, passedEnv) => {
+      const result = spawnSync(cmd, args, { encoding: 'utf8', env: passedEnv, timeout: 120_000 })
+      console.log(`REAL truncated ${args[0]}: status=${result.status}, stderr=${result.stderr?.trim() ?? ''}`)
+      return result
+    },
+  }), /codesign .* failed/)
+  assert.deepEqual([hash(bin), hash(manifest)], before)
+  assert.deepEqual(readdirSync(env.IAPEER_BIN_DIR!), ['voicetalk-runtime'], 'no stage/.dead artifact left')
+  verify()
+  assert.equal(runningVersion(), version)
+  console.log(`PASS un-signable copy rejected: old bin+manifest SHA256 unchanged ${before.join(' ')}, stage removed`)
+  await proveRunningRouter() // previous router still RUNS after the rejection
+
+  // The incident's minimal fresh-compile input: accept ONLY if strict-valid and
+  // executable, otherwise prove the real failing compiler/signing path is closed.
+  const minimal = join(tmp, 'minimal.ts')
+  const marker = 'minimal fresh compile signature proof'
+  writeFileSync(minimal, `console.log(${JSON.stringify(marker)})\n`)
+  const previous = [hash(bin), hash(manifest)]
+  let failure: unknown
+  try {
+    selfInstall({ env, sourceEntry: minimal, execPath: process.execPath, runner: (cmd, args, passedEnv) => {
+      const r = spawnSync(cmd, args, { encoding: 'utf8', env: passedEnv, timeout: 120_000 })
+      console.log(`REAL minimal ${args[0]}: status=${r.status}, error=${r.error?.message ?? '-'}, stderr=${r.stderr?.trim() ?? ''}`)
+      return r
+    } })
+  } catch (e) {
+    failure = e
+  }
+  if (failure) {
+    assert.match(String(failure), /codesign .* failed/)
+    assert.deepEqual([hash(bin), hash(manifest)], previous)
+    verify()
+    assert.equal(runningVersion(), version)
+    console.log('PASS strict-invalid minimal compile rejected: old bin+manifest SHA256 unchanged')
+  } else {
+    verify()
+    assert.equal(execFileSync(bin, [], { env, encoding: 'utf8' }).trim(), marker)
+    console.log('PASS minimal compile accepted ONLY after strict verify + execution')
+  }
+  assert.deepEqual(readdirSync(env.IAPEER_BIN_DIR!), ['voicetalk-runtime'])
+  console.log(`PASS artifact ${version}: no core/helper/voice-service dependency; all writes sandboxed`)
+} finally {
+  await stopRouter()
+  rmSync(tmp, { recursive: true, force: true })
+}

package/src/cli.ts

@@ -1141,6 +1141,7 @@ async function selfInstallCommand(): Promise<void> {
   const r = selfInstall({ env: process.env, sourceEntry: import.meta.path })
   process.stdout.write(`${BIN_NAME} self-install (idempotent)\n`)
   process.stdout.write(`  bin:      ${r.binPath}  (${r.binMode})\n`)
+  process.stdout.write(`  signature: ${r.signature}\n`)
   process.stdout.write(`  manifest: ${r.manifestPath}\n`)
   process.stdout.write(`  root:     ${r.root}\n`)
   process.stdout.write(`  docs:     ${r.docs.copied ? r.docs.dest : `skipped (${r.docs.reason ?? 'unknown'})`}\n`)
@@ -1148,6 +1149,7 @@ async function selfInstallCommand(): Promise<void> {
     bin: r.binPath,
     manifest: r.manifestPath,
     binMode: r.binMode,
+    signature: r.signature,
     root: r.root,
     docs: r.docs,
   })

package/src/installPair.ts

@@ -0,0 +1,67 @@
+import { randomUUID } from 'crypto'
+import { linkSync, lstatSync, mkdirSync, readlinkSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'fs'
+import { dirname } from 'path'
+import { runtimeManifestPath, type RuntimeManifest } from './manifest.ts'
+
+/** Publish an already signature-verified executable and its manifest.
+ * All preparation is fallible BEFORE publication. If the manifest rename fails,
+ * restore the old binary inode/signature (or symlink), or remove a first install.
+ * Two paths are NOT crash-atomic: no power-loss/SIGKILL or concurrent-writer claim.
+ * No lifecycle operations belong here; running processes keep their old inode. */
+export function publishInstallPair(
+  stagedBin: string,
+  binPath: string,
+  manifest: RuntimeManifest,
+  env: NodeJS.ProcessEnv,
+  // Narrow test seam; production always calls the real synchronous rename.
+  rename: typeof renameSync = renameSync,
+): string {
+  const manifestPath = runtimeManifestPath(env)
+  const suffix = `${process.pid}.${randomUUID()}`
+  const stagedManifest = `${manifestPath}.${suffix}.tmp`
+  const backupBin = `${binPath}.${suffix}.rollback`
+  let hadBin = false
+  let publishedBin = false
+  let retainBackup = false
+  // Cleanup cannot turn a completed new pair into a reported publication failure.
+  // If cleanup itself is denied, an unused uniquely named file can remain.
+  const cleanup = (path: string) => { try { rmSync(path, { force: true }) } catch {} }
+  try {
+    mkdirSync(dirname(manifestPath), { recursive: true, mode: 0o755 })
+    writeFileSync(stagedManifest, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o644, flag: 'wx' })
+    let symlink = false
+    try {
+      const stat = lstatSync(binPath)
+      if (!stat.isFile() && !stat.isSymbolicLink()) throw new Error(`self-install: binary is not a file or symlink: ${binPath}`)
+      symlink = stat.isSymbolicLink()
+      hadBin = true
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    if (hadBin) {
+      // macOS link(2) follows symlinks. Preserve link text explicitly, including
+      // dangling/relative links. Hard-link regular files: no copy or re-signing.
+      if (symlink) symlinkSync(readlinkSync(binPath), backupBin)
+      else linkSync(binPath, backupBin)
+    }
+    rename(stagedBin, binPath)
+    publishedBin = true
+    rename(stagedManifest, manifestPath)
+    return manifestPath // no fallible contract operation after the second rename
+  } catch (error) {
+    if (publishedBin) {
+      try {
+        if (hadBin) rename(backupBin, binPath)
+        else rmSync(binPath)
+      } catch (rollbackError) {
+        retainBackup = true
+        throw new AggregateError([error, rollbackError],
+          `self-install: pair publication AND rollback failed; ${hadBin ? `previous binary retained at ${backupBin}` : `could not remove first-install binary ${binPath}`}`)
+      }
+    }
+    throw error
+  } finally {
+    cleanup(stagedManifest)
+    if (!retainBackup) cleanup(backupBin)
+  }
+}

package/src/installSignature.ts

@@ -0,0 +1,58 @@
+// File-scoped macOS install gate. Verify the staged executable BEFORE publishing
+// it; preserve valid signatures (and their TCC identity). No keychain operations.
+import { spawnSync } from 'child_process'
+
+export interface InstallCommandResult {
+  status: number | null
+  stdout?: string
+  stderr?: string
+  error?: Error
+}
+
+/** Injectable for sandbox tests; commands use argv, never a shell or PATH codesign. */
+export type InstallCommandRunner = (
+  command: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+) => InstallCommandResult
+
+export const runInstallCommand: InstallCommandRunner = (command, args, env) =>
+  spawnSync(command, args, { encoding: 'utf8', env, timeout: 120_000 })
+
+export interface ExecutableSignatureOptions {
+  env?: NodeJS.ProcessEnv
+  platform?: NodeJS.Platform
+  runner?: InstallCommandRunner
+}
+
+export type ExecutableSignatureState = 'verified' | 'repaired' | 'skipped-platform'
+
+function failed(stage: string, r: InstallCommandResult): Error {
+  const detail = (r.error?.message || r.stderr || r.stdout || `exit ${r.status}`).trim()
+  return new Error(`self-install: codesign ${stage} failed: ${detail}`)
+}
+
+/**
+ * Runtime-package contract: strict verify → repair only an invalid signature →
+ * strict verify again. Any command failure throws; callers must retain the old
+ * binary/manifest and remove the staging file. Sandbox is NOT a skip flag: tests
+ * inject a runner, while real sandbox installs verify their own staged binary.
+ */
+export function ensureExecutableSignature(
+  stagedPath: string,
+  opts: ExecutableSignatureOptions = {},
+): ExecutableSignatureState {
+  if ((opts.platform ?? process.platform) !== 'darwin') return 'skipped-platform'
+  const run = opts.runner ?? runInstallCommand
+  const env = opts.env ?? process.env
+  const verifyArgs = ['--verify', '--deep', '--strict', stagedPath]
+  const initial = run('/usr/bin/codesign', verifyArgs, env)
+  if (initial.error || initial.status === null) throw failed('initial verify', initial)
+  if (initial.status === 0) return 'verified'
+
+  const sign = run('/usr/bin/codesign', ['--force', '--sign', '-', stagedPath], env)
+  if (sign.error || sign.status !== 0) throw failed('ad-hoc repair', sign)
+  const verified = run('/usr/bin/codesign', verifyArgs, env)
+  if (verified.error || verified.status !== 0) throw failed('post-repair verify', verified)
+  return 'repaired'
+}

package/src/selfInstall.ts

@@ -19,13 +19,20 @@
 // (the package now owns this path); a sandbox proof sets IAPEER_BIN_DIR so a test never
 // touches the real ~/.local/bin.
 
-import { spawnSync } from 'child_process'
-import { chmodSync, copyFileSync, existsSync, mkdirSync, renameSync, statSync } from 'fs'
+import { chmodSync, copyFileSync, mkdirSync, renameSync, rmSync, statSync } from 'fs'
+import { publishInstallPair } from './installPair.ts'
+import { randomUUID } from 'crypto'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { BIN_NAME, PACKAGE_NAME } from './constants.ts'
 import { scaffoldHostDocs, type HostDocsResult } from './hostDocs.ts'
-import { buildManifest, resolveIapeerRoot, writeManifestAtomic } from './manifest.ts'
+import { buildManifest, resolveIapeerRoot } from './manifest.ts'
+import {
+  ensureExecutableSignature,
+  runInstallCommand,
+  type ExecutableSignatureState,
+  type InstallCommandRunner,
+} from './installSignature.ts'
 
 /** The launcher binary name (`voicetalk-runtime`). Re-exported so callers/tests have a
  *  single import surface for the self-install contract. */
@@ -44,6 +51,11 @@ export interface SelfInstallOptions {
    *  (`<pkg>/src/cli.ts` → `<pkg>/docs`). Missing (e.g. running from a compiled bin with
    *  no source tree) → soft-skip, never fails the install. */
   docsSource?: string
+  /** Test seams: no host-global mocks or environment-based signature bypass. */
+  runner?: InstallCommandRunner
+  platform?: NodeJS.Platform
+  /** Synchronous publication fault seam for tests; no environment bypass. */
+  publishRename?: typeof renameSync
 }
 
 export type SelfInstallBinMode = 'compiled' | 'copied-self'
@@ -54,6 +66,7 @@ export interface SelfInstallResult {
   binMode: SelfInstallBinMode
   root: string
   binDir: string
+  signature: ExecutableSignatureState
   /** On-host docs scaffolding verdict (best-effort; never blocks the install). */
   docs: HostDocsResult
 }
@@ -88,20 +101,12 @@ function isBunInterpreter(execPath: string): boolean {
 
 function cleanup(path: string): void {
   try {
-    if (existsSync(path)) renameSync(path, `${path}.dead`)
+    rmSync(path, { force: true })
   } catch {
     // best-effort
   }
 }
 
-/** Tiny deterministic string hash for a unique-ish tmp suffix (Math.random is avoided
- *  to keep the tmp name reproducible within a run). */
-function hashStr(s: string): number {
-  let h = 0
-  for (let i = 0; i < s.length; i++) h = (Math.imul(31, h) + s.charCodeAt(i)) | 0
-  return h
-}
-
 /**
  * Self-install: place the launcher on PATH + write the manifest. IDEMPOTENT — a
  * repeat run produces the same on-disk bin and a byte-identical manifest (atomic
@@ -116,42 +121,51 @@ export function selfInstall(opts: SelfInstallOptions = {}): SelfInstallResult {
   const binDir = resolveBinDir(env)
   const binPath = join(binDir, BIN_NAME)
 
+  // Fail closed BEFORE any write/process: a sandbox must isolate BOTH surfaces, so
+  // both must be EXPLICIT overrides. Comparing against a "host home" cannot work —
+  // Bun's os.userInfo().homedir follows $HOME, which a sandbox points at itself.
+  if ((env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1')
+    && (!env.IAPEER_BIN_DIR?.trim() || !env.IAPEER_ROOT?.trim())) {
+    throw new Error('self-install: refusing real host bin/root under IAPEER_TEST_SANDBOX=1 — set IAPEER_BIN_DIR and IAPEER_ROOT')
+  }
   mkdirSync(binDir, { recursive: true, mode: 0o755 })
 
   // Build to a sibling tmp in the SAME dir (rename is atomic only within one FS), then
-  // chmod +x and rename over the target. A reader of `voicetalk-runtime` never sees a
-  // half-written file, and a legacy symlink at binPath is replaced atomically.
-  const tmp = `${binPath}.tmp.${process.pid}.${Math.abs(hashStr(binPath + execPath))}`
+  // chmod +x, verify/repair its macOS signature, THEN rename over the target. A
+  // reader never sees a half-written file; a legacy symlink is replaced atomically.
+  const tmp = `${binPath}.tmp.${process.pid}.${randomUUID()}`
+  const run = opts.runner ?? runInstallCommand
   let binMode: SelfInstallBinMode
+  let signature: ExecutableSignatureState
+  let manifestPath: string
 
-  if (isCompilableSource(sourceEntry) && isBunInterpreter(execPath)) {
-    // PRIMARY path: running under bun from the package source (npx → bin → bun cli.ts).
-    // Compile a self-contained snapshot so the installed bin does not depend on the npm
-    // cache (GC'd) or the source tree.
-    const r = spawnSync(execPath, ['build', '--compile', '--outfile', tmp, sourceEntry], {
-      encoding: 'utf8',
-      env: env as Record<string, string>,
-    })
-    if (r.error || (r.status ?? 1) !== 0) {
-      cleanup(tmp)
-      throw new Error(
-        `self-install: bun build --compile failed: ${(r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim()}`,
-      )
+  try {
+    if (isCompilableSource(sourceEntry) && isBunInterpreter(execPath)) {
+      // PRIMARY: compile a snapshot decoupled from the npm cache/source tree.
+      const r = run(execPath, ['build', '--compile', '--outfile', tmp, sourceEntry], env)
+      if (r.error || (r.status ?? 1) !== 0) {
+        throw new Error(
+          `self-install: bun build --compile failed: ${(r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim()}`,
+        )
+      }
+      binMode = 'compiled'
+    } else {
+      // FALLBACK: running from a compiled bin; re-assert by copying the executable.
+      copyFileSync(execPath, tmp)
+      binMode = 'copied-self'
     }
-    binMode = 'compiled'
-  } else {
-    // FALLBACK: running from an already-compiled bin (no .ts source / execPath is not
-    // bun). Re-assert the install by copying the running executable into binDir.
-    copyFileSync(execPath, tmp)
-    binMode = 'copied-self'
-  }
-
-  chmodSync(tmp, 0o755)
-  renameSync(tmp, binPath)
 
-  // Manifest pins the ABSOLUTE installed bin into the self-config descriptor.
-  const manifest = buildManifest(binPath)
-  const manifestPath = writeManifestAtomic(manifest, env)
+    chmodSync(tmp, 0o755)
+    signature = ensureExecutableSignature(tmp, { env, runner: run, platform: opts.platform })
+    // Pair publication: the manifest (pinning the ABSOLUTE installed bin into the
+    // self-config descriptor) is staged BEFORE the binary is published; a manifest
+    // rename failure restores the previous binary inode (or removes a first install).
+    manifestPath = publishInstallPair(tmp, binPath, buildManifest(binPath), env, opts.publishRename)
+  } finally {
+    // Includes partial compiler/copy output and chmod/sign/rename failures. Do not
+    // leave .dead binaries; a failed signature gate never reaches the manifest.
+    cleanup(tmp)
+  }
 
   // On-host docs — stage this version's public docs to <root>/docs/voicetalk-runtime/.
   // Best-effort: scaffoldHostDocs already soft-skips missing source / copy errors; the
@@ -168,5 +182,5 @@ export function selfInstall(opts: SelfInstallOptions = {}): SelfInstallResult {
     }
   }
 
-  return { binPath, manifestPath, binMode, root: resolveIapeerRoot(env), binDir, docs }
+  return { binPath, manifestPath, binMode, signature, root: resolveIapeerRoot(env), binDir, docs }
 }

package/tsconfig.json

@@ -11,5 +11,5 @@
     "allowImportingTsExtensions": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts"]
+  "include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts"]
 }