@agfpd/iapeer 0.2.78 → 0.2.80

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Artur Agafapudov
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.78",
+  "version": "0.2.80",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -61,7 +61,7 @@ import {
   validateProfileStandard,
 } from '../identity/profileStandard.ts'
 import { runAlwaysOn } from '../launch/launchdRun.ts'
-import { installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
+import { ensureDaemonStarted, installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
 import { MARKETPLACE_NAME, onboardHost } from '../onboard/index.ts'
 import { readMemoryProvider } from '../status/index.ts'
 import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
@@ -925,7 +925,7 @@ const USAGE = `usage: iapeer <verb> [args]
                                                                  it up on the peer's first message); always-on: launchctl bootstrap. --all = every registered peer
   remove <peer> [--force]                                        delete a peer's registry record (locked writer); refuses a LIVE peer unless --force
   send <target> (--message <text> | --message-file <f|->) [--from <id>] [--attachment <p>]… [--topic <t>]   manual IAP send (fallback)
-  <runtime>                                                      launch the cwd's peer (ALWAYS fresh)
+  <runtime>                                                      launch the cwd's peer FRESH; on a TTY drop into it (like attach), else detached
   connect telegram <peer> [--token <t>]                          attach a telegram bot to a peer (bot add → interface → router restart; asks only the token)
   enable <plugin> [peer] [--no-setup]                            install + enable an agfpd capability for a peer
   new <peer> [runtime]                                           UNCONDITIONAL fresh restart: canary-clean kill + fresh wake (emergency lever for a hung/dead session — bypasses the peer; exit 0 = fresh session up+ready)
@@ -969,6 +969,14 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // 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.
+        // STEP 0 (non-disableable): ensure the router daemon is up. Onboard is the
+        // explicit "set up the host" action, so starting the always-on daemon belongs
+        // here — the operator never types raw `launchctl bootstrap`. Idempotent (no-op
+        // if already loaded). A failure here is a real, host-breaking problem → exit 1.
+        const dstart = await ensureDaemonStarted({ dryRun: flags['dry-run'] === true, env })
+        const dLabel = dstart.state === 'would-start' ? 'would-start (dry-run)' : dstart.state
+        out(`daemon: ${dLabel}${dstart.healthy === false ? ' — UNHEALTHY' : ''}${dstart.detail ? ` — ${dstart.detail}` : ''}\n`)
+        const daemonFailed = dstart.state === 'failed' || dstart.healthy === false
         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`)
@@ -1038,7 +1046,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         })
         const memLabel = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
         out(`memory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${memLabel})\n`)
-        return r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
+        return daemonFailed || r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
       }
       case 'native-memory': {
         // The canonized runtime-memory lever (контракт «Слот памяти» §Native-память):
@@ -1735,36 +1743,8 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           return 1
         }
         out(`${r.woke ? 'woke + ' : ''}attaching ${r.identity}…\n`)
-        // Attach-window observability (whether a death happened under attach was
-        // answerable only INDIRECTLY via wake cause=attach — i.e. only when the
-        // session was dead at attach time). Bracket the operator's client
-        // window in lifecycle.log: ev=attach at entry, ev=attach-end (with the tmux
-        // client's exit code) when the operator detaches or the server dies under
-        // the client. A death timestamp inside an attach…attach-end window now
-        // reads directly off the log.
         const attachCfg = loadLifecycleConfig(env)
