@agfpd/iapeer 0.1.0

package/src/launch/adapters/codex.ts

@@ -0,0 +1,329 @@
+// codex RuntimeAdapter — the "HOW to launch / observe ONE codex session" half of
+// the launch contract (src/launch/types.ts). Runtime-agnostic launch.launch
+// drives it identically to claude: argv → boot dialogs → ready marker →
+// activity-proxy ready-gate → permission autopilot → resume preflight. Codex is
+// a tui that usesDoctrine, but the doctrine is delivered through a config field
+// (`-c model_instructions_file=<f>`) rather than a dedicated flag, and resume is
+// session-less (`resume --last`, codex matches the newest session for cwd
+// itself). Consolidated from three frozen sources:
+//
+//   - Persistent-Peer/bin/codex-start.sh — argv (224: -c
+//     model_instructions_file="<merged>", --dangerously-bypass-approvals-and-
+//     sandbox), and the three startup-dialog auto-accepts (255-275: dir-trust
+//     Enter, hooks-review Down+Enter). The update-available case is the
+//     Spawned-Peer superset (codexUpdatePromptActive).
+//   - Spawned-Peer/src/spawner.ts — buildCodexArgv (731-757: [resume --last]
+//     --no-alt-screen -C <cwd> --dangerously-bypass-approvals-and-sandbox) and
+//     hasCodexSessionForCwd (545-569: a session_meta.payload.cwd realpath-match
+//     under ~/.codex/sessions/ is the resume preflight).
+//   - Spawned-Peer/src/watcher.ts — codexInputReady (263-269), the boot-dialog
+//     predicates (codexUpdatePromptActive/codexDirTrustActive/codexHooksReview
+//     Active 253-261) + the keys the boot loop sends (382-400),
+//     newestCodexSessionMtime + codexSessionCwd (200-234), and
+//     answerPermissionDialog's codex branch (302-306: Down then Enter) over
+//     dialogs.ts codexApprovalActive (39-45).
+//
+// The doctrine -c value is the bare `model_instructions_file=<f>` token: the
+// TOML value-side quotes in codex-start.sh:224 exist only because that string is
+// re-parsed by a shell (`printf %q`) before codex sees it; here launch.launch
+// shell-quotes each argv element exactly once, so the unquoted path is correct
+// and a quoted path would arrive as a literal `"..."`-wrapped (broken) TOML
+// value. Order follows the FROZEN contract (types.ts:107), not the bash's
+// flag order.
+//
+// NO currency on this path: no marketplace check, no plugin install/update — that
+// is install-time (blueprint §0.6 fast-wake), not session bring-up. (codex-start
+// .sh:94-122 runs the currency gate OUTSIDE the tmux launch; it is not ported.)
+
+import { homedir } from 'os'
+import { join } from 'path'
+import { readFileSync, readdirSync, realpathSync, statSync } from 'fs'
+import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Boot dialog markers (watcher.codexUpdate/DirTrust/HooksReview, 253-261)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The known codex startup dialogs and the tmux send-keys the boot loop answers
+ * each with (watcher.ts:382-400, codex-start.sh:255-275). Order matters: the
+ * update screen can stack in front of the trust/hooks modals, so it is matched
+ * first. Each option below is verified default-highlighted, so the listed keys
+ * land on the proceed path:
+ *   - 'Update available!' + 'Press enter to continue' — the self-update offer;
+ *     keys ['2','Enter'] decline (option 2 = "not now") so a headless peer never
+ *     blocks on an update it cannot drive (watcher.ts:382-384).
+ *   - 'Do you trust the contents of this directory' — first-run folder-trust;
+ *     option 1 ("Yes, continue") is default-highlighted → ['Enter']
+ *     (watcher.ts:386-390, codex-start.sh:261-264).
+ *   - 'Hooks need review' — a new/changed plugin hooks.json; "Trust all and
+ *     continue" is option 2, default highlight is option 1 → ['Down','Enter']
+ *     (watcher.ts:392-399, codex-start.sh:266-272).
+ */
+function codexUpdatePromptActive(pane: string): boolean {
+  return pane.includes('Update available!') && pane.includes('Press enter to continue')
+}
+function codexDirTrustActive(pane: string): boolean {
+  return pane.includes('Do you trust the contents of this directory')
+}
+function codexHooksReviewActive(pane: string): boolean {
+  return pane.includes('Hooks need review')
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Session activity proxy + resume preflight (watcher / spawner port)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The cwd a codex session was opened in, read from the first jsonl line's
+ * `session_meta.payload.cwd` (watcher.codexSessionCwd, 200-212). null when the
+ * file is missing, unreadable, not a session_meta record, or carries no cwd.
+ */
+function codexSessionCwd(file: string): string | null {
+  try {
+    const firstLine = readFileSync(file, 'utf8').split(/\r?\n/, 1)[0]
+    if (!firstLine) return null
+    const entry = JSON.parse(firstLine) as {
+      type?: unknown
+      payload?: { cwd?: unknown }
+    }
+    return entry.type === 'session_meta' && typeof entry.payload?.cwd === 'string'
+      ? entry.payload.cwd
+      : null
+  } catch {
+    return null
+  }
+}
+
+/** realpath a path so a symlinked cwd compares equal to the dir codex recorded;
+ *  a stale/missing path falls through to the original string (the canonicalPath
+ *  helper behind watcher.newestCodexSessionMtime / spawner.hasCodexSessionForCwd). */
+function canonicalPath(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+/**
+ * Newest ~/.codex/sessions/**\/*.jsonl mtimeMs whose recorded session cwd
+ * realpath-matches `cwd`, or null when none (watcher.newestCodexSessionMtime,
+ * 214-234). Codex files its session logs in a date-nested tree, so the scan
+ * recurses. The ready-gate waits for this to strictly advance past baseline
+ * (the model produced its first turn); idle accounting reads the same proxy.
+ */
+function newestCodexSessionMtime(cwd: string): number | null {
+  const root = join(homedir(), '.codex', 'sessions')
+  const target = canonicalPath(cwd)
+  let newest = 0
+  function visit(dir: string): void {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        visit(path)
+        continue
+      }
+      if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue
+      if (canonicalPath(codexSessionCwd(path) ?? '') !== target) continue
+      try {
+        const mt = statSync(path).mtimeMs
+        if (mt > newest) newest = mt
+      } catch {
+        /* race — entry vanished between readdir and stat */
+      }
+    }
+  }
+  visit(root)
+  return newest > 0 ? newest : null
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// codexAdapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const codexAdapter: RuntimeAdapter = {
+  runtime: 'codex',
+  kind: 'tui',
+  usesDoctrine: true,
+
+  /**
+   * Delivery markers for submitIntoTui (07.06 refactor; docs/Рантайм codex
+   * "Доставка"):
+   *   - promptGlyphs ['›'] — codex's input-row arrow (the same stable invariant as
+   *     isInputReady's '› ' check; the exact glyph the prompt row starts with).
+   *     codex-only, so a stray claude '❯' no longer false-matches.
+   *   - pastePatterns '[Pasted text' / '[Image #' — kept identical to claude (the
+   *     old transport union applied them to codex too, so this preserves behaviour;
+   *     codex's exact paste-land glyph is a live-verify item — the envelope tail-
+   *     marker remains the primary landed-signal regardless).
+   */
+  deliveryMarkers: {
+    promptGlyphs: ['›'],
+    pastePatterns: [/\[Pasted text/, /\[Image #/],
+  },
+
+  /**
+   * argv = codexBin + (resume --last when spec.resume) + the TUI args +
+   * (doctrine via -c when systemPromptFile set) + bypass + extraArgs. Order is
+   * the FROZEN contract (types.ts:107); the bash's flag order differs but the
+   * resulting flag SET is identical.
+   *
+   *   - 'resume','--last'  spawner.ts:756 — ONLY when spec.resume; codex picks
+   *     the newest session matching cwd itself (resolveResume merely verified one
+   *     exists, so this is never a silent fresh fallback). No uuid — codex has no
+   *     per-session resume ref the way claude does.
+   *   - '--no-alt-screen'  spawner.ts:742 — keep codex on the main screen buffer
+   *     so capture-pane sees the live TUI (the alt screen is not captured).
+   *   - '-C', spec.cwd  spawner.ts:743 — codex's working-dir flag (the launch
+   *     primitive also new-sessions with -c <cwd>; codex needs its own -C too).
+   *   - '-c', `model_instructions_file=${spec.systemPromptFile}`  codex-start.sh
+   *     :224 — ONLY when set (a tui runtime that usesDoctrine composes one).
+   *     Swaps codex's compile-time BASE_INSTRUCTIONS for the merged peer
+   *     doctrine; MCP/plugin/AGENTS.md layers stay intact. The path is the bare
+   *     unquoted token — launch.launch shell-quotes the whole argv element once.
+   *   - '--dangerously-bypass-approvals-and-sandbox'  codex-start.sh:224,
+   *     spawner.ts:754 — codex YOLO; a headless peer has no owner to answer
+   *     approval prompts and no reason to sandbox below its peer-cwd.
+   *   - ...extraArgs  PEER_START_ARGS passthrough (LaunchSpec.extraArgs).
+   * NO currency — no marketplace/install/update on this path.
+   */
+  buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    return [
+      cfg.codexBin,
+      ...(spec.resume ? ['resume', '--last'] : []),
+      '--no-alt-screen',
+      '-C',
+      spec.cwd,
+      ...(spec.systemPromptFile
+        ? ['-c', `model_instructions_file=${spec.systemPromptFile}`]
+        : []),
+      '--dangerously-bypass-approvals-and-sandbox',
+      ...(spec.extraArgs ?? []),
+    ]
+  },
+
+  /**
+   * A visible startup dialog → the keys that clear it (watcher.ts:382-400), else
+   * null. Update offer is matched first (it can stack ahead of the trust/hooks
+   * modals): decline with ['2','Enter']; dir-trust accepts with ['Enter']; hooks
+   * -review needs ['Down','Enter'] to reach "Trust all and continue".
+   */
+  bootDialogKeys(pane: string): string[] | null {
+    if (codexUpdatePromptActive(pane)) return ['2', 'Enter']
+    if (codexDirTrustActive(pane)) return ['Enter']
+    if (codexHooksReviewActive(pane)) return ['Down', 'Enter']
+    return null
+  },
+
+  /**
+   * Ready for the first message iff the codex TUI input surface is rendered and
+   * no startup screen is still up (watcher.codexInputReady, 263-269):
+   *   - pane includes 'OpenAI Codex' — the TUI splash/header is present.
+   *   - pane does NOT include 'Press enter to continue' — the update screen (and
+   *     other "press enter" startup prompts) is gone.
+   *   - some line, trimStart, startsWith '› ' — the rendered input arrow at the
+   *     start of the input row. (Codex rotates its top-of-pane tip line, so the
+   *     input arrow is the stable ready invariant — not any single tip.)
+   */
+  isInputReady(pane: string): boolean {
+    if (!pane.includes('OpenAI Codex')) return false
+    if (pane.includes('Press enter to continue')) return false
+    return pane.split(/\r?\n/).some(line => line.trimStart().startsWith('› '))
+  },
+
+  /**
+   * Newest ~/.codex/sessions/**\/*.jsonl mtimeMs whose session_meta cwd realpath
+   * -matches cwd, or null when none (watcher.newestCodexSessionMtime, 214-234).
+   * The ready-gate waits for this to strictly advance past baseline; idle
+   * accounting reads the same proxy.
+   */
+  newestActivityMtime(cwd: string): number | null {
+    return newestCodexSessionMtime(cwd)
+  },
+
+  /**
+   * A codex approval modal is open iff the pane carries the 'enter to submit'
+   * footer AND an Allow-to-run title — the MCP tool-approval modal ("Allow the
+   * <server> MCP server to run tool …?") or the generic command-exec approval
+   * (dialogs.ts codexApprovalActive, 39-45). The footer is the discriminator
+   * against boot-phase startup screens (those say 'Press enter to continue'), so
+   * a dir-trust/update screen never matches here. Required even under YOLO:
+   * connector / consequential MCP-tool approvals are NOT suppressed by
+   * --dangerously-bypass-approvals-and-sandbox and would block a headless peer
+   * forever (codex-start.sh:229-237).
+   */
+  permissionDialogActive(pane: string): boolean {
+    if (!pane.includes('enter to submit')) return false
+    if (/Allow the .+ MCP server to run tool/.test(pane)) return true
+    return /\bAllow\b[\s\S]*\bto run\b/.test(pane)
+  },
+
+  /**
+   * Affirm a codex approval with ['Down','Enter'] (watcher.answerPermissionDialog
+   * codex branch, 302-306): the modal default-highlights option 1 ("Allow",
+   * one-shot); one Down selects option 2 ("Allow for this session") so later tool
+   * calls in this same headless session don't re-prompt, then Enter submits. Even
+   * partial key delivery is safe — Down-then-nothing leaves option 1 (still an
+   * affirmative), and the only destructive option (Cancel) is three Downs away.
+   */
+  permissionDialogKeys(): string[] {
+    return ['Down', 'Enter']
+  },
+
+  /**
+   * Resume preflight (fail-loud — never a silent fresh fallback). Codex resumes
+   * via 'resume --last' with NO ref: it matches the newest session for cwd
+   * itself, so buildArgv keys on spec.resume alone and there is nothing to
+   * resolve. We only verify a candidate session exists — a session_meta.payload
+   * .cwd that realpath-matches cwd under ~/.codex/sessions/ (spawner.hasCodex
+   * SessionForCwd, 545-569). {ok:true} when one exists (no ref), else {ok:false,
+   * reason} so the caller surfaces a real failure instead of a context-less
+   * session.
+   */
+  resolveResume(cwd: string): { ok: boolean; ref?: string; reason?: string } {
+    const target = canonicalPath(cwd)
+    const root = join(homedir(), '.codex', 'sessions')
+    function visit(dir: string): boolean {
+      let entries
+      try {
+        entries = readdirSync(dir, { withFileTypes: true })
+      } catch {
+        return false
+      }
+      for (const entry of entries) {
+        const path = join(dir, entry.name)
+        if (entry.isDirectory()) {
+          if (visit(path)) return true
+          continue
+        }
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue
+        if (canonicalPath(codexSessionCwd(path) ?? '') === target) return true
+      }
+      return false
+    }
+    return visit(root)
+      ? { ok: true }
+      : { ok: false, reason: 'no codex session to resume' }
+  },
+
+  /**
+   * Map a control command to codex's in-session mechanism (Ф-E, docs/Control-команды).
+   *   - interrupt → ['Escape']. SNAPPED LIVE (codex-cli 0.136.0): a SINGLE Escape
+   *     interrupts the turn — NOT a double. (Codex's own footer says "esc to
+   *     interrupt"; one Escape yields "■ Conversation interrupted". The contract's
+   *     open "×1/×2?" is resolved to ×1, same as claude.) Session + context intact.
+   *   - compact → null (codex has no '/compact'; context management is its own).
+   *   - anything else → null.
+   */
+  executeControl(command: ControlCommand): ControlPlan | null {
+    if (command.name === 'interrupt') return { sequence: [['Escape']] }
+    return null
+  },
+}

package/src/launch/adapters/notifier.ts

@@ -0,0 +1,90 @@
+// notifier RuntimeAdapter — the "HOW to launch / observe ONE notifier session"
+// half of the launch contract (src/launch/types.ts). Like telegram, the notifier
+// runtime is a long-running ROUTER (notifier-runtime run: a Scheduler/Supervisor
+// loop + an IAP envelope pump on stdin, ported from telegram-runtime), NOT an LLM
+// TUI. So kind:'router' tells launch.launch to SKIP every TUI phase — no pane boot
+// dialog, no ready-marker, no first-user-turn delivery, no activity-proxy ready-
+// gate, no permission modal, no transcript to resume. The pane predicates below
+// are trivial constants, present only to satisfy the frozen interface.
+//
+// ONE adapter for the whole runtime: notifier carries TWO peer-roles, `timer`
+// (primitive TIME → Scheduler) and `watcher` (primitive EVENT → Supervisor). The
+// role is NOT an adapter concern — it is dispatched INSIDE `notifier-runtime run`
+// from PEER_PERSONALITY (resolvePersonality: watcher → Supervisor, else timer →
+// Scheduler), exactly as personality reaches every other runtime: via env +
+// `tmux new-session -c "$PEER_CWD"`, i.e. launch.launch's job, not buildArgv's.
+//
+// notifier is an INFRA runtime (always-on): launchd KeepAlive holds the session so
+// the daemon can deliver send_to_peer(timer|watcher, …) into its tmux pane (the
+// stdin reader picks up the registration/live-reload envelope). That always-on
+// bring-up is the plist path (src/launch/launchd.ts); THIS adapter only describes
+// how to launch one notifier session, identical in shape to telegram.
+//
+// NO currency on this path: no marketplace check, no plugin install/update.
+
+import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+
+export const notifierAdapter: RuntimeAdapter = {
+  runtime: 'notifier',
+  kind: 'router',
+  usesDoctrine: false,
+
+  /** No submit surface — a router uses the deliverViaTmux C-j path, not submitIntoTui.
+   *  Empty glyphs. (No intelligence gate: notifier peers are intelligence='absent'
+   *  programmatic sources, which is exactly their expected nature — nothing to refuse.) */
+  deliveryMarkers: { promptGlyphs: [] },
+
+  /**
+   * argv = notifierBin + 'run' + extraArgs — symmetric with telegram-runtime
+   * (`$BIN run ${PEER_START_ARGS}`).
+   *   - cfg.notifierBin ?? 'notifier-runtime'  the launch binary; the literal is
+   *     left for launch.launch's PATH to resolve when cfg does not pin it.
+   *   - 'run'  the Scheduler/Supervisor subcommand: reads the peer's triggers,
+   *     runs the TIME grid (timer) or EVENT supervisor (watcher) by PEER_PERSONALITY,
+   *     and pumps IAP envelopes in via the session's stdin (registration/live-reload).
+   *   - ...extraArgs  PEER_START_ARGS passthrough (LaunchSpec.extraArgs).
+   *
+   * NO --system-prompt-file (usesDoctrine:false — a router is not an LLM). NO
+   * --resume (a router has no transcript). NO currency on this path.
+   */
+  buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    return [cfg.notifierBin ?? 'notifier-runtime', 'run', ...(spec.extraArgs ?? [])]
+  },
+
+  /** No startup dialogs — a router has no pane TUI to answer; launch.launch skips
+   *  the boot phase, so this is never consulted. */
+  bootDialogKeys(_pane: string): string[] | null {
+    return null
+  },
+
+  /** Always ready: a router is "up" the instant `notifier-runtime run` is launched
+   *  into the tmux session; launch.launch skips the ready-gate for kind:'router'. */
+  isInputReady(_pane: string): boolean {
+    return true
+  },
+
+  /** No activity proxy: a router writes no transcript/session jsonl to mtime. */
+  newestActivityMtime(_cwd: string): number | null {
+    return null
+  },
+
+  /** No permission/approval modal: a router is not an LLM driving tools. */
+  permissionDialogActive(_pane: string): boolean {
+    return false
+  },
+
+  /** No permission modal to affirm — empty send-keys args. */
+  permissionDialogKeys(): string[] {
+    return []
+  },
+
+  /** Nothing to resume: a router does not replay a transcript. */
+  resolveResume(_cwd: string): { ok: boolean; ref?: string; reason?: string } {
+    return { ok: true }
+  },
+
+  /** No in-session control: a router has no TUI turn. null → explicit refusal upstream. */
+  executeControl(_command: ControlCommand): ControlPlan | null {
+    return null
+  },
+}

package/src/launch/adapters/telegram.ts

@@ -0,0 +1,130 @@
+// telegram RuntimeAdapter — the "HOW to launch / observe ONE telegram session"
+// half of the launch contract (src/launch/types.ts). Unlike claude/codex, the
+// telegram runtime is a long-running ROUTER (telegram-runtime run: grammy
+// long-polling + IAP envelope pump), NOT an LLM TUI. So kind:'router' tells
+// launch.launch to SKIP every TUI phase — there is no pane boot dialog, no
+// ready-marker, no first-user-turn delivery, no activity-proxy ready-gate, no
+// permission modal, no transcript to resume. The pane predicates below are
+// therefore trivial constants, present only to satisfy the frozen interface.
+//
+// Ported from one frozen source:
+//
+//   - Persistent-Peer/bin/telegram-start.sh — the launch command (line 119:
+//     `CMD="$TELEGRAM_RUNTIME_BIN run ${PEER_START_ARGS}"`), and the explicit
+//     facts that this adapter carries NO doctrine/system-prompt (it is not an
+//     LLM that consumes one — header lines 6-16) and is gated to human peers
+//     (intelligence='human', lines 24-28/63-71). The binary defaults to the
+//     PATH-resolved literal `telegram-runtime` (line 107); the run subcommand
+//     takes only PEER_START_ARGS as extra flags — no personality/cwd positional
+//     (those are env + `tmux new-session -c "$PEER_CWD"`, i.e. launch.launch's
+//     job, not buildArgv's).
+//
+// NO currency on this path: no marketplace check, no plugin install/update —
+// that is install-time (blueprint §0.6 fast-wake), not session bring-up.
+
+import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// telegramAdapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const telegramAdapter: RuntimeAdapter = {
+  runtime: 'telegram',
+  kind: 'router',
+  usesDoctrine: false,
+
+  /** No submit surface — a router takes no bracketed-paste-then-Enter turn
+   *  (deliverViaTmux uses the router C-j path, not submitIntoTui). Empty glyphs. */
+  deliveryMarkers: { promptGlyphs: [] },
+
+  /**
+   * telegram is a HUMAN channel — launch REFUSES a non-natural peer (fail-loud).
+   * Porting the persistent-peer FATAL guard (it stood in two places): a peer with
+   * intelligence artificial/absent must never be brought up on telegram (it would
+   * route a human's bot to an agent/script). The launch primitive enforces this
+   * against LaunchSpec.intelligence; source of intelligence → docs/Идентичность.
+   */
+  requiresIntelligence: 'natural',
+
+  /**
+   * argv = telegramBin + 'run' + extraArgs (telegram-start.sh:119,
+   * `$TELEGRAM_RUNTIME_BIN run ${PEER_START_ARGS}`).
+   *
+   *   - cfg.telegramBin ?? 'telegram-runtime'  the launch binary. The bash
+   *     resolves it via `command -v telegram-runtime` (line 107) against a PATH
+   *     that prefers ~/.iapeer/runtimes/telegram/bin then ~/.local/bin; here we
+   *     defer that resolution to cfg.telegramBin when set, else emit the literal
+   *     'telegram-runtime' for launch.launch's PATH to resolve.
+   *   - 'run'  the router subcommand: reads peer-profile + global bots registry,
+   *     brings up grammy long-polling for every linked bot, and pumps IAP
+   *     envelopes both directions through the session's stdio (DECISIONS §12.1).
+   *   - ...extraArgs  PEER_START_ARGS passthrough (LaunchSpec.extraArgs) — the
+   *     only extra flags telegram-start.sh forwards to `run`.
+   *
+   * NO --system-prompt-file: usesDoctrine:false — telegram-runtime is a router,
+   * not an LLM, so there is no doctrine to merge (telegram-start.sh:6-12). NO
+   * --resume: a router has no transcript. NO currency on this path.
+   */
+  buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    return [cfg.telegramBin ?? 'telegram-runtime', 'run', ...(spec.extraArgs ?? [])]
+  },
+
+  /**
+   * No startup dialogs — the router has no pane TUI to answer (kind:'router',
+   * telegram-start.sh:14-16). launch.launch skips the boot phase, so this is
+   * never consulted; null is the contractual "no dialog to clear".
+   */
+  bootDialogKeys(_pane: string): string[] | null {
+    return null
+  },
+
+  /**
+   * Always ready: a router has no input surface waiting for a first message —
+   * it is "up" the instant `telegram-runtime run` is launched into the tmux
+   * session (telegram-start.sh has no ready-marker polling, lines 14-16).
+   * launch.launch skips the ready-gate for kind:'router'; true is the
+   * contractual "nothing to wait for".
+   */
+  isInputReady(_pane: string): boolean {
+    return true
+  },
+
+  /**
+   * No activity proxy: a router writes no transcript/session jsonl to mtime as a
+   * ready-gate or idle signal (contract: "null for a router (no proxy)").
+   * launch.launch skips the activity-proxy ready-gate for kind:'router'.
+   */
+  newestActivityMtime(_cwd: string): number | null {
+    return null
+  },
+
+  /**
+   * No permission/approval modal: a router is not an LLM driving tools behind an
+   * autopilot, so there is never a dialog to detect (telegram-start.sh:14, "no
+   * trust-dialog auto-accept, no permissions banner").
+   */
+  permissionDialogActive(_pane: string): boolean {
+    return false
+  },
+
+  /** No permission modal to affirm — empty send-keys args (see above). */
+  permissionDialogKeys(): string[] {
+    return []
+  },
+
+  /**
+   * Nothing to resume: a router does not replay a transcript, so resume cannot
+   * fail-loud the way claude/codex do — there is no prior session ref to resolve
+   * or miss. Always {ok:true} (the contract: "a router does not resume a
+   * transcript; nothing to fail on").
+   */
+  resolveResume(_cwd: string): { ok: boolean; ref?: string; reason?: string } {
+    return { ok: true }
+  },
+
+  /** No in-session control: a router has no TUI turn to interrupt/compact. null for
+   *  every command → the daemon/CLI surfaces an explicit "unsupported" refusal. */
+  executeControl(_command: ControlCommand): ControlPlan | null {
+    return null
+  },
+}

