@agfpd/iapeer 0.1.0

package/src/launch/composeSystemPrompt.ts

@@ -0,0 +1,261 @@
+// composeSystemPrompt — GOLDEN-equivalent TS reimplementation of the jq
+// doctrine-merge in Persistent-Peer/bin/claude-start.sh:264-290. Produces the
+// merged peer system prompt that --system-prompt-file / model_instructions_file
+// consume: a YAML identity block (dynamic facts) + global doctrine (optional) +
+// per-peer doctrine. Byte-for-byte equivalent to the bash/jq output — see the
+// byte-layout notes below.
+//
+// Ownership: launch (HOW to bring up ONE session); NO currency on this path.
+// Contract is FROZEN in ./types.ts (ComposePromptInput / ComposeSystemPrompt).
+
+import { readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import { IAPEER_DIR } from '../core/constants.ts'
+import { publicPeerSummary, readPeersIndex, type PublicPeerSummary } from '../registry/index.ts'
+import { resolveGlobalRoot } from '../storage/index.ts'
+import type { ComposePromptInput, PromptDomainBlock } from './types.ts'
+
+const IAPEER_DOCTRINE_FILE = 'IAPEER.md'
+
+// The bash builds $MERGED as the concatenation of two streams in a `{ … }` group:
+//
+//   1. jq --raw-output over a 10-element string array. --raw-output prints each
+//      array element on its own line, every line terminated by '\n' (including
+//      the LAST element). The array is:
+//        "---", 8×"<key>: <value | @json>", "---", ""
+//      so the final "" element emits a line that is just '\n' → the blank line
+//      after the closing '---'. Net jq output (each line '\n'-terminated):
+//        "---\n" + 8 yaml lines + "---\n" + "\n"
+//      i.e. the YAML block ALWAYS ends with "---\n\n".
+//
+//   2a. if the global doctrine file exists:  cat "$GLOBAL"  then  printf "\n".
+//       `cat` emits the file verbatim; `printf "\n"` appends exactly ONE '\n'.
+//       In TS the file content is `input.globalDoctrine`, so this contributes
+//       `globalDoctrine + "\n"` — the trailing "\n" is added UNCONDITIONALLY,
+//       whether or not globalDoctrine already ends in a newline (it mirrors the
+//       always-on `printf "\n"`). Omitted entirely when global is absent/empty.
+//
+//   2b. cat "$DOCTRINE":  the per-peer doctrine verbatim, NO added newline.
+//
+// jq @json renders each value as a JSON string literal. It equals JSON.stringify
+// byte-for-byte across the realistic field domain (empty string, tab/CR/LF/FF/BS,
+// C0 control chars, unicode passthrough, '"'/'\\' escaping, '/' left unescaped) —
+// verified by enumerating every codepoint U+0001..U+0100. The ONE divergence: jq
+// escapes U+007F (DEL) as a \u007f sequence, whereas JSON.stringify emits the raw
+// byte (the JSON spec only mandates escaping U+0000..U+001F, so DEL passes
+// through). jqJson() reproduces jq exactly by post-escaping DEL (and NUL — the
+// same class; unreachable through the bash `--arg` origin, but escaped for total
+// faithfulness). A JSON string literal is also a valid YAML double-quoted scalar,
+// so the YAML stays safe against colons/quotes/newlines in description / paths.
+function jqJson(value: string): string {
+  // JSON.stringify, then bring the two control chars jq escapes but the
+  // spec-minimal JSON.stringify leaves literal (DEL, NUL) into line with jq.
+  return JSON.stringify(value)
+    .replace(new RegExp(String.fromCharCode(0x7f), 'g'), '\\u007f')
+    .replace(new RegExp(String.fromCharCode(0x00), 'g'), '\\u0000')
+}
+
+/**
+ * Compose the merged system prompt (YAML identity block + optional global
+ * doctrine + per-peer doctrine), GOLDEN byte-for-byte equivalent to the
+ * claude-start.sh:264-290 jq pipeline.
+ */
+export function composeSystemPrompt(input: ComposePromptInput): string {
+  // The eight identity lines, in the bash's exact key order. Keys verbatim:
+  // hyphen `peer-cwd`, underscore `os_version`. Value = jqJson (= jq @json).
+  const yaml =
+    '---\n' +
+    `personality: ${jqJson(input.personality)}\n` +
+    `description: ${jqJson(input.description)}\n` +
+    `peer-cwd: ${jqJson(input.cwd)}\n` +
+    `platform: ${jqJson(input.platform)}\n` +
+    `os_version: ${jqJson(input.osVersion)}\n` +
+    `user: ${jqJson(input.user)}\n` +
+    `hostname: ${jqJson(input.hostname)}\n` +
+    `today: ${jqJson(input.today)}\n` +
+    '---\n' +
+    // jq's final "" array element → the bare blank line after the closing '---'.
+    '\n'
+
+  // Global doctrine sits between the YAML block and the per-peer doctrine so
+  // per-peer rules override global (specific over general). Bash gates on file
+  // EXISTENCE (`[ -f "$GLOBAL_DOCTRINE" ]`), NOT non-emptiness — a present but
+  // EMPTY global file still emits `cat "" + printf "\n"` = "\n". So the contract
+  // is: a present file → globalDoctrine is the string (possibly ""), absent file
+  // → undefined. Guard on `!== undefined` (NOT truthiness) to match bash exactly;
+  // an empty "" then yields "" + "\n" = "\n" (the 1-byte golden divergence the
+  // adversarial verify caught). The trailing "\n" mirrors the unconditional
+  // `printf "\n"` after `cat "$GLOBAL"`.
+  const global = input.globalDoctrine !== undefined ? input.globalDoctrine + '\n' : ''
+
+  // Layers 1+2: YAML block + global doctrine + per-peer doctrine verbatim
+  // (`cat "$DOCTRINE"`), no trailing newline added. BYTE-IDENTICAL to the legacy
+  // jq output — the golden test pins this exactly.
+  const layer12 = yaml + global + input.peerDoctrine
+
+  // Layer 3 (registry) and Layer 4 (other domains) are appended ONLY when they
+  // have content.
+  const layer3 = renderRegistry(input.peers ?? [])
+  const layer4 = renderDomains(input.pluginDomains ?? [])
+  const sections = [layer12, layer3, layer4].filter(section => section.length > 0)
+
+  // ONE section (no registry, no extra domains) → the legacy bytes, UNTOUCHED —
+  // the golden test pins layer12 exactly (peerDoctrine verbatim, incl. its own
+  // trailing-newline-or-not). MULTIPLE sections → normalize every seam to exactly
+  // one blank line: strip each section's trailing newlines, join with '\n\n', end
+  // with a single '\n'. This makes the output robust to whether the source files
+  // carried trailing newlines (a present-but-newline-only tail never widens a gap).
+  if (sections.length === 1) return sections[0]
+  return sections.map(section => section.replace(/\n+$/, '')).join('\n\n') + '\n'
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Layer 3 — normalized peer registry (publicPeerSummary, exactly 5 fields). The
+// behavioral driver for delegation: without a peer list an executor never enters
+// the model's reasoning (contract §"Реестр пиров"). Empty list → empty layer.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function renderRegistry(peers: readonly PublicPeerSummary[]): string {
+  if (peers.length === 0) return ''
+  const lines = ['## Known peers']
+  for (const p of peers) {
+    const desc = p.description ? ` — ${p.description}` : ''
+    lines.push(`- ${p.personality}${desc}`)
+    lines.push(`  runtime: ${p.runtime}`)
+    lines.push(`  runtimes: ${p.runtimes.join(', ')}`)
+    lines.push(`  intelligence: ${p.intelligence}`)
+  }
+  return lines.join('\n')
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Layer 4 — every non-IAPEER `<DOMAIN>.md` pair at the .iapeer/ root, merged
+// general → specific (global then local). The merge is ORGANIC: domain stems are
+// used only for stable ordering (done by the gatherer), never emitted — custom
+// operator files (SPAWNER_INSTRUCTIONS.md, …) flow in as ordinary domains. An
+// empty file is a presence marker (Канал B) and contributes no text here.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function renderDomains(domains: readonly PromptDomainBlock[]): string {
+  const blocks: string[] = []
+  for (const d of domains) {
+    // Per domain: global then local (general → specific), each trimmed of its
+    // trailing newlines so a 0-byte marker (or a newline-only file) drops out and
+    // the spacing is uniform. Halves of one domain are kept tight (single '\n');
+    // distinct domains are separated by a blank line below.
+    const halves = [d.global, d.local]
+      .filter((s): s is string => s !== undefined)
+      .map(s => s.replace(/\n+$/, ''))
+      .filter(s => s.length > 0)
+    if (halves.length > 0) blocks.push(halves.join('\n'))
+  }
+  return blocks.join('\n\n')
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// gatherPromptInput — the FS-discovery half: scan ~/.iapeer/*.md (global) and
+// <cwd>/.iapeer/*.md (local), split IAPEER.md (Layer 2) from every other domain
+// (Layer 4), and project the live registry through publicPeerSummary (Layer 3),
+// into a ready-to-render ComposePromptInput. Layer-1 identity/host facts are
+// supplied by the caller (lifecycle gathers them via sw_vers/hostname/etc).
+// This is the ONLY FS-touching part; composeSystemPrompt itself stays pure.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GatherPromptOptions {
+  /** Layer 1 — identity + host facts (caller-gathered). */
+  personality: string
+  description: string
+  cwd: string
+  platform: string
+  osVersion: string
+  user: string
+  hostname: string
+  today: string
+  /** The global `.iapeer` root; defaults to resolveGlobalRoot(env) (= ~/.iapeer). */
+  globalRoot?: string
+  env?: NodeJS.ProcessEnv
+  /** Layer 3 override (tests); defaults to the live-registry projection. */
+  peers?: PublicPeerSummary[]
+}
+
+function readFileIfPresent(path: string): string | undefined {
+  try {
+    if (!statSync(path).isFile()) return undefined
+    return readFileSync(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/** `*.md` files directly at a `.iapeer` root (NOT recursing), excluding IAPEER.md
+ *  (Layer 2) — the domain candidates for Layer 4. Missing dir → [].
+ *  The `.md` test and the doctrine exclusion are CASE-INSENSITIVE: the Layer-2
+ *  read (join(root,'IAPEER.md')) resolves a lowercase `iapeer.md` on a case-
+ *  insensitive FS (macOS APFS), so a byte-exact exclusion here would let that same
+ *  file ALSO surface as a Layer-4 domain and duplicate the doctrine. Lowercasing
+ *  both also picks up an uppercase-extension `NOTES.MD` (spec: no root MD ignored). */
+function listDomainFiles(root: string): string[] {
+  const doctrineLower = IAPEER_DOCTRINE_FILE.toLowerCase()
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .filter(e => {
+        if (!e.isFile()) return false
+        const lower = e.name.toLowerCase()
+        return lower.endsWith('.md') && lower !== doctrineLower
+      })
+      .map(e => e.name)
+  } catch {
+    return []
+  }
+}
+
+export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput {
+  const env = opts.env ?? process.env
+  const globalRoot = opts.globalRoot ?? resolveGlobalRoot(env)
+  const localRoot = join(opts.cwd, IAPEER_DIR)
+
+  // Layer 2 — IAPEER.md merge. Global is existence-gated (undefined when absent,
+  // '' when present-but-empty — golden parity). Local defaults to '' when absent.
+  const globalDoctrine = readFileIfPresent(join(globalRoot, IAPEER_DOCTRINE_FILE))
+  const peerDoctrine = readFileIfPresent(join(localRoot, IAPEER_DOCTRINE_FILE)) ?? ''
+
+  // Layer 4 — union of every non-IAPEER domain present globally and/or locally,
+  // sorted by filename for a deterministic prompt (plain codepoint order). Empty
+  // (0-byte) files stay as presence markers — readFileIfPresent returns '', and
+  // renderDomains drops empty halves, so a marker contributes no text/separator.
+  const domainNames = new Set<string>([...listDomainFiles(globalRoot), ...listDomainFiles(localRoot)])
+  const pluginDomains: PromptDomainBlock[] = [...domainNames]
+    .sort()
+    .map(name => {
+      const block: PromptDomainBlock = { domain: name.slice(0, -3) } // strip ".md"
+      const global = readFileIfPresent(join(globalRoot, name))
+      const local = readFileIfPresent(join(localRoot, name))
+      if (global !== undefined) block.global = global
+      if (local !== undefined) block.local = local
+      return block
+    })
+
+  // Layer 3 — peers projected through the shared normalizer, sorted by personality
+  // (determinism even if the on-disk file was hand-edited). `opts.peers` lets a
+  // caller that already read the registry (lifecycle's wake path) pass it in,
+  // avoiding a second read+parse on the hot launch path; the sort applies either
+  // way and `.slice()` keeps the caller's array untouched.
+  const peers = (opts.peers ?? readPeersIndex({ env, rootDir: globalRoot }).peers.map(publicPeerSummary))
+    .slice()
+    .sort((a, b) => (a.personality < b.personality ? -1 : a.personality > b.personality ? 1 : 0))
+
+  return {
+    personality: opts.personality,
+    description: opts.description,
+    cwd: opts.cwd,
+    platform: opts.platform,
+    osVersion: opts.osVersion,
+    user: opts.user,
+    hostname: opts.hostname,
+    today: opts.today,
+    peerDoctrine,
+    ...(globalDoctrine !== undefined ? { globalDoctrine } : {}),
+    peers,
+    pluginDomains,
+  }
+}

package/src/launch/index.ts

@@ -0,0 +1,253 @@
+// Launch — the single runtime-AGNOSTIC session bring-up primitive + adapter
+// dispatch. `launch` is the generalized form of the Ф2 wakeOrSpawn inline boot
+// loop + ready-gate (lifecycle/index.ts): pre-clean stale tmux server →
+// new-session -d with adapter.buildArgv → pipe-pane → session self-TTL → (tui)
+// boot dialogs + first-message delivery → ready-gate on adapter.newestActivity
+// Mtime. Every runtime specific (argv flags, boot dialogs, ready marker, activity
+// proxy) comes through the RuntimeAdapter; this file holds NO runtime strings.
+//
+// Ownership split (blueprint §1, §7): launch = HOW to bring up ONE session
+// (runtime-agnostic). It carries NO lifecycle concerns (no wake-lock, no
+// registry/findPeer, no launchd guard, no session-state, no supervise/reap —
+// those stay in lifecycle/index.ts, which calls launch) and NO currency (no
+// marketplace / plugin install / update — that is install-time). lifecycle
+// 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 { claudeAdapter } from './adapters/claude.ts'
+import { codexAdapter } from './adapters/codex.ts'
+import { telegramAdapter } from './adapters/telegram.ts'
+import { notifierAdapter } from './adapters/notifier.ts'
+import type {
+  LaunchConfig,
+  LaunchFn,
+  LaunchResult,
+  LaunchSpec,
+  RuntimeAdapter,
+} from './types.ts'
+
+// Re-export the launch contract so consumers (lifecycle, cli) import from the
+// module index, not the frozen types file directly.
+export type {
+  ComposePromptInput,
+  ComposeSystemPrompt,
+  PromptDomainBlock,
+  PublicPeerSummary,
+  LaunchAdapterConfig,
+  LaunchConfig,
+  LaunchFn,
+  LaunchResult,
+  LaunchSpec,
+  RuntimeAdapter,
+} from './types.ts'
+
+// Always-on launchd plist generation (infra runtimes). launchdRun.ts is a CLI
+// entrypoint (referenced by the generated plist via its file path) — deliberately
+// NOT re-exported here, to avoid an index ↔ launchdRun import cycle.
+export {
+  launchdLabel,
+  launchAgentsDir,
+  launchdPlistPath,
+  renderLaunchdPlist,
+  installAlwaysOnPlist,
+  isFoundationOwnedPlist,
+  launchctlBootstrap,
+  resolveExecutable,
+  IAPEER_PLIST_OWNER_KEY,
+} from './launchd.ts'
+export type {
+  LaunchdPlistSpec,
+  InstallAlwaysOnPlistOptions,
+  BootstrapResult,
+  BootstrapState,
+} from './launchd.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adapter dispatch — claude/codex (tui) + telegram/notifier (router, infra).
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function getAdapter(runtime: Runtime): RuntimeAdapter {
+  if (runtime === 'claude') return claudeAdapter
+  if (runtime === 'codex') return codexAdapter
+  if (runtime === 'telegram') return telegramAdapter
+  if (runtime === 'notifier') return notifierAdapter
+  throw new Error(`no launch adapter for runtime "${runtime}"`)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// tmux helpers (direct spawnSync; no lifecycle dependency)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function tmux(sock: string, ...args: string[]): { ok: boolean; out: string; err: string } {
+  const r = spawnSync('tmux', ['-S', sock, ...args], { encoding: 'utf8' })
+  return { ok: r.status === 0, out: r.stdout ?? '', err: r.stderr ?? '' }
+}
+function sessionAlive(sock: string, identity: string): boolean {
+  return tmux(sock, 'has-session', '-t', identity).ok
+}
+function capturePane(sock: string, identity: string): string {
+  return tmux(sock, 'capture-pane', '-t', identity, '-p').out
+}
+function shellQuote(value: string): string {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+function sleep(ms: number): Promise<void> {
+  return new Promise(r => setTimeout(r, ms))
+}
+
+function fail(identity: string, reason: string): LaunchResult {
+  return { status: 'FAILED', identity, process_address: identity, reason }
+}
+function ready(identity: string): LaunchResult {
+  return { status: 'READY', identity, process_address: identity }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// launch — bring up ONE session (runtime-agnostic via the adapter)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const launch: LaunchFn = async (
+  spec: LaunchSpec,
+  adapter: RuntimeAdapter,
+  firstMessage: string,
+  cfg: LaunchConfig,
+): Promise<LaunchResult> => {
+  const { identity, socketPath: sock, cwd } = spec
+  const env = cfg.env ?? process.env
+
+  // (0) Intelligence gate (fail-loud BEFORE any tmux work): an adapter that declares
+  //     requiresIntelligence (telegram → 'natural') refuses a peer whose nature does
+  //     not match — and refuses too when the nature is unknown (cannot confirm). Ports
+  //     the persistent-peer FATAL human-channel guard (docs/Рантайм-адаптеры).
+  if (adapter.requiresIntelligence && spec.intelligence !== adapter.requiresIntelligence) {
+    return fail(
+      identity,
+      `runtime "${spec.runtime}" requires intelligence=${adapter.requiresIntelligence}, ` +
+        `peer "${spec.personality}" is ${spec.intelligence ?? 'unknown'} — refusing to launch`,
+    )
+  }
+
+  // (0.5) Ensure the socket's PARENT dir exists before `tmux new-session -S <sock>` —
+  //       tmux does NOT create it and fails SILENTLY (the session "dies immediately")
+  //       when the dir is absent. In prod the sock dir is /tmp (always there) so this
+  //       never bites; it bites a sandbox/test with an IAPEER_SOCK_DIR override pointing
+  //       at a not-yet-created dir. Symmetric to the cfg.logDir mkdir before pipe-pane.
+  mkdirSync(dirname(sock), { recursive: true })
+
+  // (1) Pre-clean any stale tmux server on this socket, then launch detached.
+  spawnSync('pkill', ['-f', `tmux -S ${sock} `], { stdio: 'ignore' })
+  tmux(sock, 'kill-server')
+
+  // (2) tmux new-session -d with the adapter-built, shell-quoted argv. The per-peer
+  //     per-runtime launch.env (zone Хранение / Рантайм-адаптеры) contributes
+  //     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`,
+  }
+  const start = spawnSync(
+    'tmux',
+    ['-S', sock, 'new-session', '-d', '-s', identity, '-x', '220', '-y', '50', '-c', cwd, runtimeCmd],
+    { env: childEnv as Record<string, string>, encoding: 'utf8' },
+  )
+  if (start.status !== 0) {
+    return fail(identity, `tmux new-session failed: ${(start.stderr ?? '').trim() || 'exit ' + start.status}`)
+  }
+
+  // (3) pipe-pane the session output to the per-identity log.
+  mkdirSync(cfg.logDir, { recursive: true, mode: 0o700 })
+  const paneLog = `${cfg.logDir}/${identity}.log`
+  tmux(sock, 'pipe-pane', '-t', identity, `cat >> ${shellQuote(paneLog)}`)
+
+  // (4) Session self-TTL: a tmux server-side timer kills the session at max-age,
+  //     independent of any supervisor (bounds a zombie even if no sweep runs).
+  //     SKIPPED for an always-on (infra) session — launchd KeepAlive owns its
+  //     lifecycle, so a self-kill timer would fight it and tear down the endpoint.
+  if (!cfg.alwaysOn) {
+    tmux(sock, 'run-shell', '-b', '-d', String(cfg.maxAgeSecs),
+      `tmux -S ${shellQuote(sock)} kill-session -t ${shellQuote(identity)}`)
+  }
+
+  // (5) Router runtime (telegram): no TUI input surface — there is no boot dialog
+  //     and no ready marker to gate on. The process is up; return READY.
+  if (adapter.kind === 'router') {
+    return ready(identity)
+  }
+
+  // (6) BOOT phase (tui) — baseline the activity proxy, answer startup dialogs,
+  //     wait for the input surface, then deliver firstMessage (send-keys -l + Enter).
+  //     An EMPTY firstMessage is a BARE bring-up (folder-launch with no seed, or an
+  //     attach-resume that carries no message): reach the input surface and return
+  //     READY — there is no message to deliver and nothing to ready-gate on (the
+  //     operator drives the session). A non-empty message takes the wake path
+  //     (deliver + ready-gate on a model turn).
+  const hasMessage = firstMessage.trim().length > 0
+  const baselineMtime = adapter.newestActivityMtime(cwd) ?? 0
+  const bootIters = Math.max(1, Math.ceil(cfg.bootDeadlineSecs / 2))
+  let delivered = false
+  for (let i = 0; i < bootIters && !delivered; i++) {
+    await sleep(2000)
+    if (!sessionAlive(sock, identity)) {
+      return fail(identity, 'tmux session vanished during boot')
+    }
+    const pane = capturePane(sock, identity)
+    if (!pane) continue
+    const dialogKeys = adapter.bootDialogKeys(pane)
+    if (dialogKeys) {
+      tmux(sock, 'send-keys', '-t', identity, ...dialogKeys)
+      continue
+    }
+    if (adapter.isInputReady(pane)) {
+      if (!hasMessage) return ready(identity) // bare bring-up — session up, no message
+      // `--` terminates tmux option parsing (audit #6): without it a firstMessage that
+      // starts with '-' (e.g. a task opening with a markdown bullet) is mis-parsed as a
+      // send-keys flag, losing the boot message and failing the wake with a wrong reason.
+      tmux(sock, 'send-keys', '-t', identity, '-l', '--', firstMessage)
+      await sleep(300)
+      tmux(sock, 'send-keys', '-t', identity, 'Enter')
+      delivered = true
+    }
+  }
+  if (!delivered) {
+    return fail(identity, 'never-became-ready (stuck at a startup prompt or boot hang)')
+  }
+
+  // (7) READY-GATE — the activity proxy must strictly advance past baseline
+  //     (the model picked up and processed the first message).
+  const readyDeadline = Date.now() + cfg.readyGateSecs * 1000
+  while (Date.now() < readyDeadline) {
+    await sleep(2000)
+    if (!sessionAlive(sock, identity)) {
+      return fail(identity, 'tmux session vanished during ready-gate')
+    }
+    const mt = adapter.newestActivityMtime(cwd) ?? 0
+    if (mt > baselineMtime) {
+      return ready(identity)
+    }
+  }
+  return fail(identity, 'model-did-not-process-task (no activity advance after delivery)')
+}