@agfpd/iapeer 0.2.63 → 0.2.65

package/package.json

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

package/src/cli/cli.test.ts

@@ -470,7 +470,7 @@ describe('compact (resume sleeping dialogue)', () => {
         wakeCalls.push(args)
         return { status: 'READY', woke: true, runtime: args.runtime, process_address: `${args.runtime}-${args.personality}`, taskDelivered: true }
       },
-      controlFn: (personality, runtime, command) => {
+      controlFn: async (personality, runtime, command) => {
         controlCalls.push({ personality, runtime, command })
         return ok({ ok: true, controlled: { personality, runtime: runtime! }, command: command.name, ts: 't' })
       },
@@ -495,7 +495,7 @@ describe('compact (resume sleeping dialogue)', () => {
     const o = await compactPeer('slow', 'codex', {
       env: e,
       wakeFn: async args => ({ status: 'READY', woke: true, runtime: args.runtime, process_address: `${args.runtime}-${args.personality}`, taskDelivered: true }),
-      controlFn: (personality, runtime, command) => ok({ ok: true, controlled: { personality, runtime: runtime! }, command: command.name, ts: 't' }),
+      controlFn: async (personality, runtime, command) => ok({ ok: true, controlled: { personality, runtime: runtime! }, command: command.name, ts: 't' }),
       compactDoneFn: () => err('compact did not complete within test'),
     })
     expect(o.action).toBe('failed')

package/src/cli/index.ts

@@ -48,6 +48,8 @@ import {
   type WakeResult,
 } from '../lifecycle/index.ts'
 import { getAdapter } from '../launch/index.ts'
+import { hostRunDir, hostSessionAlive } from '../launch/ptyHost.ts' // spawn-flip Ф0b-3: host-aware attach
+import { runSupervisorClient } from '../supervisor/client.ts' // @xterm-free attach client (both reattach port-deps baked in)
 import { cycleDaemon, isFoundationOwnedPlist, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
 import { readPeerProfile, resolveCallerIdentity, resolveIdentity, writePeerProfileAtomic } from '../identity/index.ts'
 import { peerProfilePath } from '../storage/index.ts'
@@ -583,7 +585,7 @@ export async function compactPeer(
       }
     }
     const baseline = compactDoneBaseline(rt, peer.cwd, { env })
-    const r = control(personality, rt, { name: 'compact' })
+    const r = await control(personality, rt, { name: 'compact' })
     if (!r.ok) return { personality, runtime: rt, action: 'failed', reason: r.error.message }
     const waited = waitDone(r.value.controlled.runtime as Runtime, baseline, false)
     if (waited) return waited
@@ -622,7 +624,7 @@ export async function compactPeer(
   }
   clearIdleReaped(cfg, identity)
   const baseline = compactDoneBaseline(rt, peer.cwd, { env })
-  const r = control(personality, rt, { name: 'compact' })
+  const r = await control(personality, rt, { name: 'compact' })
   if (!r.ok) return { personality, runtime: rt, action: 'failed', woke: true, reason: r.error.message }
   const waited = waitDone(rt, baseline, true)
   if (waited) return waited
@@ -1656,7 +1658,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // In-session control (Ф-E, clean-slash namespace): interrupt a stuck/raving
         // turn (Escape). UNCONDITIONAL — acts on the live session.
         if (!positionals[0]) return usage(errOut)
-        const r = routeControl(positionals[0], positionals[1], { name: verb })
+        const r = await routeControl(positionals[0], positionals[1], { name: verb })
         if (!r.ok) {
           errOut(`${verb}: ${r.error.message}\n`)
           return 1
@@ -1743,6 +1745,17 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // reads directly off the log.
         const attachCfg = loadLifecycleConfig(env)
         appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach', identity: r.identity, woke: String(r.woke) }, { env })
+        // SPAWN-FLIP Ф0b-3: a supervisor-HOSTED session has no tmux to attach — hand the operator to
+        // the supervisor client (runSupervisorClient: raw passthrough + repaint-on-attach + Ctrl-]
+        // detach + both reattach port-deps). It calls process.exit on every terminal path, so bracket
+        // attach-end via an exit hook (appendFileSync is signal/exit-safe). Flag-off → tmux attach.
+        if (hostSessionAlive(r.identity)) {
+          process.on('exit', () =>
+            appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach-end', identity: r.identity, rc: process.exitCode ?? 0 }, { env }),
+          )
+          await runSupervisorClient(hostRunDir(), r.identity)
+          return 0 // unreachable — runSupervisorClient exits on detach / session end
+        }
         // Drop the operator into the session. `env -u TMUX` so a nested attach from
         // inside tmux does not error ("sessions should be nested with care").
         const attachEnv = { ...env }

package/src/cli/listTui.ts

@@ -9,6 +9,8 @@
 
 import { spawnSync } from 'child_process'
 import { attachPeer } from '../lifecycle/index.ts'
+import { hostRunDir, hostSessionAlive } from '../launch/ptyHost.ts' // spawn-flip Ф0b-3: host-aware attach
+import { runSupervisorClient } from '../supervisor/client.ts'
 import { listPeers, type PeerListing } from './index.ts'
 
 const GLYPH: Record<'live' | 'asleep' | 'stopped', string> = { live: '●', asleep: '○', stopped: '✕' }
@@ -138,6 +140,11 @@ export async function runListTui(env: NodeJS.ProcessEnv = process.env): Promise<
           return 1
         }
         stdout.write(`${r.woke ? 'woke + ' : ''}attaching ${r.identity}…\n`)
+        // SPAWN-FLIP Ф0b-3: a supervisor-HOSTED session attaches via the supervisor client (no tmux).
+        if (hostSessionAlive(r.identity)) {
+          await runSupervisorClient(hostRunDir(), r.identity)
+          return 0 // unreachable — runSupervisorClient exits on detach / session end
+        }
         const attachEnv = { ...env }
         delete attachEnv.TMUX
         const a = spawnSync('tmux', ['-S', r.socketPath, 'attach', '-t', r.identity], {

package/src/daemon/main.ts

@@ -214,6 +214,10 @@ export function makeComposerQueueRouteDeps(cfg: LifecycleConfig, env: NodeJS.Pro
 
   return createComposerDeliveryQueue({
     env,
+    // Spawn-flip Ф0b-3 slice 3c: the HOSTED occupancy default reads <logDir>/<identity>.log — the SAME
+    // dir the wake→launch path writes warm-peer pane-logs to (cfg.logDir), shared with the ready-gate
+    // flip + the shadow observer. tmux targets ignore it.
+    logDir: cfg.logDir,
     noteLiveTopic,
     onDelivered,
     notifyFailed: async (job, reason) => {

package/src/launch/hostComposerOccupied.test.ts

@@ -0,0 +1,63 @@
+// Spawn-flip cutover Block 2, Ф0b-2 slice 2 — hosted composer-occupancy DETECTION.
+//
+// paneLogComposerOccupied reads a supervisor-HOSTED session's pane-log model and runs the burn-in-
+// validated composerOccupancyFromModel (REUSED from the leaf, not reimplemented). These suites are
+// boris's slice-2 acceptance: the guard FIRES on a busy-composer model-state and stays cold on an
+// empty / dim-ghost composer — proven by injecting real rendered frames into a pane-log. The end-to-
+// end hold (attached human + warm-deliver respects the guard) is validated with the attach client in
+// Ф0b-3; here we bind the DETECTOR. Bun-native @xterm is loaded dynamically by the function under test.
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { paneLogComposerOccupied } from './readyGateModel.ts'
+
+const COLS = 80
+const ROWS = 24
+
+let dir: string | null = null
+function paneLogWith(frame: string): string {
+  dir = mkdtempSync(join(tmpdir(), 'iapeer-occ-'))
+  const log = join(dir, 'pane.log')
+  writeFileSync(log, Buffer.from(frame, 'utf8')) // raw bytes — preserve the multibyte ❯ / › glyphs
+  return log
+}
+afterEach(() => {
+  if (dir) rmSync(dir, { recursive: true, force: true })
+  dir = null
+})
+
+describe('paneLogComposerOccupied — guard FIRES on a busy hosted composer (slice-2 acceptance)', () => {
+  test('claude ❯ with human text → BUSY (true)', async () => {
+    const log = paneLogWith('\x1b[24;1H❯ the quick brown fox')
+    expect(await paneLogComposerOccupied(log, COLS, ROWS, 'claude')).toBe(true)
+  })
+
+  test('codex › with human text → BUSY (true)', async () => {
+    const log = paneLogWith('\x1b[24;1H› reviewer note')
+    expect(await paneLogComposerOccupied(log, COLS, ROWS, 'codex')).toBe(true)
+  })
+})
+
+describe('paneLogComposerOccupied — guard stays COLD on a free composer', () => {
+  test('claude ❯ empty → free (false)', async () => {
+    const log = paneLogWith('\x1b[24;1H❯ ')
+    expect(await paneLogComposerOccupied(log, COLS, ROWS, 'claude')).toBe(false)
+  })
+
+  test('dim-ghost placeholder (grey246 + dim) → NOT human → free (false)', async () => {
+    const log = paneLogWith('\x1b[24;1H❯ \x1b[2m\x1b[38;5;246mTry "fix typecheck errors"\x1b[0m')
+    expect(await paneLogComposerOccupied(log, COLS, ROWS, 'claude')).toBe(false)
+  })
+
+  test('no prompt glyph rendered → free (false)', async () => {
+    const log = paneLogWith('\x1b[24;1Hjust some output, no composer')
+    expect(await paneLogComposerOccupied(log, COLS, ROWS, 'claude')).toBe(false)
+  })
+})
+
+describe('paneLogComposerOccupied — uncertainty is conservative (BUSY)', () => {
+  test('missing pane-log → BUSY (true): never paste into a maybe-occupied composer', async () => {
+    expect(await paneLogComposerOccupied(join(tmpdir(), 'iapeer-occ-nonexistent.log'), COLS, ROWS, 'claude')).toBe(true)
+  })
+})

package/src/launch/index.ts

@@ -14,13 +14,14 @@
 // decides WHEN/HOW-MANY and hands launch a fully-resolved LaunchSpec + adapter.
 
 import { mkdirSync } from 'fs'
-import { homedir } from 'os'
 import { dirname } from 'path'
 import { spawnSync } from 'child_process'
-import { CODEX_BEARER_ENV_VAR, CODEX_DUMMY_BEARER, type Runtime } from '../core/constants.ts'
-import { readLaunchEnv } from '../storage/index.ts'
+import { type Runtime } from '../core/constants.ts'
+import { buildLaunchInvocation } from './invocation.ts'
 import { canaryChannel, dismissCanary, ensureServerCanary, exitLogPath, signalCanaryClean } from './canary.ts'
 import { hardenCmdLogDir, prepareCmdLogDir } from './cmdlog.ts'
+import { logReadyGateCrossCheck, readyGatePtyFlipEnabled, readyGateViewport } from './readyGateModel.ts'
+import { deliverHosted, hostSessionAlive, ptyHostEnabled, startPtyHost, waitHostReady } from './ptyHost.ts'
 import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { claudeAdapter } from './adapters/claude.ts'
 import { codexAdapter } from './adapters/codex.ts'
@@ -248,6 +249,53 @@ export const launch: LaunchFn = async (
   //       at a not-yet-created dir. Symmetric to the cfg.logDir mkdir before pipe-pane.
   mkdirSync(dirname(sock), { recursive: true })
 
+  // ── SPAWN-FLIP (cutover Block 2, Ф0a) — per-peer `.pty-host` flag, DARK by default ────────────────
+  // A flag-on tui peer is HOSTED by the supervisor (it owns the pty + boot-driver + pane-log) instead
+  // of `tmux new-session`. The supervisor serves the SAME launch-composed argv+env (buildLaunchInvocation,
+  // the single source the tmux path also uses), so the hosted session is parity-identical. Readiness is
+  // read off the pane-log model (the supervisor's boot-driver answers startup dialogs internally);
+  // delivery goes over the supervisor socket. UNCONDITIONAL SPAWN-FALLBACK: any host-bringup failure
+  // falls through to the tmux path below — a flipped peer is NEVER worse than tmux ON SPAWN. Flag-off →
+  // this whole block is skipped and the tmux path is byte-identical (golden). Routers are never hosted
+  // (infra, launchd-owned). @xterm stays out of THIS process (ptyHost: @xterm-free start + deliver +
+  // sessionAlive; readiness's @xterm import is dynamic and only loads here, flag-on).
+  if (adapter.kind === 'tui' && ptyHostEnabled(cfg.logDir, identity)) {
+    const invocation = buildLaunchInvocation(spec, adapter, cfg)
+    mkdirSync(cfg.logDir, { recursive: true, mode: 0o700 }) // the supervisor writes the pane-log here
+    const paneLogPath = `${cfg.logDir}/${identity}.log`
+    const host = await startPtyHost({
+      identity,
+      runtime: spec.runtime,
+      cwd,
+      paneLogPath,
+      exitLogPath: cfg.exitLogDir ? exitLogPath(cfg.exitLogDir) : undefined,
+      invocation,
+    })
+    if (host.ok) {
+      // BOOT: the supervisor's boot-driver dismisses startup dialogs internally; wait for the input
+      // surface via the pane-log model, then deliver over the socket + ready-gate on a model turn —
+      // the SAME shape as the tmux boot/deliver/ready-gate below, with host equivalents.
+      const baselineMtime = adapter.newestActivityMtime(cwd) ?? 0
+      const isReady = await waitHostReady(
+        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs },
+        sleep,
+      )
+      if (!isReady) return fail(identity, 'never-became-ready (hosted: supervisor input surface not ready)')
+      if (firstMessage.trim().length === 0) return ready(identity) // bare bring-up — no message to deliver
+      const d = await deliverHosted(identity, firstMessage)
+      if (!d.ok) return fail(identity, `hosted deliver failed: ${d.error}`)
+      const readyDeadline = Date.now() + cfg.readyGateSecs * 1000
+      while (Date.now() < readyDeadline) {
+        await sleep(2000)
+        if (!hostSessionAlive(identity)) return fail(identity, 'hosted session vanished during ready-gate')
+        if ((adapter.newestActivityMtime(cwd) ?? 0) > baselineMtime) return ready(identity)
+      }
+      return fail(identity, 'model-did-not-process-task (hosted: no activity advance after delivery)')
+    }
+    // SPAWN-FALLBACK — host bringup failed; record it and fall through to the tmux path (never worse).
+    appendLifecycleEvent(cfg.exitLogDir, { ev: 'pty-host-fallback', identity, reason: host.error }, { env })
+  }
+
   // (1) Pre-clean any stale tmux server on this socket, then launch detached.
   //     Silence the server-death canary EXPLICITLY first — this teardown is
   //     deliberate: signal the channel (client exits 0) AND dismiss the sh
@@ -266,27 +314,13 @@ export const launch: LaunchFn = async (
   //     PEER_START_ARGS (APPENDED after the adapter's base flags — extraArgs is last
   //     in every buildArgv) and extra child env. spec.extraArgs (an explicit caller
   //     override) comes first, then launch.env's; both land after the base flags.
-  const launchEnv = readLaunchEnv(cwd, spec.runtime)
-  const specWithArgs: LaunchSpec =
-    launchEnv.startArgs.length > 0
-      ? { ...spec, extraArgs: [...(spec.extraArgs ?? []), ...launchEnv.startArgs] }
-      : spec
-  const runtimeCmd = adapter.buildArgv(specWithArgs, cfg).map(shellQuote).join(' ')
-  // Child env: base env + launch.env extras + the identity ABI (identity LAST so a
-  // stray PEER_* in launch.env can never override the resolved identity) + PATH.
-  const childEnv: NodeJS.ProcessEnv = {
-    ...env,
-    ...launchEnv.env,
-    // codex token-free MCP import: the daemon's bearer env var is set to the PUBLIC,
-    // non-secret stub so codex flips authStatus unsupported→bearer_token and imports
-    // send_to_peer (the OPEN daemon ignores it, authenticating by PEER_IDENTITY below
-    // via env_http_headers). Only for codex — claude carries its identity in .mcp.json.
-    ...(spec.runtime === 'codex' ? { [CODEX_BEARER_ENV_VAR]: CODEX_DUMMY_BEARER } : {}),
-    PEER_PERSONALITY: spec.personality,
-    PEER_RUNTIME: spec.runtime,
-    PEER_IDENTITY: identity,
-    PATH: env.PATH ?? `${homedir()}/.bun/bin:${homedir()}/.local/bin:/opt/homebrew/bin:/usr/bin:/bin`,
-  }
+  // argv + child env are composed by buildLaunchInvocation (invocation.ts) — the SINGLE source shared
+  // with the supervisor serving path (cutover Block 2) so a served session is byte-identical to this
+  // tmux-launched one. The tmux path shell-quotes+joins the argv into the new-session string; the
+  // supervisor path passes the same argv array to Bun.spawn. (PEER_START_ARGS append, codex bearer
+  // stub, identity ABI, PATH — all live there now, byte-for-byte unchanged.)
+  const { argv: runtimeArgv, env: childEnv } = buildLaunchInvocation(spec, adapter, cfg)
+  const runtimeCmd = runtimeArgv.map(shellQuote).join(' ')
   // (2.4) tmux command-log (killer-hunt socket-command layer, cmdlog.ts): WARM
   //       agent sessions start their server with `-v` so every client command —
   //       incl. a killer's `kill-server`/`kill-session`, invisible to signal
@@ -385,7 +419,29 @@ export const launch: LaunchFn = async (
       tmux(sock, 'send-keys', '-t', identity, ...dialogKeys)
       continue
     }
-    if (adapter.isInputReady(pane)) {
+    // Ф1 READY-GATE SOURCE FLIP (per-peer flag, DARK by default). When the peer's flip flag is set,
+    // run the SAME isInputReady predicate on the pty-MODEL viewport (validated 0-divergence vs
+    // capture-pane by the burn-in gate, incl. the codex resume-with-history splash-off-screen center)
+    // instead of the capture-pane scrape, with an UNCONDITIONAL capture-pane fallback. This is the
+    // ONLY changed input — dialog detection (above) and delivery + delivery-confirm (below + transport)
+    // are untouched. Flag OFF → readyView === pane (byte-identical to today).
+    let readyView = pane
+    if (readyGatePtyFlipEnabled(cfg.logDir, identity)) {
+      const geo = tmux(sock, 'display', '-p', '-t', identity, '#{pane_width}x#{pane_height}')
+      const [c, r] = geo.ok ? geo.out.trim().split('x').map(Number) : [0, 0]
+      readyView = await readyGateViewport({ logDir: cfg.logDir, identity, fallback: pane, cols: c ?? 0, rows: r ?? 0 })
+      // SERVING-path cross-check (post-flip soak gate): the model verdict is AUTHORITATIVE (readyView);
+      // record what capture-pane WOULD have said, to prove 0 model-vs-capture divergence live in the
+      // serving path. Observability only — never affects the ready decision.
+      logReadyGateCrossCheck(cfg.exitLogDir, {
+        identity,
+        modelReady: adapter.isInputReady(readyView),
+        captureReady: adapter.isInputReady(pane),
+        geom: `${c ?? 0}x${r ?? 0}`,
+        nowISO: new Date().toISOString(),
+      })
+    }
+    if (adapter.isInputReady(readyView)) {
       if (!hasMessage) return ready(identity) // bare bring-up — session up, no message
       // Boot delivery = load-buffer → paste-buffer -p → Enter (Ф-#8b hardening):
       // the SAME mechanism warm delivery uses (transport.deliverViaTmux), replacing

package/src/launch/invocation.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'bun:test'
+import { homedir } from 'os'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { CODEX_BEARER_ENV_VAR, CODEX_DUMMY_BEARER } from '../core/constants.ts'
+import { readLaunchEnv, peerLaunchEnvPath } from '../storage/index.ts'
+import { claudeAdapter } from './adapters/claude.ts'
+import { codexAdapter } from './adapters/codex.ts'
+import { buildLaunchInvocation } from './invocation.ts'
+import type { LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from './types.ts'
+
+// NON-CIRCULAR GOLDEN (boris's bar): the ORACLE is the PRE-extraction inline build copied VERBATIM
+// from launch/index.ts @595b0f4 — the source of truth is the OLD code, NOT buildLaunchInvocation.
+// The differential test asserts the extracted function reproduces the oracle byte-for-byte; the
+// independent contract assertions (hardcoded from the contract, not from the function's output) catch
+// the case where oracle and function are wrong together. Two anchors: differential catches a
+// reorganization drift, contract catches a shared error.
+function oracleInline(
+  spec: LaunchSpec,
+  adapter: RuntimeAdapter,
+  cfg: LaunchAdapterConfig & { env?: NodeJS.ProcessEnv },
+): { argv: string[]; env: NodeJS.ProcessEnv } {
+  const env = cfg.env ?? process.env
+  const cwd = spec.cwd
+  const identity = spec.identity
+  const launchEnv = readLaunchEnv(cwd, spec.runtime)
+  const specWithArgs: LaunchSpec =
+    launchEnv.startArgs.length > 0
+      ? { ...spec, extraArgs: [...(spec.extraArgs ?? []), ...launchEnv.startArgs] }
+      : spec
+  const runtimeArgv = adapter.buildArgv(specWithArgs, cfg)
+  const childEnv: NodeJS.ProcessEnv = {
+    ...env,
+    ...launchEnv.env,
+    ...(spec.runtime === 'codex' ? { [CODEX_BEARER_ENV_VAR]: CODEX_DUMMY_BEARER } : {}),
+    PEER_PERSONALITY: spec.personality,
+    PEER_RUNTIME: spec.runtime,
+    PEER_IDENTITY: identity,
+    PATH: env.PATH ?? `${homedir()}/.bun/bin:${homedir()}/.local/bin:/opt/homebrew/bin:/usr/bin:/bin`,
+  }
+  return { argv: runtimeArgv, env: childEnv }
+}
+
+const CFG: LaunchAdapterConfig & { env: NodeJS.ProcessEnv } = {
+  claudeBin: '/bin/claude',
+  codexBin: '/bin/codex',
+  env: { PATH: '/test/path', BASE_VAR: 'base' },
+}
+
+function spec(over: Partial<LaunchSpec>): LaunchSpec {
+  return {
+    personality: 'p',
+    runtime: 'claude',
+    cwd: '/nonexistent-cwd-no-launchenv',
+    identity: 'claude-p',
+    socketPath: '/tmp/s.sock',
+    extraArgs: [],
+    ...over,
+  }
+}
+
+const adapterFor = (s: LaunchSpec): RuntimeAdapter => (s.runtime === 'codex' ? codexAdapter : claudeAdapter)
+
+// Representative specs: both runtimes × {bare, with system-prompt, with resume + extraArgs}.
+const SPECS: Array<{ name: string; spec: LaunchSpec }> = [
+  { name: 'claude bare', spec: spec({ runtime: 'claude', identity: 'claude-p' }) },
+  {
+    name: 'claude + system-prompt + resume + extras',
+    spec: spec({ runtime: 'claude', identity: 'claude-p', systemPromptFile: '/sp.md', resume: true, resumeRef: 'uuid-9', extraArgs: ['--foo'] }),
+  },
+  { name: 'codex bare', spec: spec({ runtime: 'codex', identity: 'codex-p' }) },
+  {
+    name: 'codex + system-prompt + resume',
+    spec: spec({ runtime: 'codex', identity: 'codex-p', systemPromptFile: '/sp.md', resume: true }),
+  },
+]
+
+describe('buildLaunchInvocation — differential vs the verbatim pre-extraction oracle', () => {
+  for (const { name, spec: s } of SPECS) {
+    test(`byte-identical to the inline build: ${name}`, () => {
+      const got = buildLaunchInvocation(s, adapterFor(s), CFG)
+      const want = oracleInline(s, adapterFor(s), CFG)
+      expect(got.argv).toEqual(want.argv)
+      expect(got.env).toEqual(want.env)
+    })
+  }
+
+  test('the launch.env merge branch (non-empty startArgs + extra env) is byte-identical too', () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'inv-launchenv-'))
+    try {
+      const p = peerLaunchEnvPath(cwd, 'codex')
+      mkdirSync(dirname(p), { recursive: true })
+      writeFileSync(p, 'PEER_START_ARGS=--from-env-a --from-env-b\nEXTRA_VAR=xyz\n')
+      const s = spec({ runtime: 'codex', identity: 'codex-p', cwd, extraArgs: ['--explicit'] })
+      const got = buildLaunchInvocation(s, codexAdapter, CFG)
+      const want = oracleInline(s, codexAdapter, CFG)
+      expect(got.argv).toEqual(want.argv)
+      expect(got.env).toEqual(want.env)
+      // sanity on the branch itself: explicit extras precede launch.env startArgs, both after base flags
+      expect(got.argv).toContain('--explicit')
+      expect(got.argv).toContain('--from-env-a')
+      expect(got.env.EXTRA_VAR).toBe('xyz')
+    } finally {
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+})
+
+// Independent contract anchors — expectations come from the CONTRACT, not from the function output.
+describe('buildLaunchInvocation — identity ABI + system-prompt swap (contract values)', () => {
+  test('codex carries the non-secret IAPEER_BEARER stub; claude does NOT (identity in .mcp.json)', () => {
+    expect(buildLaunchInvocation(spec({ runtime: 'codex', identity: 'codex-p' }), codexAdapter, CFG).env[CODEX_BEARER_ENV_VAR]).toBe(
+      CODEX_DUMMY_BEARER,
+    )
+    expect(
+      buildLaunchInvocation(spec({ runtime: 'claude', identity: 'claude-p' }), claudeAdapter, CFG).env[CODEX_BEARER_ENV_VAR],
+    ).toBeUndefined()
+  })
+
+  test('the identity ABI is present and matches the spec', () => {
+    const { env } = buildLaunchInvocation(spec({ runtime: 'codex', personality: 'boris', identity: 'codex-boris' }), codexAdapter, CFG)
+    expect(env.PEER_PERSONALITY).toBe('boris')
+    expect(env.PEER_RUNTIME).toBe('codex')
+    expect(env.PEER_IDENTITY).toBe('codex-boris')
+  })
+
+  test('the per-session system-prompt swap rides in argv (codex -c, claude --system-prompt-file)', () => {
+    const codexArgv = buildLaunchInvocation(spec({ runtime: 'codex', identity: 'codex-p', systemPromptFile: '/sp.md' }), codexAdapter, CFG).argv
+    expect(codexArgv).toContain('model_instructions_file=/sp.md')
+    const claudeArgv = buildLaunchInvocation(spec({ runtime: 'claude', identity: 'claude-p', systemPromptFile: '/sp.md' }), claudeAdapter, CFG).argv
+    expect(claudeArgv.join(' ')).toContain('--system-prompt-file /sp.md')
+  })
+})

package/src/launch/invocation.ts

@@ -0,0 +1,56 @@
+// buildLaunchInvocation — the argv + child-env composition shared by the tmux launch path and the
+// (cutover Block 2) supervisor serving path. Factored out of launch()'s inline build so BOTH produce
+// a BYTE-IDENTICAL invocation from ONE source — parity by construction (a supervisor-served session
+// must be indistinguishable from a tmux-launched one: same flags, same env, same identity). PURE
+// composition: reads the per-peer launch.env + assembles the identity ABI env; no spawn, no tmux.
+// The tmux path shell-quotes the argv into a new-session string; the supervisor path hands the argv
+// array straight to Bun.spawn — same argv, same env, different transport.
+import { homedir } from 'os'
+import { CODEX_BEARER_ENV_VAR, CODEX_DUMMY_BEARER } from '../core/constants.ts'
+import { readLaunchEnv } from '../storage/index.ts'
+import type { LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from './types.ts'
+
+export interface LaunchInvocation {
+  /** Runtime argv: binary + flags, including the per-session system-prompt swap (claude
+   *  --system-prompt-file / codex -c model_instructions_file=) and the appended PEER_START_ARGS.
+   *  The tmux path shell-quotes+joins it; the supervisor path passes it to Bun.spawn verbatim. */
+  argv: string[]
+  /** Full child environment: base env + per-peer launch.env extras + (codex) the non-secret bearer
+   *  stub + the identity ABI (PEER_PERSONALITY/RUNTIME/IDENTITY, written LAST so a stray PEER_* in
+   *  launch.env can never override the resolved identity) + PATH. */
+  env: NodeJS.ProcessEnv
+}
+
+/**
+ * Compose the runtime invocation (argv + child env) for a fully-resolved spec — the single source
+ * for both the tmux launch path and the supervisor serving path. PEER_START_ARGS from launch.env
+ * append AFTER the adapter's base flags (extraArgs is last in every buildArgv); an explicit
+ * spec.extraArgs (caller override) comes first, then launch.env's.
+ */
+export function buildLaunchInvocation(
+  spec: LaunchSpec,
+  adapter: RuntimeAdapter,
+  cfg: LaunchAdapterConfig & { env?: NodeJS.ProcessEnv },
+): LaunchInvocation {
+  const env = cfg.env ?? process.env
+  const launchEnv = readLaunchEnv(spec.cwd, spec.runtime)
+  const specWithArgs: LaunchSpec =
+    launchEnv.startArgs.length > 0
+      ? { ...spec, extraArgs: [...(spec.extraArgs ?? []), ...launchEnv.startArgs] }
+      : spec
+  const argv = adapter.buildArgv(specWithArgs, cfg)
+  const childEnv: NodeJS.ProcessEnv = {
+    ...env,
+    ...launchEnv.env,
+    // codex token-free MCP import: the bearer env var is set to the PUBLIC, non-secret stub so codex
+    // flips authStatus unsupported→bearer_token and imports send_to_peer (the OPEN daemon ignores it,
+    // authenticating by PEER_IDENTITY below via env_http_headers). Only for codex — claude carries its
+    // identity in .mcp.json.
+    ...(spec.runtime === 'codex' ? { [CODEX_BEARER_ENV_VAR]: CODEX_DUMMY_BEARER } : {}),
+    PEER_PERSONALITY: spec.personality,
+    PEER_RUNTIME: spec.runtime,
+    PEER_IDENTITY: spec.identity,
+    PATH: env.PATH ?? `${homedir()}/.bun/bin:${homedir()}/.local/bin:/opt/homebrew/bin:/usr/bin:/bin`,
+  }
+  return { argv, env: childEnv }
+}

package/src/launch/ptyHost.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ptyHostEnabled } from './ptyHost.ts'
+import { readyGatePtyFlipEnabled } from './readyGateModel.ts'
+
+describe('ptyHostEnabled — the spawn-flip per-peer flag', () => {
+  test('off by default; on when the .pty-host marker exists', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ptyhost-flag-'))
+    try {
+      expect(ptyHostEnabled(dir, 'codex-x')).toBe(false)
+      writeFileSync(join(dir, 'codex-x.pty-host'), '')
+      expect(ptyHostEnabled(dir, 'codex-x')).toBe(true)
+      expect(ptyHostEnabled(dir, 'codex-y')).toBe(false) // per-peer, not global
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('DISTINCT from the ready-gate flip marker — a readygate-flipped peer is NOT pty-hosted', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ptyhost-distinct-'))
+    try {
+      writeFileSync(join(dir, 'codex-perplex.pty-readygate'), '') // ready-gate flipped, still tmux-hosted
+      expect(readyGatePtyFlipEnabled(dir, 'codex-perplex')).toBe(true)
+      expect(ptyHostEnabled(dir, 'codex-perplex')).toBe(false) // the .pty-host marker is separate
+      writeFileSync(join(dir, 'codex-perplex.pty-host'), '')
+      expect(ptyHostEnabled(dir, 'codex-perplex')).toBe(true) // now supervisor-hosted too
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})