@agfpd/iapeer 0.2.19 → 0.2.21

package/package.json

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

package/src/cli/cli.test.ts

@@ -153,6 +153,37 @@ describe('send validation', () => {
   })
 })
 
+describe('send → ephemeral target: M3 FIFO parity with the daemon path (iapeer-memory ask)', () => {
+  test('a CLI send to a wake_policy:ephemeral peer ENQUEUES (queued ack), no live/miss bypass', async () => {
+    // an ephemeral worker cwd (profile declares wake_policy) registered in the index
+    const cwd = mkdtempSync(join(tmpdir(), 'iapeer-cli-eph-'))
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      join(cwd, '.iapeer', 'peer-profile.json'),
+      JSON.stringify({ personality: 'ephw', runtime: 'claude', runtimes: ['claude'], intelligence: 'artificial', wake_policy: 'ephemeral' }),
+    )
+    const e = env()
+    // routeSend resolves the peers index from the PROCESS env (transport reads
+    // readPeersIndex() bare) — point the process-level root at the sandbox too.
+    const prevRoot = process.env.IAPEER_ROOT
+    process.env.IAPEER_ROOT = root
+    try {
+      await upsertPeer({ personality: 'ephw', runtime: 'claude', cwd, intelligence: 'artificial' }, { rootDir: root })
+      await register('sender')
+      const r = await sendMessage({ from: 'claude-sender', target: 'ephw', message: 'task', env: e })
+      expect(r.queued).toBe(true) // serialized via the disk FIFO, exactly like the daemon path
+      expect(r.queueDepth).toBe(1)
+      // the task is durably on disk for the daemon tick to drain
+      const qdir = join(loadLifecycleConfig(e).stateDir, 'claude-ephw.queue')
+      expect(existsSync(qdir)).toBe(true)
+    } finally {
+      if (prevRoot !== undefined) process.env.IAPEER_ROOT = prevRoot
+      else delete process.env.IAPEER_ROOT
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+})
+
 describe('--help/-h global intercept (CLI hygiene — usage printed, NOTHING executed)', () => {
   let captured: string
   let origWrite: typeof process.stdout.write

package/src/cli/index.ts

@@ -323,9 +323,21 @@ export interface SendOptions extends CliEnvOptions {
 const cliWake: WakeFn = req =>
   wakeOrSpawn({ personality: req.personality, runtime: req.runtime, topic: req.topic, task: req.task })
 
-export async function sendMessage(opts: SendOptions): Promise<{ ok: true; delivered_to: { personality: string; runtime: string } }> {
+export async function sendMessage(
+  opts: SendOptions,
+): Promise<{ ok: true; delivered_to: { personality: string; runtime: string }; queued?: boolean; queueDepth?: number }> {
   const env = opts.env ?? process.env
   const caller = resolveCallerIdentity(parseIdentity(opts.from), readPeersIndex({ env }))
+  // wake_policy:ephemeral M3 parity (iapeer-memory ask, 10.06): the CLI path used
+  // to route an ephemeral target through the normal live/miss path — a notifier
+  // burst landed as TURNS in one live worker session instead of serializing
+  // through the disk FIFO the daemon path uses. Same seam, ONE difference: the
+  // drain kick is a NOOP here — a CLI process exits right after the ack, so an
+  // unawaited in-process wake would die with it; the daemon's supervise-tick
+  // drain scan (≤60 s) picks the queue up — the EXISTING retry path for failed
+  // kicks, not a new mechanism.
+  const { makeEphemeralRouteDeps } = await import('../daemon/main.ts')
+  const cfg = loadLifecycleConfig(env)
   const result = await routeSend(
     caller,
     {
@@ -335,10 +347,15 @@ export async function sendMessage(opts: SendOptions): Promise<{ ok: true; delive
       topic: opts.topic,
       attachments: opts.attachments,
     },
-    { wake: cliWake },
+    { wake: cliWake, ephemeral: makeEphemeralRouteDeps(cfg, env, () => {}) },
   )
   if (!result.ok) throw new Error(result.error.message)
-  return { ok: true, delivered_to: result.value.delivered_to }
+  return {
+    ok: true,
+    delivered_to: result.value.delivered_to,
+    queued: result.value.queued,
+    queueDepth: result.value.queueDepth,
+  }
 }
 
 function parseIdentity(identity: string): { personality: string; runtime: Runtime } {
@@ -714,7 +731,11 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           attachments: attachments.length ? attachments : undefined,
           env,
         })
-        out(`delivered to ${r.delivered_to.personality} (${r.delivered_to.runtime})\n`)
+        out(
+          r.queued
+            ? `queued for ${r.delivered_to.personality} (${r.delivered_to.runtime}), depth ${r.queueDepth ?? '?'} — the daemon tick drains it\n`
+            : `delivered to ${r.delivered_to.personality} (${r.delivered_to.runtime})\n`,
+        )
         return 0
       }
       case 'version':
@@ -807,10 +828,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/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,147 @@
+// 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'
+
+/** CROSS-PRODUCT CONTRACT (agreed with iapeer-memory, 10.06): this CN is the
+ *  SHARED signing identity of the whole agfpd stack. Each product signs with its
+ *  OWN --identifier (foundation: com.agfpd.iapeer; memory: com.agfpd.iapeer-memory),
+ *  so TCC subjects stay separate while the host carries ONE key (one keychain
+ *  prompt ever). Creation is first-needs-creates with the IDENTICAL profile (EKU
+ *  codeSigning, system LibreSSL p12, import -T /usr/bin/codesign) on both sides.
+ *  Changing the CN or the creation profile is a COORDINATED change across repos.
+ *  Known shared costs: re-creating the identity (deleted/expired — cert is 10 y)
+ *  migrates the TCC grants of EVERY stack product at once; a concurrent
+ *  first-creation by two installers could duplicate the CN (codesign would then
+ *  report an ambiguous identity) — installs are operator-sequential, residual
+ *  risk accepted. */
+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/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}`) }
 }
 
 /**