@agfpd/voicetalk-runtime 0.1.0

package/src/constants.ts

@@ -0,0 +1,35 @@
+// Shared constants for the voicetalk runtime PACKAGE-FACING contract surface
+// (manifest / self-install / self-config — landing in Фаза 2). Kept tiny and
+// dependency-free so the contract modules can import it without pulling in the
+// audio run-loop.
+
+import pkg from '../package.json'
+
+/** The runtime id this package implements — the namespace folder under
+ *  ~/.iapeer/runtimes/<runtime>/ AND the manifest's `runtime` field. Matches
+ *  the foundation's NATURAL_RUNTIMES / INFRA_RUNTIMES entry (Фаза 1). */
+export const RUNTIME = 'voicetalk'
+
+/** The package version — single source of truth is package.json. Stamped into
+ *  the runtime manifest (foundation reads it for `iapeer status` and
+ *  `update-runtime` version-gating vs npm-latest). Bumping package.json is
+ *  enough; nothing here needs hand-editing. */
+export const VERSION: string = pkg.version
+
+/** The launcher binary name placed on PATH — `<runtime>-runtime`. Mirrors the
+ *  foundation's INFRA_RUNTIME_DEFAULT_BIN.voicetalk and the voicetalk adapter's
+ *  buildArgv fallback (`voicetalk-runtime`). */
+export const BIN_NAME = `${RUNTIME}-runtime`
+
+/** The unscoped npm package name — the per-package subdir id for the on-host
+ *  docs convention (`<IAPEER_ROOT>/docs/<PACKAGE_NAME>/`). The scope is stripped
+ *  (`@agfpd/voicetalk-runtime` → `voicetalk-runtime`). Single source of truth is
+ *  package.json `name`. */
+export const PACKAGE_NAME: string = pkg.name.split('/').pop() ?? pkg.name
+
+/** Peer-name grammar — identical to the IAP/foundation ecosystem
+ *  (/^[a-z][a-z0-9-]{0,31}$/). */
+export const NAME_RE = /^[a-z][a-z0-9-]{0,31}$/
+
+export const IAPEER_DIR = '.iapeer'
+export const PEER_PROFILE_FILE = 'peer-profile.json'

package/src/fsAtomic.ts

@@ -0,0 +1,17 @@
+// Atomic JSON write shared across the package (cli.ts + selfConfig.ts). Write to a
+// unique sibling tmp in the same directory, then rename over the target — rename is
+// atomic WITHIN one filesystem, so a concurrent reader never observes a half-written
+// file and a repeat write overwrites in place (idempotent). Default mode 0o600: the
+// files this writes (peer profiles, operator state) are private. mkdir -p the parent
+// (0o700) first so a first write into a fresh tree succeeds.
+
+import { mkdirSync, renameSync, writeFileSync } from 'fs'
+import { randomUUID } from 'crypto'
+import { dirname } from 'path'
+
+export function writeJsonAtomic(path: string, value: unknown, mode = 0o600): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode })
+  renameSync(tmp, path)
+}

package/src/hostDocs.ts