-        appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach', identity: r.identity, woke: String(r.woke) }, { env })
-        // SPAWN-FLIP Ф0b-3: a supervisor-HOSTED session has no tmux to attach — hand the operator to
-        // the supervisor client (runSupervisorClient: raw passthrough + repaint-on-attach + Ctrl-]
-        // detach + both reattach port-deps). It calls process.exit on every terminal path, so bracket
-        // attach-end via an exit hook (appendFileSync is signal/exit-safe). Flag-off → tmux attach.
-        if (hostSessionAlive(r.identity)) {
-          process.on('exit', () =>
-            appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach-end', identity: r.identity, rc: process.exitCode ?? 0 }, { env }),
-          )
-          await runSupervisorClient(hostRunDir(), r.identity)
-          return 0 // unreachable — runSupervisorClient exits on detach / session end
-        }
-        // 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>,
-        })
-        appendLifecycleEvent(attachCfg.eventLogDir, { ev: 'attach-end', identity: r.identity, rc: a.status ?? -1 }, { env })
-        return a.status ?? 0
+        return await attachIntoSession(r.identity, r.socketPath, env, attachCfg.eventLogDir, r.woke)
       }
       case 'shadow': {
         // Read-only fidelity OBSERVER for the tmux→pty migration burn-in (track «b»). Compares
@@ -1823,14 +1803,25 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return await runSupervisorCli(rest)
       }
       default: {
-        // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh.
+        // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh. On a TTY this is
+        // the human "start a fresh session and work in it" verb (parallel to `attach`, which resumes):
+        // after a successful fresh bring-up it drops the operator straight into the new session.
+        // Non-TTY (scripted / piped) keeps the fire-and-forget behavior — report the launch and exit.
         if (verb && isRuntime(verb)) {
-          const r = await folderLaunch({ cwd: process.cwd(), runtime: verb, env })
+          const cfg = loadLifecycleConfig(env)
+          const id = resolveIdentity({ env })
+          const r = await folderLaunch({ cwd: process.cwd(), runtime: verb, env, cfg })
           if (r.status === 'FAILED') {
             errOut(`launch: ${r.reason}\n`)
             return 1
           }
-          out(`launched ${r.process_address} (fresh)\n`)
+          const identity = r.process_address ?? buildProcessAddress(verb, id.personality)
+          if (process.stdin.isTTY && process.stdout.isTTY) {
+            const socketPath = buildSocketPath(verb, id.personality, cfg.sockDir)
+            out(`launched ${identity} (fresh) — attaching…\n`)
+            return await attachIntoSession(identity, socketPath, env, cfg.eventLogDir, true)
+          }
+          out(`launched ${identity} (fresh)\n`)
           return 0
         }
         return usage(errOut)
@@ -1853,6 +1844,41 @@ function defaultFromIdentity(env: NodeJS.ProcessEnv): string {
   return resolveIdentity({ env }).address
 }
 
+/** Drop the operator into a live peer session — the interactive open shared by `attach` (resume)
+ *  and a TTY `iapeer <runtime>` (fresh launch). A supervisor-HOSTED session has no tmux to attach,
+ *  so the operator is handed to the supervisor client (raw passthrough + repaint-on-attach + Ctrl-]
+ *  detach); otherwise `tmux attach`. The operator window is bracketed in lifecycle.log
+ *  (ev=attach … ev=attach-end) so a death timestamp inside the window reads directly off the log.
+ *  Returns the client exit code. */
+async function attachIntoSession(
+  identity: string,
+  socketPath: string,
+  env: NodeJS.ProcessEnv,
+  eventLogDir: string,
+  woke: boolean,
+): Promise<number> {
+  appendLifecycleEvent(eventLogDir, { ev: 'attach', identity, woke: String(woke) }, { env })
+  if (hostSessionAlive(identity)) {
+    // runSupervisorClient calls process.exit on every terminal path → bracket attach-end via an
+    // exit hook (appendFileSync is signal/exit-safe).
+    process.on('exit', () =>
+      appendLifecycleEvent(eventLogDir, { ev: 'attach-end', identity, rc: process.exitCode ?? 0 }, { env }),
+    )
+    await runSupervisorClient(hostRunDir(), identity)
+    return 0 // unreachable — runSupervisorClient exits on detach / session end
+  }
+  // `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', socketPath, 'attach', '-t', identity], {
+    stdio: 'inherit',
+    env: attachEnv as Record<string, string>,
+  })
+  appendLifecycleEvent(eventLogDir, { ev: 'attach-end', identity, rc: a.status ?? -1 }, { env })
+  return a.status ?? 0
+}
+
 if (import.meta.main) {
   runCli(process.argv.slice(2)).then(code => process.exit(code))
 }

package/src/daemon/main.ts

@@ -23,11 +23,13 @@ import { DAEMON_PLIST_LABEL } from '../core/constants.ts'
 import { IapError } from '../core/errors.ts'
 import { pluginLogsDir } from '../storage/index.ts'
 import {
+  bootstrapDaemon,
   isFoundationOwnedPlist,
   launchAgentsDir,
   renderLaunchdPlist,
 } from '../launch/launchd.ts'
-import type { LaunchdPlistSpec } from '../launch/launchd.ts'
+import type { BootstrapState, LaunchdPlistSpec } from '../launch/launchd.ts'
+import { waitForDaemonHealthy } from '../update/index.ts'
 import {
   drainAllEphemeralQueues,
   drainEphemeralQueue,
@@ -450,6 +452,40 @@ export function installDaemonPlist(opts: InstallDaemonPlistOptions = {}): Instal
   return { path, changed: true }
 }
 
