@agfpd/iapeer 0.1.0

package/src/cli/index.ts

@@ -0,0 +1,608 @@
+// iapeer CLI — the unified operator/agent entrypoint (`iapeer <verb> …`, contract
+// Примитивы §Карта verbs). Thin verbs over the foundation primitives: list (registry
+// + liveness + C1 stopped), stop/start (C1 durable flag for warm; launchctl for
+// always-on), send (routeSend fallback). init delegates to src/init; launch (folder)
+// and attach (last-active resume) land in the next increment.
+//
+// FLEET SAFETY (H4): the live persistent-peer fleet is launchd-managed (com.iapeer.<p>
+// plists the foundation does NOT own). stop/start REFUSE such a peer — the foundation
+// is read-only for it; stopping it would fight PP's KeepAlive / tear a live telegram
+// bridge off launchd. Only foundation-owned peers (warm no-plist, or our own
+// sentinel-marked always-on plist) are stop/start-able.
+
+import { spawnSync } from 'child_process'
+import { fileURLToPath } from 'url'
+import {
+  isInfraRuntime,
+  isRuntime,
+  type Intelligence,
+  type Runtime,
+} from '../core/constants.ts'
+import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
+import { ensureGlobalIapScaffold } from '../storage/index.ts'
+import { findPeer, readPeersIndex, type PeerRecord } from '../registry/index.ts'
+import { isPeerLive, routeControl, routeSend, type WakeFn } from '../transport/index.ts'
+import {
+  attachPeer,
+  clearStopped,
+  folderLaunch,
+  isLaunchdManaged,
+  isStopped,
+  killSession,
+  loadLifecycleConfig,
+  setStopped,
+  wakeOrSpawn,
+} from '../lifecycle/index.ts'
+import { getAdapter } from '../launch/index.ts'
+import { isFoundationOwnedPlist, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
+import { resolveCallerIdentity, resolveIdentity } from '../identity/index.ts'
+import { runAlwaysOn } from '../launch/launchdRun.ts'
+import { installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
+import { MARKETPLACE_NAME, onboardHost } from '../onboard/index.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// list — registry + per-runtime liveness (contract Примитивы §list)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type RuntimeLiveness = 'live' | 'asleep' | 'stopped'
+export interface RuntimeStatus {
+  runtime: Runtime
+  status: RuntimeLiveness
+}
+export interface PeerListing {
+  personality: string
+  default_runtime: Runtime
+  /** Runtime with the freshest activity (what `attach` resumes); undefined if none. */
+  last_active_runtime?: Runtime
+  intelligence: Intelligence
+  description: string
+  runtimes: RuntimeStatus[]
+}
+
+export interface CliEnvOptions {
+  env?: NodeJS.ProcessEnv
+}
+
+/**
+ * Gather the peer listing: one row per registered peer, per-runtime liveness (live
+ * via tmux has-session / stopped via the C1 durable flag / else asleep) and the
+ * last-active runtime by transcript-mtime (the same proxy `attach` keys on).
+ */
+export function listPeers(opts: CliEnvOptions = {}): PeerListing[] {
+  const env = opts.env ?? process.env
+  const cfg = loadLifecycleConfig(env)
+  const index = readPeersIndex({ env })
+  return index.peers.map(peer => {
+    const runtimes: RuntimeStatus[] = peer.runtimes.map(rt => ({
+      runtime: rt,
+      status: isPeerLive(rt, peer.personality, cfg.sockDir)
+        ? 'live'
+        : isStopped(cfg, buildProcessAddress(rt, peer.personality))
+          ? 'stopped'
+          : 'asleep',
+    }))
+    let lastActive: Runtime | undefined
+    let bestMt = -1
+    for (const rt of peer.runtimes) {
+      try {
+        const mt = getAdapter(rt).newestActivityMtime(peer.cwd)
+        if (mt !== null && mt > bestMt) {
+          bestMt = mt
+          lastActive = rt
+        }
+      } catch {
+        /* no adapter / no proxy for this runtime */
+      }
+    }
+    return {
+      personality: peer.personality,
+      default_runtime: peer.runtime,
+      last_active_runtime: lastActive,
+      intelligence: peer.intelligence,
+      description: peer.description,
+      runtimes,
+    }
+  })
+}
+
+const GLYPH: Record<RuntimeLiveness, string> = { live: '●', asleep: '○', stopped: '✕' }
+
+/** Render the scriptable list table (non-tty default). */
+export function formatListTable(rows: PeerListing[]): string {
+  if (rows.length === 0) return 'no peers registered\n'
+  const lines = rows.map(r => {
+    const status = r.runtimes.map(s => `${GLYPH[s.status]} ${s.runtime}`).join('  ')
+    const la = r.last_active_runtime ? ` last-active:${r.last_active_runtime}` : ''
+    return `${r.personality}  [${r.default_runtime}]  ${r.intelligence}  ${status}${la}`
+  })
+  return lines.join('\n') + '\n'
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// stop / start — dispatch by runtime class, with the FLEET GUARD (H4)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface StopStartOutcome {
+  personality: string
+  runtime: Runtime
+  action: 'stopped' | 'started' | 'bootout' | 'bootstrap' | 'refused-foreign-launchd'
+  reason?: string
+}
+
+function uid(): string {
+  const r = spawnSync('id', ['-u'], { encoding: 'utf8' })
+  const u = (r.stdout ?? '').trim()
+  // Audit #29: NEVER fall back to '0' — that would aim launchctl bootout/bootstrap at
+  // the ROOT gui domain. A non-numeric/empty result means `id -u` failed; refuse.
+  if (!/^\d+$/.test(u)) {
+    throw new Error('cannot resolve the current uid (id -u failed) — refusing to target launchctl at an unknown domain')
+  }
+  return u
+}
+
+/** FLEET GUARD: a peer launchd-managed by a NON-foundation plist (persistent-peer)
+ *  is off-limits to stop/start — the foundation is read-only for it (H4). */
+function isForeignLaunchd(personality: string, env: NodeJS.ProcessEnv): boolean {
+  return isLaunchdManaged(personality, env) && !isFoundationOwnedPlist(launchdPlistPath(personality, env))
+}
+
+function targetRuntimes(peer: PeerRecord, runtime: string | undefined): Runtime[] {
+  if (runtime) {
+    // Audit #28: an explicit runtime the peer does not declare would act on a PHANTOM
+    // identity — a spurious durable stop-flag or a no-op bootout on a label that isn't
+    // this peer's. Refuse instead of silently targeting a non-existent runtime.
+    if (peer.runtime !== runtime && !peer.runtimes.includes(runtime as Runtime)) {
+      throw new Error(
+        `peer "${peer.personality}" does not declare runtime "${runtime}" (declared: ${peer.runtimes.join(', ')})`,
+      )
+    }
+    return [runtime as Runtime]
+  }
+  return peer.runtimes
+}
+
+/**
+ * stop <peer> [runtime]: warm runtime → durable C1 stop flag + kill the session (the
+ * daemon will not wake it until `start`); always-on (infra, foundation-owned) → launchctl
+ * bootout + kill. REFUSES a foreign-launchd peer (live PP fleet) — fleet guard.
+ */
+export function stopPeer(personality: string, runtime: string | undefined, opts: CliEnvOptions = {}): StopStartOutcome[] {
+  const env = opts.env ?? process.env
+  const cfg = loadLifecycleConfig(env)
+  const peer = findPeer(readPeersIndex({ env }), personality)
+  if (!peer) throw new Error(`peer "${personality}" is not registered`)
+  if (isForeignLaunchd(personality, env)) {
+    return [{ personality, runtime: peer.runtime, action: 'refused-foreign-launchd', reason: `"${personality}" is managed by persistent-peer (foreign launchd plist) — the foundation does not stop it` }]
+  }
+  const out: StopStartOutcome[] = []
+  for (const rt of targetRuntimes(peer, runtime)) {
+    const identity = buildProcessAddress(rt, personality)
+    const sock = buildSocketPath(rt, personality, cfg.sockDir)
+    if (isInfraRuntime(rt)) {
+      // Audit #13: do NOT swallow the launchctl result. (bootout returns non-zero when
+      // the service was already not loaded — benign for stop — but surface the detail in
+      // the reason rather than silently claiming success.)
+      const r = spawnSync('launchctl', ['bootout', `gui/${uid()}/${launchdLabel(personality)}`], { encoding: 'utf8' })
+      killSession(sock, identity)
+      out.push({ personality, runtime: rt, action: 'bootout', reason: r.status === 0 ? undefined : `launchctl bootout exited ${r.status}${(r.stderr ?? '').trim() ? `: ${(r.stderr ?? '').trim()}` : ''}` })
+    } else {
+      setStopped(cfg, identity)
+      killSession(sock, identity)
+      out.push({ personality, runtime: rt, action: 'stopped' })
+    }
+  }
+  return out
+}
+
+/**
+ * start <peer> [runtime]: warm runtime → clear the C1 stop flag (wakeable again on
+ * the next message); always-on → launchctl bootstrap the plist. REFUSES a foreign-
+ * launchd peer (fleet guard).
+ */
+export function startPeer(personality: string, runtime: string | undefined, opts: CliEnvOptions = {}): StopStartOutcome[] {
+  const env = opts.env ?? process.env
+  const cfg = loadLifecycleConfig(env)
+  const peer = findPeer(readPeersIndex({ env }), personality)
+  if (!peer) throw new Error(`peer "${personality}" is not registered`)
+  if (isForeignLaunchd(personality, env)) {
+    return [{ personality, runtime: peer.runtime, action: 'refused-foreign-launchd', reason: `"${personality}" is managed by persistent-peer (foreign launchd plist) — the foundation does not start it` }]
+  }
+  const out: StopStartOutcome[] = []
+  for (const rt of targetRuntimes(peer, runtime)) {
+    const identity = buildProcessAddress(rt, personality)
+    if (isInfraRuntime(rt)) {
+      const plist = launchdPlistPath(personality, env)
+      // Audit #13: a failed bootstrap means the peer did NOT start — surface it instead
+      // of reporting success silently.
+      const r = spawnSync('launchctl', ['bootstrap', `gui/${uid()}`, plist], { encoding: 'utf8' })
+      out.push({ personality, runtime: rt, action: 'bootstrap', reason: r.status === 0 ? undefined : `launchctl bootstrap FAILED (exit ${r.status})${(r.stderr ?? '').trim() ? `: ${(r.stderr ?? '').trim()}` : ''} — peer not started` })
+    } else {
+      clearStopped(cfg, identity)
+      out.push({ personality, runtime: rt, action: 'started' })
+    }
+  }
+  return out
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// send — manual IAP send fallback (contract Примитивы §send). Goes through the
+// same router path as send_to_peer (resolve → deliver / wake), in-process so it
+// works even when the daemon HTTP listener is down. --from sets the sender.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SendOptions extends CliEnvOptions {
+  /** Sender identity `<runtime>-<personality>`; default = the cwd peer's identity. */
+  from: string
+  target: string
+  runtime?: string
+  message: string
+  topic?: string
+  attachments?: string[]
+}
+
+const cliWake: WakeFn = req =>
+  wakeOrSpawn({ personality: req.personality, runtime: req.runtime, topic: req.topic, task: req.task })
+
+export async function sendMessage(opts: SendOptions): Promise<{ ok: true; delivered_to: { personality: string; runtime: string } }> {
+  const env = opts.env ?? process.env
+  const caller = resolveCallerIdentity(parseIdentity(opts.from), readPeersIndex({ env }))
+  const result = await routeSend(
+    caller,
+    {
+      personality: opts.target,
+      runtime: opts.runtime,
+      message: opts.message,
+      topic: opts.topic,
+      attachments: opts.attachments,
+    },
+    { wake: cliWake },
+  )
+  if (!result.ok) throw new Error(result.error.message)
+  return { ok: true, delivered_to: result.value.delivered_to }
+}
+
+function parseIdentity(identity: string): { personality: string; runtime: Runtime } {
+  const dash = identity.indexOf('-')
+  if (dash <= 0) throw new Error(`invalid --from identity "${identity}" — expected <runtime>-<personality>`)
+  const runtime = identity.slice(0, dash)
+  if (!isRuntime(runtime)) throw new Error(`invalid runtime in --from "${identity}"`)
+  return { runtime, personality: identity.slice(dash + 1) }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI dispatch — `iapeer <verb> …`
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function parseArgs(argv: string[]): { positionals: string[]; flags: Record<string, string | true> } {
+  const positionals: string[] = []
+  const flags: Record<string, string | true> = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      // Audit #27: support `--key=value` so a value that itself starts with '--' (e.g.
+      // `send --message=--look-at-this`) is not silently dropped by the look-ahead form.
+      const eq = a.indexOf('=')
+      if (eq > 2) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1)
+        continue
+      }
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith('--')) flags[key] = true
+      else flags[key] = argv[++i]
+    } else {
+      positionals.push(a)
+    }
+  }
+  return { positionals, flags }
+}
+
+const USAGE = `usage: iapeer <verb> [args]
+  install                                                        build binary + global scaffold + daemon plist (one bootstrap)
+  daemon [--install-plist]                                       run the host-wide HTTP-MCP router (launchd-held)
+  onboard [--dry-run] [--infra <csv>]                            register the agfpd marketplace (+ npx-install & deploy infra runtimes)
+  install-runtime <runtime> [--package pkg] [--npx]              npx-install a runtime package + deploy its declared peer-set
+  init [cwd] [--personality p] [--runtime r] [--description d]   onboard the CURRENT folder as a peer (identity + MCP + doctrine)
+  create <personality> [--runtime r] [--path dir] [--bin abs]   create a peer anywhere (default ~/.iapeer/peers/<p>) + provision
+  list [--json]                                                  registered peers + per-runtime liveness
+  stop <peer> [runtime] | --all                                  durable-stop a warm peer / bootout an always-on one
+  start <peer> [runtime]                                         re-enable a stopped peer / bootstrap an always-on one
+  send <target> --message <text> [--from <id>] [--topic <t>]     manual IAP send (fallback)
+  <runtime>                                                      launch the cwd's peer (ALWAYS fresh)
+  enable <plugin> [peer] [--no-setup]                            install + enable an agfpd capability for a peer
+  attach <peer> [runtime]                                        ensure-live + resume, then tmux attach
+  interrupt <peer> [runtime]                                     interrupt the current turn (Escape) — context intact
+  compact <peer> [runtime]                                       compact the peer's context (/compact)
+`
+
+export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  const [verb, ...rest] = argv
+  const { positionals, flags } = parseArgs(rest)
+  const out = (s: string) => process.stdout.write(s)
+  const errOut = (s: string) => process.stderr.write(s)
+
+  try {
+    switch (verb) {
+      case 'onboard': {
+        // Host-phase: register OUR marketplace in claude + codex (IDEMPOTENT — detect
+        // → skip when present; an already-configured host is a no-op). --dry-run
+        // reports the would-be actions without touching anything. --infra <csv> ALSO
+        // onboards infra runtimes (§6): npx-install each package (auto-resolved) + deploy
+        // its declared set. notifier → timer+watcher auto; telegram → operator-add after.
+        const r = onboardHost({ dryRun: flags['dry-run'] === true, env })
+        for (const m of r.marketplaces) {
+          out(`marketplace ${MARKETPLACE_NAME} @ ${m.runtime}: ${m.state}${m.detail ? ` — ${m.detail}` : ''}\n`)
+        }
+        out(r.noop ? 'onboard: no marketplace changes (already configured / dry-run)\n' : 'onboard: marketplace(s) registered\n')
+        let infraFailed = false
+        const infra = typeof flags.infra === 'string' ? flags.infra.split(',').map(s => s.trim()).filter(Boolean) : []
+        if (infra.length && flags['dry-run'] !== true) {
+          const { onboardRuntime } = await import('../runtime/deploy.ts')
+          for (const rt of infra) {
+            try {
+              const or = await onboardRuntime({ runtime: rt as Runtime, env, warn: m => errOut(`warn: ${m}\n`) })
+              out(`infra ${rt}: package ${or.install.package ?? '(none)'} ${or.install.state}; ` +
+                (or.deploy!.operatorAddOnly ? `operator-add (use \`iapeer create <peer> --runtime ${rt}\`)` : `${or.deploy!.peers.length} peer(s) deployed`) + '\n')
+              if (or.deploy!.peers.some(p => p.bootstrap === 'failed' || p.selfConfig === 'failed')) infraFailed = true
+            } catch (e) {
+              infraFailed = true
+              errOut(`infra ${rt}: ${e instanceof Error ? e.message : String(e)}\n`)
+            }
+          }
+        } else if (infra.length) {
+          out(`onboard --dry-run: would onboard infra runtimes: ${infra.join(', ')}\n`)
+        }
+        return r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
+      }
+      case 'install-runtime': {
+        // §6 onboard a runtime END-TO-END: npx-install the package (auto-resolved from
+        // the built-in runtime→package registry, or --package; self-deploys bin +
+        // manifest), THEN deploy its declared peer-set (each → provision + per-peer
+        // self-config + auto-bootstrap). A runtime whose manifest declares no peers
+        // (telegram) is operator-add — use `iapeer create <human> --runtime telegram`.
+        if (!positionals[0]) return usage(errOut)
+        const { onboardRuntime } = await import('../runtime/deploy.ts')
+        const r = await onboardRuntime({
+          runtime: positionals[0] as Runtime,
+          package: typeof flags.package === 'string' ? flags.package : undefined,
+          npx: flags.npx === true,
+          bootstrap: flags['no-bootstrap'] === true ? false : undefined,
+          env,
+          warn: m => errOut(`warn: ${m}\n`),
+        })
+        out(`package ${r.install.package ?? '(none)'}: ${r.install.state}${r.install.detail ? ` — ${r.install.detail}` : ''}\n`)
+        const d = r.deploy!
+        if (d.operatorAddOnly) {
+          out(`runtime "${d.runtime}": no declared peer-set (operator-add — use \`iapeer create <peer> --runtime ${d.runtime}\`)\n`)
+          return 0
+        }
+        for (const p of d.peers) {
+          out(`  ${p.personality} @ ${p.location}: self-config ${p.selfConfig ?? 'n/a'}; bootstrap ${p.bootstrap ?? 'n/a'}\n`)
+        }
+        out(`deployed runtime "${d.runtime}" (${d.peers.length} peer(s))\n`)
+        return d.peers.some(p => p.bootstrap === 'failed' || p.selfConfig === 'failed') ? 1 : 0
+      }
+      case 'init': {
+        // cwd-DEPENDENT: onboard the CURRENT folder (or positional cwd) as a peer —
+        // identity + MCP wiring + doctrine, runtime resolved from the cwd's markers
+        // when not explicit. Auto-bootstraps an infra plist unless --no-bootstrap.
+        const { initPeer } = await import('../init/index.ts')
+        const r = await initPeer({
+          cwd: positionals[0] ?? process.cwd(),
+          runtime: typeof flags.runtime === 'string' ? (flags.runtime as Runtime) : undefined,
+          personality: typeof flags.personality === 'string' ? flags.personality : undefined,
+          description: typeof flags.description === 'string' ? flags.description : undefined,
+          runtimeBin: typeof flags.bin === 'string' ? flags.bin : undefined,
+          bootstrap: flags['no-bootstrap'] === true ? false : undefined,
+          env,
+          warn: m => errOut(`warn: ${m}\n`),
+        })
+        out(
+          `initialized "${r.personality}" (${r.runtime}); mcp: ${r.mcpConfigPaths.join(', ') || r.codexMcpConfigPath || 'none'}` +
+            `${r.bootstrapped ? `; bootstrap: ${r.bootstrapped.state}` : ''}\n`,
+        )
+        return 0
+      }
+      case 'create': {
+        // cwd-INDEPENDENT: resolve a location (default ~/.iapeer/peers/<p> or --path),
+        // scaffold the folder (no-clobber), then init it. Operator-add for an infra
+        // human (telegram) or any agentic peer; provisions + auto-bootstraps infra.
+        if (!positionals[0]) return usage(errOut)
+        const { createPeer } = await import('../create/index.ts')
+        const r = await createPeer({
+          personality: positionals[0],
+          runtime: typeof flags.runtime === 'string' ? (flags.runtime as Runtime) : undefined,
+          path: typeof flags.path === 'string' ? flags.path : undefined,
+          description: typeof flags.description === 'string' ? flags.description : undefined,
+          intelligence: typeof flags.intelligence === 'string' ? (flags.intelligence as Intelligence) : undefined,
+          runtimeBin: typeof flags.bin === 'string' ? flags.bin : undefined,
+          bootstrap: flags['no-bootstrap'] === true ? false : undefined,
+          env,
+          warn: m => errOut(`warn: ${m}\n`),
+        })
+        out(
+          `created "${r.personality}" (${r.runtime}) at ${r.location}; mcp: ${r.mcpConfigPaths.join(', ') || r.codexMcpConfigPath || 'none'}` +
+            `${r.plistPath ? `; plist: ${r.plistPath}` : ''}${r.bootstrapped ? `; bootstrap: ${r.bootstrapped.state}` : ''}\n`,
+        )
+        return r.bootstrapped && (r.bootstrapped.state === 'failed' || r.bootstrapped.state === 'refused-foreign') ? 1 : 0
+      }
+      case 'list': {
+        // tty + no --json → the interactive control-panel (↑/↓ · Enter=attach · / · q);
+        // non-tty / --json → the scriptable table (machine-parsable).
+        if (flags.json !== true && process.stdout.isTTY && process.stdin.isTTY) {
+          const { runListTui } = await import('./listTui.ts')
+          return await runListTui(env)
+        }
+        const rows = listPeers({ env })
+        out(flags.json ? JSON.stringify(rows, null, 2) + '\n' : formatListTable(rows))
+        return 0
+      }
+      case 'stop': {
+        // --all stops every registered peer (the fleet guard still refuses foreign
+        // persistent-peer plists, so the live fleet stays untouched).
+        const peers = flags.all === true
+          ? readPeersIndex({ env }).peers.map(p => p.personality)
+          : positionals[0]
+            ? [positionals[0]]
+            : null
+        if (!peers) return usage(errOut)
+        const outcomes = peers.flatMap(p => stopPeer(p, flags.all === true ? undefined : positionals[1], { env }))
+        for (const o of outcomes) out(`${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
+        return outcomes.some(o => o.action === 'refused-foreign-launchd') ? 1 : 0
+      }
+      case 'start': {
+        if (!positionals[0]) return usage(errOut)
+        const outcomes = startPeer(positionals[0], positionals[1], { env })
+        for (const o of outcomes) out(`${o.personality} (${o.runtime}): ${o.action}${o.reason ? ` — ${o.reason}` : ''}\n`)
+        return outcomes.some(o => o.action === 'refused-foreign-launchd') ? 1 : 0
+      }
+      case 'send': {
+        if (!positionals[0] || typeof flags.message !== 'string') return usage(errOut)
+        const r = await sendMessage({
+          target: positionals[0],
+          from: typeof flags.from === 'string' ? flags.from : defaultFromIdentity(env),
+          message: flags.message,
+          runtime: typeof flags.runtime === 'string' ? flags.runtime : undefined,
+          topic: typeof flags.topic === 'string' ? flags.topic : undefined,
+          env,
+        })
+        out(`delivered to ${r.delivered_to.personality} (${r.delivered_to.runtime})\n`)
+        return 0
+      }
+      case 'install': {
+        // UNIFIED foundation install (contract Установка §1 — "один npx ставит
+        // фундамент"): ONE command does all three install-phase steps that used to be
+        // split across `install` + `daemon --install-plist`:
+        //   (1) global scaffold ~/.iapeer/ (+ peers/, state/logs/cache, runtime scopes)
+        //   (2) build + place the stable ~/.local/bin/iapeer binary (atomic)
+        //   (3) WRITE the daemon's com.agfpd.iapeer plist (NOT bootstrapped — a live
+        //       daemon already runs; migrating it onto the installed binary is a
+        //       separate coordinated wave, contract Установка §1).
+        // Bootstrap path — run from the src tree (`bun src/cli/index.ts install`) or
+        // npx; the compiled binary cannot rebuild itself from source (its
+        // import.meta.url is the binary → build fails with a clear error).
+        const { installIapeer } = await import('../install/index.ts')
+        ensureGlobalIapScaffold({ env })
+        const r = installIapeer(fileURLToPath(import.meta.url), env)
+        const plist = installDaemonPlist({ env })
+        out(
+          `installed iapeer → ${r.binPath}` +
+            `${r.prevPath ? ` (previous kept: ${r.prevPath})` : ''}` +
+            `${r.size ? ` (${Math.round(r.size / 1e6)}M)` : ''}\n` +
+            `  scaffold: ~/.iapeer/ ensured (peers/, state, logs, cache, runtimes)\n` +
+            `  daemon plist written: ${plist}\n` +
+            `  (NOT loaded — a live daemon migration is a separate step: launchctl bootstrap gui/$(id -u) ${plist})\n`,
+        )
+        return 0
+      }
+      case 'daemon': {
+        // Ф-F: the prod daemon entrypoint. The launchd plist runs `iapeer daemon`
+        // (the INSTALLED binary), decoupling prod from the mutable src tree.
+        if (flags['install-plist'] === true) {
+          const p = installDaemonPlist({ env })
+          out(`installed daemon plist: ${p}\nNOT loaded — to start: launchctl bootstrap gui/$(id -u) ${p}\n`)
+          return 0
+        }
+        const handle = await startConfiguredDaemon({
+          port: env.IAPEER_PORT?.trim() ? Number(env.IAPEER_PORT) : undefined,
+          socketPath: env.IAPEER_DAEMON_SOCKET?.trim() || undefined,
+          env,
+        })
+        errOut(`[iapeer] daemon READY tcp=${handle.url} sock=${handle.socketPath}\n`)
+        const shutdown = () => void handle.close().then(() => process.exit(0))
+        process.on('SIGTERM', shutdown)
+        process.on('SIGINT', shutdown)
+        await new Promise(() => {}) // launchd KeepAlive holds this process; block forever
+        return 0
+      }
+      case 'run-infra': {
+        // Ф-F: the always-on infra entrypoint (telegram/notifier), held by launchd.
+        // The infra plist runs `iapeer run-infra <personality> <runtime>` (installed
+        // binary) instead of `bun launchdRun.ts`. cwd = the launchd WorkingDirectory.
+        if (!positionals[0] || !positionals[1]) return usage(errOut)
+        return await runAlwaysOn(positionals[0], positionals[1], process.cwd())
+      }
+      case 'interrupt':
+      case 'compact': {
+        // In-session control (Ф-E, clean-slash namespace): interrupt a stuck/raving
+        // turn (Escape) / compact context. UNCONDITIONAL — acts on the live session.
+        if (!positionals[0]) return usage(errOut)
+        const r = routeControl(positionals[0], positionals[1], { name: verb })
+        if (!r.ok) {
+          errOut(`${verb}: ${r.error.message}\n`)
+          return 1
+        }
+        out(`${verb} → ${r.value.controlled.personality} (${r.value.controlled.runtime})\n`)
+        return 0
+      }
+      case 'enable': {
+        // Per-peer capability install (contract Установка §3): install <plugin>@agfpd
+        // per-runtime (claude project-scope IN the peer cwd / codex global) + enable +
+        // call the plugin's `setup` ONLY if its iapeer.json declares it. Idempotent and
+        // fleet-safe — claude is keyed by the peer's projectPath. `enable <plugin> [peer]`.
+        if (!positionals[0]) return usage(errOut)
+        const { enableCapability } = await import('../enable/index.ts')
+        const r = enableCapability({
+          plugin: positionals[0],
+          peer: positionals[1],
+          noSetup: flags['no-setup'] === true,
+          env,
+        })
+        for (const rt of r.runtimes) {
+          out(`  ${rt.runtime}: ${rt.state}${rt.detail ? ` — ${rt.detail}` : ''}\n`)
+        }
+        out(`enable ${r.plugin} @ ${r.personality}: setup ${r.setup}${r.setupDetail ? ` — ${r.setupDetail}` : ''}\n`)
+        return r.runtimes.some(rt => rt.state === 'failed') || r.setup === 'failed' ? 1 : 0
+      }
+      case 'attach': {
+        if (!positionals[0]) return usage(errOut)
+        const r = await attachPeer({ personality: positionals[0], runtime: positionals[1], env })
+        if (!r.ok) {
+          errOut(`attach: ${r.reason}\n`)
+          return 1
+        }
+        out(`${r.woke ? 'woke + ' : ''}attaching ${r.identity}…\n`)
+        // Drop the operator into the session. `env -u TMUX` so a nested attach from
+        // inside tmux does not error ("sessions should be nested with care").
+        const attachEnv = { ...env }
+        delete attachEnv.TMUX
+        const a = spawnSync('tmux', ['-S', r.socketPath, 'attach', '-t', r.identity], {
+          stdio: 'inherit',
+          env: attachEnv as Record<string, string>,
+        })
+        return a.status ?? 0
+      }
+      default: {
+        // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh.
+        if (verb && isRuntime(verb)) {
+          const r = await folderLaunch({ cwd: process.cwd(), runtime: verb, env })
+          if (r.status === 'FAILED') {
+            errOut(`launch: ${r.reason}\n`)
+            return 1
+          }
+          out(`launched ${r.process_address} (fresh)\n`)
+          return 0
+        }
+        return usage(errOut)
+      }
+    }
+  } catch (e) {
+    errOut(`iapeer ${verb ?? ''}: ${e instanceof Error ? e.message : String(e)}\n`)
+    return 1
+  }
+}
+
+function usage(errOut: (s: string) => void): number {
+  errOut(USAGE)
+  return 2
+}
+
+/** Default --from for `send`: the identity of the peer in the current cwd (contract:
+ *  "по умолчанию — identity пира текущей папки"). Requires running from a peer cwd. */
+function defaultFromIdentity(env: NodeJS.ProcessEnv): string {
+  return resolveIdentity({ env }).address
+}
+
+if (import.meta.main) {
+  runCli(process.argv.slice(2)).then(code => process.exit(code))
+}