@@ -0,0 +1,87 @@
+// On-host docs per-package convention (`<IAPEER_ROOT>/docs/<package>/`).
+//
+// A faithful mirror of the foundation's scaffoldHostDocs (iapeer src/install/index.ts):
+// on EVERY install + update, copy this package's PUBLIC docs to a stable on-host path so
+// an agent (or a human) reads the docs that ship WITH the installed version, without
+// needing the source tree. Versioned-as-artifact: each install/update refreshes the copy
+// (the atomic temp-swap prunes docs removed in a newer version). We own ONLY our own
+// `<root>/docs/voicetalk-runtime/` subdir; the foundation owns the `<root>/docs/` parent
+// and the system-prompt pointer to it.
+//
+// EXCLUDES the `internals/` subtree (internals are local-only, never published). The npm
+// `files` allowlist already keeps internals out of the tarball (docs/*.md + docs/ru/,
+// not docs/) — the filter here is defense-in-depth for a dev source tree that still
+// carries docs/internals/.
+//
+// BEST-EFFORT: a missing docs source or any copy error returns a soft verdict and never
+// throws — the install MUST NOT fail because docs could not be staged (the caller in
+// selfInstall additionally wraps the call). The ONE hard failure is the fail-closed
+// sandbox guard: a misconfigured test that would otherwise write the REAL ~/.iapeer.
+
+import { cpSync, existsSync, mkdirSync, renameSync, rmSync } from 'fs'
+import { homedir } from 'os'
+import { basename, join, relative, sep } from 'path'
+import { resolveIapeerRoot } from './manifest.ts'
+
+export interface HostDocsResult {
+  copied: boolean
+  /** The per-package destination — `<root>/docs/<pkg>/`. Always set (even on skip). */
+  dest: string
+  /** Why nothing was copied (missing source / copy error). Absent on success. */
+  reason?: string
+}
+
+/**
+ * Copy `docsSource` to `<IAPEER_ROOT or ~/.iapeer>/docs/<pkg>/`, atomically and
+ * excluding the `internals/` subtree. Idempotent: re-running replaces the package's
+ * docs cleanly (the atomic copy→tmp→rm-dest→rename drops the previous tree, so a doc
+ * removed in a newer version is pruned, and a reader never sees a half-written tree).
+ *
+ * Returns what it did. Throws ONLY on the fail-closed sandbox guard; for a missing
+ * source or any copy error it returns `{ copied: false, reason }`.
+ */
+export function scaffoldHostDocs(
+  pkg: string,
+  docsSource: string,
+  env: NodeJS.ProcessEnv = process.env,
+): HostDocsResult {
+  const root = resolveIapeerRoot(env)
+  const dest = join(root, 'docs', pkg)
+  // Fail-closed sandbox guard (mirrors the foundation): never write the REAL
+  // ~/.iapeer/docs under a sandboxed test that forgot to set IAPEER_ROOT. Compared
+  // against the ACTUAL OS home (homedir()), not env.HOME — the root IS the isolation,
+  // so an env.HOME-based check would false-trip when a test legitimately points
+  // IAPEER_ROOT at <tmp>/.iapeer (with env.HOME also <tmp>).
+  if (env.IAPEER_TEST_SANDBOX === '1' && root === join(homedir(), '.iapeer')) {
+    throw new Error(
+      `refusing to scaffold docs into the REAL ${join(root, 'docs')} under IAPEER_TEST_SANDBOX=1 — set IAPEER_ROOT`,
+    )
+  }
+  if (!existsSync(docsSource)) return { copied: false, dest, reason: `docs source not found: ${docsSource}` }
+  const tmp = `${dest}.tmp-${process.pid}`
+  try {
+    rmSync(tmp, { recursive: true, force: true })
+    mkdirSync(join(dest, '..'), { recursive: true })
+    cpSync(docsSource, tmp, {
+      recursive: true,
+      // Returning false for a directory skips its whole subtree.
+      filter: src => {
+        // macOS clutter: a dev/host docs tree carries .DS_Store; skip it everywhere so
+        // it never leaks into <root>/docs/<pkg>/ (matches the foundation's filter).
+        if (basename(src) === '.DS_Store') return false
+        const rel = relative(docsSource, src)
+        return rel !== 'internals' && !rel.startsWith(`internals${sep}`)
+      },
+    })
+    rmSync(dest, { recursive: true, force: true })
+    renameSync(tmp, dest)
+    return { copied: true, dest }
+  } catch (e) {
+    try {
+      rmSync(tmp, { recursive: true, force: true })
+    } catch {
+      /* best-effort cleanup */
+    }
+    return { copied: false, dest, reason: e instanceof Error ? e.message : String(e) }
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,109 @@
+// Runtime MANIFEST — the package-facing contract surface (layer 2 of the presence-
+// runtime contract, iapeer-memory «Контракт presence-рантайма в iapeer 0.4.x — два
+// слоя, router-модель» § «Слой 2 — package-facing манифест»). The package WRITES this
+// at npx-install (self-deploy); the foundation only READS it (readRuntimeManifest →
+// createPeer/deployRuntime). The path MUST match byte-for-byte where the foundation
+// looks: <IAPEER_ROOT or ~/.iapeer>/runtimes/voicetalk/runtime.json
+//
+// OPERATOR-ADD mode (mode b): voicetalk peers are the human OWNER of a local voice
+// endpoint — the package cannot know them ahead of time, so the manifest declares NO
+// `peers[]`. Humans are added one at a time with `iapeer create <owner> --runtime
+// voicetalk`. (Contrast the notifier pilot, declared-set mode a, which lists
+// timer+watcher.) The shared per-peer self-config hook is the same; only the
+// enumeration differs.
+//
+// IAPEER_ROOT-aware: we re-implement the foundation's resolveGlobalRoot contract HERE
+// (we cannot import from the foundation repo — it is a separate package). The rule is
+// the SAME: IAPEER_ROOT env wins, else $HOME/.iapeer. A manifest written under the
+// wrong root (npx not inheriting IAPEER_ROOT) is the most likely first failure — so we
+// always resolve it from the passed env, never hard-code ~/.iapeer.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
+import { randomUUID } from 'crypto'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import { RUNTIME, VERSION } from './constants.ts'
+
+/** A self-config hook descriptor (mirror of the foundation's SelfConfigDescriptor):
+ *  a bare command (PATH-resolvable / absolute) or {command, args}. We always emit the
+ *  OBJECT form — a string descriptor carries no args, but the hook needs the
+ *  `self-config` subcommand, and we pin the ABSOLUTE installed bin so the hook is
+ *  PATH-independent (the foundation runs it with cwd=peer.cwd + namespaced env). */
+export interface SelfConfigDescriptor {
+  command: string
+  args?: string[]
+}
+
+/** One declared peer in a package's FIXED set (mode a). voicetalk (operator-add, mode
+ *  b) emits NO peers[], so this is only here for round-trip type fidelity with the
+ *  frozen manifest schema. */
+export interface RuntimePeerDecl {
+  personality: string
+  intelligence?: 'absent' | 'natural' | 'artificial'
+  description?: string
+  path?: string
+  runtimeBin?: string
+}
+
+export interface RuntimeManifest {
+  runtime: string
+  /** Package version, stamped from package.json (see VERSION). The foundation schema
+   *  (runtime/index.ts) declares it; it powers `iapeer status` version reporting and
+   *  `update-runtime` gating against npm-latest. Optional in the type for round-trip
+   *  fidelity with legacy manifests written before it was stamped. */
+  version?: string
+  selfConfig?: string | SelfConfigDescriptor
+  peers?: RuntimePeerDecl[]
+}
+
+/** Mirror of the foundation's resolveGlobalRoot: IAPEER_ROOT wins, else $HOME/.iapeer.
+ *  Re-implemented (not imported) because the foundation is a separate package; kept in
+ *  lockstep with its contract on purpose. */
+export function resolveIapeerRoot(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.IAPEER_ROOT?.trim()
+  if (override) return override
+  const home = env.HOME?.trim() || homedir()
+  if (!home) throw new Error('cannot resolve home directory for ~/.iapeer')
+  return join(home, '.iapeer')
+}
+
+/** <root>/runtimes/voicetalk/runtime.json (IAPEER_ROOT-aware). */
+export function runtimeManifestPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveIapeerRoot(env), 'runtimes', RUNTIME, 'runtime.json')
+}
+
+/**
+ * Build the voicetalk runtime manifest. `binPath` is the ABSOLUTE path the self-
+ * installer placed the launcher at — pinned into the self-config descriptor so the
+ * hook resolves without any PATH dependency. OPERATOR-ADD: NO `peers[]` (the package
+ * does not know the owners ahead of time; they arrive via `iapeer create`).
+ */
+export function buildManifest(binPath: string): RuntimeManifest {
+  return {
+    runtime: RUNTIME,
+    version: VERSION,
+    selfConfig: { command: binPath, args: ['self-config'] },
+    // NO peers[] — operator-add. Omitted on purpose (foundation reads its absence as
+    // "operator-add only"; deployRuntime.operatorAddOnly === true).
+  }
+}
+
+/** Write the manifest atomically (tmp+rename) under <root>/runtimes/voicetalk/. mkdir
+ *  -p the runtime dir first. Returns the written path. Idempotent: a repeat write
+ *  produces byte-identical content (stable key order, sorted-by-construction). */
+export function writeManifestAtomic(manifest: RuntimeManifest, env: NodeJS.ProcessEnv = process.env): string {
+  const path = runtimeManifestPath(env)
+  mkdirSync(dirname(path), { recursive: true, mode: 0o755 })
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
+  writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o644 })
+  renameSync(tmp, path)
+  return path
+}
+
+/** Read the manifest, or null when absent. Throws on present-but-malformed JSON (it
+ *  is our declared contract — a corruption should surface, not silently degrade). */
+export function readManifest(env: NodeJS.ProcessEnv = process.env): RuntimeManifest | null {
+  const path = runtimeManifestPath(env)
+  if (!existsSync(path)) return null
+  return JSON.parse(readFileSync(path, 'utf8')) as RuntimeManifest
+}

