@agfpd/iapeer 0.2.18 → 0.2.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -40,7 +40,7 @@ import {
   wakeOrSpawn,
 } from '../lifecycle/index.ts'
 import { getAdapter } from '../launch/index.ts'
-import { isFoundationOwnedPlist, kickstartDaemon, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
+import { isFoundationOwnedPlist, kickstartDaemon, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
 import { resolveCallerIdentity, resolveIdentity } from '../identity/index.ts'
 import { runAlwaysOn } from '../launch/launchdRun.ts'
 import { installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
@@ -231,10 +231,22 @@ export function startPeer(personality: string, runtime: string | undefined, opts
     const identity = buildProcessAddress(rt, personality)
     if (isInfraRuntime(rt)) {
       const plist = launchdPlistPath(personality, env)
-      // Audit #13: a failed bootstrap means the peer did NOT start — surface it instead
-      // of reporting success silently.
-      const r = spawnSync('launchctl', ['bootstrap', `gui/${uid()}`, plist], { encoding: 'utf8' })
-      out.push({ personality, runtime: rt, action: 'bootstrap', reason: r.status === 0 ? undefined : `launchctl bootstrap FAILED (exit ${r.status})${(r.stderr ?? '').trim() ? `: ${(r.stderr ?? '').trim()}` : ''} — peer not started` })
+      // UNDEAD-JOB-SAFE start (boris's connect-acceptance find 10.06): a bootstrap
+      // right after a bootout used to hit the still-dismantling job (exit 5 I/O
+      // error) and leave the router DOWN. launchctlBootstrap now waits for the
+      // job to vanish and retries with backoff (~22 s budget); a failure after
+      // every attempt is LOUD with the manual rescue recipe. (Also gains the
+      // sentinel fleet-guard + sandbox guard the raw spawn never had.)
+      const r = launchctlBootstrap(personality, plist, env)
+      const ok = r.state === 'loaded' || r.state === 'already-loaded' || r.state === 'skipped-sandbox'
+      out.push({
+        personality,
+        runtime: rt,
+        action: 'bootstrap',
+        reason: ok
+          ? undefined
+          : `launchctl bootstrap FAILED${r.detail ? `: ${r.detail}` : ''} — peer not started; manual rescue: launchctl bootstrap gui/$(id -u) ${plist}`,
+      })
     } else {
       clearStopped(cfg, identity)
       out.push({ personality, runtime: rt, action: 'started' })
@@ -795,10 +807,17 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         ensureGlobalIapScaffold({ env })
         const r = installIapeer(fileURLToPath(import.meta.url), env)
         const plist = installDaemonPlist({ env })
+        const signingLine =
+          r.signing == null
+            ? ''
+            : r.signing.state === 'failed-soft'
+              ? `  WARNING signing: ${r.signing.detail}\n`
+              : `  signing: ${r.signing.state}${r.signing.state === 'signed-new-identity' ? ' (local identity created — the one install-time event)' : ''}\n`
         out(
           `installed iapeer → ${r.binPath}` +
             `${r.prevPath ? ` (previous kept: ${r.prevPath})` : ''}` +
             `${r.size ? ` (${Math.round(r.size / 1e6)}M)` : ''}\n` +
+            signingLine +
             `  scaffold: ~/.iapeer/ ensured (peers/, state, logs, cache, runtimes)\n` +
             `  daemon plist written: ${plist}\n` +
             `  (NOT loaded — a live daemon migration is a separate step: launchctl bootstrap gui/$(id -u) ${plist})\n`,

package/src/connect/connect.test.ts

@@ -39,11 +39,12 @@ async function fixture(): Promise<{ env: NodeJS.ProcessEnv; calls: string[][]; r
   const runTg: TgRunner = (args, e) => {
     calls.push(args)
     if (args[0] === 'bot' && args[1] === 'add') {
-      // the package's behavior: token → bots/<alias>/.env; prints the validated @username
+      // the package's behavior: token → bots/<alias>/.env (incl. the username
+      // field — the RELIABLE source, live-host fact); stdout also prints one
       const p = botEnvPath(args[2]!, e)
       mkdirSync(dirname(p), { recursive: true })
-      writeFileSync(p, `TELEGRAM_BOT_TOKEN=${args[4]}\n`)
-      return { status: 0, stdout: 'bot added: @leo_test_bot\n', stderr: '' }
+      writeFileSync(p, `TELEGRAM_BOT_TOKEN=${args[4]}\nTELEGRAM_BOT_USERNAME=leo_env_bot\n`)
+      return { status: 0, stdout: 'bot added: @leo_stdout_bot\n', stderr: '' }
     }
     return { status: 0, stdout: '', stderr: '' }
   }
@@ -63,7 +64,7 @@ describe('connectTelegram (one flow: bot add → interface → restart → activ
     const { env, calls, runTg, restarts } = await fixture()
     const r = await connectTelegram({ peer: 'leo', token: 'T1:abc', env, runTg, restart: okRestart(restarts) })
     expect(r.state).toBe('connected')
-    expect(r.username).toBe('@leo_test_bot')
+    expect(r.username).toBe('@leo_env_bot') // .env field WINS over the stdout match
     expect(r.restart?.state).toBe('restarted')
     expect(restarts).toEqual(['arthur']) // the router = the natural telegram peer, not leo
     expect(calls[0]).toEqual(['bot', 'add', 'leo', '--token', 'T1:abc'])
@@ -116,6 +117,24 @@ describe('connectTelegram (one flow: bot add → interface → restart → activ
     expect(r2.state).toBe('refused-no-token')
   })
 
+  test('username falls back to the bot-add stdout when .env carries no username field', async () => {
+    const env = envFor(mkTmp())
+    writeRuntimeManifest({ runtime: 'telegram', selfConfig: '/stub/telegram-runtime self-config' }, { env })
+    await upsertPeer({ personality: 'leo', runtime: 'claude', cwd: '/tmp/leo', intelligence: 'artificial' }, { env })
+    await upsertPeer({ personality: 'arthur', runtime: 'telegram', cwd: '/tmp/arthur', intelligence: 'natural' }, { env })
+    const runTg: TgRunner = (args, e) => {
+      if (args[0] === 'bot') {
+        const p = botEnvPath('leo', e)
+        mkdirSync(dirname(p), { recursive: true })
+        writeFileSync(p, 'TELEGRAM_BOT_TOKEN=T\n') // no username field (older package)
+        return { status: 0, stdout: 'added @stdout_only_bot\n', stderr: '' }
+      }
+      return { status: 0, stdout: '', stderr: '' }
+    }
+    const r = await connectTelegram({ peer: 'leo', token: 'T', env, runTg, restart: okRestart([]) })
+    expect(r.username).toBe('@stdout_only_bot')
+  })
+
   test('bot add failure (getMe refusal on a bad token) → bot-add-failed with the package detail', async () => {
     const { env } = await fixture()
     const failTg: TgRunner = args =>

package/src/connect/index.ts

@@ -183,7 +183,17 @@ export async function connectTelegram(opts: ConnectTelegramOptions): Promise<Con
   if (add.status !== 0) {
     return { state: 'bot-add-failed', peer, detail: (add.stderr || add.stdout || `exit ${add.status}`).trim() }
   }
-  const username = add.stdout.match(/@[A-Za-z0-9_]{3,}/)?.[0]
+  // @username: the bots/<alias>/.env TELEGRAM_BOT_USERNAME field is the RELIABLE
+  // source (present on the live host; survives a quiet bot-add stdout — boris's
+  // acceptance saw the activation line degrade to the BotFather hint). stdout
+  // match stays as the fallback.
+  const envAfterAdd = readBotEnv(alias, env)
+  const envUser = envAfterAdd?.match(/^TELEGRAM_BOT_USERNAME=(.+)$/m)?.[1]?.trim()
+  const username = envUser
+    ? envUser.startsWith('@')
+      ? envUser
+      : `@${envUser}`
+    : add.stdout.match(/@[A-Za-z0-9_]{3,}/)?.[0]
 
   // (2) interface bot — merge the channel binding into the peer's profile.
   const iface = runTg(['interface', 'bot', alias, '--peer', peer], env)

package/src/core/constants.test.ts

@@ -18,4 +18,15 @@ describe('resolveSockDir', () => {
     expect(resolveSockDir({ IAPEER_SOCK_DIR: '   ' })).toBe(DEFAULT_SOCK_DIR)
     expect(resolveSockDir({ IAPEER_SOCK_DIR: '' })).toBe(DEFAULT_SOCK_DIR)
   })
+  test('IAPEER_ROOT implies socket isolation: <root>/socks (boris e2e find 10.06)', () => {
+    // An alt-root used to inherit GLOBAL /tmp — a sandboxed list saw PROD sessions
+    // live by name collision, and sandboxed stop/start would have hit prod.
+    expect(resolveSockDir({ IAPEER_ROOT: '/tmp/sbx/iapeer' })).toBe('/tmp/sbx/iapeer/socks')
+  })
+  test('explicit IAPEER_SOCK_DIR wins over the root-derived dir', () => {
+    expect(resolveSockDir({ IAPEER_ROOT: '/tmp/sbx/iapeer', IAPEER_SOCK_DIR: '/tmp/elsewhere' })).toBe('/tmp/elsewhere')
+  })
+  test('prod shape (no IAPEER_ROOT, no IAPEER_SOCK_DIR) stays on /tmp — untouched', () => {
+    expect(resolveSockDir({ HOME: '/Users/x' })).toBe('/tmp')
+  })
 })

package/src/core/constants.ts

@@ -2,6 +2,8 @@
 // Consolidated from inter-agent-protocol/src/lib/constants.ts (wins as-is) and
 // extended with storage-layer path names (blueprint §1 core/constants).
 
+import { join } from 'path'
+
 export const NAME_RE = /^[a-z][a-z0-9-]{0,31}$/
 export const NAME_RE_SOURCE = '^[a-z][a-z0-9-]{0,31}$'
 export const RUNTIME_RE = /^[a-z][a-z0-9]{0,31}$/
@@ -124,8 +126,18 @@ export const DEFAULT_SOCK_DIR = '/tmp'
 // scan/resolve, lifecycle, launchdRun) MUST resolve through this ONE helper so they
 // agree — a site that hardcodes DEFAULT_SOCK_DIR would look in /tmp while a sandbox
 // (IAPEER_SOCK_DIR set) created the session elsewhere → a false "offline".
+//
+// IAPEER_ROOT IMPLIES SOCKET ISOLATION (boris's e2e find 10.06): an alt-root used
+// to inherit the GLOBAL /tmp, so a sandboxed `list` saw PROD sessions live by name
+// collision, and a sandboxed stop/start would have HIT a prod session. A set root
+// now derives `<root>/socks` unless IAPEER_SOCK_DIR explicitly says otherwise; the
+// prod daemon (no IAPEER_ROOT) keeps the canonical /tmp untouched.
 export function resolveSockDir(env: NodeJS.ProcessEnv = process.env): string {
-  return env.IAPEER_SOCK_DIR?.trim() || DEFAULT_SOCK_DIR
+  const explicit = env.IAPEER_SOCK_DIR?.trim()
+  if (explicit) return explicit
+  const root = env.IAPEER_ROOT?.trim()
+  if (root) return join(root, 'socks')
+  return DEFAULT_SOCK_DIR
 }
 
 // === per-peer cwd scope ===

package/src/install/index.ts

@@ -5,13 +5,19 @@
 // plists run the INSTALLED binary, and any edit/git-op in the tree no longer hits
 // prod. Update = atomic overwrite in place (build to .tmp → rename over), with ONE
 // .prev for rollback. NO versions/ catalog + resolver-symlink (that pattern is for
-// multi-version toolchains; the foundation is one-latest — and a stable path keeps
-// macOS TCC rights through updates, which a versioned path would re-prompt).
+// multi-version toolchains; the foundation is one-latest).
+//
+// macOS TCC: a stable PATH is NOT enough to keep grants through updates — TCC keys
+// on the code requirement, and an ad-hoc bun-compiled binary's requirement is its
+// CDHash (changes every build → re-prompts; live-proven 10.06, Артур's DX
+// requirement). signInstalledBinary (signing.ts) re-signs each install with the
+// stable local identity so the designated requirement — and the grants — survive.
 
 import { copyFileSync, existsSync, mkdirSync, renameSync, statSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { spawnSync } from 'child_process'
+import { signInstalledBinary, type SigningOutcome } from './signing.ts'
 
 /** The stable host-wide install path of the `iapeer` binary. Standard user-bin (no
  *  admin, not tied to a node/bun version), ON $PATH. The launchd plists reference
@@ -30,6 +36,9 @@ export interface InstallResult {
   prevPath?: string
   /** Bytes of the installed binary. */
   size?: number
+  /** Stable-identity re-sign outcome (TCC grants survive updates). Soft: a signing
+   *  hiccup never fails the install — the binary works ad-hoc-signed. */
+  signing?: SigningOutcome
 }
 
 /**
@@ -74,13 +83,16 @@ export function installIapeer(cliEntrypoint: string, env: NodeJS.ProcessEnv = pr
     copyFileSync(binPath, prevPath)
   }
   renameSync(tmp, binPath) // atomic replace in place (POSIX rename over an existing file)
+  // Stable-identity re-sign (TCC grants survive updates). AFTER the rename: the
+  // signature belongs to the final inode at the final path. Soft-fail by design.
+  const signing = signInstalledBinary(binPath, env)
   let size: number | undefined
   try {
     size = statSync(binPath).size
   } catch {
     /* best-effort */
   }
-  return { binPath, prevPath, size }
+  return { binPath, prevPath, size, signing }
 }
 
 /** The previous-binary path kept by the last install for one-step rollback. */
@@ -113,6 +125,9 @@ export function rollbackIapeer(env: NodeJS.ProcessEnv = process.env): RollbackRe
   try {
     copyFileSync(prev, tmp)
     renameSync(tmp, binPath)
+    // Keep the stable requirement on the restored bytes too (a .prev taken before
+    // the signing era is ad-hoc — re-signing it heals that). Soft by design.
+    signInstalledBinary(binPath, env)
   } catch (e) {
     try {
       if (existsSync(tmp)) renameSync(tmp, `${tmp}.discard`) // never leave a half-written tmp on the path

package/src/install/signing.test.ts

@@ -0,0 +1,84 @@
+// signInstalledBinary — stable-identity re-sign so TCC grants survive updates
+// (Артур's DX requirement 10.06). DI-runner units; the real keychain flow was
+// proven live (/tmp experiment: two binaries, different CDHash, IDENTICAL
+// designated requirement `identifier "com.agfpd.iapeer" and certificate leaf`).
+// The sandbox guard double-checks process.env, so these tests inject a runner
+// AND call with the flag stripped via a direct env — guard tested separately.
+
+import { describe, expect, test } from 'bun:test'
+import { SIGNING_IDENTIFIER, SIGNING_IDENTITY_CN, signInstalledBinary, type SigningRunner } from './signing.ts'
+
+function harness(opts: { identityExists: boolean; failAt?: 'req' | 'pkcs12' | 'import' | 'codesign' }) {
+  const calls: { cmd: string; args: string[] }[] = []
+  const run: SigningRunner = (cmd, args) => {
+    calls.push({ cmd, args })
+    if (cmd === 'security' && args[0] === 'find-identity') {
+      return { status: 0, stdout: opts.identityExists ? `1) ABC "${SIGNING_IDENTITY_CN}" (CSSMERR_TP_NOT_TRUSTED)\n` : 'no identities\n', stderr: '' }
+    }
+    if (cmd.endsWith('openssl') && args[0] === 'req') return { status: opts.failAt === 'req' ? 1 : 0, stdout: '', stderr: 'req boom' }
+    if (cmd.endsWith('openssl') && args[0] === 'pkcs12') return { status: opts.failAt === 'pkcs12' ? 1 : 0, stdout: '', stderr: 'p12 boom' }
+    if (cmd === 'security' && args[0] === 'import') return { status: opts.failAt === 'import' ? 1 : 0, stdout: '', stderr: 'import boom' }
+    if (cmd === 'codesign') return { status: opts.failAt === 'codesign' ? 1 : 0, stdout: '', stderr: 'sign boom' }
+    return { status: 0, stdout: '', stderr: '' }
+  }
+  return { calls, run }
+}
+
+// NOTE: process.env.IAPEER_TEST_SANDBOX === '1' under `bun run test`, so the
+// guard SHORT-CIRCUITS every real call — these units therefore stub process.env
+// off for the duration of each call.
+function withSandboxOff<T>(fn: () => T): T {
+  const prev = process.env.IAPEER_TEST_SANDBOX
+  delete process.env.IAPEER_TEST_SANDBOX
+  try {
+    return fn()
+  } finally {
+    if (prev !== undefined) process.env.IAPEER_TEST_SANDBOX = prev
+  }
+}
+
+describe('signInstalledBinary (stable identity → TCC grants survive updates)', () => {
+  test('sandbox guard: never touches the keychain under IAPEER_TEST_SANDBOX', () => {
+    const h = harness({ identityExists: true })
+    const r = signInstalledBinary('/x/iapeer', { IAPEER_TEST_SANDBOX: '1' } as NodeJS.ProcessEnv, h.run)
+    expect(r.state).toBe('skipped-sandbox')
+    expect(h.calls.length).toBe(0)
+  })
+
+  test('existing identity → single codesign with the stable identifier', () => {
+    const h = harness({ identityExists: true })
+    const r = withSandboxOff(() => signInstalledBinary('/x/iapeer', {} as NodeJS.ProcessEnv, h.run))
+    expect(r.state).toBe('signed')
+    const sign = h.calls.find(c => c.cmd === 'codesign')!
+    expect(sign.args).toEqual(['-f', '-s', SIGNING_IDENTITY_CN, '--identifier', SIGNING_IDENTIFIER, '/x/iapeer'])
+    // identity lookup is NOT -v (an untrusted self-signed identity must be found)
+    const find = h.calls.find(c => c.args[0] === 'find-identity')!
+    expect(find.args).not.toContain('-v')
+  })
+
+  test('no identity → created once (openssl req → pkcs12 → import -T codesign), then signed', () => {
+    const h = harness({ identityExists: false })
+    const r = withSandboxOff(() => signInstalledBinary('/x/iapeer', {} as NodeJS.ProcessEnv, h.run))
+    expect(r.state).toBe('signed-new-identity')
+    const seq = h.calls.map(c => `${c.cmd.split('/').pop()}:${c.args[0]}`)
+    expect(seq).toEqual(['security:find-identity', 'openssl:req', 'openssl:pkcs12', 'security:import', 'codesign:-f'])
+    const imp = h.calls.find(c => c.args[0] === 'import')!
+    expect(imp.args).toContain('-T') // codesign pre-authorized in the key ACL
+    expect(imp.args).toContain('/usr/bin/codesign')
+  })
+
+  test('identity-creation failure → failed-soft with the loud TCC consequence, codesign never attempted', () => {
+    const h = harness({ identityExists: false, failAt: 'import' })
+    const r = withSandboxOff(() => signInstalledBinary('/x/iapeer', {} as NodeJS.ProcessEnv, h.run))
+    expect(r.state).toBe('failed-soft')
+    expect(r.detail).toContain('TCC prompts will re-appear')
+    expect(h.calls.some(c => c.cmd === 'codesign')).toBe(false)
+  })
+
+  test('codesign failure → failed-soft (install never breaks on a signing hiccup)', () => {
+    const h = harness({ identityExists: true, failAt: 'codesign' })
+    const r = withSandboxOff(() => signInstalledBinary('/x/iapeer', {} as NodeJS.ProcessEnv, h.run))
+    expect(r.state).toBe('failed-soft')
+    expect(r.detail).toContain('sign boom')
+  })
+})

package/src/install/signing.ts

@@ -0,0 +1,135 @@
+// Stable code-signing for the installed binary — TCC grants must SURVIVE updates
+// (Артур's DX requirement 10.06: «1 раз при установке, потом обновления не должны
+// опять триггерить»).
+//
+// ROOT CAUSE (proven on the host): `bun build --compile` output is ad-hoc
+// linker-signed (Identifier=a.out, no cert chain) — its only stable identity is
+// the CDHash, which CHANGES with every build. macOS TCC keys grants on the code
+// requirement; for an ad-hoc binary that collapses to the cdhash → every update
+// is a NEW TCC subject → re-prompts.
+//
+// FIX (proven live, /tmp experiment 10.06): a LOCAL self-signed code-signing
+// identity ("iapeer Local Codesign", created once at install) re-signs the binary
+// after every build. Two different binaries signed by it carry the IDENTICAL
+// designated requirement:
+//   identifier "com.agfpd.iapeer" and certificate leaf = H"<leaf-hash>"
+// — stable across updates, so the TCC grant follows the requirement, not the
+// bytes. Trust of the cert chain is NOT needed: codesign signs with an untrusted
+// (CSSMERR_TP_NOT_TRUSTED) identity fine, and TCC matches the requirement.
+//
+// Failure policy: SOFT. The binary works ad-hoc-signed exactly as before; a
+// signing hiccup must never break install/update. It is reported loud (the
+// operator learns TCC prompts will re-appear) but the install succeeds.
+
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+
+export const SIGNING_IDENTITY_CN = 'iapeer Local Codesign'
+export const SIGNING_IDENTIFIER = 'com.agfpd.iapeer'
+
+/** System LibreSSL — ALWAYS present on macOS and its pkcs12 output imports into
+ *  the keychain directly. (Homebrew OpenSSL 3.x defaults to PBES2/AES p12, which
+ *  `security import` rejects with "MAC verification failed" unless -legacy —
+ *  live-caught during the experiment; pinning the system binary removes the
+ *  PATH-dependent branch entirely.) */
+const SYSTEM_OPENSSL = '/usr/bin/openssl'
+
+export interface SigningRunner {
+  (cmd: string, args: string[], input?: string): { status: number | null; stdout: string; stderr: string }
+}
+
+const defaultRunner: SigningRunner = (cmd, args) => {
+  // 90 s ceiling: a keychain GUI prompt left unanswered must not wedge an
+  // unattended update forever — it degrades to failed-soft instead.
+  const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 90_000 })
+  return { status: r.error ? null : r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+export interface SigningOutcome {
+  state:
+    | 'signed' // re-signed with the existing identity
+    | 'signed-new-identity' // identity created this run (the ONE install-time event), then signed
+    | 'skipped-sandbox' // tests never touch the real keychain
+    | 'failed-soft' // signing failed — binary stays ad-hoc (works; TCC prompts return)
+  detail?: string
+}
+
+/** True iff the local signing identity already exists in the keychain. Deliberately
+ *  NOT `-v` (valid-only): the self-signed cert reads CSSMERR_TP_NOT_TRUSTED, which
+ *  is fine for signing — `-v` would hide it and re-create endlessly. */
+function identityPresent(run: SigningRunner): boolean {
+  const r = run('security', ['find-identity', '-p', 'codesigning'])
+  return r.status === 0 && r.stdout.includes(`"${SIGNING_IDENTITY_CN}"`)
+}
+
+/** Create the local self-signed code-signing identity (key + cert with EKU
+ *  codeSigning → p12 → keychain import with codesign pre-authorized via -T).
+ *  The one-time install event. */
+function createIdentity(run: SigningRunner): { ok: boolean; detail?: string } {
+  const dir = mkdtempSync(join(tmpdir(), 'iapeer-signing-'))
+  const key = join(dir, 'key.pem')
+  const cert = join(dir, 'cert.pem')
+  const p12 = join(dir, 'id.p12')
+  // Throwaway p12 transport password — the file lives seconds inside a 0700 tmp dir.
+  const pass = `iapeer-${process.pid}-${Math.floor(Math.random() * 1e9)}`
+  try {
+    const req = run(SYSTEM_OPENSSL, [
+      'req', '-x509', '-newkey', 'rsa:2048', '-keyout', key, '-out', cert,
+      '-days', '3650', '-nodes', '-subj', `/CN=${SIGNING_IDENTITY_CN}`,
+      '-addext', 'keyUsage=digitalSignature', '-addext', 'extendedKeyUsage=codeSigning',
+    ])
+    if (req.status !== 0) return { ok: false, detail: `openssl req failed: ${req.stderr.trim().split('\n')[0] ?? ''}` }
+    const exp = run(SYSTEM_OPENSSL, [
+      'pkcs12', '-export', '-inkey', key, '-in', cert, '-out', p12,
+      '-passout', `pass:${pass}`, '-name', SIGNING_IDENTITY_CN,
+    ])
+    if (exp.status !== 0) return { ok: false, detail: `openssl pkcs12 failed: ${exp.stderr.trim().split('\n')[0] ?? ''}` }
+    // -T /usr/bin/codesign pre-authorizes codesign in the key's ACL — at most ONE
+    // keychain confirmation at the very first signing (the install-time event).
+    const imp = run('security', ['import', p12, '-P', pass, '-T', '/usr/bin/codesign'])
+    if (imp.status !== 0) return { ok: false, detail: `security import failed: ${imp.stderr.trim().split('\n')[0] ?? ''}` }
+    return { ok: true }
+  } finally {
+    try {
+      rmSync(dir, { recursive: true, force: true })
+    } catch {
+      /* best-effort cleanup of the throwaway key material */
+    }
+  }
+}
+
+/**
+ * Re-sign the installed binary with the stable local identity (creating the
+ * identity on first use). Called by installIapeer after the atomic rename —
+ * i.e. on EVERY install/update path, so the designated requirement (and with it
+ * every TCC grant) stays constant while the bytes change.
+ */
+export function signInstalledBinary(
+  binPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+  run: SigningRunner = defaultRunner,
+): SigningOutcome {
+  // Keychain + codesign are HOST-GLOBAL — same fail-closed double-check as the
+  // launchctl guards: consult both the passed env and the process env.
+  if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') {
+    return { state: 'skipped-sandbox', detail: 'IAPEER_TEST_SANDBOX=1 — not touching the real keychain' }
+  }
+  let created = false
+  if (!identityPresent(run)) {
+    const c = createIdentity(run)
+    if (!c.ok) {
+      return { state: 'failed-soft', detail: `${c.detail} — binary stays ad-hoc-signed (works, but TCC prompts will re-appear after updates)` }
+    }
+    created = true
+  }
+  const sign = run('codesign', ['-f', '-s', SIGNING_IDENTITY_CN, '--identifier', SIGNING_IDENTIFIER, binPath])
+  if (sign.status !== 0) {
+    return {
+      state: 'failed-soft',
+      detail: `codesign failed: ${sign.stderr.trim().split('\n')[0] ?? `exit ${sign.status}`} — binary stays ad-hoc-signed (works, but TCC prompts will re-appear after updates)`,
+    }
+  }
+  return created ? { state: 'signed-new-identity' } : { state: 'signed' }
+}

package/src/launch/index.ts

@@ -57,6 +57,7 @@ export {
   installAlwaysOnPlist,
   isFoundationOwnedPlist,
   launchctlBootstrap,
+  bootstrapJobCore,
   resolveExecutable,
   IAPEER_PLIST_OWNER_KEY,
 } from './launchd.ts'
@@ -65,6 +66,9 @@ export type {
   InstallAlwaysOnPlistOptions,
   BootstrapResult,
   BootstrapState,
+  BootstrapCoreDeps,
+  BootstrapCoreResult,
+  LaunchctlRunner,
 } from './launchd.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/launch/launchd.test.ts

@@ -10,6 +10,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from 'os'
 import { join } from 'path'
 import {
+  bootstrapJobCore,
   getAdapter,
   installAlwaysOnPlist,
   isFoundationOwnedPlist,
@@ -326,6 +327,74 @@ describe('resolveExecutable + runtime-bin pinning', () => {
   })
 })
 
+// ─────────────────────────────────────────────────────────────────────────────
+// bootstrapJobCore — the undead-job-safe bootstrap (boris's connect-acceptance
+// find 10.06: bootout → immediate bootstrap → exit 5 I/O error → the whole
+// fleet's telegram router stayed DOWN). Pure DI core: run/sleep injected.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('bootstrapJobCore (undead-job race)', () => {
+  type Call = { args: string[] }
+  function harness(script: { printStatuses: number[]; bootstrapStatuses: number[] }) {
+    const calls: Call[] = []
+    const sleeps: number[] = []
+    let printI = 0
+    let bootI = 0
+    const run = (args: string[]) => {
+      calls.push({ args })
+      if (args[0] === 'print') {
+        const status = script.printStatuses[Math.min(printI, script.printStatuses.length - 1)]!
+        printI++
+        return { status, stderr: '' }
+      }
+      const status = script.bootstrapStatuses[Math.min(bootI, script.bootstrapStatuses.length - 1)]!
+      bootI++
+      return { status, stderr: status === 0 ? '' : 'Bootstrap failed: 5: Input/output error' }
+    }
+    return { calls, sleeps, deps: { run, sleepMs: (ms: number) => void sleeps.push(ms) } }
+  }
+
+  test('clean path: job not listed, first bootstrap succeeds — zero sleeps', () => {
+    const h = harness({ printStatuses: [1], bootstrapStatuses: [0] })
+    const r = bootstrapJobCore('501', 'com.iapeer.x', '/p.plist', h.deps)
+    expect(r).toEqual({ state: 'loaded', attempts: 1 })
+    expect(h.sleeps).toEqual([])
+  })
+
+  test("boris's repro: undead job vanishes after polls, first bootstrap exit 5, retry succeeds", () => {
+    // print: listed, listed, gone (the bootout dismantle window) → bootstrap:
+    // exit 5 once (still racy), success on the retry after backoff.
+    const h = harness({ printStatuses: [0, 0, 1, 1, 1], bootstrapStatuses: [5, 0] })
+    const r = bootstrapJobCore('501', 'com.iapeer.arthur', '/p.plist', h.deps)
+    expect(r.state).toBe('loaded')
+    expect(r.attempts).toBe(2)
+    expect(h.sleeps.length).toBeGreaterThan(0) // waited for gone + backoff before retry
+  })
+
+  test('genuinely LIVE job (stays listed through the gone budget) → already-loaded, bootstrap NEVER called', () => {
+    const h = harness({ printStatuses: [0], bootstrapStatuses: [0] }) // always listed
+    const r = bootstrapJobCore('501', 'com.iapeer.x', '/p.plist', { ...h.deps, goneTimeoutMs: 2_000 })
+    expect(r).toEqual({ state: 'already-loaded', attempts: 0 })
+    expect(h.calls.some(c => c.args[0] === 'bootstrap')).toBe(false)
+  })
+
+  test('every attempt fails → failed with the attempt count and the last stderr (LOUD, not silent)', () => {
+    const h = harness({ printStatuses: [1], bootstrapStatuses: [5] })
+    const r = bootstrapJobCore('501', 'com.iapeer.x', '/p.plist', h.deps)
+    expect(r.state).toBe('failed')
+    expect(r.attempts).toBe(4)
+    expect(r.detail).toContain('Input/output error')
+    expect(r.detail).toContain('4 bootstrap attempts')
+  })
+
+  test('a racing load between attempts reads already-loaded (idempotent success)', () => {
+    // first bootstrap fails; before the retry the job shows up listed (raced in)
+    const h = harness({ printStatuses: [1, 0], bootstrapStatuses: [5] })
+    const r = bootstrapJobCore('501', 'com.iapeer.x', '/p.plist', h.deps)
+    expect(r.state).toBe('already-loaded')
+  })
+})
+
 describe('runAlwaysOn guard', () => {
   test('a non-infra runtime is rejected with exit code 1 (no tmux touched)', async () => {
     expect(await runAlwaysOn('boris', 'claude', '/tmp/whatever')).toBe(1)

package/src/launch/launchd.ts

@@ -215,6 +215,89 @@ function isLaunchdLoaded(label: string, uid: string): boolean {
   return spawnSync('launchctl', ['print', `gui/${uid}/${label}`], { stdio: 'ignore' }).status === 0
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// UNDEAD-JOB-SAFE bootstrap core (boris's live find 10.06, connect acceptance):
+// after `launchctl bootout` launchd dismantles the job ASYNCHRONOUSLY — an
+// immediate `bootstrap` hits the still-listed "undead" job and fails with
+// exit 5 "Input/output error" (the known PP race class, canon «Жизненный цикл
+// запуска persistent-peer и точки гонки»). On the connect flow that left the
+// WHOLE fleet's telegram router down. This core makes every restart-shaped flow
+// (stop→start, connect router restart, update-runtime) survive the race:
+//   (1) WAIT-FOR-GONE: while the job is still listed, poll `print` up to
+//       goneTimeoutMs. Vanished → proceed to bootstrap. STILL listed at the
+//       deadline → it is a genuinely LIVE job (KeepAlive running), not an undead
+//       one → 'already-loaded' (the idempotent no-op, same meaning as before).
+//   (2) BOOTSTRAP WITH BACKOFF: attempts with [0, 2 s, 5 s, 15 s] pauses
+//       (~22 s budget — covers the observed "manual retry succeeded after ~30 s"
+//       window), re-checking gone before each retry. All attempts failed →
+//       'failed' with the attempt count and the last stderr, so the caller can
+//       print the manual rescue recipe LOUD instead of leaving the job down
+//       silently.
+// Pure DI core (run/sleep injected) — unit-testable without launchctl and
+// without tripping the test-sandbox guard that wraps the public function.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface LaunchctlRunner {
+  (args: string[]): { status: number | null; stderr: string }
+}
+
+export interface BootstrapCoreDeps {
+  run: LaunchctlRunner
+  sleepMs: (ms: number) => void
+  /** Budget for the undead job to vanish after a bootout (default 10 000 ms). */
+  goneTimeoutMs?: number
+  /** Pauses BEFORE each bootstrap attempt (default [0, 2000, 5000, 15000]). */
+  backoffMs?: number[]
+}
+
+export interface BootstrapCoreResult {
+  state: 'loaded' | 'already-loaded' | 'failed'
+  attempts: number
+  detail?: string
+}
+
+export function bootstrapJobCore(
+  uid: string,
+  label: string,
+  plistPath: string,
+  deps: BootstrapCoreDeps,
+): BootstrapCoreResult {
+  const goneTimeout = deps.goneTimeoutMs ?? 10_000
+  const backoffs = deps.backoffMs ?? [0, 2_000, 5_000, 15_000]
+  const listed = () => deps.run(['print', `gui/${uid}/${label}`]).status === 0
+
+  // (1) wait-for-gone (an undead job vanishes within seconds; a LIVE KeepAlive
+  //     job stays listed → idempotent no-op, exactly the old 'already-loaded').
+  if (listed()) {
+    const pollStep = 500
+    let waited = 0
+    while (waited < goneTimeout) {
+      deps.sleepMs(pollStep)
+      waited += pollStep
+      if (!listed()) break
+    }
+    if (listed()) return { state: 'already-loaded', attempts: 0 }
+  }
+
+  // (2) bootstrap with backoff; re-verify gone before each retry.
+  let last = ''
+  for (let attempt = 0; attempt < backoffs.length; attempt++) {
+    if (backoffs[attempt]! > 0) deps.sleepMs(backoffs[attempt]!)
+    if (attempt > 0 && listed()) {
+      // the failed attempt may have half-loaded it, or a race loaded it — success
+      return { state: 'already-loaded', attempts: attempt }
+    }
+    const r = deps.run(['bootstrap', `gui/${uid}`, plistPath])
+    if (r.status === 0) return { state: 'loaded', attempts: attempt + 1 }
+    last = r.stderr.trim() || `exit ${r.status}`
+  }
+  return {
+    state: 'failed',
+    attempts: backoffs.length,
+    detail: `${backoffs.length} bootstrap attempts failed (last: ${last})`,
+  }
+}
+
 export type DaemonRestartState =
   | 'restarted' // kickstart -k succeeded → the daemon is now on the freshly-installed binary
   | 'not-loaded' // com.agfpd.iapeer is not in the gui domain → nothing to restart (new binary
@@ -286,13 +369,20 @@ export function launchctlBootstrap(
     return { state: 'skipped-sandbox', label, detail: 'IAPEER_TEST_SANDBOX=1 — not loading a real launchd job' }
   }
   const uid = currentUid()
-  if (isLaunchdLoaded(label, uid)) return { state: 'already-loaded', label }
-  const r = spawnSync('launchctl', ['bootstrap', `gui/${uid}`, plistPath], { encoding: 'utf8' })
-  if (r.status === 0) return { state: 'loaded', label }
-  // A race could have loaded it between the check and the bootstrap; treat a
-  // now-loaded service as success (still idempotent).
-  if (isLaunchdLoaded(label, uid)) return { state: 'already-loaded', label }
-  return { state: 'failed', label, detail: (r.stderr ?? '').trim() || `launchctl bootstrap exited ${r.status}` }
+  // UNDEAD-JOB-SAFE core (boris's connect-acceptance find): wait for a booted-out
+  // job to actually vanish, then bootstrap with backoff. A genuinely LIVE job
+  // reads 'already-loaded' (idempotent no-op, same semantics as before); only a
+  // job that stays failing through every attempt reads 'failed'.
+  const core = bootstrapJobCore(uid, label, plistPath, {
+    run: args => {
+      const r = spawnSync('launchctl', args, { encoding: 'utf8' })
+      return { status: r.status, stderr: r.stderr ?? '' }
+    },
+    sleepMs: ms => spawnSync('sleep', [String(ms / 1000)]),
+  })
+  return core.state === 'failed'
+    ? { state: 'failed', label, detail: core.detail }
+    : { state: core.state, label }
 }
 
 export interface InstallAlwaysOnPlistOptions {

package/src/onboard/index.ts

@@ -65,11 +65,15 @@ function isExecutable(binOrName: string, env: NodeJS.ProcessEnv = process.env):
     }
   }
   // bare name → PRESENCE probe over PATH (`command -v` semantics), NO spawn.
-  // History (both live finds 10.06): the original `--version` ANSWER probe HANGS
-  // FOREVER for codex in a non-tty (three stray probes sat 25+ min); the 10 s
-  // timeout that replaced it then DEGRADED a LIVE codex to 'runtime-missing' —
-  // masking a working runtime (boris's catch). The skip-decision only asks "is
-  // the runtime installed", and presence answers that without executing anything.
+  // History (live finds 10.06): the original `--version` ANSWER probe hung forever
+  // (three stray probes sat 25+ min); the 10 s timeout that replaced it then
+  // DEGRADED a live-looking codex to 'runtime-missing' (boris's catch). ROOT CAUSE
+  // (final, boris+iapeer-memory): macOS held the cask-updated codex on a GUI
+  // launch-approval dialog — EVERY invocation parked before main (observed as a
+  // dyld hang) until the owner confirmed the dialog. NOT a non-tty class, not a
+  // broken binary. The presence probe stays right regardless: the skip question is
+  // "is the runtime installed", and presence answers it without executing a
+  // possibly-wedged binary at all.
   for (const dir of (env.PATH ?? '').split(':')) {
     if (!dir) continue
     try {
@@ -90,10 +94,11 @@ function isExecutable(binOrName: string, env: NodeJS.ProcessEnv = process.env):
  */
 export function isMarketplaceRegistered(runtime: OnboardRuntime, env: NodeJS.ProcessEnv = process.env): boolean {
   const bin = runtimeBin(runtime, env)
-  // HARD TIMEOUT — the codex CLI hangs FOREVER in a non-tty on ANY subcommand
-  // (live 10.06: first `--version`, then `plugin marketplace list` after the
-  // presence-probe fix let a live codex through). Timeout → status null →
-  // "not registered" → the add (also time-bounded) decides; never a wedge.
+  // HARD TIMEOUT — a runtime CLI can wedge before main on ANY invocation (live
+  // 10.06: macOS launch-approval pending after a cask update parked codex — first
+  // `--version`, then this very `plugin marketplace list` after the presence
+  // probe let the binary through). Timeout → status null → "not registered" →
+  // the add (also time-bounded) decides; never a wedge.
   const r = spawnSync(bin, ['plugin', 'marketplace', 'list'], { encoding: 'utf8', timeout: 60_000 })
   if (r.status !== 0) return false
   return isAgfpdInList(`${r.stdout ?? ''}`)
@@ -115,12 +120,13 @@ export function isAgfpdInList(listOutput: string): boolean {
 /** Register OUR marketplace for this runtime (`<runtime> plugin marketplace add <ref>`). */
 function registerMarketplace(runtime: OnboardRuntime, env: NodeJS.ProcessEnv): { ok: boolean; detail?: string } {
   const bin = runtimeBin(runtime, env)
-  // Same hard timeout as the list probe (codex non-tty hang class) — a wedged add
-  // degrades to a loud 'failed' line instead of freezing the host phase.
+  // Same hard timeout as the list probe (the pre-main wedge class — known live
+  // representative: macOS launch-approval pending after a cask update) — a wedged
+  // add degrades to a loud 'failed' line instead of freezing the host phase.
   const r = spawnSync(bin, ['plugin', 'marketplace', 'add', MARKETPLACE_REF], { encoding: 'utf8', timeout: 120_000 })
   return r.status === 0
     ? { ok: true }
-    : { ok: false, detail: (r.stderr ?? '').trim() || (r.status === null ? 'timed out (non-tty hang?)' : `exit ${r.status}`) }
+    : { ok: false, detail: (r.stderr ?? '').trim() || (r.status === null ? 'timed out (wedged runtime CLI?)' : `exit ${r.status}`) }
 }
 
 /**