@agfpd/iapeer 0.2.13 → 0.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/cli/cli.test.ts

@@ -7,7 +7,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 import { mkdtempSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
-import { formatListTable, listPeers, parseArgs, removePeerCli, sendMessage, startPeer, stopPeer } from './index.ts'
+import { formatListTable, listPeers, parseArgs, removePeerCli, runCli, sendMessage, startPeer, stopPeer } from './index.ts'
 import { findPeer, readPeersIndex, upsertPeer } from '../registry/index.ts'
 import { isStopped, loadLifecycleConfig, setStopped } from '../lifecycle/index.ts'
 import { launchdPlistPath } from '../launch/launchd.ts'
@@ -132,6 +132,69 @@ describe('send validation', () => {
   })
 })
 
+describe('--help/-h global intercept (CLI hygiene — usage printed, NOTHING executed)', () => {
+  let captured: string
+  let origWrite: typeof process.stdout.write
+  beforeEach(() => {
+    captured = ''
+    origWrite = process.stdout.write
+    process.stdout.write = ((s: string | Uint8Array) => {
+      captured += typeof s === 'string' ? s : Buffer.from(s).toString('utf8')
+      return true
+    }) as typeof process.stdout.write
+  })
+  afterEach(() => {
+    process.stdout.write = origWrite
+  })
+
+  test('every verb with --help prints usage to stdout and exits 0', async () => {
+    // The full verb surface — including verbs with REAL side effects (onboard ran on
+    // prod swallowing --help; stop would set a durable flag; remove would delete).
+    const verbs = [
+      'onboard', 'install', 'update', 'rollback', 'version', 'daemon', 'status',
+      'install-runtime', 'init', 'create', 'list', 'stop', 'start', 'remove', 'send',
+      'enable', 'attach', 'interrupt', 'compact', 'self-fresh', 'native-memory', 'run-infra',
+    ]
+    for (const v of verbs) {
+      captured = ''
+      const code = await runCli([v, '--help'], env())
+      expect({ verb: v, code }).toEqual({ verb: v, code: 0 })
+      expect(captured).toContain('usage: iapeer')
+    }
+  })
+  test('-h works like --help, anywhere on the line', async () => {
+    expect(await runCli(['stop', 'somebody', '-h'], env())).toBe(0)
+    expect(captured).toContain('usage: iapeer')
+  })
+  test('bare `iapeer --help` / `-h` / `help` print usage', async () => {
+    for (const a of [['--help'], ['-h'], ['help']]) {
+      captured = ''
+      expect(await runCli(a, env())).toBe(0)
+      expect(captured).toContain('usage: iapeer')
+    }
+  })
+  test('--help does NOT execute the verb: `stop <peer> --help` leaves no durable stop flag', async () => {
+    await register('helpcheck')
+    const e = env()
+    expect(await runCli(['stop', 'helpcheck', '--help'], e)).toBe(0)
+    expect(isStopped(loadLifecycleConfig(e), 'claude-helpcheck')).toBe(false)
+  })
+  test('--help does NOT execute the verb: `remove <peer> --help` keeps the registry record', async () => {
+    await register('keepme')
+    const e = env()
+    expect(await runCli(['remove', 'keepme', '--help'], e)).toBe(0)
+    expect(findPeer(readPeersIndex({ env: e }), 'keepme')).not.toBeNull()
+  })
+  test('version --help shows usage, not the version number', async () => {
+    expect(await runCli(['version', '--help'], env())).toBe(0)
+    expect(captured).toContain('usage: iapeer')
+    expect(captured.trim().split('\n').length).toBeGreaterThan(3) // usage, not a bare semver line
+  })
+  test('a literal "--help" value stays expressible via --key=--help (not intercepted)', () => {
+    expect(parseArgs(['boris', '--message=--help']).flags.message).toBe('--help')
+  })
+})
+
 describe('parseArgs (audit #27 — value beginning with --)', () => {
   test('--key=value preserves a value that starts with --', () => {
     expect(parseArgs(['send', 'boris', '--message=--look', '--topic=re: x']).flags).toMatchObject({

package/src/cli/index.ts

@@ -60,6 +60,11 @@ export interface PeerListing {
   last_active_runtime?: Runtime
   intelligence: Intelligence
   description: string
+  /** The peer's working directory (registry fact). Machine-readable so host-local
+   *  tooling (e.g. the memory provider's init/verify rendering doctrine into
+   *  <cwd>/.iapeer/) keys on the REGISTRY instead of copying the layout default —
+   *  a layout change must not silently strand consumers (iapeer-memory ask, 10.06). */
+  cwd: string
   runtimes: RuntimeStatus[]
 }
 
@@ -104,6 +109,7 @@ export function listPeers(opts: CliEnvOptions = {}): PeerListing[] {
       last_active_runtime: lastActive,
       intelligence: peer.intelligence,
       description: peer.description,
+      cwd: peer.cwd,
       runtimes,
     }
   })
@@ -351,8 +357,10 @@ const USAGE = `usage: iapeer <verb> [args]
   update [version] [--force]                                     pull latest (or an exact version) of @agfpd/iapeer from npm + restart the daemon
   rollback                                                       revert to the previous binary (.prev) + restart the daemon
   version | --version | -v                                       print the installed binary's version
+  help | --help | -h                                             print this usage (works appended to any verb; executes nothing)
   daemon [--install-plist]                                       run the host-wide HTTP-MCP router (launchd-held)
-  onboard [--dry-run] [--infra <csv>] [--no-memory] [--memory <pkg>]   register the agfpd marketplace (+ infra runtimes; + default memory provider, default YES)
+  onboard [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--infra <csv>]
+                                                                 backbone host-phase: marketplace → notifier → telegram (human peer) → memory (all default YES)
   status                                                         host snapshot: version, daemon health, memory slot (<provider> | none)
   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)
@@ -373,6 +381,17 @@ const USAGE = `usage: iapeer <verb> [args]
 
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
   const [verb, ...rest] = argv
+  // CLI hygiene (design «Onboard костяка» §CLI-гигиена): an explicit help request —
+  // `--help`/`-h` ANYWHERE on the line, or the bare `help` verb — prints usage and
+  // executes NOTHING. Checked on the RAW argv BEFORE the switch: parseArgs would
+  // bury `--help` in flags no case reads (a cold-start `onboard --help` EXECUTED on
+  // prod — idempotency saved it), and `-h` would land in positionals. Token-exact
+  // match is safe: the look-ahead parser never consumes a `--`-token as a value, so
+  // a LITERAL "--help" value is only expressible as `--key=--help` (not intercepted).
+  if (verb === 'help' || argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(USAGE)
+    return 0
+  }
   const { positionals, flags } = parseArgs(rest)
   const out = (s: string) => process.stdout.write(s)
   const errOut = (s: string) => process.stderr.write(s)
@@ -392,6 +411,39 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         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) : []
+        // Backbone default-yes steps (design «Onboard костяка», FINAL 10.06). ORDER is
+        // significant: notifier → TELEGRAM (creates the human peer) → memory below
+        // (its --human resolves from the natural peer that just appeared). Each step
+        // is soft-skip on unavailability; only a REAL deploy/create break fails.
+        const { onboardNotifierStep, onboardTelegramStep } = await import('./../onboard/steps.ts')
+        // An explicit `--infra notifier` takes the fail-closed explicit path below —
+        // the default-yes (soft-skip) step then stands aside to avoid double-deploy.
+        const ns = await onboardNotifierStep({
+          skip: flags['no-notifier'] === true || infra.includes('notifier'),
+          dryRun: flags['dry-run'] === true,
+          env,
+          warn: m => errOut(`warn: ${m}\n`),
+        })
+        if (ns.state !== 'skipped-flag') {
+          const peersLine = ns.peers.length ? ` — ${ns.peers.map(p => `${p.personality} (bootstrap ${p.bootstrap ?? 'n/a'})`).join(', ')}` : ''
+          out(`notifier: ${ns.state}${ns.detail ? ` — ${ns.detail}` : ''}${peersLine}\n`)
+          if (ns.state === 'deploy-failed') infraFailed = true
+        }
+        const ts = await onboardTelegramStep({
+          skip: flags['no-telegram'] === true,
+          human: typeof flags['telegram-human'] === 'string' ? flags['telegram-human'] : undefined,
+          userId: typeof flags['telegram-user-id'] === 'string' ? flags['telegram-user-id'] : undefined,
+          dryRun: flags['dry-run'] === true,
+          env,
+          warn: m => errOut(`warn: ${m}\n`),
+        })
+        if (ts.state !== 'skipped-flag') {
+          const line = `telegram: ${ts.state}${ts.personality ? ` — ${ts.personality}` : ''}${ts.detail ? ` — ${ts.detail}` : ''}\n`
+          // a refusal/failure goes to stderr (loud), the rest to stdout
+          if (ts.state === 'refused-non-tty' || ts.state === 'invalid-input' || ts.state === 'create-failed') errOut(line)
+          else out(line)
+          if (ts.state === 'invalid-input' || ts.state === 'create-failed') infraFailed = true
+        }
         if (infra.length && flags['dry-run'] !== true) {
           const { onboardRuntime } = await import('../runtime/deploy.ts')
           for (const rt of infra) {

package/src/cli/listTui.test.ts

@@ -10,6 +10,7 @@ function row(over: Partial<PeerListing>): PeerListing {
     default_runtime: 'claude',
     intelligence: 'artificial',
     description: '',
+    cwd: '/tmp/p',
     runtimes: [{ runtime: 'claude', status: 'asleep' }],
     ...over,
   }

package/src/launch/adapters/claude.ts

@@ -39,7 +39,8 @@ import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, Runt
  *     (claude-start.sh:337), shown when PEER_START_ARGS carries
  *     --dangerously-load-development-channels.
  *   - 'Resume from summary'      — the resume compact-picker (default cursor =
- *     "summary (recommended)", which compacts; bootDialogKeys picks "full" instead).
+ *     "summary (recommended)", which compacts; bootDialogKeys steps the cursor to
+ *     "full" ONE key per iteration and confirms only after SEEING it there).
  *   - 'Resuming the full session' — the post-select load state (still not ready).
  */
 const CLAUDE_BOOT_DIALOG_MARKERS = [
@@ -146,21 +147,30 @@ export const claudeAdapter: RuntimeAdapter = {
   /**
    * Map a visible startup dialog to the keys that clear it correctly:
    *
-   *   - RESUME COMPACT-PICKER ('Resume from summary …') → ['Down','Enter'].
+   *   - RESUME COMPACT-PICKER ('Resume from summary …') → CURSOR-VERIFIED two-step.
    *     This menu's cursor DEFAULTS to "1. Resume from summary (recommended)",
    *     and selecting it COMPACTS the session (claude implements that choice as an
-   *     internal /compact). A bare Enter would therefore silently compact a warm
-   *     peer on EVERY idle-reap→resume — losing its full context. Move the cursor
-   *     DOWN one to "2. Resume full session as-is" and confirm, keeping full
-   *     context. (Verified against the live picker: ❯ on option 1, ↑↓ navigation,
-   *     "Enter to confirm".)
+   *     internal /compact) — the owner's invariant is «на resume не должно быть
+   *     компакта». The original blind ['Down','Enter'] burst (0e67e1f) put BOTH
+   *     keys into one pty chunk; under a heavy resume (boris 10.06, 313k-token
+   *     session) the TUI dropped the Down and the Enter confirmed the DEFAULT →
+   *     silent /compact (proven: pane log shows the picker frame with ❯ on
+   *     option 1 followed by "❯ /compact"; transcript compactMetadata
+   *     trigger=manual). Fix: ONE key per boot-iteration — Down while the cursor
+   *     is NOT yet seen on "2. Resume full session", Enter ONLY after the
+   *     captured pane PROVES it ("❯ 2."). A swallowed Down self-heals on the
+   *     next 2 s iteration; Enter can never hit the compacting default. If the
+   *     picker layout ever changes, the loop Downs until the boot deadline and
+   *     the wake fails LOUD — never a silent compact.
    *   - OTHER MODALS (folder-trust / external-import / dev-channels) → ['Enter']:
    *     their default-highlighted option IS the proceed path, so a bare Enter clears
    *     each (claude-start.sh:341).
    *   - anything else (incl. the post-select "Resuming…" load state) → null (wait).
    */
   bootDialogKeys(pane: string): string[] | null {
-    if (pane.includes('Resume from summary')) return ['Down', 'Enter']
+    if (pane.includes('Resume from summary')) {
+      return /❯\s*2\./.test(pane) ? ['Enter'] : ['Down']
+    }
     if (
       pane.includes('trust this folder') ||
       pane.includes('Allow external CLAUDE.md file imports?') ||

package/src/launch/launch.test.ts

@@ -172,12 +172,25 @@ describe('claudeAdapter', () => {
     expect(claudeAdapter.bootDialogKeys('❯ ready')).toBeNull()
   })
 
-  test('bootDialogKeys: resume compact-picker → [Down, Enter] (pick "full", NOT the recommended summary)', () => {
-    // Default cursor is "1. Resume from summary (recommended)"; bare Enter would compact.
-    // Move DOWN to "2. Resume full session as-is" and confirm → full context preserved.
-    expect(
-      claudeAdapter.bootDialogKeys('❯ 1. Resume from summary (recommended)\n  2. Resume full session as-is'),
-    ).toEqual(['Down', 'Enter'])
+  test('bootDialogKeys: resume compact-picker is CURSOR-VERIFIED — Enter ONLY after ❯ is seen on "2. full"', () => {
+    // Regression (boris 10.06, 313k resume): the blind ['Down','Enter'] burst lost the
+    // Down in one pty chunk and Enter confirmed the DEFAULT "1. Resume from summary"
+    // → silent /compact. Owner's invariant: NO compact on resume. One key per boot
+    // iteration; confirm only on a PROVEN cursor position.
+    const cursorOn1 = '❯ 1. Resume from summary (recommended)\n  2. Resume full session as-is'
+    const cursorOn2 = '  1. Resume from summary (recommended)\n❯ 2. Resume full session as-is'
+    // cursor on the compacting default → step down, do NOT confirm
+    expect(claudeAdapter.bootDialogKeys(cursorOn1)).toEqual(['Down'])
+    // a swallowed Down self-heals: the unchanged pane just gets another Down
+    expect(claudeAdapter.bootDialogKeys(cursorOn1)).toEqual(['Down'])
+    // cursor PROVEN on "2. Resume full session" → now (and only now) confirm
+    expect(claudeAdapter.bootDialogKeys(cursorOn2)).toEqual(['Enter'])
+    // Enter can never reach the compacting default: option-1 cursor never maps to Enter
+    expect(claudeAdapter.bootDialogKeys(cursorOn1)).not.toContain('Enter')
+    // the 2.1.170 live layout (3rd item present) behaves the same
+    const live170 =
+      "This session is 7h 3m old and 314.2k tokens.\n❯ 1. Resume from summary (recommended)\n  2. Resume full session as-is\n  3. Don't ask me again\nEnter to confirm · Esc to cancel"
+    expect(claudeAdapter.bootDialogKeys(live170)).toEqual(['Down'])
   })
 
   test('permissionDialog: proceed prompt → active, [Enter]', () => {

package/src/lifecycle/index.ts

@@ -572,6 +572,26 @@ function sessionAlive(sock: string, identity: string): boolean {
   return tmux(sock, 'has-session', '-t', identity).ok
 }
 
+/** Death-class tag for a gone session (live case: iapeer-memory 10.06 — the WHOLE
+ *  tmux server died by SIGKILL-class and exits.log stayed empty, because the
+ *  pane-died hook needs a living tmux event loop). Two distinguishable classes:
+ *  - `session-gone` — the server on the socket still ANSWERS but the session is not
+ *    there: a pane died inside a living server → the pane-died hook had its chance,
+ *    exits.log should carry the cause.
+ *  - `server-dead` — the server itself is gone: the socket file is missing, or it
+ *    exists but nothing serves it (stale socket — the SIGKILL/OOM class). pane-died
+ *    could never fire, so the lifecycle.log line is the only durable trace. */
+export function classifyGoneSession(sock: string): { death: 'server-dead' | 'session-gone'; reason: string } {
+  if (!existsSync(sock)) {
+    return { death: 'server-dead', reason: 'tmux server gone (socket file missing)' }
+  }
+  // Ask the SERVER, not the session: any server-level command answering (exit 0)
+  // proves the server is alive and merely lost this session.
+  return tmux(sock, 'list-sessions').ok
+    ? { death: 'session-gone', reason: 'session gone, tmux server alive (exit cause should be in exits.log)' }
+    : { death: 'server-dead', reason: 'tmux server dead — stale socket (SIGKILL/OOM class; exits.log has no entry)' }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // System-prompt composition for a woken peer (delegates the jq doctrine-merge to
 // launch/composeSystemPrompt). The tmux launch + boot/ready + activity-proxy all
@@ -1007,8 +1027,13 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       }
       // Crash / self-close: NO marker written, NO eager relaunch — the peer stays
       // asleep and wakes FRESH lazily on the next message (resolveWakeMode branch 3a).
-      out.push({ identity: s.identity, action: 'reaped-gone', reason: 'session no longer live' })
-      trace({ identity: s.identity, action: 'reaped-gone', reason: 'session no longer live', outcome: 'fresh-next-msg' })
+      // The death-class tag (classifyGoneSession) makes the two gone-classes
+      // distinguishable in lifecycle.log: `session-gone` (pane died, server alive →
+      // exits.log should have the cause) vs `server-dead` (whole tmux server died →
+      // exits.log structurally empty; this line is the only durable trace).
+      const gone = classifyGoneSession(sock)
+      out.push({ identity: s.identity, action: 'reaped-gone', reason: gone.reason })
+      trace({ identity: s.identity, action: 'reaped-gone', death: gone.death, reason: gone.reason, outcome: 'fresh-next-msg' })
       continue
     }
     // Idle accounting via the runtime adapter's activity proxy (claude transcript

package/src/lifecycle/lifecycle.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import {
   attachPeer,
+  classifyGoneSession,
   clearEphemeralArmed,
   clearNewEager,
   clearStopped,
@@ -229,6 +230,8 @@ describe('superviseTick H4 guard', () => {
     const logged = readFileSync(join(c.eventLogDir, 'lifecycle.log'), 'utf8')
     expect(logged).toContain(`ev=supervise identity=${id} action=reaped-gone`)
     expect(logged).toContain('outcome=fresh-next-msg')
+    // death-class tag: no socket file at all in this sandbox → the server is gone
+    expect(logged).toContain('death=server-dead')
   })
 
   test('empty state dir → no outcomes', () => {
@@ -621,6 +624,83 @@ describe('ephemeral-armed marker + config', () => {
   })
 })
 
+// ─────────────────────────────────────────────────────────────────────────────
+// classifyGoneSession — the death-class tag for reaped-gone (server-dead vs
+// session-gone). Live case: iapeer-memory 10.06 — the whole tmux server died
+// (SIGKILL class), exits.log stayed empty; lifecycle.log must carry the class.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('classifyGoneSession (death-class tag)', () => {
+  const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+
+  test('missing socket file → server-dead', () => {
+    const r = classifyGoneSession(join(tmpdir(), 'iapeer-no-such-sock-ever.sock'))
+    expect(r.death).toBe('server-dead')
+    expect(r.reason).toContain('socket file missing')
+  })
+
+  test('stale socket (file exists, nothing serves it) → server-dead', () => {
+    // The SIGKILL/OOM class: the killed server never unlinks its socket file.
+    const dir = mkdtempSync(join(tmpdir(), 'iapeer-stale-sock-'))
+    const sock = join(dir, 'tmux-iap-claude-stale.sock')
+    try {
+      writeFileSync(sock, '') // a plain file — tmux cannot connect to it
+      const r = classifyGoneSession(sock)
+      expect(r.death).toBe('server-dead')
+      expect(r.reason).toContain('stale socket')
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  test.if(tmuxAvailable)('server alive but the session is not there → session-gone', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'iapeer-sg-sock-'))
+    const sock = join(dir, 'tmux-iap-claude-sg.sock')
+    try {
+      // a LIVING server on the socket holding some OTHER session
+      spawnSync('tmux', ['-S', sock, 'new-session', '-d', '-s', 'other-session', 'sleep', '60'])
+      const r = classifyGoneSession(sock)
+      expect(r.death).toBe('session-gone')
+      expect(r.reason).toContain('server alive')
+    } finally {
+      spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  test.if(tmuxAvailable)('superviseTick logs death=session-gone when the pane died inside a living server', () => {
+    const root = mkdtempSync(join(tmpdir(), 'iapeer-sg-root-'))
+    const laDir = mkdtempSync(join(tmpdir(), 'iapeer-sg-la-')) // empty → not launchd-managed
+    const env = {
+      ...process.env,
+      IAPEER_ROOT: root,
+      IAPEER_LAUNCHAGENTS_DIR: laDir,
+      IAPEER_SOCK_DIR: join(root, 'socks'),
+    }
+    const cfg = loadLifecycleConfig(env)
+    const identity = 'claude-sg'
+    const sock = join(root, 'socks', 'tmux-iap-claude-sg.sock')
+    try {
+      mkdirSync(join(root, 'socks'), { recursive: true })
+      mkdirSync(cfg.stateDir, { recursive: true })
+      // the server LIVES (another session holds it) but claude-sg's session is gone
+      spawnSync('tmux', ['-S', sock, 'new-session', '-d', '-s', 'placeholder', 'sleep', '60'])
+      writeFileSync(
+        join(cfg.stateDir, `${identity}.session`),
+        JSON.stringify({ identity, runtime: 'claude', personality: 'sg', cwd: '/tmp/none', wokeAt: 0 }),
+      )
+      const out = superviseTick(cfg, { env })
+      expect(out.find(x => x.identity === identity)?.action).toBe('reaped-gone')
+      const logged = readFileSync(join(cfg.eventLogDir, 'lifecycle.log'), 'utf8')
+      expect(logged).toContain(`identity=${identity} action=reaped-gone death=session-gone`)
+    } finally {
+      spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+      rmSync(root, { recursive: true, force: true })
+      rmSync(laDir, { recursive: true, force: true })
+    }
+  })
+})
+
 describe('superviseTick quiet-reap (M2 die-after-reply, real tmux)', () => {
   const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
 

package/src/onboard/steps.test.ts

@@ -0,0 +1,201 @@
+// Backbone default-yes onboard steps (design «Onboard костяка» FINAL 10.06) —
+// notifier (zero questions, soft-skip on unavailability) and telegram (human peer
+// via TELEGRAM_USER_ID env → the package's self-config hook; idempotent vs an
+// existing natural peer). All sandboxed: IAPEER_ROOT / IAPEER_LAUNCHAGENTS_DIR
+// temp dirs, IAPEER_TEST_SANDBOX skips real launchctl, injected npx/ask.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { findNaturalPeer, onboardNotifierStep, onboardTelegramStep } from './steps.ts'
+import { writeRuntimeManifest, type RuntimeManifest } from '../runtime/index.ts'
+import { findPeer, readPeersIndex, upsertPeer } from '../registry/index.ts'
+
+const roots: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-steps-'))
+  roots.push(d)
+  return d
+}
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function envFor(root: string, path?: string): NodeJS.ProcessEnv {
+  return {
+    IAPEER_ROOT: join(root, 'iapeer'),
+    IAPEER_LAUNCHAGENTS_DIR: join(root, 'LA'),
+    IAPEER_TEST_SANDBOX: '1',
+    HOME: root,
+    ...(path ? { PATH: path } : {}),
+  } as NodeJS.ProcessEnv
+}
+
+/** Stub launcher + recording self-config hook on a PATH dir. */
+function stubBins(bin: string): { dir: string; hook: string } {
+  const dir = mkTmp()
+  writeFileSync(join(dir, bin), '#!/bin/sh\nexec sleep 1\n', { mode: 0o755 })
+  const hook = join(dir, 'sc.sh')
+  // records personality + the TELEGRAM_USER_ID it received → proves env passthrough
+  writeFileSync(
+    hook,
+    '#!/bin/sh\nprintf "%s|%s" "$IAPEER_PEER_PERSONALITY" "$TELEGRAM_USER_ID" > "$IAPEER_ROOT/sc-$IAPEER_PEER_PERSONALITY"\nexit 0\n',
+    { mode: 0o755 },
+  )
+  return { dir, hook }
+}
+
+describe('onboardNotifierStep (а — default-yes, zero questions)', () => {
+  test('npx self-deploy → declared set provisioned', async () => {
+    const root = mkTmp()
+    const { dir, hook } = stubBins('notifier-runtime')
+    const env = envFor(root, dir)
+    const runNpx = (_pkg: string, e: NodeJS.ProcessEnv) => {
+      const m: RuntimeManifest = {
+        runtime: 'notifier',
+        selfConfig: hook,
+        peers: [
+          { personality: 'timer', intelligence: 'absent' },
+          { personality: 'watcher', intelligence: 'absent' },
+        ],
+      }
+      writeRuntimeManifest(m, { env: e })
+      return { ok: true }
+    }
+    const r = await onboardNotifierStep({ env, runNpx })
+    expect(r.state).toBe('deployed')
+    expect(r.peers.map(p => p.personality).sort()).toEqual(['timer', 'watcher'])
+    expect(findPeer(readPeersIndex({ env }), 'timer')).not.toBeNull()
+  })
+
+  test('npx failure (no bun / unpublished / no network) → SOFT skip, not a failure', async () => {
+    const env = envFor(mkTmp())
+    const r = await onboardNotifierStep({ env, runNpx: () => ({ ok: false, detail: 'bun: command not found' }) })
+    expect(r.state).toBe('skipped-unavailable')
+    expect(r.detail).toContain('bun: command not found')
+    expect(r.detail).toContain('install later')
+  })
+
+  test('package installed but manifest missing → deploy-failed (REAL break, not unavailability)', async () => {
+    const env = envFor(mkTmp())
+    // npx "succeeds" but self-deploys nothing — the package broke its contract
+    const r = await onboardNotifierStep({ env, runNpx: () => ({ ok: true }) })
+    expect(r.state).toBe('deploy-failed')
+    expect(r.detail).toContain('manifest')
+  })
+
+  test('--no-notifier → skipped-flag; dry-run reports intent without touching anything', async () => {
+    const env = envFor(mkTmp())
+    expect((await onboardNotifierStep({ skip: true, env })).state).toBe('skipped-flag')
+    const dry = await onboardNotifierStep({ dryRun: true, env })
+    expect(dry.state).toBe('dry-run')
+    expect(dry.detail).toContain('@agfpd/notifier-runtime')
+  })
+
+  test('idempotent re-run: manifest present → install skipped, deploy no-clobber', async () => {
+    const root = mkTmp()
+    const { dir, hook } = stubBins('notifier-runtime')
+    const env = envFor(root, dir)
+    writeRuntimeManifest(
+      { runtime: 'notifier', selfConfig: hook, peers: [{ personality: 'timer', intelligence: 'absent' }] },
+      { env },
+    )
+    let npxCalled = false
+    const first = await onboardNotifierStep({ env, runNpx: () => ((npxCalled = true), { ok: true }) })
+    expect(first.state).toBe('deployed')
+    expect(npxCalled).toBe(false) // manifest-gated — npx never re-ran
+    const second = await onboardNotifierStep({ env, runNpx: () => ({ ok: true }) })
+    expect(second.state).toBe('deployed') // no-clobber re-verify
+    expect(readPeersIndex({ env }).peers.filter(p => p.personality === 'timer').length).toBe(1)
+  })
+})
+
+describe('onboardTelegramStep (б — human peer, идемпотентность, non-tty)', () => {
+  test('flags path: creates the human peer; TELEGRAM_USER_ID reaches the self-config hook', async () => {
+    const root = mkTmp()
+    const { dir, hook } = stubBins('telegram-runtime')
+    const env = envFor(root, dir)
+    writeRuntimeManifest({ runtime: 'telegram', selfConfig: hook }, { env }) // installed (mode b — no declared peers)
+    const r = await onboardTelegramStep({ human: 'Arthur', userId: '123456789', env })
+    expect(r.state).toBe('created')
+    expect(r.personality).toBe('arthur') // normalized
+    const peer = findPeer(readPeersIndex({ env }), 'arthur')!
+    expect(peer.intelligence).toBe('natural')
+    expect(peer.runtime).toBe('telegram')
+    // the hook saw the user id via env (owner's contract: hook writes interfaces itself)
+    expect(readFileSync(join(env.IAPEER_ROOT as string, 'sc-arthur'), 'utf8')).toBe('arthur|123456789')
+  })
+
+  test('IDEMPOTENT: an existing natural peer → already, NEVER a second human (boris check)', async () => {
+    const env = envFor(mkTmp())
+    await upsertPeer(
+      { personality: 'arthur', runtime: 'telegram', cwd: '/tmp/arthur', intelligence: 'natural' },
+      { env },
+    )
+    let asked = false
+    const r = await onboardTelegramStep({
+      env,
+      ask: async () => ((asked = true), 'never'),
+      isTty: true,
+    })
+    expect(r.state).toBe('already')
+    expect(r.personality).toBe('arthur')
+    expect(r.detail).toContain('уже есть')
+    expect(asked).toBe(false) // no questions, no install — the WHOLE step no-ops
+  })
+
+  test('non-tty without flags → refusal of the STEP (with the flag recipe), not of onboard', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    writeRuntimeManifest({ runtime: 'telegram' }, { env })
+    const r = await onboardTelegramStep({ env, isTty: false })
+    expect(r.state).toBe('refused-non-tty')
+    expect(r.detail).toContain('--telegram-human')
+  })
+
+  test('tty prompt path: answers flow in; empty answer → soft refusal', async () => {
+    const root = mkTmp()
+    const { dir, hook } = stubBins('telegram-runtime')
+    const env = envFor(root, dir)
+    writeRuntimeManifest({ runtime: 'telegram', selfConfig: hook }, { env })
+    const answers = ['leo', '42']
+    const r = await onboardTelegramStep({ env, isTty: true, ask: async () => answers.shift() ?? '' })
+    expect(r.state).toBe('created')
+    expect(r.personality).toBe('leo')
+    // empty answer → not now
+    const env2 = envFor(mkTmp())
+    writeRuntimeManifest({ runtime: 'telegram' }, { env: env2 })
+    const r2 = await onboardTelegramStep({ env: env2, isTty: true, ask: async () => '' })
+    expect(r2.state).toBe('refused-non-tty')
+  })
+
+  test('invalid explicit flags → invalid-input (hard): bad name / non-digit user id', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    writeRuntimeManifest({ runtime: 'telegram' }, { env })
+    expect((await onboardTelegramStep({ human: '!!!', userId: '42', env })).state).toBe('invalid-input')
+    const r = await onboardTelegramStep({ human: 'leo', userId: 'abc', env })
+    expect(r.state).toBe('invalid-input')
+    expect(r.detail).toContain('@userinfobot')
+  })
+
+  test('package unavailable → soft skip (step), with the install-later recipe', async () => {
+    const env = envFor(mkTmp())
+    const r = await onboardTelegramStep({
+      human: 'leo',
+      userId: '42',
+      env,
+      runNpx: () => ({ ok: false, detail: 'npm ERR 404' }),
+    })
+    expect(r.state).toBe('skipped-unavailable')
+    expect(r.detail).toContain('install-runtime telegram')
+  })
+
+  test('findNaturalPeer: null on empty/no registry, found when present', async () => {
+    const env = envFor(mkTmp())
+    expect(findNaturalPeer(env)).toBeNull()
+    await upsertPeer({ personality: 'h', runtime: 'telegram', cwd: '/tmp/h', intelligence: 'natural' }, { env })
+    expect(findNaturalPeer(env)).toBe('h')
+  })
+})

package/src/onboard/steps.ts

@@ -0,0 +1,246 @@
+// Default-yes onboard steps for the distribution BACKBONE (design doc
+// docs/«Onboard костяка — notifier, telegram, каналы, update» — FINAL 10.06,
+// sanctioned by Артур; owners' facts baked: notifier ack «ноль вопросов»,
+// telegram self-config contract v0.10.0+).
+//
+// Backbone = core + memory slot + notifier-runtime + telegram-runtime. The onboard
+// step ORDER is significant: marketplace → notifier → TELEGRAM (creates the human
+// peer) → memory (its --human resolves from the natural peer that just appeared).
+//
+// UX principle («вопросами владеет рантайм»): the package owns its questions; the
+// core orchestrates the steps, passes only facts IT owns, and inherits stdio for
+// the package's own interactive. Every step is OPTIONAL (default-yes, removed by a
+// flag); unavailability is a SOFT SKIP, never a core failure.
+
+import { spawnSync } from 'child_process'
+import { isValidName, normalizeIntelligenceValue, normalizeNameCandidate } from '../core/constants.ts'
+import { readPeersIndex } from '../registry/index.ts'
+import { createPeer } from '../create/index.ts'
+import {
+  deployRuntime,
+  installRuntimePackage,
+  RUNTIME_PACKAGES,
+  type DeployedPeer,
+  type NpxRunner,
+} from '../runtime/deploy.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// (а) notifier — default-yes, ZERO questions (owner-confirmed: the whole chain
+// has no prompt/stdin/tty dependency; all failures are fail-closed exit≠0).
+// Prereq (not a question): `bun` on PATH — without it the npx shim exits non-zero
+// → SOFT SKIP with a clear message (design: unavailability is not a core error).
+// Idempotent re-onboard: install is manifest-gated (skipped), deploy is no-clobber
+// («1 плист = 1 infra-пир»).
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface NotifierStepOptions {
+  /** --no-notifier: remove the default-yes step. */
+  skip?: boolean
+  dryRun?: boolean
+  env?: NodeJS.ProcessEnv
+  /** Injected npx runner (tests / sandbox proof). */
+  runNpx?: NpxRunner
+  warn?: (message: string) => void
+}
+
+export interface NotifierStepResult {
+  state:
+    | 'deployed' // declared set provisioned (or re-verified — idempotent)
+    | 'skipped-flag' // --no-notifier
+    | 'skipped-unavailable' // npx failed (no bun / not published / no network) — soft skip
+    | 'deploy-failed' // the package installed but the declared-set deploy broke — REAL failure
+    | 'dry-run'
+  peers: DeployedPeer[]
+  detail?: string
+}
+
+export async function onboardNotifierStep(opts: NotifierStepOptions = {}): Promise<NotifierStepResult> {
+  const env = opts.env ?? process.env
+  if (opts.skip) return { state: 'skipped-flag', peers: [] }
+  if (opts.dryRun) {
+    return {
+      state: 'dry-run',
+      peers: [],
+      detail: `would npx-install ${RUNTIME_PACKAGES.notifier} + deploy its declared peer-set (timer, watcher)`,
+    }
+  }
+  const install = installRuntimePackage({ runtime: 'notifier', env, runNpx: opts.runNpx })
+  if (install.state === 'failed' || install.state === 'no-package') {
+    // SOFT skip (design (а)): a missing prereq (bun) / unpublished package / no
+    // network must not fail the core's onboard — report and move on.
+    return {
+      state: 'skipped-unavailable',
+      peers: [],
+      detail: `${install.package ?? 'notifier package'} install failed (${install.detail?.split('\n')[0] ?? 'npx non-zero'}) — install later: iapeer install-runtime notifier`,
+    }
+  }
+  try {
+    const deploy = await deployRuntime({ runtime: 'notifier', env, warn: opts.warn })
+    const broken = deploy.peers.some(p => p.bootstrap === 'failed' || p.selfConfig === 'failed')
+    return {
+      state: broken ? 'deploy-failed' : 'deployed',
+      peers: deploy.peers,
+      detail: broken ? 'a declared peer failed self-config/bootstrap — see the per-peer lines' : undefined,
+    }
+  } catch (e) {
+    // The package installed but its manifest/deploy contract broke — a REAL failure
+    // (not unavailability), surfaced as such.
+    return { state: 'deploy-failed', peers: [], detail: e instanceof Error ? e.message : String(e) }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// (б) telegram — default-yes, install WITH setup. The human owes exactly two
+// facts: the human-peer name and their telegram user_id (prompt hints at
+// @userinfobot). The core creates the HUMAN peer via createPeer with
+// TELEGRAM_USER_ID in env — the package's self-config hook (contract v0.10.0+)
+// writes interfaces.telegram.user_id itself; no prepare / interface-human calls.
+// Bot tokens are NOT asked here — they are per-channel (`iapeer connect telegram`).
+//
+// IDEMPOTENT re-onboard (boris's check, baked into the design): an EXISTING
+// natural peer in the registry → the step is a no-op/skip with a clear message —
+// NEVER an offer to create a second human peer.
+//
+// Interactive lives INSIDE the step (tty only); non-tty without the flags
+// (--telegram-human + --telegram-user-id) → an explicit refusal of the STEP, not
+// of the whole onboard.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TelegramStepOptions {
+  /** --no-telegram: remove the default-yes step. */
+  skip?: boolean
+  /** --telegram-human <p>: the human peer's personality (skips the prompt). */
+  human?: string
+  /** --telegram-user-id <id>: the owner's telegram user id (skips the prompt). */
+  userId?: string
+  dryRun?: boolean
+  env?: NodeJS.ProcessEnv
+  runNpx?: NpxRunner
+  /** Injectable prompt (tests). Default: readline on the live tty. */
+  ask?: (question: string) => Promise<string>
+  /** Override tty detection (tests). Default: stdin AND stdout are ttys. */
+  isTty?: boolean
+  warn?: (message: string) => void
+}
+
+export interface TelegramStepResult {
+  state:
+    | 'created' // human peer created; user_id delivered via the self-config hook
+    | 'already' // a natural peer already exists — idempotent skip (never a second human)
+    | 'skipped-flag' // --no-telegram
+    | 'skipped-unavailable' // package install failed — soft skip
+    | 'refused-non-tty' // no tty and no flags — the STEP refuses, onboard continues
+    | 'invalid-input' // explicit flags carried an invalid name / user id — hard
+    | 'create-failed' // createPeer threw — hard
+    | 'dry-run'
+  personality?: string
+  detail?: string
+}
+
+async function ttyAsk(question: string): Promise<string> {
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await rl.question(question)).trim()
+  } finally {
+    rl.close()
+  }
+}
+
+/** The registry's existing natural peer, if any (the idempotency key of the step). */
+export function findNaturalPeer(env: NodeJS.ProcessEnv): string | null {
+  try {
+    const naturals = readPeersIndex({ env }).peers.filter(
+      p => normalizeIntelligenceValue(p.intelligence) === 'natural',
+    )
+    return naturals[0]?.personality ?? null
+  } catch {
+    return null // no registry yet → no natural peer
+  }
+}
+
+export async function onboardTelegramStep(opts: TelegramStepOptions = {}): Promise<TelegramStepResult> {
+  const env = opts.env ?? process.env
+  if (opts.skip) return { state: 'skipped-flag' }
+
+  // Idempotency FIRST (before any install/questions): an existing natural peer
+  // means the host already has its human — the whole step is a no-op.
+  const existing = findNaturalPeer(env)
+  if (existing) {
+    return { state: 'already', personality: existing, detail: `human-пир "${existing}" уже есть — шаг пропущен` }
+  }
+
+  if (opts.dryRun) {
+    return {
+      state: 'dry-run',
+      detail: `would npx-install ${RUNTIME_PACKAGES.telegram} + create the human peer (asks: name, telegram user_id)`,
+    }
+  }
+
+  const install = installRuntimePackage({ runtime: 'telegram', env, runNpx: opts.runNpx })
+  if (install.state === 'failed' || install.state === 'no-package') {
+    return {
+      state: 'skipped-unavailable',
+      detail: `${install.package ?? 'telegram package'} install failed (${install.detail?.split('\n')[0] ?? 'npx non-zero'}) — install later: iapeer install-runtime telegram`,
+    }
+  }
+
+  // Resolve the two human-owed facts: flags → prompt (tty) → refuse (non-tty).
+  let human = opts.human?.trim()
+  let userId = opts.userId?.trim()
+  if (!human || !userId) {
+    const tty = opts.isTty ?? (process.stdin.isTTY === true && process.stdout.isTTY === true)
+    if (!tty) {
+      return {
+        state: 'refused-non-tty',
+        detail:
+          'no tty for the telegram questions — re-run with --telegram-human <name> --telegram-user-id <id>, ' +
+          'or skip with --no-telegram (add later: iapeer create <name> --runtime telegram)',
+      }
+    }
+    const ask = opts.ask ?? ttyAsk
+    if (!human) human = (await ask('telegram step — your human-peer name (short, latin): ')).trim()
+    if (human && !userId) {
+      userId = (await ask('your telegram user_id (message @userinfobot — it replies with the id): ')).trim()
+    }
+    if (!human || !userId) {
+      // An empty answer on the live tty is a "not now" — soft refusal of the step.
+      return {
+        state: 'refused-non-tty',
+        detail: 'no answer — telegram step skipped (add later: iapeer create <name> --runtime telegram)',
+      }
+    }
+  }
+
+  const personality = normalizeNameCandidate(human)
+  if (!isValidName(personality)) {
+    return { state: 'invalid-input', detail: `invalid human-peer name "${human}" — must normalize to /^[a-z][a-z0-9-]{0,31}$/` }
+  }
+  if (!/^\d+$/.test(userId)) {
+    return { state: 'invalid-input', detail: `invalid telegram user_id "${userId}" — expected digits (ask @userinfobot)` }
+  }
+
+  try {
+    // TELEGRAM_USER_ID rides the env into createPeer → initPeer → the package's
+    // self-config hook, which writes interfaces.telegram.user_id itself (owner's
+    // simplification, contract v0.10.0+ — no prepare / interface-human from the core).
+    const r = await createPeer({
+      personality,
+      runtime: 'telegram',
+      intelligence: 'natural',
+      env: { ...env, TELEGRAM_USER_ID: userId },
+      warn: opts.warn,
+    })
+    const sc = r.selfConfig?.state ?? 'absent'
+    if (sc === 'failed') {
+      return {
+        state: 'create-failed',
+        personality,
+        detail: `peer created but the telegram self-config hook failed: ${r.selfConfig?.detail ?? ''}`,
+      }
+    }
+    return { state: 'created', personality, detail: `self-config ${sc}; bootstrap ${r.bootstrapped?.state ?? 'n/a'}` }
+  } catch (e) {
+    return { state: 'create-failed', personality, detail: e instanceof Error ? e.message : String(e) }
+  }
+}

package/src/update/index.ts

@@ -226,7 +226,18 @@ export function updateIapeer(deps: UpdateDeps = {}): UpdateResult {
 
   const runInstall = deps.runInstall ?? defaultRunInstall
   if (!runInstall(desired, env)) {
-    return { status: 'failed', from, latest: desired, reason: `\`npx ${IAPEER_PACKAGE}@${desired} install\` failed` }
+    // NB: the installer is the DETERMINISTIC pack+build path (no npx — see
+    // defaultRunInstall); the most common cause right after a publish is the npm
+    // CDN tarball lagging the version metadata (live-hit 10.06: `npm view` already
+    // showed the version, `npm pack` still failed; a retry ~1 min later succeeded).
+    return {
+      status: 'failed',
+      from,
+      latest: desired,
+      reason:
+        `deterministic install of ${IAPEER_PACKAGE}@${desired} failed (npm pack/deps/build) — ` +
+        `if just published, the registry tarball may still be propagating; retry in ~1 min`,
+    }
   }
 
   const restart = deps.restartDaemon ?? kickstartDaemon