@agfpd/iapeer 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Foundation core for the IAPeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
   "scripts": {
     "test": "IAPEER_TEST_SANDBOX=1 bun test",
     "typecheck": "tsc --noEmit",
+    "preversion": "npm run test && npm run typecheck",
     "release": "npm version patch && npm publish && git push --follow-tags",
     "release:minor": "npm version minor && npm publish && git push --follow-tags",
     "release:major": "npm version major && npm publish && git push --follow-tags",

package/src/cli/index.ts

@@ -20,7 +20,7 @@ import {
   type Runtime,
 } from '../core/constants.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
-import { updateIapeer } from '../update/index.ts'
+import { updateIapeer, waitForDaemonHealthy } from '../update/index.ts'
 import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { ensureGlobalIapScaffold } from '../storage/index.ts'
 import { findPeer, readPeersIndex, removePeer, type PeerRecord } from '../registry/index.ts'
@@ -38,7 +38,7 @@ import {
   wakeOrSpawn,
 } from '../lifecycle/index.ts'
 import { getAdapter } from '../launch/index.ts'
-import { isFoundationOwnedPlist, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
+import { isFoundationOwnedPlist, kickstartDaemon, 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'
@@ -348,7 +348,8 @@ export function parseArgs(argv: string[]): { positionals: string[]; flags: Recor
 
 const USAGE = `usage: iapeer <verb> [args]
   install                                                        build binary + global scaffold + daemon plist (one bootstrap)
-  update [--force]                                               pull the latest @agfpd/iapeer from npm (cloud) + restart the daemon
+  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
   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)
@@ -560,31 +561,73 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         return 0
       }
       case 'update': {
-        // The single deploy path: pull the latest published foundation from npm and
-        // restart the daemon onto it (cloud-only — never a working-tree build). Foundation
-        // ONLY; the plist and other host packages are untouched. --force reinstalls even
-        // when already at latest. (Run from the installed binary; the first-ever install is
-        // `npx @agfpd/iapeer`.)
-        const r = updateIapeer({ env, force: flags.force === true })
+        // The single deploy path: pull a version of the foundation from npm and restart
+        // the daemon onto it (cloud-only — never a working-tree build). No arg → latest;
+        // an explicit `update <version>` pins to that exact version (downgrade / recover
+        // deeper than the single .prev). Foundation ONLY; the plist and other host packages
+        // are untouched. --force reinstalls even when already at the desired version. (Run
+        // from the installed binary; the first-ever install is `npx @agfpd/iapeer`.)
+        const r = updateIapeer({ env, force: flags.force === true, targetVersion: positionals[0] })
         if (r.status === 'failed') {
           errOut(`update failed: ${r.reason}\n`)
           return 1
         }
         if (r.status === 'already-latest') {
-          out(`already at the latest version (${r.from})\n`)
+          out(`already at version ${r.from}\n`)
+          return 0
+        }
+        // 'updated': the binary is swapped. If the daemon was restarted, VERIFY it
+        // actually came back up before declaring success — a new binary that fails to
+        // boot must not read as a healthy deploy (it's the cue to roll back).
+        if (r.daemon === 'restarted') {
+          const h = await waitForDaemonHealthy({ env })
+          if (!h.healthy) {
+            errOut(`updated ${r.from} → ${r.to} but the daemon is NOT healthy after restart (${h.detail}).\n` +
+              `roll back now: iapeer rollback\n`)
+            return 1
+          }
+          out(`updated ${r.from} → ${r.to}; daemon restarted and healthy\n`)
           return 0
         }
         const daemonNote =
-          r.daemon === 'restarted'
-            ? 'daemon restarted onto the new binary'
-            : r.daemon === 'not-loaded'
-              ? 'daemon not loaded — new binary will be used on next start'
-              : r.daemon === 'failed'
-                ? `WARNING — ${r.reason}`
-                : String(r.daemon)
+          r.daemon === 'not-loaded'
+            ? 'daemon not loaded — new binary will be used on next start'
+            : r.daemon === 'failed'
+              ? `WARNING — ${r.reason}; roll back with: iapeer rollback`
+              : String(r.daemon)
         out(`updated ${r.from} → ${r.to}; ${daemonNote}\n`)
         return r.daemon === 'failed' ? 1 : 0
       }
+      case 'rollback': {
+        // Recovery: restore the .prev binary kept by the last install, restart the
+        // daemon onto it, and verify health. ONE level deep (single .prev). Cloud is
+        // still the source of truth — rollback is the local "undo the last update" while
+        // a fixed version is published.
+        const { rollbackIapeer } = await import('../install/index.ts')
+        const rb = rollbackIapeer(env)
+        if (rb.status === 'failed') {
+          errOut(`rollback failed: ${rb.reason}\n`)
+          return 1
+        }
+        const restart = kickstartDaemon(env)
+        if (restart.state === 'restarted') {
+          const h = await waitForDaemonHealthy({ env })
+          out(
+            h.healthy
+              ? `rolled back to the previous binary; daemon restarted and healthy\n`
+              : `rolled back, but the daemon is NOT healthy after restart (${h.detail})\n`,
+          )
+          return h.healthy ? 0 : 1
+        }
+        out(
+          `rolled back to the previous binary; ${
+            restart.state === 'not-loaded'
+              ? 'daemon not loaded — previous binary will be used on next start'
+              : `daemon restart ${restart.state}${restart.detail ? ` (${restart.detail})` : ''}`
+          }\n`,
+        )
+        return restart.state === 'failed' ? 1 : 0
+      }
       case 'install': {
         // UNIFIED foundation install (contract Установка §1 — "один npx ставит
         // фундамент"): ONE command does all three install-phase steps that used to be

package/src/install/index.ts

@@ -82,3 +82,44 @@ export function installIapeer(cliEntrypoint: string, env: NodeJS.ProcessEnv = pr
   }
   return { binPath, prevPath, size }
 }
+
+/** The previous-binary path kept by the last install for one-step rollback. */
+export function iapeerPrevBinPath(env: NodeJS.ProcessEnv = process.env): string {
+  return `${iapeerBinPath(env)}.prev`
+}
+
+export interface RollbackResult {
+  status: 'rolled-back' | 'failed'
+  binPath: string
+  reason?: string
+}
+
+/**
+ * Roll the installed binary back to the `.prev` kept by the last install — the
+ * recovery path when an `iapeer update` ships a bad version. ONE level deep (the
+ * foundation keeps a single `.prev`, not a history stack): rollback restores the
+ * binary that was live BEFORE the most recent install. Atomic (copy .prev → .tmp →
+ * rename over the binary), so the binary is never absent. The CALLER restarts the
+ * daemon afterwards (kickstartDaemon) — rollback only swaps the bytes. Sandbox-guarded.
+ */
+export function rollbackIapeer(env: NodeJS.ProcessEnv = process.env): RollbackResult {
+  const binPath = iapeerBinPath(env)
+  assertInstallSandboxIsolated(binPath, env)
+  const prev = iapeerPrevBinPath(env)
+  if (!existsSync(prev)) {
+    return { status: 'failed', binPath, reason: `no previous binary at ${prev} — nothing to roll back to` }
+  }
+  const tmp = `${binPath}.rollback.tmp`
+  try {
+    copyFileSync(prev, tmp)
+    renameSync(tmp, binPath)
+  } catch (e) {
+    try {
+      if (existsSync(tmp)) renameSync(tmp, `${tmp}.discard`) // never leave a half-written tmp on the path
+    } catch {
+      /* best-effort */
+    }
+    return { status: 'failed', binPath, reason: e instanceof Error ? e.message : String(e) }
+  }
+  return { status: 'rolled-back', binPath }
+}

package/src/install/install.test.ts

@@ -3,9 +3,11 @@
 // file. The full `bun build --compile` is exercised LIVE (it writes a ~60M binary —
 // too heavy for a unit test); here we pin the path resolution.
 
-import { describe, expect, test } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
 import { join } from 'path'
-import { iapeerBinPath, installIapeer } from './index.ts'
+import { iapeerBinPath, iapeerPrevBinPath, installIapeer, rollbackIapeer } from './index.ts'
 
 describe('iapeerBinPath', () => {
   test('default = <home>/.local/bin/iapeer (stable host-wide path, on $PATH)', () => {
@@ -29,3 +31,36 @@ describe('installIapeer fail-closed sandbox guard', () => {
     expect(() => installIapeer('/x/entry.ts', env)).toThrow(/refusing to overwrite the REAL prod binary/)
   })
 })
+
+describe('rollbackIapeer', () => {
+  let binDir: string
+  let env: NodeJS.ProcessEnv
+  beforeEach(() => {
+    binDir = mkdtempSync(join(tmpdir(), 'iapeer-rollback-'))
+    env = { IAPEER_TEST_SANDBOX: '1', HOME: '/Users/x', IAPEER_BIN_DIR: binDir } as NodeJS.ProcessEnv
+  })
+  afterEach(() => {
+    rmSync(binDir, { recursive: true, force: true })
+  })
+
+  test('no .prev → failed (nothing to roll back to), binary untouched', () => {
+    writeFileSync(iapeerBinPath(env), 'CURRENT')
+    const r = rollbackIapeer(env)
+    expect(r.status).toBe('failed')
+    expect(r.reason).toMatch(/nothing to roll back/i)
+    expect(readFileSync(iapeerBinPath(env), 'utf8')).toBe('CURRENT') // unchanged
+  })
+
+  test('restores the .prev bytes over the binary', () => {
+    writeFileSync(iapeerBinPath(env), 'NEW-BROKEN')
+    writeFileSync(iapeerPrevBinPath(env), 'OLD-GOOD')
+    const r = rollbackIapeer(env)
+    expect(r.status).toBe('rolled-back')
+    expect(readFileSync(iapeerBinPath(env), 'utf8')).toBe('OLD-GOOD')
+  })
+
+  test('fail-closed sandbox guard: refuses the REAL prod binary path', () => {
+    const realEnv = { IAPEER_TEST_SANDBOX: '1', HOME: '/Users/fake-home' } as NodeJS.ProcessEnv
+    expect(() => rollbackIapeer(realEnv)).toThrow(/refusing to overwrite the REAL prod binary/)
+  })
+})

package/src/launch/adapters/claude.ts

@@ -30,15 +30,17 @@ import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, Runt
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * The known claude startup dialogs whose default-highlighted option is the
- * proceed path, so a single Enter clears each:
+ * Markers that a claude startup dialog / picker is on screen — used by isInputReady
+ * to GATE delivery (a dialog up ⇒ not ready). The KEYS that clear each live in
+ * bootDialogKeys (NOT uniformly Enter — the resume picker must be NAVIGATED, see there):
  *   - 'trust this folder'                      — first-run folder-trust modal.
  *   - 'Allow external CLAUDE.md file imports?' — external-import consent.
  *   - 'I am using this for local development'   — dev-channels accept
  *     (claude-start.sh:337), shown when PEER_START_ARGS carries
  *     --dangerously-load-development-channels.
- *   - 'Resume from summary' / 'Resuming the full session' — the --resume picker.
- * Same set, same order as lifecycle.claudeBootDialog (index.ts:281-289).
+ *   - 'Resume from summary'      — the resume compact-picker (default cursor =
+ *     "summary (recommended)", which compacts; bootDialogKeys picks "full" instead).
+ *   - 'Resuming the full session' — the post-select load state (still not ready).
  */
 const CLAUDE_BOOT_DIALOG_MARKERS = [
   'trust this folder',
@@ -104,7 +106,7 @@ export const claudeAdapter: RuntimeAdapter = {
 
   /**
    * argv = claudeBin + headless flags + (system-prompt-file when set) +
-   * (--resume <ref> when resumeRef set) + extraArgs.
+   * (--continue when resuming) + extraArgs.
    *
    *   - '--dangerously-skip-permissions'  claude-start.sh:318, spawner.ts:776 —
    *     headless peer has no interactive owner to grant per-tool permission.
@@ -117,8 +119,15 @@ export const claudeAdapter: RuntimeAdapter = {
    *     ONLY when set (a tui runtime that usesDoctrine composes one). Swaps the
    *     CC coding baseline for the merged peer doctrine; plugin/MCP/CLAUDE.md
    *     layers stay intact (claude-start.sh:293-303).
-   *   - '--resume', spec.resumeRef  spawner.ts:779-781 — ONLY when the caller
-   *     pre-resolved a uuid (resolveResume); never a silent fresh fallback.
+   *   - '--continue' when spec.resume — continue the cwd's MOST-RECENT session
+   *     (one session-lineage per peer cwd, so most-recent == the warm peer's
+   *     session, == the newest transcript resolveResume validated). NOT
+   *     '--resume <uuid>': in claude 2.1.169 `--resume <arg>` treats arg as a
+   *     SEARCH QUERY (opens a session-list picker), not a session-id — so a bare
+   *     uuid no longer resumes directly. `--continue` resumes the last session
+   *     with no session-list step. The summary-vs-full compact picker still
+   *     appears (handled in bootDialogKeys: pick "full", never the recommended
+   *     summary). resolveResume still gates resume-vs-fresh upstream (fail-loud).
    *   - ...extraArgs  PEER_START_ARGS passthrough (LaunchSpec.extraArgs).
    * NO currency — no marketplace/install/update on this path.
    */
@@ -129,19 +138,37 @@ export const claudeAdapter: RuntimeAdapter = {
       '--disallowedTools',
       'AskUserQuestion',
       ...(spec.systemPromptFile ? ['--system-prompt-file', spec.systemPromptFile] : []),
-      ...(spec.resumeRef ? ['--resume', spec.resumeRef] : []),
+      ...(spec.resume ? ['--continue'] : []),
       ...(spec.extraArgs ?? []),
     ]
   },
 
   /**
-   * A visible startup dialog → ['Enter'] to clear it (its default-highlighted
-   * option is the proceed path), else null. Same marker set as
-   * lifecycle.claudeBootDialog; claude-start.sh:341 (dev-channels) and the
-   * folder-trust/import/resume modals all accept a bare Enter.
+   * Map a visible startup dialog to the keys that clear it correctly:
+   *
+   *   - RESUME COMPACT-PICKER ('Resume from summary …') → ['Down','Enter'].
+   *     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".)
+   *   - 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 {
-    return anyBootDialog(pane) ? ['Enter'] : null
+    if (pane.includes('Resume from summary')) return ['Down', 'Enter']
+    if (
+      pane.includes('trust this folder') ||
+      pane.includes('Allow external CLAUDE.md file imports?') ||
+      pane.includes('I am using this for local development')
+    ) {
+      return ['Enter']
+    }
+    return null
   },
 
   /**

package/src/launch/launch.test.ts

@@ -120,9 +120,12 @@ describe('claudeAdapter', () => {
     ])
   })
 
-  test('buildArgv with system-prompt-file + resume + extras (exact flags/order)', () => {
+  test('buildArgv with system-prompt-file + resume + extras → --continue (NOT --resume <uuid>)', () => {
+    // resume uses `--continue` (continue the cwd's most-recent session), NOT
+    // `--resume <uuid>` — in claude 2.1.169 `--resume <arg>` is a search query, not a
+    // session-id. resumeRef is set by the daemon but no longer consumed by the launch.
     const argv = claudeAdapter.buildArgv(
-      spec({ systemPromptFile: '/tmp/sp.md', resumeRef: 'uuid-1', extraArgs: ['--foo'] }),
+      spec({ systemPromptFile: '/tmp/sp.md', resume: true, resumeRef: 'uuid-1', extraArgs: ['--foo'] }),
       cfg,
     )
     expect(argv).toEqual([
@@ -132,10 +135,17 @@ describe('claudeAdapter', () => {
       'AskUserQuestion',
       '--system-prompt-file',
       '/tmp/sp.md',
-      '--resume',
-      'uuid-1',
+      '--continue',
       '--foo',
     ])
+    expect(argv).not.toContain('--resume')
+    expect(argv).not.toContain('uuid-1')
+  })
+
+  test('buildArgv: resume FALSE (fresh) → no --continue / --resume', () => {
+    const argv = claudeAdapter.buildArgv(spec({ resume: false, resumeRef: 'uuid-1' }), cfg)
+    expect(argv).not.toContain('--continue')
+    expect(argv).not.toContain('--resume')
   })
 
   test('buildArgv carries NO currency (no marketplace/plugin tokens)', () => {
@@ -153,12 +163,23 @@ describe('claudeAdapter', () => {
     expect(claudeAdapter.isInputReady('❯ just a prompt')).toBe(false)
   })
 
-  test('bootDialogKeys: a dialog → [Enter], clean pane → null', () => {
+  test('bootDialogKeys: proceed-modals → [Enter]; clean/load pane → null', () => {
     expect(claudeAdapter.bootDialogKeys('I am using this for local development')).toEqual(['Enter'])
-    expect(claudeAdapter.bootDialogKeys('Resuming the full session')).toEqual(['Enter'])
+    expect(claudeAdapter.bootDialogKeys('trust this folder')).toEqual(['Enter'])
+    expect(claudeAdapter.bootDialogKeys('Allow external CLAUDE.md file imports?')).toEqual(['Enter'])
+    // the post-select "Resuming…" load state is NOT a modal to Enter — just wait.
+    expect(claudeAdapter.bootDialogKeys('Resuming the full session')).toBeNull()
     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('permissionDialog: proceed prompt → active, [Enter]', () => {
     expect(claudeAdapter.permissionDialogActive('Do you want to proceed?')).toBe(true)
     expect(claudeAdapter.permissionDialogActive('nothing')).toBe(false)

package/src/lifecycle/lifecycle.test.ts

@@ -78,17 +78,25 @@ describe('resolveWakeRuntime (H5)', () => {
 // H4 — isLaunchdManaged on the LIVE fleet (read-only)
 // ─────────────────────────────────────────────────────────────────────────────
 
-describe('isLaunchdManaged (H4 detector, live read-only)', () => {
-  test('a launchd-managed peer (timer has com.iapeer.timer.plist) → true', () => {
-    // Post foundation-migration the always-on INFRA peers (timer/watcher/arthur) keep
-    // their com.iapeer.<p>.plist; the daemon must treat them READ-ONLY (never
-    // wake/reap). This proves the detector fires on the live fleet. (boris and the
-    // agent peers became warm-on-demand — plist relocated — so they are NOT managed.)
-    expect(isLaunchdManaged('timer')).toBe(true)
+describe('isLaunchdManaged (H4 detector)', () => {
+  // HERMETIC: point the detector at a TEMP LaunchAgents dir (IAPEER_LAUNCHAGENTS_DIR),
+  // never the live ~/Library/LaunchAgents — so the test fires identically on CI and any
+  // host, not just one where the timer peer happens to be installed.
+  let laDir: string
+  beforeEach(() => {
+    laDir = mkdtempSync(join(tmpdir(), 'iapeer-h4-'))
+  })
+  afterEach(() => {
+    rmSync(laDir, { recursive: true, force: true })
+  })
+
+  test('a com.iapeer.<p>.plist present in the LaunchAgents dir → true (read-only managed)', () => {
+    writeFileSync(join(laDir, 'com.iapeer.timer.plist'), '')
+    expect(isLaunchdManaged('timer', { IAPEER_LAUNCHAGENTS_DIR: laDir } as NodeJS.ProcessEnv)).toBe(true)
   })
 
-  test('a made-up daemon-owned name (no plist) → false', () => {
-    expect(isLaunchdManaged('iapeer-throwaway-no-plist-xyz')).toBe(false)
+  test('no plist in the dir → false (daemon-owned, not launchd-managed)', () => {
+    expect(isLaunchdManaged('iapeer-throwaway-no-plist-xyz', { IAPEER_LAUNCHAGENTS_DIR: laDir } as NodeJS.ProcessEnv)).toBe(false)
   })
 })
 

package/src/update/index.ts

@@ -20,22 +20,27 @@
 // unit-testable with no network and no launchctl; the defaults are the real impls.
 
 import { spawnSync } from 'child_process'
+import { connect } from 'net'
 import { IapError } from '../core/errors.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
 import { kickstartDaemon, type DaemonRestartResult } from '../launch/launchd.ts'
+import { defaultDaemonSocketPath } from '../daemon/index.ts'
 
 /** The npm package the foundation publishes / updates from. */
 export const IAPEER_PACKAGE = '@agfpd/iapeer'
 
 export interface UpdateDeps {
   env?: NodeJS.ProcessEnv
-  /** Reinstall + restart even when already at the latest version. */
+  /** Reinstall + restart even when already at the desired version. */
   force?: boolean
   /** The currently-installed version (default: this binary's baked IAPEER_VERSION). */
   currentVersion?: string
-  /** Resolve the latest published version (default: `npm view`). Returns null on
-   *  any failure (offline / registry error / non-semver) — update then fails loud. */
-  fetchLatest?: (env: NodeJS.ProcessEnv) => string | null
+  /** Install this EXACT version instead of latest (one-shot pin / downgrade /
+   *  recover-to-a-known-good deeper than the single .prev). Omit → latest. */
+  targetVersion?: string
+  /** Resolve a spec ('latest' or an exact 'X.Y.Z') to the concrete published version it
+   *  names, or null on a miss / npm error (default: `npm view @agfpd/iapeer@<spec> version`). */
+  resolveVersion?: (spec: string, env: NodeJS.ProcessEnv) => string | null
   /** Pull + rebuild the binary for `version` (default: `npx @agfpd/iapeer@<v> install`).
    *  Returns true on success. */
   runInstall?: (version: string, env: NodeJS.ProcessEnv) => boolean
@@ -57,11 +62,83 @@ export interface UpdateResult {
   reason?: string
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Post-restart health — verify the daemon actually came up, not just that
+// `launchctl kickstart` exited 0. A new binary that fails to boot would otherwise
+// be reported as a successful "restarted". The probe connects to the daemon's unix
+// socket (the always-present same-uid listener it binds right before printing READY);
+// a refused connection = not serving. Requires a short STREAK of successes so a
+// bind-then-crash flap reads as unhealthy, not healthy.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface HealthResult {
+  healthy: boolean
+  detail?: string
+}
+
+export interface HealthOptions {
+  env?: NodeJS.ProcessEnv
+  timeoutMs?: number
+  intervalMs?: number
+  /** Consecutive successful probes required to call it healthy (flap guard). */
+  needConsecutive?: number
+  /** Injectable probe (tests). Default: connect to the daemon's unix socket. */
+  probe?: () => Promise<boolean>
+}
+
+/** True iff a connection to the daemon's router socket is accepted (it is serving). */
+function probeDaemonSocket(env: NodeJS.ProcessEnv): Promise<boolean> {
+  const path = defaultDaemonSocketPath({ env })
+  return new Promise(resolve => {
+    let settled = false
+    const done = (v: boolean): void => {
+      if (settled) return
+      settled = true
+      try {
+        sock.destroy()
+      } catch {
+        /* already gone */
+      }
+      resolve(v)
+    }
+    const sock = connect({ path })
+    sock.once('connect', () => done(true))
+    sock.once('error', () => done(false))
+    sock.setTimeout(1000, () => done(false))
+  })
+}
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+
+/**
+ * Poll the daemon until it is healthy (its socket accepts `needConsecutive`
+ * connections in a row) or `timeoutMs` elapses. Under IAPEER_TEST_SANDBOX with no
+ * injected probe it short-circuits healthy (never touches a real socket).
+ */
+export async function waitForDaemonHealthy(opts: HealthOptions = {}): Promise<HealthResult> {
+  const env = opts.env ?? process.env
+  if (env.IAPEER_TEST_SANDBOX === '1' && !opts.probe) return { healthy: true, detail: 'skipped-sandbox' }
+  const probe = opts.probe ?? (() => probeDaemonSocket(env))
+  const timeoutMs = opts.timeoutMs ?? 15_000
+  const intervalMs = opts.intervalMs ?? 400
+  const need = opts.needConsecutive ?? 2
+  const deadline = Date.now() + timeoutMs
+  let streak = 0
+  for (;;) {
+    streak = (await probe()) ? streak + 1 : 0
+    if (streak >= need) return { healthy: true }
+    if (Date.now() >= deadline) return { healthy: false, detail: `daemon did not become healthy within ${timeoutMs}ms (socket not accepting connections)` }
+    await sleep(intervalMs)
+  }
+}
+
 const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/
 
-/** Default latest-resolver: `npm view @agfpd/iapeer version`. */
-function defaultFetchLatest(env: NodeJS.ProcessEnv): string | null {
-  const r = spawnSync('npm', ['view', IAPEER_PACKAGE, 'version'], { encoding: 'utf8', env })
+/** Default version resolver: `npm view @agfpd/iapeer@<spec> version` (spec = 'latest'
+ *  or an exact 'X.Y.Z'). Returns the concrete version, or null on a miss / npm error
+ *  (a non-existent pinned version exits non-zero → null → a loud "not found"). */
+function defaultResolveVersion(spec: string, env: NodeJS.ProcessEnv): string | null {
+  const r = spawnSync('npm', ['view', `${IAPEER_PACKAGE}@${spec}`, 'version'], { encoding: 'utf8', env })
   if (r.status !== 0) return null
   const v = (r.stdout ?? '').trim()
   return SEMVER_RE.test(v) ? v : null
@@ -86,19 +163,29 @@ function defaultRunInstall(version: string, env: NodeJS.ProcessEnv): boolean {
 export function updateIapeer(deps: UpdateDeps = {}): UpdateResult {
   const env = deps.env ?? process.env
   const from = deps.currentVersion ?? IAPEER_VERSION
-  const fetchLatest = deps.fetchLatest ?? defaultFetchLatest
+  const resolve = deps.resolveVersion ?? defaultResolveVersion
+  const pinned = deps.targetVersion != null && deps.targetVersion !== ''
+  const spec = pinned ? deps.targetVersion! : 'latest'
 
-  const latest = fetchLatest(env)
-  if (!latest) {
-    return { status: 'failed', from, reason: `could not resolve the latest ${IAPEER_PACKAGE} version from npm (offline / registry error)` }
+  // Resolve the DESIRED version (latest, or the exact pinned version) — and, for a pin,
+  // VALIDATE it exists (a non-existent version → null → fail loud, never an npx error).
+  const desired = resolve(spec, env)
+  if (!desired) {
+    return {
+      status: 'failed',
+      from,
+      reason: pinned
+        ? `version "${deps.targetVersion}" not found on npm`
+        : `could not resolve the latest ${IAPEER_PACKAGE} version from npm (offline / registry error)`,
+    }
   }
-  if (latest === from && !deps.force) {
-    return { status: 'already-latest', from, latest }
+  if (desired === from && !deps.force) {
+    return { status: 'already-latest', from, latest: desired }
   }
 
   const runInstall = deps.runInstall ?? defaultRunInstall
-  if (!runInstall(latest, env)) {
-    return { status: 'failed', from, latest, reason: `\`npx ${IAPEER_PACKAGE}@${latest} install\` failed` }
+  if (!runInstall(desired, env)) {
+    return { status: 'failed', from, latest: desired, reason: `\`npx ${IAPEER_PACKAGE}@${desired} install\` failed` }
   }
 
   const restart = deps.restartDaemon ?? kickstartDaemon
@@ -106,8 +193,8 @@ export function updateIapeer(deps: UpdateDeps = {}): UpdateResult {
   return {
     status: 'updated',
     from,
-    to: latest,
-    latest,
+    to: desired,
+    latest: desired,
     daemon: d.state,
     reason: d.state === 'failed' ? `binary updated but daemon restart failed: ${d.detail ?? ''}`.trim() : undefined,
   }

package/src/update/update.test.ts

@@ -4,25 +4,31 @@
 // exercised too (a test must never npx-install over the prod binary).
 
 import { describe, expect, test } from 'bun:test'
-import { IAPEER_VERSION, updateIapeer } from '../index.ts'
+import { IAPEER_VERSION, updateIapeer, waitForDaemonHealthy } from '../index.ts'
 import type { DaemonRestartResult } from '../launch/launchd.ts'
 
 const restarted = (): DaemonRestartResult => ({ state: 'restarted' })
 
-/** A deps bundle with call-tracking spies. */
+/** A deps bundle with call-tracking spies. `latest` is what the resolver returns for
+ *  the spec (latest OR a pinned `target`); null simulates "not found / unreachable". */
 function harness(opts: {
   current: string
   latest: string | null
+  target?: string
   installOk?: boolean
   restart?: DaemonRestartResult
   force?: boolean
 }) {
-  const calls = { install: [] as string[], restart: 0 }
+  const calls = { install: [] as string[], restart: 0, resolved: [] as string[] }
   const result = updateIapeer({
     env: { IAPEER_TEST_SANDBOX: '1' },
     force: opts.force,
     currentVersion: opts.current,
-    fetchLatest: () => opts.latest,
+    targetVersion: opts.target,
+    resolveVersion: spec => {
+      calls.resolved.push(spec)
+      return opts.latest
+    },
     runInstall: v => {
       calls.install.push(v)
       return opts.installOk ?? true
@@ -62,6 +68,36 @@ describe('updateIapeer — version gate', () => {
     expect(calls.install).toEqual(['0.3.0']) // installs latest, not current
     expect(calls.restart).toBe(1)
   })
+
+  test('no target → resolves the "latest" spec', () => {
+    const { calls } = harness({ current: '0.2.2', latest: '0.3.0' })
+    expect(calls.resolved).toEqual(['latest'])
+  })
+})
+
+describe('updateIapeer — pinned version (one-shot target)', () => {
+  test('pin to an exact version → resolves THAT spec and installs it', () => {
+    const { result, calls } = harness({ current: '0.2.4', target: '0.2.2', latest: '0.2.2' })
+    expect(calls.resolved).toEqual(['0.2.2']) // resolves the pinned spec, not "latest"
+    expect(result.status).toBe('updated')
+    expect(result.from).toBe('0.2.4')
+    expect(result.to).toBe('0.2.2') // a DOWNGRADE — deeper recovery than the single .prev
+    expect(calls.install).toEqual(['0.2.2'])
+  })
+
+  test('pinned version already installed → already-at, no install', () => {
+    const { result, calls } = harness({ current: '0.2.2', target: '0.2.2', latest: '0.2.2' })
+    expect(result.status).toBe('already-latest')
+    expect(calls.install).toEqual([])
+  })
+
+  test('pinned version not found on npm → failed (not an npx error)', () => {
+    const { result, calls } = harness({ current: '0.2.4', target: '9.9.9', latest: null })
+    expect(result.status).toBe('failed')
+    expect(result.reason).toMatch(/"9\.9\.9" not found on npm/i)
+    expect(calls.install).toEqual([])
+    expect(calls.restart).toBe(0)
+  })
 })
 
 describe('updateIapeer — failure paths', () => {
@@ -108,7 +144,7 @@ describe('updateIapeer — real-installer sandbox guard', () => {
       updateIapeer({
         env: { IAPEER_TEST_SANDBOX: '1' },
         currentVersion: '0.2.2',
-        fetchLatest: () => '0.3.0',
+        resolveVersion: () => '0.3.0',
         // runInstall NOT injected → exercises the real defaultRunInstall guard.
         restartDaemon: restarted,
       }),
@@ -121,3 +157,35 @@ describe('IAPEER_VERSION', () => {
     expect(IAPEER_VERSION).toMatch(/^\d+\.\d+\.\d+/)
   })
 })
+
+/** A probe returning the given sequence (repeats the last element once exhausted). */
+function seqProbe(seq: boolean[]): () => Promise<boolean> {
+  let i = 0
+  return () => Promise.resolve(seq[Math.min(i++, seq.length - 1)])
+}
+
+describe('waitForDaemonHealthy', () => {
+  test('two consecutive successes → healthy', async () => {
+    const h = await waitForDaemonHealthy({ probe: seqProbe([true, true]), needConsecutive: 2, timeoutMs: 1000, intervalMs: 1 })
+    expect(h.healthy).toBe(true)
+  })
+
+  test('a single bind-then-crash flap does NOT read as healthy (streak resets)', async () => {
+    // true, false, true, true → first success is wiped by the false; only the trailing
+    // pair (true,true) satisfies needConsecutive=2.
+    const h = await waitForDaemonHealthy({ probe: seqProbe([true, false, true, true]), needConsecutive: 2, timeoutMs: 1000, intervalMs: 1 })
+    expect(h.healthy).toBe(true)
+  })
+
+  test('never responds within the window → unhealthy with a detail', async () => {
+    const h = await waitForDaemonHealthy({ probe: seqProbe([false]), needConsecutive: 2, timeoutMs: 40, intervalMs: 5 })
+    expect(h.healthy).toBe(false)
+    expect(h.detail).toMatch(/did not become healthy/i)
+  })
+
+  test('IAPEER_TEST_SANDBOX with no injected probe → skipped healthy (never hits a real socket)', async () => {
+    const h = await waitForDaemonHealthy({ env: { IAPEER_TEST_SANDBOX: '1' } as NodeJS.ProcessEnv })
+    expect(h.healthy).toBe(true)
+    expect(h.detail).toBe('skipped-sandbox')
+  })
+})