@agfpd/iapeer 0.1.0

package/src/launch/launchd.ts

@@ -0,0 +1,375 @@
+// launchd — always-on plist generation for INFRA runtimes (notifier, telegram).
+// The foundation DEPLOYS the launchd LaunchAgent that holds an infra peer live
+// (KeepAlive) AND reads it back for the H4 sweep-guard (lifecycle.isLaunchdManaged).
+// Both sides MUST agree on the label + dir scheme, so those are the SINGLE shared
+// helpers here (lifecycle imports them) — there is no second place that spells
+// `com.iapeer.<personality>.plist`, so the generator and the detector cannot drift.
+//
+// The plist runs the always-on entrypoint (launchdRun.ts): it brings the peer up
+// in a tmux session (launch alwaysOn → a live pane/socket for the daemon's
+// deliverViaTmux to paste send_to_peer envelopes into) and blocks until the session
+// dies → KeepAlive respawns. ThrottleInterval PINS launchd's respawn floor EXPLICITLY
+// (launchd's own default is also 10s, so this restates rather than widens it — set
+// here so the crashloop bound is visible and tunable, not an implicit default; raise
+// throttleIntervalSecs for a wider window). RunAtLoad+KeepAlive = always-on.
+
+import { accessSync, constants as FS, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+import { iapeerBinPath } from '../install/index.ts'
+import {
+  IAPEER_DIR,
+  INFRA_RUNTIME_BIN_ENV,
+  INFRA_RUNTIME_DEFAULT_BIN,
+  LAUNCHD_LABEL_PREFIX,
+  isInfraRuntime,
+  type Runtime,
+} from '../core/constants.ts'
+import { buildProcessAddress } from '../core/socket.ts'
+import { peerLogsDir } from '../storage/index.ts'
+import { IapError } from '../core/errors.ts'
+
+const DEFAULT_THROTTLE_SECS = 10
+
+/**
+ * OWNERSHIP SENTINEL — an inert top-level plist key the foundation renderer ALWAYS
+ * embeds, marking a plist as foundation-managed. The launchd Label is keyed on
+ * personality (`com.iapeer.<p>`) and SHARED with the live persistent-peer fleet, so
+ * the label alone CANNOT tell a foundation plist from a PP-managed one. This key
+ * can: the proof of ownership travels WITH the artifact (no side ownership registry
+ * to drift), so the install guard refuses to clobber any com.iapeer.* plist that
+ * lacks it. launchd ignores keys it does not recognize, so the marker is inert at
+ * load time (and never reaches the runtime process, unlike an env var would).
+ * NOT a Label: a Label value renders inside `<string>`, this only ever appears as
+ * `<key>…</key>`, so the detection substring can never collide with a peer named
+ * "managed". Bumping this string is a breaking change (older plists read as foreign).
+ */
+export const IAPEER_PLIST_OWNER_KEY = 'com.iapeer.managed'
+
+/**
+ * True iff the plist file at `path` was rendered by the foundation (carries the
+ * ownership sentinel). A foreign / persistent-peer plist at the same com.iapeer.*
+ * label lacks it → false. An absent or unreadable file → false (not provably ours,
+ * so the guard treats it as foreign and refuses). Substring match is reliable
+ * because renderLaunchdPlist emits the sentinel verbatim as a `<key>` node.
+ */
+export function isFoundationOwnedPlist(path: string): boolean {
+  try {
+    return readFileSync(path, 'utf8').includes(`<key>${IAPEER_PLIST_OWNER_KEY}</key>`)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Resolve an executable to an ABSOLUTE path against `env.PATH` (the RICH
+ * provisioning PATH), so the result can be baked into a launchd plist whose own
+ * PATH is minimal. A name containing '/' is treated as a path and returned iff it
+ * is an executable file. Returns undefined when nothing executable is found.
+ * Pure PATH scan (no `which` dependency) — deterministic and testable.
+ */
+export function resolveExecutable(bin: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const isExec = (p: string): boolean => {
+    try {
+      accessSync(p, FS.X_OK)
+      return true
+    } catch {
+      return false
+    }
+  }
+  if (bin.includes('/')) return isExec(bin) ? bin : undefined
+  for (const dir of (env.PATH ?? '').split(':')) {
+    if (!dir) continue
+    const p = join(dir, bin)
+    if (isExec(p)) return p
+  }
+  return undefined
+}
+
+/** `com.iapeer.<personality>` — the launchd Label AND the plist basename stem.
+ *  The single source for the scheme; isLaunchdManaged reads the same. */
+export function launchdLabel(personality: string): string {
+  return `${LAUNCHD_LABEL_PREFIX}${personality}`
+}
+
+/** The LaunchAgents dir: IAPEER_LAUNCHAGENTS_DIR override (tests/sandbox) else
+ *  ~/Library/LaunchAgents. Shared with isLaunchdManaged. */
+export function launchAgentsDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env.IAPEER_LAUNCHAGENTS_DIR?.trim() || join(env.HOME?.trim() || homedir(), 'Library', 'LaunchAgents')
+}
+
+export function launchdPlistPath(personality: string, env: NodeJS.ProcessEnv = process.env): string {
+  return join(launchAgentsDir(env), `${launchdLabel(personality)}.plist`)
+}
+
+// XML-escape a plist <string> text node. cwd / personality / PATH can carry '&',
+// '<', '>' (or unicode) — a literal '&' or '<' would corrupt the XML, so escape the
+// three significant characters. Also DROP XML-1.0-illegal control characters (NUL +
+// the C0 set except tab/LF/CR): they are not representable in XML 1.0 text and `plutil`
+// only leniently tolerates them. Inputs here are NAME_RE-clean personalities and real
+// filesystem paths, so this is belt-and-suspenders, never lossy in practice.
+function xmlEscape(value: string): string {
+  return value
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+export interface LaunchdPlistSpec {
+  label: string
+  programArguments: string[]
+  workingDirectory: string
+  environment: Record<string, string>
+  stdoutPath: string
+  stderrPath: string
+  /** Seconds launchd waits before respawning a fast-exiting job (crashloop
+   *  circuit). Default 10 — explicit, so a broken infra peer cannot respawn-storm. */
+  throttleIntervalSecs?: number
+}
+
+/** Render a launchd LaunchAgent plist (RunAtLoad + KeepAlive = always-on). PURE
+ *  and deterministic — golden/lint-testable. */
+export function renderLaunchdPlist(spec: LaunchdPlistSpec): string {
+  const throttle = spec.throttleIntervalSecs ?? DEFAULT_THROTTLE_SECS
+  const args = spec.programArguments.map(a => `        <string>${xmlEscape(a)}</string>`).join('\n')
+  const envEntries = Object.entries(spec.environment)
+    .map(([k, v]) => `        <key>${xmlEscape(k)}</key>\n        <string>${xmlEscape(v)}</string>`)
+    .join('\n')
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${xmlEscape(spec.label)}</string>
+    <key>${IAPEER_PLIST_OWNER_KEY}</key>
+    <true/>
+    <key>ProgramArguments</key>
+    <array>
+${args}
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${xmlEscape(spec.workingDirectory)}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+${envEntries}
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>${throttle}</integer>
+    <key>StandardOutPath</key>
+    <string>${xmlEscape(spec.stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xmlEscape(spec.stderrPath)}</string>
+</dict>
+</plist>
+`
+}
+
+/** Default ProgramArguments prefix (Ф-F): the INSTALLED `iapeer` binary running the
+ *  always-on infra entrypoint (`iapeer run-infra`), NOT `bun launchdRun.ts` — prod is
+ *  decoupled from the src tree. The personality + runtime positionals are appended by
+ *  install. (The pre-Ф-F `[bun, launchdRun.ts]` is overridable via entrypointArgv for
+ *  tests / a tree-run dev layout.) */
+function defaultEntrypointArgv(env: NodeJS.ProcessEnv = process.env): string[] {
+  return [iapeerBinPath(env), 'run-infra']
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// launchctl bootstrap — AUTO-load a freshly-provisioned foundation plist
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Resolve the current gui-domain uid for `launchctl bootstrap gui/<uid>`. NEVER
+ *  falls back to 0 (that would aim the ROOT gui domain — audit #29); a non-numeric
+ *  `id -u` result throws. */
+function currentUid(): string {
+  const r = spawnSync('id', ['-u'], { encoding: 'utf8' })
+  const u = (r.stdout ?? '').trim()
+  if (!/^\d+$/.test(u)) {
+    throw new IapError('cannot resolve the current uid (id -u failed) — refusing to target launchctl at an unknown domain')
+  }
+  return u
+}
+
+export type BootstrapState =
+  | 'loaded' // bootstrapped now (was not loaded)
+  | 'already-loaded' // service already in the gui domain → no-op (idempotent)
+  | 'skipped-sandbox' // IAPEER_TEST_SANDBOX=1 → never touch the real launchd
+  | 'refused-foreign' // the plist is not foundation-owned → never load someone else's
+  | 'failed' // launchctl bootstrap exited non-zero
+
+export interface BootstrapResult {
+  state: BootstrapState
+  label: string
+  detail?: string
+}
+
+/** Is `com.iapeer.<personality>` already loaded in the gui domain? (`launchctl print`
+ *  exits 0 when the service exists.) Used to make bootstrap idempotent. */
+function isLaunchdLoaded(label: string, uid: string): boolean {
+  return spawnSync('launchctl', ['print', `gui/${uid}/${label}`], { stdio: 'ignore' }).status === 0
+}
+
+/**
+ * AUTO-bootstrap a freshly-provisioned foundation plist into the gui domain
+ * (`launchctl bootstrap gui/<uid> <plist>`) — the "load it now, don't write-and-wait
+ * for the operator" step (contract Установка / Фаза §5). Designed to be SAFE on a
+ * live host:
+ *   - FLEET GUARD: refuses any plist that is not foundation-owned (lacks the
+ *     ownership sentinel) — a foreign / persistent-peer plist at the shared
+ *     com.iapeer.* label is never loaded by us (`refused-foreign`).
+ *   - IDEMPOTENT: a service already in the gui domain is a no-op (`already-loaded`),
+ *     so a repeat provision/create never errors on a double bootstrap.
+ *   - SANDBOX FAIL-SAFE: under IAPEER_TEST_SANDBOX=1 it NEVER calls launchctl
+ *     (`bootstrap gui/<uid>` is host-global regardless of where the plist file lives,
+ *     so a test must not load a real launchd job). Returns `skipped-sandbox`.
+ * A live e2e proof runs WITHOUT IAPEER_TEST_SANDBOX (isolated IAPEER_ROOT + a
+ * non-fleet personality) so this actually loads — additive and reversible (bootout).
+ */
+export function launchctlBootstrap(
+  personality: string,
+  plistPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+): BootstrapResult {
+  const label = launchdLabel(personality)
+  if (!isFoundationOwnedPlist(plistPath)) {
+    return {
+      state: 'refused-foreign',
+      label,
+      detail: `${plistPath} is not foundation-owned (no ${IAPEER_PLIST_OWNER_KEY} sentinel) — refusing to launchctl bootstrap a foreign plist`,
+    }
+  }
+  // SANDBOX FAIL-CLOSED: `launchctl bootstrap gui/<uid>` is HOST-GLOBAL — it loads a
+  // real launchd job regardless of where the plist file lives or what IAPEER_ROOT is.
+  // So the skip MUST consult BOTH the passed env AND the PROCESS env: a test harness
+  // that passes an explicit env (isolated IAPEER_ROOT) but omits the flag would
+  // otherwise bypass the guard and load a real job (this exact hole bit B1 once). The
+  // process-level flag (set by `bun test`) forces the skip even then — mirror of the
+  // registry's fail-closed sandbox lesson. A live e2e proof runs with NEITHER flag set.
+  if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') {
+    return { state: 'skipped-sandbox', label, detail: 'IAPEER_TEST_SANDBOX=1 — not loading a real launchd job' }
+  }
+  const uid = currentUid()
+  if (isLaunchdLoaded(label, uid)) return { state: 'already-loaded', label }
+  const r = spawnSync('launchctl', ['bootstrap', `gui/${uid}`, plistPath], { encoding: 'utf8' })
+  if (r.status === 0) return { state: 'loaded', label }
+  // A race could have loaded it between the check and the bootstrap; treat a
+  // now-loaded service as success (still idempotent).
+  if (isLaunchdLoaded(label, uid)) return { state: 'already-loaded', label }
+  return { state: 'failed', label, detail: (r.stderr ?? '').trim() || `launchctl bootstrap exited ${r.status}` }
+}
+
+export interface InstallAlwaysOnPlistOptions {
+  personality: string
+  runtime: Runtime
+  cwd: string
+  /** How to invoke the always-on entrypoint, WITHOUT the trailing personality/
+   *  runtime (those are appended). Defaults to [bun, launchdRun.ts]. */
+  entrypointArgv?: string[]
+  /** PATH for the launchd minimal env (default: bun/local/homebrew/usr/bin). */
+  path?: string
+  /** Absolute path to the infra runtime's launcher binary, baked into the plist
+   *  env (NOTIFIER_RUNTIME_BIN / TELEGRAM_RUNTIME_BIN) so the launchd-minimal PATH
+   *  can resolve it. When omitted, the default bin is resolved against env.PATH
+   *  (best-effort); unresolved → not baked (the bare name + plist PATH remain). */
+  runtimeBin?: string
+  env?: NodeJS.ProcessEnv
+  throttleIntervalSecs?: number
+}
+
+/**
+ * Generate and install the always-on launchd plist for an INFRA peer, returning
+ * the written path. Gated on isInfraRuntime (a warm-on-demand claude/codex peer is
+ * daemon-managed, never launchd-held — installing a plist would flip it to H4
+ * read-only and break wake). The plist's ProgramArguments run the always-on
+ * entrypoint with PEER_* env + WorkingDirectory=cwd; logs land under
+ * <cwd>/.iapeer/logs/<runtime>/.
+ *
+ * COLLISION GUARD (H4 — shared label namespace): the launchd Label is
+ * com.iapeer.<personality> — keyed on PERSONALITY, not identity, and SHARED with the
+ * already-deployed persistent-peer fleet (~/Library/LaunchAgents/
+ * com.iapeer.<persistent-peer>.plist run by start.sh). A personality collision (a
+ * notifier peer named like a live PP peer) must NOT silently overwrite that foreign
+ * plist — doing so would tear a live PP peer off launchd. So before writing we
+ * REFUSE when a plist already sits at the target and is not foundation-owned
+ * (isFoundationOwnedPlist: it lacks the sentinel renderLaunchdPlist embeds). The
+ * label prefix alone cannot tell ours from theirs (PP is com.iapeer.* too); the
+ * sentinel can. Re-installing our OWN plist (sentinel present) is allowed
+ * (idempotent re-provision). The guard is checked FIRST, before any mkdir/write, so
+ * a refusal leaves the filesystem untouched.
+ */
+export function installAlwaysOnPlist(opts: InstallAlwaysOnPlistOptions): string {
+  if (!isInfraRuntime(opts.runtime)) {
+    throw new IapError(
+      `runtime "${opts.runtime}" is not an always-on infra runtime; no launchd plist generated`,
+    )
+  }
+  const env = opts.env ?? process.env
+  // Collision guard FIRST — never clobber a plist the foundation does not own.
+  const path = launchdPlistPath(opts.personality, env)
+  if (existsSync(path) && !isFoundationOwnedPlist(path)) {
+    throw new IapError(
+      `refusing to overwrite launchd plist ${path}: label ${launchdLabel(opts.personality)} ` +
+        `is not foundation-managed (no ${IAPEER_PLIST_OWNER_KEY} sentinel) — a persistent-peer ` +
+        `or other manager owns it; rename the peer to avoid the com.iapeer.<personality> collision`,
+    )
+  }
+  // GLOBAL infra logs (Фаза §8): ~/.iapeer/logs/<personality>/, NOT per-peer
+  // <cwd>/.iapeer/logs/ — host-service logs live in the global log area.
+  const logDir = peerLogsDir(opts.personality, { env })
+  // Resolve home the SAME way launchAgentsDir does (env.HOME first) so a test/
+  // sandbox overriding HOME keeps the PATH fallback and the plist dir in step.
+  const home = env.HOME?.trim() || homedir()
+  const defaultPath = `${home}/.bun/bin:${home}/.local/bin:/opt/homebrew/bin:/usr/bin:/bin`
+  const environment: Record<string, string> = {
+    PEER_PERSONALITY: opts.personality,
+    PEER_RUNTIME: opts.runtime,
+    PEER_IDENTITY: buildProcessAddress(opts.runtime, opts.personality),
+    PATH: opts.path ?? env.PATH ?? defaultPath,
+  }
+  // Propagate the non-default path overrides into the plist env (mirror of the daemon
+  // plist, audit #26): in PRODUCTION these are unset → nothing is baked, the always-on
+  // session uses the real ~/.iapeer + /tmp sockets (correct). In a SANDBOX they ARE set
+  // → baked, so a sandboxed infra peer's run-infra resolves the SAME isolated root +
+  // socket dir the provision used (its tmux endpoint lands in the sandbox, not /tmp).
+  // This is what lets a live e2e proof be fully isolated AND leaves prod unchanged.
+  for (const key of ['IAPEER_ROOT', 'IAPEER_SOCK_DIR', 'IAPEER_LAUNCHAGENTS_DIR'] as const) {
+    if (env[key]?.trim()) environment[key] = env[key]!.trim()
+  }
+  // Pin the infra runtime's launcher to an ABSOLUTE path so launchd's minimal PATH
+  // can find it (a bare name would crash-loop the always-on session). opts.runtimeBin
+  // wins; else resolve the runtime's default bin against the rich provisioning
+  // env.PATH. Unresolved → leave it out (the bare name + plist PATH still apply).
+  const binEnvVar = INFRA_RUNTIME_BIN_ENV[opts.runtime]
+  if (binEnvVar) {
+    const resolved = opts.runtimeBin ?? resolveExecutable(INFRA_RUNTIME_DEFAULT_BIN[opts.runtime] ?? opts.runtime, env)
+    if (resolved) environment[binEnvVar] = resolved
+  }
+  const spec: LaunchdPlistSpec = {
+    label: launchdLabel(opts.personality),
+    programArguments: [...(opts.entrypointArgv ?? defaultEntrypointArgv(env)), opts.personality, opts.runtime],
+    workingDirectory: opts.cwd,
+    environment,
+    stdoutPath: join(logDir, 'launchd-stdout.log'),
+    stderrPath: join(logDir, 'launchd-stderr.log'),
+    throttleIntervalSecs: opts.throttleIntervalSecs,
+  }
+  mkdirSync(launchAgentsDir(env), { recursive: true })
+  // The global infra log dir now resolves under ~/.iapeer (Фаза §8). Under a sandbox
+  // (test) run, NEVER mkdir under the REAL ~/.iapeer — a test that forgot IAPEER_ROOT
+  // would otherwise create real ~/.iapeer/logs/<p>. Skip the mkdir then (the plist
+  // still carries the path; a real run — no sandbox flag — always makes it). Consult
+  // process.env too, since a test passes an explicit env without the flag. Mirror of
+  // the registry/install fail-closed sandbox guards.
+  const sandbox = env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1'
+  const realRoot = join(homedir(), IAPEER_DIR)
+  if (!(sandbox && logDir.startsWith(`${realRoot}/`))) {
+    mkdirSync(logDir, { recursive: true, mode: 0o700 })
+  }
+  writeFileSync(path, renderLaunchdPlist(spec), { mode: 0o644 })
+  return path
+}

package/src/launch/launchdRun.ts

@@ -0,0 +1,168 @@
+// launchd always-on entrypoint — the blocking process launchd KeepAlive holds for
+// an INFRA (always-on) peer. It brings the peer's session up via the launch
+// primitive in alwaysOn mode (tmux endpoint for the daemon's deliverViaTmux; NO
+// self-TTL) and then BLOCKS until that session dies, at which point it exits so
+// launchd respawns it (the plist's ThrottleInterval bounds a crashloop).
+//
+// IDEMPOTENT: if the session is already live (a prior instance, or a manual
+// bring-up), it skips the launch and only block-watches — never a second spawn.
+// The bring-up is a check-then-launch with NO advisory lock (unlike wakeOrSpawn's
+// withWakeLock): serialization is delegated to launchd, which runs at most one
+// instance per Label. Do NOT invoke this manually alongside the launchd-managed job
+// for the same identity — two concurrent racers could both pass the liveness check.
+//
+// Invoked by the generated plist (launchd.ts installAlwaysOnPlist):
+//   bun <this> <personality> <runtime>
+// with WorkingDirectory=<peer cwd> and EnvironmentVariables PEER_* set by launchd,
+// so process.cwd() IS the peer cwd.
+
+import { spawnSync } from 'child_process'
+import { join } from 'path'
+import { INFRA_RUNTIME_BIN_ENV, isInfraRuntime, resolveSockDir } from '../core/constants.ts'
+import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
+import { peerLogsDir } from '../storage/index.ts'
+import { readPeerProfile } from '../identity/index.ts'
+import { getAdapter, launch } from './index.ts'
+import type { LaunchConfig, LaunchSpec } from './types.ts'
+
+/** Block-watch poll cadence — seconds, deliberately NOT a tight loop (the session
+ *  rarely dies; this only needs to notice a crash within a few seconds). The sleep
+ *  is cancelable, so a shutdown signal does not wait out a full interval. */
+const WATCH_INTERVAL_MS = 5000
+
+/** After a router launch returns READY (= tmux new-session succeeded), wait this
+ *  long and recheck: a missing/broken runtime bin lets the pane die instantly, and
+ *  this turns that into a NON-zero diagnostic exit instead of a clean-looking run. */
+const BOOT_RECHECK_MS = 2000
+
+function sessionAlive(sock: string, identity: string): boolean {
+  return spawnSync('tmux', ['-S', sock, 'has-session', '-t', identity], { stdio: 'ignore' }).status === 0
+}
+
+/**
+ * Build the always-on LaunchSpec for an infra peer, reading intelligence from the
+ * local peer-profile.json. launchd sets WorkingDirectory = peer cwd, so that file
+ * is the authoritative per-peer source (it self-heals legacy human→natural on read).
+ *
+ * The intelligence field is LOAD-BEARING for the launch primitive's nature gate
+ * (telegram requires natural). Omitting it (the original bug) made every always-on
+ * telegram launch fail the gate (`natural !== undefined`) → exit 1 → launchd
+ * KeepAlive crash-loop. A correctly-provisioned telegram peer (intelligence=natural)
+ * now clears the gate; a mis-provisioned one is refused LOUDLY, not crash-looped.
+ * Exported so this invariant is unit-testable WITHOUT touching tmux.
+ */
+export function buildAlwaysOnSpec(
+  personality: string,
+  runtime: string,
+  cwd: string,
+  sockDir: string,
+): LaunchSpec {
+  const profile = readPeerProfile(cwd)
+  return {
+    personality,
+    runtime,
+    cwd,
+    identity: buildProcessAddress(runtime, personality),
+    socketPath: buildSocketPath(runtime, personality, sockDir),
+    intelligence: profile?.intelligence,
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * Bring up (if needed) and block-watch one always-on infra session. Returns the
+ * process exit code: 0 when the watched session died (→ KeepAlive respawns),
+ * 1 when bring-up failed or the runtime is not infra.
+ */
+export async function runAlwaysOn(personality: string, runtime: string, cwd: string): Promise<number> {
+  if (!isInfraRuntime(runtime)) {
+    process.stderr.write(`launchdRun: "${runtime}" is not an always-on infra runtime\n`)
+    return 1
+  }
+  const env = process.env
+  const sockDir = resolveSockDir(env)
+  const identity = buildProcessAddress(runtime, personality)
+  const sock = buildSocketPath(runtime, personality, sockDir)
+  const adapter = getAdapter(runtime)
+
+  const cfg: LaunchConfig = {
+    claudeBin: env.CLAUDE_BIN ?? 'claude',
+    codexBin: env.CODEX_BIN ?? 'codex',
+    // Read the abs runtime-bin the plist baked, via the SAME var-name map the baker
+    // (installAlwaysOnPlist) uses — so the pin and the read can never drift.
+    telegramBin: env[INFRA_RUNTIME_BIN_ENV.telegram],
+    notifierBin: env[INFRA_RUNTIME_BIN_ENV.notifier],
+    sockDir,
+    bootDeadlineSecs: 30,
+    readyGateSecs: 30,
+    maxAgeSecs: 0, // unused — alwaysOn skips the self-TTL
+    // GLOBAL infra logs (Фаза §8): ~/.iapeer/logs/<personality>/ — match the plist's
+    // stdout/stderr dir (installAlwaysOnPlist), not per-peer <cwd>/.iapeer/logs/.
+    logDir: peerLogsDir(personality, { env }),
+    env,
+    alwaysOn: true,
+  }
+  // Intelligence MUST be on the spec so the launch primitive's nature gate
+  // (telegram requires natural) passes for a correctly-provisioned infra peer
+  // (see buildAlwaysOnSpec — omitting it crash-looped every telegram launch).
+  const spec = buildAlwaysOnSpec(personality, runtime, cwd, sockDir)
+
+  // Idempotent: bring up only when not already live.
+  if (!sessionAlive(sock, identity)) {
+    const result = await launch(spec, adapter, '', cfg)
+    if (result.status !== 'READY') {
+      process.stderr.write(`launchdRun: launch FAILED for ${identity}: ${result.reason ?? 'unknown'}\n`)
+      return 1 // exit → launchd respawns after ThrottleInterval
+    }
+    // A router returns READY the moment `tmux new-session` succeeds — it does NOT
+    // verify the pane command STAYED up. If the runtime bin is missing/broken the
+    // session dies at once; recheck after a beat so a crash-on-boot exits NON-zero
+    // (a diagnostic, throttled by the plist) instead of a clean exit that reads as a
+    // healthy run in the launchd logs.
+    await sleep(BOOT_RECHECK_MS)
+    if (!sessionAlive(sock, identity)) {
+      process.stderr.write(
+        `launchdRun: ${identity} session died immediately after launch — check ${cfg.notifierBin ?? `${runtime}-runtime`}\n`,
+      )
+      return 1
+    }
+  }
+
+  // Block-watch until the session dies, then exit 0 so KeepAlive respawns a fresh
+  // bring-up. The per-iteration sleep is CANCELABLE: SIGTERM/SIGINT (launchctl
+  // bootout / clean shutdown) clears the pending timer and breaks the loop at once,
+  // so shutdown does not wait out a full poll interval.
+  let stop = false
+  let interrupt: (() => void) | null = null
+  const onSignal = () => {
+    stop = true
+    interrupt?.()
+  }
+  process.on('SIGTERM', onSignal)
+  process.on('SIGINT', onSignal)
+  while (!stop && sessionAlive(sock, identity)) {
+    await new Promise<void>(resolve => {
+      const timer = setTimeout(resolve, WATCH_INTERVAL_MS)
+      interrupt = () => {
+        clearTimeout(timer)
+        resolve()
+      }
+    })
+    interrupt = null
+  }
+  return 0
+}
+
+// CLI entry: bun launchdRun.ts <personality> <runtime>. cwd = launchd WorkingDirectory.
+if (import.meta.main) {
+  const personality = process.argv[2] ?? process.env.PEER_PERSONALITY ?? ''
+  const runtime = process.argv[3] ?? process.env.PEER_RUNTIME ?? ''
+  if (!personality || !runtime) {
+    process.stderr.write('usage: launchdRun <personality> <runtime>\n')
+    process.exit(2)
+  }
+  runAlwaysOn(personality, runtime, process.cwd()).then(code => process.exit(code))
+}

package/src/launch/sockdir.test.ts

@@ -0,0 +1,70 @@
+// Regression: launch() must `mkdir -p` the socket's parent dir before
+// `tmux new-session -S <sock>` — tmux does NOT create it and fails silently
+// ("session died immediately") when the IAPEER_SOCK_DIR override points at a
+// not-yet-created dir (prod sock=/tmp always exists; this bit a sandbox pilot).
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join } from 'path'
+import { spawnSync } from 'child_process'
+import { launch } from './index.ts'
+import { notifierAdapter } from './adapters/notifier.ts'
+import type { LaunchConfig, LaunchSpec } from './types.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-sockdir-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+
+describe('launch creates a missing socket dir', () => {
+  test.if(tmuxAvailable)('router launch into a NON-EXISTENT IAPEER_SOCK_DIR comes up (dir auto-created)', async () => {
+    const root = mkTmp()
+    const sockDir = join(root, 'does', 'not', 'exist', 'yet') // deep, absent
+    const sock = join(sockDir, 'tmux-iap-notifier-sockt.sock')
+    const bin = join(root, 'notifier-runtime')
+    writeFileSync(bin, '#!/bin/sh\nexec sleep 30\n', { mode: 0o755 })
+
+    const spec: LaunchSpec = {
+      personality: 'sockt',
+      runtime: 'notifier',
+      cwd: root,
+      identity: 'notifier-sockt',
+      socketPath: sock,
+      intelligence: 'absent',
+    }
+    const cfg: LaunchConfig = {
+      claudeBin: 'claude',
+      codexBin: 'codex',
+      notifierBin: bin,
+      sockDir,
+      bootDeadlineSecs: 1,
+      readyGateSecs: 1,
+      maxAgeSecs: 0,
+      logDir: join(root, 'logs'),
+      alwaysOn: true,
+    }
+
+    try {
+      // The regression assertion: before the fix the dir was NOT created and
+      // `tmux new-session -S <sock>` failed silently; now launch mkdir's it. (We assert
+      // dir creation, not the READY outcome — whether the session reaches READY depends
+      // on tmux + the test-runner env, which is orthogonal to this fix.)
+      await launch(spec, notifierAdapter, '', cfg)
+      expect(existsSync(sockDir)).toBe(true)
+    } finally {
+      spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+    }
+  })
+
+  test('the fix is unconditional dirname(sock) creation (documents the parent)', () => {
+    expect(dirname('/a/b/c/tmux-iap-notifier-x.sock')).toBe('/a/b/c')
+  })
+})