package/src/launch/bootstrap.test.ts

@@ -0,0 +1,56 @@
+// launchctlBootstrap — the AUTO-load primitive guards. The happy `loaded` path is
+// proven LIVE (it calls real launchctl); the unit tests cover the three guards that
+// must hold WITHOUT touching launchd: foreign-plist refusal, sandbox skip, and the
+// foundation-owned gate. (The test script sets IAPEER_TEST_SANDBOX=1, so the skip
+// branch is the default; the foreign-refusal branch is checked first regardless.)
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { launchctlBootstrap, installAlwaysOnPlist } from './index.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-boot-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+describe('launchctlBootstrap guards', () => {
+  test('refuses a NON-foundation plist (no ownership sentinel) — fleet guard, checked first', () => {
+    const dir = mkTmp()
+    const foreign = join(dir, 'com.iapeer.boris.plist')
+    writeFileSync(foreign, '<?xml version="1.0"?><plist><dict></dict></plist>')
+    // refused-foreign wins even with IAPEER_TEST_SANDBOX=1 (the guard is checked before sandbox)
+    const r = launchctlBootstrap('boris', foreign, { IAPEER_TEST_SANDBOX: '1' } as NodeJS.ProcessEnv)
+    expect(r.state).toBe('refused-foreign')
+    expect(r.label).toBe('com.iapeer.boris')
+  })
+
+  test('a foundation-owned plist under IAPEER_TEST_SANDBOX=1 → skipped-sandbox (no launchctl)', () => {
+    const root = mkTmp()
+    const bindir = mkTmp()
+    const bin = join(bindir, 'notifier-runtime')
+    writeFileSync(bin, '#!/bin/sh\nexec sleep 1\n', { mode: 0o755 })
+    const env = {
+      IAPEER_LAUNCHAGENTS_DIR: join(root, 'LA'),
+      HOME: root,
+      PATH: bindir,
+      IAPEER_TEST_SANDBOX: '1',
+    } as NodeJS.ProcessEnv
+    const cwd = join(root, 'timer')
+    const plist = installAlwaysOnPlist({ personality: 'timer', runtime: 'notifier', cwd, runtimeBin: bin, env })
+    const r = launchctlBootstrap('timer', plist, env)
+    expect(r.state).toBe('skipped-sandbox')
+    expect(r.label).toBe('com.iapeer.timer')
+  })
+
+  test('absent/unreadable plist → refused-foreign (not provably ours)', () => {
+    const r = launchctlBootstrap('ghost', join(mkTmp(), 'nope.plist'), { IAPEER_TEST_SANDBOX: '1' } as NodeJS.ProcessEnv)
+    expect(r.state).toBe('refused-foreign')
+  })
+})