package/src/selfConfig.ts

@@ -0,0 +1,129 @@
+// Per-peer self-config hook — the shared contract BOTH provision modes call (layer 2 of
+// the presence-runtime contract, § «Per-peer self-config-хук»). The foundation invokes
+// it per peer as `voicetalk-runtime self-config` with cwd = the peer's cwd and the peer
+// context in NAMESPACED env (IAPEER_PEER_PERSONALITY/_CWD/_RUNTIME/_INTELLIGENCE +
+// IAPEER_ROOT — NOT the bare PEER_* the identity gate keys on). Our job is the RICH,
+// voicetalk-specific state: this owner's voice BINDING (wake_word + optional audio
+// device → interfaces.voicetalk).
+//
+// NARROWED schema (design dialog 21.06): interfaces.voicetalk = { wake_word, device? }.
+// STT/TTS/voice config is DELIBERATELY NOT here — it lives in the shared voice-connect
+// service (one place for voicetalk + Telegram voice + Peer-Voice). NO sender-guard
+// (unlike telegram's bot_username): the speaker is a single local endpoint of the owner,
+// any fleet peer may answer by voice, so there is no separate "voicetalk-face" sender to
+// record (decision: «Sender-guard: NO for the MVP»).
+//
+// IDEMPOTENT ("ensure runtime state for peer X"): read-merge-write, byte-stable. exit 0
+// = configured, ≠0 = failed (the foundation is fail-closed — a failed hook means the
+// plist is written but NOT bootstrapped, so a misconfigured always-on voicetalk session
+// never crash-loops).
+//
+// IDENTITY IS THE FOUNDATION'S DOMAIN — and voicetalk is intelligence-GATED (the launch
+// primitive requires `natural`; the foundation provisions it). So the hook does a RAW
+// read-merge-write that PRESERVES every field the foundation provisioned (especially
+// `intelligence`=natural and `personality`). It deliberately does NOT use a typed reader
+// that would coerce the contract `natural` back to a legacy value and clobber it
+// (the pilot-notifier lesson: preserve, don't re-derive identity).
+//
+// OPERATOR INPUTS come via env at `iapeer create` time (the foundation forwards the whole
+// env into the hook): VOICETALK_WAKE_WORD → interfaces.voicetalk.wake_word;
+// VOICETALK_DEVICE → interfaces.voicetalk.device. Absent inputs → the hook is still
+// `configured` (a no-op that confirms state); the operator can complete the binding later
+// via the `interface` verb.
+
+import { existsSync, readFileSync } from 'fs'
+import { basename, join } from 'path'
+import { IAPEER_DIR, NAME_RE, PEER_PROFILE_FILE } from './constants.ts'
+import { writeJsonAtomic } from './fsAtomic.ts'
+
+export interface SelfConfigOptions {
+  env?: NodeJS.ProcessEnv
+  cwd?: string
+}
+
+export interface SelfConfigOutcome {
+  personality: string
+  profilePath: string
+  /** What was written into interfaces.voicetalk this run (for the CLI summary/log). */
+  wakeWord?: string
+  device?: string
+}
+
+function trimmed(value: string | undefined): string | undefined {
+  const v = value?.trim()
+  return v && v.length > 0 ? v : undefined
+}
+
+/** Resolve the peer's personality for this hook invocation: prefer the NAMESPACED
+ *  IAPEER_PEER_PERSONALITY (the contract env), then the bare PEER_PERSONALITY, then the
+ *  cwd basename (so a manual `voicetalk-runtime self-config` in a peer cwd still works). */
+function resolvePersonality(env: NodeJS.ProcessEnv, cwd: string): string {
+  const candidate =
+    trimmed(env.IAPEER_PEER_PERSONALITY) ?? trimmed(env.PEER_PERSONALITY) ?? basename(cwd).toLowerCase()
+  if (!NAME_RE.test(candidate)) {
+    throw new Error(`self-config: resolved personality "${candidate}" must match /^[a-z][a-z0-9-]{0,31}$/`)
+  }
+  return candidate
+}
+
+function peerProfilePath(cwd: string): string {
+  return join(cwd, IAPEER_DIR, PEER_PROFILE_FILE)
+}
+
+/** Read the peer profile as a RAW object (no typed coercion) so every foundation-
+ *  provisioned field — especially `intelligence` — round-trips untouched. Returns {}
+ *  when the file is absent or malformed (nothing to preserve in the malformed case). */
+function readRawProfile(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {}
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'))
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) return raw as Record<string, unknown>
+  } catch {
+    // malformed → start clean (nothing valid to preserve)
+  }
+  return {}
+}
+
+/**
+ * Configure runtime state for ONE voicetalk peer (idempotent). Merges this owner's voice
+ * binding (wake_word + optional device, from env) into <cwd>/.iapeer/peer-profile.json
+ * `interfaces.voicetalk`, PRESERVING every other field — most importantly the
+ * foundation-provisioned `intelligence` (natural). Atomic tmp+rename. Returns what was
+ * configured.
+ */
+export function runSelfConfig(opts: SelfConfigOptions = {}): SelfConfigOutcome {
+  const env = opts.env ?? process.env
+  const cwd = opts.cwd ?? trimmed(env.IAPEER_PEER_CWD) ?? process.cwd()
+  const personality = resolvePersonality(env, cwd)
+  const profilePath = peerProfilePath(cwd)
+
+  const profile = readRawProfile(profilePath)
+
+  // Operator-supplied voice binding (env, forwarded by the foundation).
+  const wakeWord = trimmed(env.VOICETALK_WAKE_WORD)
+  const device = trimmed(env.VOICETALK_DEVICE)
+
+  // Merge interfaces.voicetalk (preserve any existing voicetalk fields). Only set
+  // wake_word/device when provided — never blank out a value the operator set earlier.
+  const interfaces =
+    profile.interfaces && typeof profile.interfaces === 'object' && !Array.isArray(profile.interfaces)
+      ? { ...(profile.interfaces as Record<string, unknown>) }
+      : {}
+  const voicetalk =
+    (interfaces as { voicetalk?: unknown }).voicetalk &&
+    typeof (interfaces as { voicetalk?: unknown }).voicetalk === 'object'
+      ? { ...((interfaces as { voicetalk: Record<string, unknown> }).voicetalk) }
+      : {}
+  if (wakeWord) voicetalk.wake_word = wakeWord
+  if (device) voicetalk.device = device
+  ;(interfaces as Record<string, unknown>).voicetalk = voicetalk
+
+  // Identity stays the foundation's domain — spread the raw profile FIRST so every
+  // provisioned field (intelligence=natural, personality, runtimes, description, and any
+  // unknown adjacent-contract fields) is preserved; only `interfaces` is replaced.
+  const merged: Record<string, unknown> = { ...profile, interfaces }
+
+  writeJsonAtomic(profilePath, merged)
+
+  return { personality, profilePath, wakeWord, device }
+}