+export interface DaemonStartResult {
+  /** 'would-start' = dryRun report; otherwise the bootstrap outcome. */
+  state: BootstrapState | 'would-start'
+  /** Socket health after a (non-sandbox) bootstrap; undefined when not probed. */
+  healthy?: boolean
+  detail?: string
+}
+
+/**
+ * `iapeer onboard`'s first, non-disableable step: ensure the foundation daemon is up.
+ * Writes the plist if missing (idempotent write-if-changed — defensive when onboard
+ * runs on a host where the plist is absent), idempotently bootstraps it (no-op when
+ * already loaded — NOT a restart), then health-checks the socket. dryRun reports the
+ * intent without touching launchctl. Sandbox-safe: bootstrapDaemon + waitForDaemonHealthy
+ * both short-circuit under IAPEER_TEST_SANDBOX, so this never loads a real job in tests.
+ */
+export async function ensureDaemonStarted(
+  opts: { env?: NodeJS.ProcessEnv; dryRun?: boolean } = {},
+): Promise<DaemonStartResult> {
+  const env = opts.env ?? process.env
+  if (opts.dryRun) {
+    return {
+      state: 'would-start',
+      detail: 'install plist if missing + launchctl bootstrap com.agfpd.iapeer (idempotent) + health-check',
+    }
+  }
+  installDaemonPlist({ env })
+  const b = bootstrapDaemon(env)
+  if (b.state === 'failed') return { state: 'failed', detail: b.detail }
+  if (b.state === 'skipped-sandbox') return { state: 'skipped-sandbox', detail: b.detail }
+  const h = await waitForDaemonHealthy({ env })
+  return { state: b.state, healthy: h.healthy, detail: h.healthy ? undefined : h.detail }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // CLI — launchd-held process / foreground acceptance entrypoint
 // ─────────────────────────────────────────────────────────────────────────────
@@ -463,7 +499,7 @@ if (import.meta.main) {
     const { path: p, changed } = installDaemonPlist()
     process.stdout.write(
       `daemon plist ${changed ? 'written' : 'unchanged'}: ${p}\n` +
-        `NOT loaded. To start it live: launchctl bootstrap gui/$(id -u) ${p}\n`,
+        `NOT loaded. \`iapeer onboard\` starts it (idempotent); or manually: launchctl bootstrap gui/$(id -u) ${p}\n`,
     )
     process.exit(0)
   } else {

package/src/launch/launchd.ts

@@ -382,6 +382,33 @@ export function cycleDaemon(env: NodeJS.ProcessEnv = process.env): DaemonRestart
   return cycleLaunchdJob(DAEMON_PLIST_LABEL, join(launchAgentsDir(env), `${DAEMON_PLIST_LABEL}.plist`), env)
 }
 
+/**
+ * Ensure the foundation daemon (`com.agfpd.iapeer`) is LOADED in the gui domain — an
+ * IDEMPOTENT `launchctl bootstrap` (no-op when already loaded), NOT a restart. This is
+ * the "start it now" step `iapeer onboard` runs, so an operator never types raw
+ * launchctl. Composed on bootstrapJobCore (undead-job-safe wait-for-gone + backoff).
+ * SANDBOX FAIL-SAFE: under IAPEER_TEST_SANDBOX it never calls launchctl (`bootstrap
+ * gui/<uid>` is host-global regardless of IAPEER_ROOT), consulting BOTH the passed env
+ * and the process env — mirror of launchctlBootstrap's guard.
+ */
+export function bootstrapDaemon(env: NodeJS.ProcessEnv = process.env): BootstrapResult {
+  if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') {
+    return { state: 'skipped-sandbox', label: DAEMON_PLIST_LABEL, detail: 'IAPEER_TEST_SANDBOX=1 — not loading a real launchd job' }
+  }
+  const uid = currentUid()
+  const plistPath = join(launchAgentsDir(env), `${DAEMON_PLIST_LABEL}.plist`)
+  const core = bootstrapJobCore(uid, DAEMON_PLIST_LABEL, plistPath, {
+    run: args => {
+      const r = spawnSync('launchctl', args, { encoding: 'utf8' })
+      return { status: r.status, stderr: r.stderr ?? '' }
+    },
+    sleepMs: ms => spawnSync('sleep', [String(ms / 1000)]),
+  })
+  return core.state === 'failed'
+    ? { state: 'failed', label: DAEMON_PLIST_LABEL, detail: core.detail }
+    : { state: core.state, label: DAEMON_PLIST_LABEL }
+}
+
 /**
  * Restart any launchd job onto the executable(s) currently referenced by its plist:
  * bootout → bootstrap, never kickstart. Used by the daemon update path AND by

package/src/supervisor/daemon.ts

@@ -1,12 +1,13 @@
 // Supervisor DAEMON — holds the pty + child + headless-xterm model + capability responder
-// independent of any terminal; clients attach/detach over a unix socket (cutover Block 2, ported
-// from the validated PoC pts.mjs). DARK: reachable only via the `supervisor` CLI verb (dynamic
-// import), so @xterm never loads in the delivery hot path. NOT wired into launch/lifecycle — it
-// serves NOTHING on the live fleet yet; it is validated on throwaway sessions only.
+// independent of any terminal; clients attach/detach over a unix socket. It HOSTS tui/router peers
+// by default (the pty-host launch path; opt-out per-peer via a `.no-pty-host` marker), and is also
+// reachable manually via the `supervisor` CLI verb for throwaway validation. It runs in its OWN
+// detached process, dynamic-imported from the launch path (supervisor/index.ts → daemon.ts), so
+// @xterm never loads in the central router's delivery path nor in the launch/lifecycle process.
 //
 // Loads @xterm/headless + @xterm/addon-serialize (the latter is the repaint source: a reattaching
 // client gets the full current screen even if the child is silent). Both bundle under
-// `bun build --compile` (pure JS; the Bun-native pty has no native addon — PoC-proven).
+// `bun build --compile` (pure JS; the Bun-native pty has no native addon).
 import { Terminal } from '@xterm/headless'
 import { SerializeAddon } from '@xterm/addon-serialize'
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'