@agfpd/iapeer 0.1.0

package/src/lifecycle/lifecycle.test.ts

@@ -0,0 +1,496 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  attachPeer,
+  clearNewMark,
+  clearStopped,
+  composeFirstMessage,
+  folderLaunch,
+  hasNewMark,
+  isLaunchdManaged,
+  isStopped,
+  lastActiveRuntime,
+  loadLifecycleConfig,
+  resolveWakeMode,
+  resolveWakeRuntime,
+  setNewMark,
+  setStopped,
+  superviseTick,
+  wakeOrSpawn,
+  withWakeLock,
+  type LifecycleConfig,
+} from './index.ts'
+import { upsertPeer, type PeerRecord } from '../registry/index.ts'
+
+function peer(over: Partial<PeerRecord>): PeerRecord {
+  return {
+    personality: 'p',
+    runtime: 'claude',
+    runtimes: ['claude'],
+    description: '',
+    intelligence: 'artificial',
+    cwd: '/tmp/p',
+    ...over,
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// H5 — resolveWakeRuntime (registry-based, no live-socket scan)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('resolveWakeRuntime (H5)', () => {
+  test('explicit declared caller runtime wins', () => {
+    const r = resolveWakeRuntime('codex', peer({ runtimes: ['claude', 'codex'] }))
+    expect(r.ok && r.value).toBe('codex')
+  })
+
+  test('explicit UNDECLARED caller runtime → fail-loud (no silent claude)', () => {
+    const r = resolveWakeRuntime('codex', peer({ runtime: 'claude', runtimes: ['claude'] }))
+    expect(r.ok).toBe(false)
+  })
+
+  test('no caller runtime → peer.runtime (registry default)', () => {
+    const r = resolveWakeRuntime(undefined, peer({ runtime: 'codex', runtimes: ['codex', 'claude'] }))
+    expect(r.ok && r.value).toBe('codex')
+  })
+
+  test('no caller runtime, no peer.runtime → first of runtimes[]', () => {
+    const r = resolveWakeRuntime(undefined, peer({ runtime: '' as never, runtimes: ['codex'] }))
+    expect(r.ok && r.value).toBe('codex')
+  })
+
+  test('nothing to pick → fail-loud', () => {
+    const r = resolveWakeRuntime(undefined, peer({ runtime: '' as never, runtimes: [] }))
+    expect(r.ok).toBe(false)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// H4 — isLaunchdManaged on the LIVE fleet (read-only)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('isLaunchdManaged (H4 detector, live read-only)', () => {
+  test('a launchd-managed peer (boris has com.iapeer.boris.plist) → true', () => {
+    // The live host has com.iapeer.boris.plist — the daemon must treat boris as
+    // READ-ONLY (never wake/reap). This proves the detector fires on the fleet.
+    expect(isLaunchdManaged('boris')).toBe(true)
+  })
+
+  test('a made-up daemon-owned name (no plist) → false', () => {
+    expect(isLaunchdManaged('iapeer-throwaway-no-plist-xyz')).toBe(false)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// withWakeLock — serializes per identity (concurrent = one at a time)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('withWakeLock', () => {
+  let stateDir: string
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), 'iapeer-wakelock-'))
+  })
+  afterEach(() => {
+    rmSync(stateDir, { recursive: true, force: true })
+  })
+
+  const cfg = (): LifecycleConfig =>
+    ({
+      claudeBin: 'claude',
+      codexBin: 'codex',
+      sockDir: '/tmp',
+      stateDir,
+      logDir: stateDir,
+      bootDeadlineSecs: 1,
+      readyGateSecs: 1,
+      idleSecs: 1,
+      maxAgeSecs: 1,
+    }) as LifecycleConfig
+
+  test('two concurrent locks on the same identity run strictly serialized', async () => {
+    const order: string[] = []
+    const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
+    const p1 = withWakeLock(cfg(), 'claude-x', async () => {
+      order.push('1-start')
+      await sleep(150)
+      order.push('1-end')
+    })
+    // ensure p1 grabs the lock first
+    await sleep(20)
+    const p2 = withWakeLock(cfg(), 'claude-x', async () => {
+      order.push('2-start')
+      order.push('2-end')
+    })
+    await Promise.all([p1, p2])
+    expect(order).toEqual(['1-start', '1-end', '2-start', '2-end'])
+  })
+
+  test('locks on DIFFERENT identities do not block each other', async () => {
+    const order: string[] = []
+    const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
+    const a = withWakeLock(cfg(), 'claude-a', async () => {
+      order.push('a-start')
+      await sleep(120)
+      order.push('a-end')
+    })
+    await sleep(20)
+    const b = withWakeLock(cfg(), 'claude-b', async () => {
+      order.push('b-start') // must interleave — different lock
+    })
+    await Promise.all([a, b])
+    expect(order.indexOf('b-start')).toBeLessThan(order.indexOf('a-end'))
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// superviseTick — H4 guard FIRST (safe: temp LaunchAgents dir, no real fleet)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('superviseTick H4 guard', () => {
+  let stateDir: string
+  let laDir: string
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), 'iapeer-sup-state-'))
+    laDir = mkdtempSync(join(tmpdir(), 'iapeer-sup-la-'))
+  })
+  afterEach(() => {
+    rmSync(stateDir, { recursive: true, force: true })
+    rmSync(laDir, { recursive: true, force: true })
+  })
+
+  const cfg = (): LifecycleConfig =>
+    ({
+      claudeBin: 'claude',
+      codexBin: 'codex',
+      sockDir: '/tmp',
+      stateDir,
+      logDir: stateDir,
+      bootDeadlineSecs: 1,
+      readyGateSecs: 1,
+      idleSecs: 1,
+      maxAgeSecs: 1,
+    }) as LifecycleConfig
+
+  function writeState(personality: string): string {
+    const identity = `claude-${personality}`
+    writeFileSync(
+      join(stateDir, `${identity}.session`),
+      JSON.stringify({ identity, runtime: 'claude', personality, cwd: '/tmp/none', wokeAt: 0 }),
+    )
+    return identity
+  }
+  const env = () => ({ ...process.env, IAPEER_LAUNCHAGENTS_DIR: laDir })
+
+  test('a launchd-managed peer (plist present) is SKIPPED first — never reaped', () => {
+    // a fake plist in the TEMP LaunchAgents dir (real ~/Library is untouched)
+    writeFileSync(join(laDir, 'com.iapeer.iapeer-fakelaunchd.plist'), '')
+    const id = writeState('iapeer-fakelaunchd')
+    const out = superviseTick(cfg(), { env: env(), nowMs: Date.now() })
+    const o = out.find(x => x.identity === id)
+    expect(o?.action).toBe('skipped-launchd')
+    // read-only: its session-state is NOT removed
+    expect(existsSync(join(stateDir, `${id}.session`))).toBe(true)
+  })
+
+  test('a no-plist peer with a dead session → reaped-gone, state removed', () => {
+    const id = writeState('iapeer-supgone') // no plist, no live tmux session
+    const out = superviseTick(cfg(), { env: env(), nowMs: Date.now() })
+    const o = out.find(x => x.identity === id)
+    expect(o?.action).toBe('reaped-gone')
+    expect(existsSync(join(stateDir, `${id}.session`))).toBe(false)
+  })
+
+  test('empty state dir → no outcomes', () => {
+    expect(superviseTick(cfg(), { env: env() })).toEqual([])
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// wakeOrSpawn H4 — REFUSES to wake a launchd-managed peer (no spawn at all)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('wakeOrSpawn H4 refusal', () => {
+  test('a launchd-managed peer is NOT woken (returns FAILED before any spawn)', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-h4-root-'))
+    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-h4-la-'))
+    try {
+      // a registered peer that ALSO has a (fake) launchd plist → launchd domain
+      writeFileSync(join(laDir, 'com.iapeer.iapeer-h4ld.plist'), '')
+      await upsertPeer(
+        { personality: 'iapeer-h4ld', runtime: 'claude', cwd: '/tmp/none', intelligence: 'artificial' },
+        { rootDir: root },
+      )
+      const env = { ...process.env, IAPEER_ROOT: root, IAPEER_LAUNCHAGENTS_DIR: laDir }
+      const r = await wakeOrSpawn({ personality: 'iapeer-h4ld', runtime: 'claude', task: 'must not spawn' }, { env })
+      expect(r.status).toBe('FAILED')
+      expect(r.woke).toBe(false)
+      expect(r.reason).toMatch(/launchd-managed/)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+      rmSync(laDir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// C1 — durable stopped flag (stop/start; daemon refuses to wake a stopped peer)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('C1 durable stopped flag', () => {
+  test('isStopped/setStopped/clearStopped round-trip', () => {
+    const stateDir = mkdtempSync(join(tmpdir(), 'iapeer-stopped-'))
+    const cfg = { stateDir } as LifecycleConfig
+    try {
+      expect(isStopped(cfg, 'claude-x')).toBe(false)
+      setStopped(cfg, 'claude-x')
+      expect(isStopped(cfg, 'claude-x')).toBe(true)
+      clearStopped(cfg, 'claude-x')
+      expect(isStopped(cfg, 'claude-x')).toBe(false)
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+
+  test('wakeOrSpawn REFUSES a stopped peer (FAILED stopped:true, before any spawn)', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-stp-root-'))
+    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-stp-la-')) // empty → not launchd-managed
+    try {
+      await upsertPeer(
+        { personality: 'stp', runtime: 'claude', cwd: '/tmp/none', intelligence: 'artificial' },
+        { rootDir: root },
+      )
+      const env = { ...process.env, IAPEER_ROOT: root, IAPEER_LAUNCHAGENTS_DIR: laDir }
+      const cfg = loadLifecycleConfig(env)
+      setStopped(cfg, 'claude-stp')
+      const r = await wakeOrSpawn({ personality: 'stp', runtime: 'claude', task: 'must not wake' }, { env })
+      expect(r.status).toBe('FAILED')
+      expect(r.stopped).toBe(true)
+      expect(r.reason).toMatch(/stopped/)
+      // cleared → wakeable again (it will then FAIL later for the missing cwd, NOT stopped)
+      clearStopped(cfg, 'claude-stp')
+      const r2 = await wakeOrSpawn({ personality: 'stp', runtime: 'claude', task: 'x' }, { env })
+      expect(r2.stopped).toBeFalsy()
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+      rmSync(laDir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// C2 — initial_prompt launch-seed (composeFirstMessage)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('C2 initial_prompt (composeFirstMessage)', () => {
+  function withProfile(initial_prompt?: string): string {
+    const cwd = mkdtempSync(join(tmpdir(), 'iapeer-seed-'))
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      join(cwd, '.iapeer', 'peer-profile.json'),
+      JSON.stringify({
+        personality: 'p',
+        runtime: 'claude',
+        runtimes: ['claude'],
+        intelligence: 'artificial',
+        ...(initial_prompt ? { initial_prompt } : {}),
+      }),
+    )
+    return cwd
+  }
+
+  test('fresh wake + initial_prompt → seed THEN task (both, seed first)', () => {
+    const cwd = withProfile('First, read STATE.md.')
+    try {
+      expect(composeFirstMessage(cwd, '<iap>msg</iap>', true)).toBe('First, read STATE.md.\n\n<iap>msg</iap>')
+    } finally {
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+
+  test('resume (fresh=false) → task only, no seed', () => {
+    const cwd = withProfile('First, read STATE.md.')
+    try {
+      expect(composeFirstMessage(cwd, 'TASK', false)).toBe('TASK')
+    } finally {
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+
+  test('fresh wake, NO initial_prompt → task only', () => {
+    const cwd = withProfile(undefined)
+    try {
+      expect(composeFirstMessage(cwd, 'TASK', true)).toBe('TASK')
+    } finally {
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+
+  test('fresh with seed but EMPTY task (eager /new) → seed alone (no trailing)', () => {
+    const cwd = withProfile('Report you are up.')
+    try {
+      expect(composeFirstMessage(cwd, '', true)).toBe('Report you are up.')
+    } finally {
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// C3a + C4a — resolveWakeMode (resume-vs-fresh; the contract-divergence fix)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('resolveWakeMode (C3a default-resume + C4a /new-mark)', () => {
+  let stateDir: string
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), 'iapeer-wakemode-'))
+  })
+  afterEach(() => {
+    rmSync(stateDir, { recursive: true, force: true })
+  })
+  const cfg = () => ({ stateDir } as LifecycleConfig)
+  const hasTranscript = () => ({ ok: true, ref: 'uuid-1' })
+  const noTranscript = () => ({ ok: false, reason: 'no transcript to resume' })
+
+  test('DEFAULT (undefined) + transcript exists → RESUME (the warm-asleep contract fix)', () => {
+    expect(resolveWakeMode(cfg(), 'claude-p', '/cwd', undefined, hasTranscript)).toEqual({ resume: true, resumeRef: 'uuid-1' })
+  })
+  test('DEFAULT + NO transcript → FRESH (first-ever launch, not an error)', () => {
+    expect(resolveWakeMode(cfg(), 'claude-p', '/cwd', undefined, noTranscript)).toEqual({ resume: false })
+  })
+  test('explicit resume=true + nothing to resume → FAIL-LOUD (failReason, no silent fresh)', () => {
+    const m = resolveWakeMode(cfg(), 'claude-p', '/cwd', true, noTranscript)
+    expect(m.resume).toBe(false)
+    expect(m.failReason).toMatch(/nothing to resume|no transcript/)
+  })
+  test('explicit resume=false → FRESH', () => {
+    expect(resolveWakeMode(cfg(), 'claude-p', '/cwd', false, hasTranscript)).toEqual({ resume: false })
+  })
+  test('/new-mark present → FRESH and CONSUMES the mark (even if a transcript exists)', () => {
+    const c = cfg()
+    setNewMark(c, 'claude-p')
+    expect(hasNewMark(c, 'claude-p')).toBe(true)
+    expect(resolveWakeMode(c, 'claude-p', '/cwd', undefined, hasTranscript)).toEqual({ resume: false })
+    expect(hasNewMark(c, 'claude-p')).toBe(false) // consumed
+  })
+})
+
+describe('C4a /new-mark round-trip', () => {
+  test('set/has/clear', () => {
+    const stateDir = mkdtempSync(join(tmpdir(), 'iapeer-newmark-'))
+    const cfg = { stateDir } as LifecycleConfig
+    try {
+      expect(hasNewMark(cfg, 'claude-y')).toBe(false)
+      setNewMark(cfg, 'claude-y')
+      expect(hasNewMark(cfg, 'claude-y')).toBe(true)
+      clearNewMark(cfg, 'claude-y')
+      expect(hasNewMark(cfg, 'claude-y')).toBe(false)
+    } finally {
+      rmSync(stateDir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// C4b — eager fresh re-launch detection (superviseTick flags a dead +/new session)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('C4b eager fresh re-launch (superviseTick detection)', () => {
+  test('a DEAD session carrying a /new-mark → needs-eager-fresh (mark LEFT for relaunch)', () => {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-c4b-root-'))
+    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-c4b-la-')) // empty → not launchd-managed
+    try {
+      const env = {
+        ...process.env,
+        IAPEER_ROOT: root,
+        IAPEER_LAUNCHAGENTS_DIR: laDir,
+        IAPEER_SOCK_DIR: join(root, 'socks'), // isolated, no live session here → dead
+      }
+      const cfg = loadLifecycleConfig(env)
+      mkdirSync(cfg.stateDir, { recursive: true })
+      // a session-state for a peer whose session is NOT live (dead)
+      writeFileSync(
+        join(cfg.stateDir, 'claude-z.session'),
+        JSON.stringify({ identity: 'claude-z', runtime: 'claude', personality: 'z', cwd: '/tmp/z', wokeAt: Date.now() }),
+      )
+      setNewMark(cfg, 'claude-z')
+      const out = superviseTick(cfg, { env })
+      const o = out.find(x => x.identity === 'claude-z')
+      expect(o?.action).toBe('needs-eager-fresh')
+      expect(o?.personality).toBe('z')
+      expect(o?.runtime).toBe('claude')
+      // the session-state is removed, but the /new-mark is LEFT for the eager
+      // relaunch's resolveWakeMode to consume (so the relaunch resolves to fresh).
+      expect(hasNewMark(cfg, 'claude-z')).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+      rmSync(laDir, { recursive: true, force: true })
+    }
+  })
+
+  test('a DEAD session with NO /new-mark → reaped-gone (not eager)', () => {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-c4b2-root-'))
+    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-c4b2-la-'))
+    try {
+      const env = { ...process.env, IAPEER_ROOT: root, IAPEER_LAUNCHAGENTS_DIR: laDir, IAPEER_SOCK_DIR: join(root, 'socks') }
+      const cfg = loadLifecycleConfig(env)
+      mkdirSync(cfg.stateDir, { recursive: true })
+      writeFileSync(
+        join(cfg.stateDir, 'claude-w.session'),
+        JSON.stringify({ identity: 'claude-w', runtime: 'claude', personality: 'w', cwd: '/tmp/w', wokeAt: Date.now() }),
+      )
+      const out = superviseTick(cfg, { env })
+      expect(out.find(x => x.identity === 'claude-w')?.action).toBe('reaped-gone')
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+      rmSync(laDir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Ф-D launch / attach — operator verbs (error paths; success paths are live-verified)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('lastActiveRuntime', () => {
+  test('a peer with no transcript anywhere → undefined (never run)', () => {
+    const cfg = { sockDir: '/tmp' } as LifecycleConfig
+    const rt = lastActiveRuntime(peer({ personality: 'np', runtimes: ['claude', 'codex'], cwd: '/tmp/does-not-exist-xyz' }), cfg)
+    expect(rt).toBeUndefined()
+  })
+})
+
+describe('attachPeer (error paths)', () => {
+  test('an unregistered peer → ok:false', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-att-'))
+    try {
+      const r = await attachPeer({ personality: 'ghost', env: { ...process.env, IAPEER_ROOT: root } })
+      expect(r.ok).toBe(false)
+      if (!r.ok) expect(r.reason).toMatch(/not registered/)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+  test('an explicit UNDECLARED runtime → ok:false (fail-loud)', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-att2-'))
+    try {
+      await upsertPeer({ personality: 'solo', runtime: 'claude', cwd: '/tmp/solo', intelligence: 'artificial' }, { rootDir: root })
+      const r = await attachPeer({ personality: 'solo', runtime: 'codex', env: { ...process.env, IAPEER_ROOT: root } })
+      expect(r.ok).toBe(false)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('folderLaunch (error path)', () => {
+  test('a cwd without a peer-profile → throws (resolveIdentity fail-loud)', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'iapeer-fl-'))
+    try {
+      await expect(folderLaunch({ cwd, env: { ...process.env } })).rejects.toThrow()
+    } finally {
+      rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+})

package/src/onboard/index.ts

@@ -0,0 +1,135 @@
+// onboard — the host-phase (contract Установка §2 ONBOARD). The linking step
+// between install (the binary) and init (per-peer): register OUR marketplace in
+// claude AND codex so peers can install agfpd capability plugins. Infra-runtime
+// install (telegram/notifier self-installable npx) is the operator-choice follow-up.
+//
+// FLEET SAFETY: a host already configured for the legacy fleet MUST NOT be mutated by
+// onboard. So onboard is strictly IDEMPOTENT — it DETECTS whether the marketplace is
+// already registered (the runtime's own `plugin marketplace list`) and SKIPS when it
+// is. On a configured host every step is a no-op; only a fresh host is written. A
+// dry-run reports the would-be actions without touching anything.
+
+import { spawnSync } from 'child_process'
+import { homedir } from 'os'
+import { join } from 'path'
+import { accessSync, constants as FS } from 'fs'
+
+/** OUR marketplace — GitHub owner/repo, the source both runtimes' `marketplace add`
+ *  takes; and the registered NAME both runtimes' `marketplace list` shows. */
+export const MARKETPLACE_REF = 'agfpd/agfpd-marketplace'
+export const MARKETPLACE_NAME = 'agfpd'
+
+export type OnboardRuntime = 'claude' | 'codex'
+
+export type MarketplaceState =
+  | 'already-registered' // present → no-op (fleet-safe)
+  | 'registered' // was absent → added now
+  | 'would-register' // dry-run: absent, would add
+  | 'runtime-missing' // the runtime binary is not installed
+  | 'failed' // the add command failed
+
+export interface OnboardRuntimeResult {
+  runtime: OnboardRuntime
+  state: MarketplaceState
+  detail?: string
+}
+
+export interface OnboardResult {
+  marketplaces: OnboardRuntimeResult[]
+  /** True when nothing was mutated (every runtime already-registered / dry-run / missing). */
+  noop: boolean
+}
+
+export interface OnboardOptions {
+  /** Report the would-be actions without running any `marketplace add`. */
+  dryRun?: boolean
+  /** Restrict to these runtimes (default both). */
+  runtimes?: OnboardRuntime[]
+  env?: NodeJS.ProcessEnv
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+function runtimeBin(runtime: OnboardRuntime, env: NodeJS.ProcessEnv): string {
+  if (runtime === 'claude') return env.IAPEER_CLAUDE_BIN?.trim() || join(env.HOME?.trim() || homedir(), '.local', 'bin', 'claude')
+  return env.IAPEER_CODEX_BIN?.trim() || 'codex'
+}
+
+function isExecutable(binOrName: string): boolean {
+  if (binOrName.includes('/')) {
+    try {
+      accessSync(binOrName, FS.X_OK)
+      return true
+    } catch {
+      return false
+    }
+  }
+  // bare name → resolved by spawnSync against PATH; probe with `which`-free spawn
+  const r = spawnSync(binOrName, ['--version'], { stdio: 'ignore' })
+  return r.error === undefined && r.status !== null
+}
+
+/**
+ * Is OUR marketplace already registered for this runtime? Reads the runtime's own
+ * `plugin marketplace list` and matches the agfpd source-ref OR a standalone agfpd
+ * name entry (both runtimes render the name; claude also shows the GitHub ref). A
+ * word-boundary-ish match so a different agfpd-* string never false-positives.
+ */
+export function isMarketplaceRegistered(runtime: OnboardRuntime, env: NodeJS.ProcessEnv = process.env): boolean {
+  const bin = runtimeBin(runtime, env)
+  const r = spawnSync(bin, ['plugin', 'marketplace', 'list'], { encoding: 'utf8' })
+  if (r.status !== 0) return false
+  return isAgfpdInList(`${r.stdout ?? ''}`)
+}
+
+/**
+ * Pure detector over a `plugin marketplace list` output: is OUR marketplace present?
+ * Matches the agfpd GitHub source-ref (claude renders it) OR a standalone agfpd name
+ * entry (both runtimes render the name). The name match is anchored to a line start
+ * (optionally after the `❯` selection glyph) and followed by whitespace/EOL, so a
+ * different `agfpd-<something>` token never false-positives. Pure → unit-testable
+ * against real claude/codex samples (the fleet-guard hinges on it).
+ */
+export function isAgfpdInList(listOutput: string): boolean {
+  if (new RegExp(MARKETPLACE_REF.replace('/', '\\/')).test(listOutput)) return true
+  return /(^|\n)\s*(❯\s*)?agfpd(\s|$)/.test(listOutput)
+}
+
+/** 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)
+  const r = spawnSync(bin, ['plugin', 'marketplace', 'add', MARKETPLACE_REF], { encoding: 'utf8' })
+  return r.status === 0 ? { ok: true } : { ok: false, detail: (r.stderr ?? '').trim() || `exit ${r.status}` }
+}
+
+/**
+ * Onboard the host: ensure OUR marketplace is registered in each runtime — IDEMPOTENT
+ * (detect → skip when present). On an already-configured host every runtime is
+ * 'already-registered' and NOTHING is mutated (fleet-safe). dryRun reports 'would-
+ * register' for any absent one without running the add. A missing runtime binary is
+ * 'runtime-missing' (skipped, not an error). Infra-runtime install is a separate
+ * operator-choice step (not done here).
+ */
+export function onboardHost(opts: OnboardOptions = {}): OnboardResult {
+  const env = opts.env ?? process.env
+  const runtimes = opts.runtimes ?? (['claude', 'codex'] as OnboardRuntime[])
+  const marketplaces: OnboardRuntimeResult[] = []
+  for (const runtime of runtimes) {
+    if (!isExecutable(runtimeBin(runtime, env))) {
+      marketplaces.push({ runtime, state: 'runtime-missing' })
+      continue
+    }
+    if (isMarketplaceRegistered(runtime, env)) {
+      marketplaces.push({ runtime, state: 'already-registered' })
+      continue
+    }
+    if (opts.dryRun) {
+      marketplaces.push({ runtime, state: 'would-register' })
+      continue
+    }
+    const r = registerMarketplace(runtime, env)
+    marketplaces.push({ runtime, state: r.ok ? 'registered' : 'failed', detail: r.detail })
+  }
+  const noop = marketplaces.every(m => m.state !== 'registered')
+  return { marketplaces, noop }
+}

package/src/onboard/onboard.test.ts

@@ -0,0 +1,39 @@
+// onboard — the fleet-critical detector (isAgfpdInList): is OUR marketplace already
+// registered? A false negative would RE-register on an already-configured host (the
+// exact fleet-mutation onboard must avoid). Tested against REAL claude/codex
+// `plugin marketplace list` output shapes.
+
+import { describe, expect, test } from 'bun:test'
+import { isAgfpdInList } from './index.ts'
+
+describe('isAgfpdInList (marketplace-registered detector)', () => {
+  test('claude list shape (❯ name + GitHub source ref) → true', () => {
+    const claudeOut = `Configured marketplaces:
+
+  ❯ claude-plugins-official
+    Source: GitHub (anthropics/claude-plugins-official)
+
+  ❯ agfpd
+    Source: GitHub (agfpd/agfpd-marketplace)
+`
+    expect(isAgfpdInList(claudeOut)).toBe(true)
+  })
+
+  test('codex list shape (name + root path columns) → true', () => {
+    const codexOut = `MARKETPLACE              ROOT
+agfpd                    /Users/x/.codex/.tmp/marketplaces/agfpd
+claude-plugins-official  /Users/x/.codex/.tmp/marketplaces/claude-plugins-official
+`
+    expect(isAgfpdInList(codexOut)).toBe(true)
+  })
+
+  test('NOT registered (only other marketplaces) → false', () => {
+    expect(isAgfpdInList('Configured marketplaces:\n\n  ❯ claude-plugins-official\n    Source: GitHub (anthropics/claude-plugins-official)\n')).toBe(false)
+    expect(isAgfpdInList('')).toBe(false)
+  })
+
+  test('a different agfpd-* token (e.g. a plugin name) does NOT false-positive', () => {
+    // a line that mentions agfpd-prompt-architect but the agfpd marketplace is NOT listed
+    expect(isAgfpdInList('plugins:\n  agfpd-prompt-architect@somewhere (installed)\n')).toBe(false)
+  })
+})