package/src/selfInstall.ts

@@ -0,0 +1,172 @@
+// npx-self-install — the package's self-deploy (layer 2 of the presence-runtime
+// contract). `npx @agfpd/voicetalk-runtime` (a bare, no-subcommand invocation — the
+// foundation's defaultNpxRunner runs `npx -y <pkg>` with NO args) IDEMPOTENTLY:
+//   (a) puts an executable `voicetalk-runtime` on PATH (a self-contained `bun build
+//       --compile` snapshot — decoupled from the npm-cache source dir, which GC's),
+//   (b) writes the runtime manifest at <IAPEER_ROOT>/runtimes/voicetalk/runtime.json.
+//
+// This is the npx↔foundation seam: after this, `iapeer create <owner> --runtime
+// voicetalk` resolves the launcher on PATH (provisionPeer refuses a crash-looper if it
+// is missing), bakes its abs path into the always-on plist (VOICETALK_RUNTIME_BIN), and
+// runs the per-peer self-config hook the manifest declares. Two ordering invariants:
+// the manifest lands under the RIGHT root (manifest.ts resolves IAPEER_ROOT from env),
+// and the bin is on PATH BEFORE provision (this runs first).
+//
+// Bin placement: IAPEER_BIN_DIR override → else ~/.local/bin (the standard user-bin,
+// same home as the foundation's `iapeer`, and on the launchd-minimal PATH the plist
+// bakes — `~/.bun/bin:~/.local/bin:/opt/homebrew/bin:/usr/bin:/bin`). Overwriting a
+// legacy ~/.local/bin/voicetalk-runtime symlink with a real compiled bin is INTENDED
+// (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 { 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'
+
+/** The launcher binary name (`voicetalk-runtime`). Re-exported so callers/tests have a
+ *  single import surface for the self-install contract. */
+export { BIN_NAME }
+
+export interface SelfInstallOptions {
+  env?: NodeJS.ProcessEnv
+  /** The cli.ts source entry to compile (default: this module's sibling cli.ts). When
+   *  it is not a real .ts file on disk (running FROM a compiled bin), self-install
+   *  falls back to copying the running executable instead of recompiling. */
+  sourceEntry?: string
+  /** The running interpreter / compiled bin (default process.execPath). When the
+   *  source path is real and this is `bun`, it is the compiler we invoke. */
+  execPath?: string
+  /** On-host docs source dir. Default: `<package-root>/docs` derived from `sourceEntry`
+   *  (`<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
+}
+
+export type SelfInstallBinMode = 'compiled' | 'copied-self'
+
+export interface SelfInstallResult {
+  binPath: string
+  manifestPath: string
+  binMode: SelfInstallBinMode
+  root: string
+  binDir: string
+  /** On-host docs scaffolding verdict (best-effort; never blocks the install). */
+  docs: HostDocsResult
+}
+
+/** Resolve the bin dir: IAPEER_BIN_DIR override → else ~/.local/bin. */
+export function resolveBinDir(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.IAPEER_BIN_DIR?.trim()
+  if (override) return override
+  const home = env.HOME?.trim() || homedir()
+  if (!home) throw new Error('cannot resolve home directory for the bin dir')
+  return join(home, '.local', 'bin')
+}
+
+/** True when `path` is a real .ts source file we can `bun build --compile`. */
+function isCompilableSource(path: string | undefined): path is string {
+  if (!path || !path.endsWith('.ts')) return false
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** Is `execPath` a bun interpreter (so `<execPath> build` works)? When running
+ *  `bun src/cli.ts`, process.execPath IS the bun binary (basename `bun`). A compiled
+ *  voicetalk-runtime has basename `voicetalk-runtime` → NOT bun → we must not call
+ *  `<it> build` (it would be `voicetalk-runtime build …`), so we fall back to copy-self. */
+function isBunInterpreter(execPath: string): boolean {
+  const base = execPath.split('/').pop() ?? execPath
+  return base === 'bun' || base === 'bun-debug'
+}
+
+function cleanup(path: string): void {
+  try {
+    if (existsSync(path)) renameSync(path, `${path}.dead`)
+  } 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
+ * overwrite-in-place; no duplicated or divergent state). Returns what it did.
+ */
+export function selfInstall(opts: SelfInstallOptions = {}): SelfInstallResult {
+  const env = opts.env ?? process.env
+  const sourceEntry = opts.sourceEntry ?? join(import.meta.dir, 'cli.ts')
+  // `<pkg>/docs` from the source entry's package root (`<pkg>/src/cli.ts` → `<pkg>/docs`).
+  const docsSource = opts.docsSource ?? join(dirname(sourceEntry), '..', 'docs')
+  const execPath = opts.execPath ?? process.execPath
+  const binDir = resolveBinDir(env)
+  const binPath = join(binDir, BIN_NAME)
+
+  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))}`
+  let binMode: SelfInstallBinMode
+
+  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()}`,
+      )
+    }
+    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)
+
+  // 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
+  // try/catch additionally swallows the fail-closed sandbox guard so a docs problem can
+  // NEVER fail the install (bin + manifest are the install contract, docs are a bonus).
+  let docs: HostDocsResult
+  try {
+    docs = scaffoldHostDocs(PACKAGE_NAME, docsSource, env)
+  } catch (e) {
+    docs = {
+      copied: false,
+      dest: join(resolveIapeerRoot(env), 'docs', PACKAGE_NAME),
+      reason: e instanceof Error ? e.message : String(e),
+    }
+  }
+
+  return { binPath, manifestPath, binMode, root: resolveIapeerRoot(env), binDir, docs }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "strict": true,
+    "types": ["bun-types"],
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}