@agfpd/iapeer 0.2.10 → 0.2.12

package/src/lifecycle/queue.ts

@@ -0,0 +1,159 @@
+// Ephemeral serial queue (wake_policy:"ephemeral" M3) — per-peer disk FIFO of
+// pending tasks for a stateless worker. Deliveries to an ephemeral target are
+// NEVER injected into a live session (one task = one clean context window =
+// the whole point of the policy); they are ALWAYS enqueued here, and the drain
+// (drainEphemeralQueue in index.ts) feeds the worker one task per fresh session.
+//
+// Layout: `<stateDir>/<identity>.queue/<seq>` — one JSON file per task
+// ({ task, topic? }), zero-padded numeric names so lexicographic order IS the
+// FIFO order. Durable by construction: the queue survives a daemon restart and
+// is drained by the supervise tick (the same scan that retries a failed wake).
+//
+// Concurrency: the daemon is the main writer, but a direct CLI `iap send`
+// (daemon down) can race it from another process. Enqueue is therefore
+// EXCLUSIVE-CREATE: write a temp file, then linkSync it to the next seq —
+// linkSync fails with EEXIST on a taken name (atomic on POSIX), so two
+// concurrent enqueues can never share a seq; the loser just advances. Content
+// is complete before the link lands (no partial reads).
+//
+// Retry semantics (boris acceptance (b)): the consumer PEEKS (reads without
+// removing), wakes the worker, and removes the item ONLY on READY — a failed
+// wake leaves the task at the head for the next supervise-tick drain. See
+// drainEphemeralQueue.
+
+import { linkSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import type { LifecycleConfig } from './index.ts'
+
+/** One queued task for an ephemeral worker. */
+export interface EphemeralQueueItem {
+  /** The routed envelope — becomes the boot first-message of the fresh session. */
+  task: string
+  /** Optional topic (threading; recorded by the wake as the session topic). */
+  topic?: string
+}
+
+/** A peeked item: the queue position (for the later remove) plus the payload. */
+export interface PeekedQueueItem extends EphemeralQueueItem {
+  seq: string
+}
+
+export function ephemeralQueueDir(cfg: LifecycleConfig, identity: string): string {
+  return join(cfg.stateDir, `${identity}.queue`)
+}
+
+const SEQ_PAD = 6
+
+function listSeqs(dir: string): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return [] // no dir yet → empty queue
+  }
+  // Only the numbered items — temp files (.tmp-*) and strays are not queue entries.
+  return entries.filter(name => /^\d+$/.test(name)).sort()
+}
+
+/** Queue depth (pending tasks). 0 for a missing dir. */
+export function ephemeralQueueDepth(cfg: LifecycleConfig, identity: string): number {
+  return listSeqs(ephemeralQueueDir(cfg, identity)).length
+}
+
+/**
+ * Append a task to the identity's FIFO. Returns the depth AFTER the append
+ * (≥1 — usable as the "qd" observability field). Exclusive-create: safe against
+ * a concurrent enqueue from another process. Throws only on a real FS failure
+ * (the caller surfaces it as a delivery error — an un-enqueued task must NOT be
+ * reported queued).
+ */
+export function enqueueEphemeralTask(
+  cfg: LifecycleConfig,
+  identity: string,
+  item: EphemeralQueueItem,
+): number {
+  const dir = ephemeralQueueDir(cfg, identity)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const tmp = join(dir, `.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  writeFileSync(tmp, JSON.stringify({ task: item.task, ...(item.topic ? { topic: item.topic } : {}) }), {
+    mode: 0o600,
+  })
+  try {
+    // Next seq = max existing + 1; on an EEXIST race, advance and retry.
+    let seq = (() => {
+      const seqs = listSeqs(dir)
+      return seqs.length ? parseInt(seqs[seqs.length - 1]!, 10) + 1 : 1
+    })()
+    // Bounded retry: a competitor can win a name at most once per its own enqueue.
+    for (let attempt = 0; attempt < 1000; attempt++, seq++) {
+      const target = join(dir, String(seq).padStart(SEQ_PAD, '0'))
+      try {
+        linkSync(tmp, target) // atomic exclusive-create (EEXIST when taken)
+        return listSeqs(dir).length
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+      }
+    }
+    throw new Error(`ephemeral queue enqueue: could not claim a seq for ${identity} after 1000 attempts`)
+  } finally {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/**
+ * Read the HEAD of the FIFO without removing it (retry semantics: the item is
+ * removed only after the wake went READY — removeEphemeralTask). null on empty.
+ * A corrupt head (unparseable JSON) is dropped with its slot — a poison task
+ * must not wedge the whole queue — and the next item (if any) is returned.
+ */
+export function peekEphemeralTask(cfg: LifecycleConfig, identity: string): PeekedQueueItem | null {
+  const dir = ephemeralQueueDir(cfg, identity)
+  for (const seq of listSeqs(dir)) {
+    const path = join(dir, seq)
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+      if (typeof raw.task === 'string' && raw.task.length > 0) {
+        return { seq, task: raw.task, topic: typeof raw.topic === 'string' ? raw.topic : undefined }
+      }
+    } catch {
+      /* unreadable/corrupt → drop the slot below */
+    }
+    try {
+      rmSync(path, { force: true }) // poison/corrupt item: drop, do not wedge the queue
+    } catch {
+      return null // cannot even drop it — give up this round, retry next tick
+    }
+  }
+  return null
+}
+
+/** Remove a consumed item (after its wake went READY). Idempotent. */
+export function removeEphemeralTask(cfg: LifecycleConfig, identity: string, seq: string): void {
+  try {
+    rmSync(join(ephemeralQueueDir(cfg, identity), seq), { force: true })
+  } catch {
+    /* already gone */
+  }
+}
+
+/** Identities with a non-empty queue (the supervise-tick drain scan; also the
+ *  drain-on-start surface — the queue is durable across daemon restarts). */
+export function listQueuedIdentities(cfg: LifecycleConfig): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(cfg.stateDir)
+  } catch {
+    return []
+  }
+  const out: string[] = []
+  for (const name of entries) {
+    if (!name.endsWith('.queue')) continue
+    const identity = name.slice(0, -'.queue'.length)
+    if (listSeqs(join(cfg.stateDir, name)).length > 0) out.push(identity)
+  }
+  return out.sort()
+}

package/src/onboard/memory.test.ts

@@ -0,0 +1,157 @@
+// onboardMemoryProvider — the host-phase memory-slot step (контракт «Слот
+// памяти»). Default-YES, report-only for the exit code; the PROVIDER writes the
+// slot declaration (the step verifies it did). All writes under a temp
+// IAPEER_ROOT — never the live host.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { coreKnownInitArgs, onboardMemoryProvider, DEFAULT_MEMORY_PACKAGE } from './memory.ts'
+import { memoryProviderPath } from '../status/index.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-memstep-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+function envFor(root: string): NodeJS.ProcessEnv {
+  return { IAPEER_ROOT: root } as NodeJS.ProcessEnv
+}
+
+const SLOT = {
+  provider: 'iapeer-memory',
+  package: DEFAULT_MEMORY_PACKAGE,
+  version: '0.1.0',
+  registeredAt: '2026-06-10T00:00:00Z',
+}
+
+function registry(root: string, naturals: string[]): void {
+  writeFileSync(
+    join(root, 'peers-profiles.json'),
+    JSON.stringify({
+      version: 2,
+      peers: [
+        ...naturals.map(p => ({ personality: p, runtime: 'telegram', runtimes: ['telegram'], description: '', intelligence: 'natural', cwd: `/tmp/${p}` })),
+        { personality: 'bot', runtime: 'claude', runtimes: ['claude'], description: '', intelligence: 'artificial', cwd: '/tmp/bot' },
+      ],
+    }),
+  )
+}
+
+describe('coreKnownInitArgs (the EXHAUSTIVE v1 passthrough list)', () => {
+  test('exactly one natural peer → --human <personality>', () => {
+    const root = mkTmp()
+    registry(root, ['arthur'])
+    expect(coreKnownInitArgs(envFor(root))).toEqual(['--human', 'arthur'])
+  })
+  test('zero or many naturals → pass NOTHING (the provider asks itself)', () => {
+    const none = mkTmp()
+    registry(none, [])
+    expect(coreKnownInitArgs(envFor(none))).toEqual([])
+    const many = mkTmp()
+    registry(many, ['arthur', 'maria'])
+    expect(coreKnownInitArgs(envFor(many))).toEqual([])
+  })
+  test('legacy intelligence "human" normalizes to natural (read-compat)', () => {
+    const root = mkTmp()
+    writeFileSync(
+      join(root, 'peers-profiles.json'),
+      JSON.stringify({ version: 2, peers: [{ personality: 'arthur', runtime: 'telegram', runtimes: ['telegram'], description: '', intelligence: 'human', cwd: '/tmp/a' }] }),
+    )
+    expect(coreKnownInitArgs(envFor(root))).toEqual(['--human', 'arthur'])
+  })
+  test('no registry at all → [] (never throws)', () => {
+    expect(coreKnownInitArgs(envFor(mkTmp()))).toEqual([])
+  })
+})
+
+describe('onboardMemoryProvider', () => {
+  test('--no-memory → skipped-flag, init never invoked', async () => {
+    const root = mkTmp()
+    let invoked = 0
+    const r = await onboardMemoryProvider({
+      skip: true,
+      env: envFor(root),
+      runInit: () => ((invoked++), { status: 0, unavailable: false }),
+    })
+    expect(r.state).toBe('skipped-flag')
+    expect(invoked).toBe(0)
+  })
+
+  test('same package already in the slot → already (idempotent no-op, no init call)', async () => {
+    const root = mkTmp()
+    writeFileSync(memoryProviderPath(envFor(root)), JSON.stringify(SLOT))
+    let invoked = 0
+    const r = await onboardMemoryProvider({
+      env: envFor(root),
+      runInit: () => ((invoked++), { status: 0, unavailable: false }),
+    })
+    expect(r.state).toBe('already')
+    expect(r.provider?.provider).toBe('iapeer-memory')
+    expect(invoked).toBe(0)
+  })
+
+  test('slot occupied by ANOTHER provider → refused-foreign (never silent overwrite)', async () => {
+    const root = mkTmp()
+    writeFileSync(memoryProviderPath(envFor(root)), JSON.stringify({ ...SLOT, provider: 'other-mem', package: '@x/other' }))
+    const r = await onboardMemoryProvider({ env: envFor(root), runInit: () => ({ status: 0, unavailable: false }) })
+    expect(r.state).toBe('refused-foreign')
+    expect(r.detail).toMatch(/occupied .*other-mem.*uninstall/)
+  })
+
+  test('dry-run → reports the exact would-be command incl. --human passthrough', async () => {
+    const root = mkTmp()
+    registry(root, ['arthur'])
+    const r = await onboardMemoryProvider({ dryRun: true, env: envFor(root) })
+    expect(r.state).toBe('dry-run')
+    expect(r.detail).toBe(`would run: npx -y ${DEFAULT_MEMORY_PACKAGE} init --human arthur`)
+  })
+
+  test('package unavailable → skipped-unavailable (SOFT skip — release order never blocks onboard)', async () => {
+    const root = mkTmp()
+    registry(root, [])
+    const r = await onboardMemoryProvider({ env: envFor(root), runInit: () => ({ status: 1, unavailable: true }) })
+    expect(r.state).toBe('skipped-unavailable')
+    expect(r.detail).toMatch(/not available/)
+  })
+
+  test('init ok + provider declared the slot → installed (slot read back)', async () => {
+    const root = mkTmp()
+    registry(root, ['arthur'])
+    const env = envFor(root)
+    const calls: string[][] = []
+    const r = await onboardMemoryProvider({
+      env,
+      runInit: (pkg, args) => {
+        calls.push([pkg, ...args])
+        writeFileSync(memoryProviderPath(env), JSON.stringify(SLOT)) // the PROVIDER writes the slot
+        return { status: 0, unavailable: false }
+      },
+    })
+    expect(r.state).toBe('installed')
+    expect(r.provider?.version).toBe('0.1.0')
+    expect(calls).toEqual([[DEFAULT_MEMORY_PACKAGE, 'init', '--human', 'arthur']])
+  })
+
+  test('init ok but slot NOT declared → provider-init-failed (its contract duty, surfaced)', async () => {
+    const root = mkTmp()
+    registry(root, [])
+    const r = await onboardMemoryProvider({ env: envFor(root), runInit: () => ({ status: 0, unavailable: false }) })
+    expect(r.state).toBe('provider-init-failed')
+    expect(r.detail).toMatch(/did not declare/)
+  })
+
+  test('init non-zero (e.g. non-tty refusal) → provider-init-failed with the exit code', async () => {
+    const root = mkTmp()
+    registry(root, [])
+    const r = await onboardMemoryProvider({ env: envFor(root), runInit: () => ({ status: 2, unavailable: false }) })
+    expect(r.state).toBe('provider-init-failed')
+    expect(r.detail).toMatch(/exited 2/)
+  })
+})

package/src/onboard/memory.ts

@@ -0,0 +1,124 @@
+// Memory-slot onboard step (docs/Слот памяти — контракт memory provider.md,
+// agreed with iapeer-memory + boris 10.06). Host-phase, optional, DEFAULT-YES:
+// install the default memory provider package and run ITS OWN init-verb — the
+// provider writes the slot declaration and deploys its surfaces; the core never
+// writes the slot itself. The provider OWNS the install questions (two-mode
+// init): we run it with INHERITED stdio so its tty interactive happens inside
+// the onboard host phase, exactly once. The core passes as flags ONLY facts it
+// owns by its own contracts — v1 list is exactly one: `--human <personality>`
+// when EXACTLY ONE natural peer is registered.
+//
+// Outcome semantics: this step NEVER fails the onboard exit code — an empty
+// slot is a fully valid state regardless of why (skipped / package not yet
+// published / provider refused non-tty). Outcomes are reported, not enforced.
+
+import { spawnSync } from 'child_process'
+import { normalizeIntelligenceValue } from '../core/constants.ts'
+import { readPeersIndex } from '../registry/index.ts'
+import { readMemoryProvider, type MemoryProvider } from '../status/index.ts'
+
+/** The distribution default provider (Артур: memory is a first-class core option). */
+export const DEFAULT_MEMORY_PACKAGE = '@agfpd/iapeer-memory'
+
+export interface MemoryOnboardOptions {
+  /** --no-memory: skip the step entirely. */
+  skip?: boolean
+  /** --memory <pkg>: override the provider package (default @agfpd/iapeer-memory). */
+  package?: string
+  dryRun?: boolean
+  env?: NodeJS.ProcessEnv
+  /** Injectable runner (tests). Default: availability probe + `npx -y <pkg> init …`
+   *  with inherited stdio. */
+  runInit?: (pkg: string, args: string[], env: NodeJS.ProcessEnv) => { status: number | null; unavailable: boolean }
+}
+
+export interface MemoryOnboardResult {
+  state:
+    | 'installed' // provider init succeeded and declared the slot
+    | 'already' // slot already occupied by the SAME package — idempotent no-op
+    | 'skipped-flag' // --no-memory
+    | 'skipped-unavailable' // package not published / no network — soft skip (contract)
+    | 'refused-foreign' // slot occupied by ANOTHER provider — explicit refusal
+    | 'provider-init-failed' // provider init ran and exited non-zero / declared nothing
+    | 'dry-run'
+  provider: MemoryProvider | null
+  detail?: string
+}
+
+function defaultRunInit(
+  pkg: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+): { status: number | null; unavailable: boolean } {
+  // Availability probe FIRST (cheap, side-effect-free): an unpublished package /
+  // no network → soft-skip per the contract (the provider's release order must
+  // never block the core's onboard).
+  const probe = spawnSync('npm', ['view', `${pkg}@latest`, 'version'], { encoding: 'utf8', env })
+  if (probe.status !== 0) return { status: probe.status, unavailable: true }
+  // INHERITED stdio — the provider owns its install questions (tty interactive
+  // happens here, once). npx bin-name nuance (cf. the 0.2.9 update грабли): with
+  // the provider bin already on PATH npx runs the INSTALLED one — acceptable for
+  // an idempotent init (unlike the self-update case where it was a structural bug).
+  const r = spawnSync('npx', ['-y', pkg, ...args], { stdio: 'inherit', env })
+  return { status: r.status, unavailable: false }
+}
+
+/** The exhaustive v1 list of core-known facts passed to the provider init:
+ *  `--human <personality>` iff EXACTLY ONE natural peer is registered (the core
+ *  has no separate owner-name config — the owner IS the natural peer). */
+export function coreKnownInitArgs(env: NodeJS.ProcessEnv = process.env): string[] {
+  try {
+    const naturals = readPeersIndex({ env }).peers.filter(
+      p => normalizeIntelligenceValue(p.intelligence) === 'natural',
+    )
+    return naturals.length === 1 ? ['--human', naturals[0]!.personality] : []
+  } catch {
+    return [] // no registry / unreadable → pass nothing, the provider asks itself
+  }
+}
+
+export async function onboardMemoryProvider(opts: MemoryOnboardOptions = {}): Promise<MemoryOnboardResult> {
+  const env = opts.env ?? process.env
+  const pkg = opts.package?.trim() || DEFAULT_MEMORY_PACKAGE
+  const existing = readMemoryProvider(env)
+  if (opts.skip) return { state: 'skipped-flag', provider: existing }
+  if (existing) {
+    if (existing.package === pkg) return { state: 'already', provider: existing }
+    // Never silently install over an occupied slot (contract: ЗАПРЕЩЕНО).
+    return {
+      state: 'refused-foreign',
+      provider: existing,
+      detail: `slot is occupied by "${existing.provider}" (${existing.package}) — uninstall it first`,
+    }
+  }
+  const args = ['init', ...coreKnownInitArgs(env)]
+  if (opts.dryRun) {
+    return { state: 'dry-run', provider: null, detail: `would run: npx -y ${pkg} ${args.join(' ')}` }
+  }
+  const run = opts.runInit ?? defaultRunInit
+  const r = run(pkg, args, env)
+  if (r.unavailable) {
+    return {
+      state: 'skipped-unavailable',
+      provider: null,
+      detail: `${pkg} is not available (not published yet / no network) — install later: npx ${pkg} init`,
+    }
+  }
+  if (r.status !== 0) {
+    return {
+      state: 'provider-init-failed',
+      provider: readMemoryProvider(env),
+      detail: `provider init exited ${r.status ?? 'null'}`,
+    }
+  }
+  // The PROVIDER declares the slot; verify it actually did (its contract duty).
+  const after = readMemoryProvider(env)
+  if (!after) {
+    return {
+      state: 'provider-init-failed',
+      provider: null,
+      detail: 'provider init succeeded but did not declare the slot (memory-provider.json missing)',
+    }
+  }
+  return { state: 'installed', provider: after }
+}

package/src/provision/index.ts

@@ -91,6 +91,27 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
     runtimeBin,
     warn: opts.warn,
   })
+  // wake_policy:"ephemeral" sanity (M2 edge cases — warn, don't refuse: the policy
+  // lives in the hand-editable local profile, provision just surfaces the mismatch):
+  //   • + interfaces.telegram: ephemeral WINS in resolveWakeMode (explicit policy
+  //     beats the inferred human type), so a human dialogue channel would die-after-
+  //     reply and never resume — almost certainly a config mistake.
+  //   • + infra (always-on) runtime: launchd KeepAlive owns the session (H4 read-only)
+  //     — the daemon never wakes/reaps it, so the ephemeral policy is INERT.
+  if (profile.wake_policy === 'ephemeral') {
+    if (profile.interfaces?.telegram != null) {
+      opts.warn?.(
+        `peer "${profile.personality}" declares BOTH wake_policy:"ephemeral" AND interfaces.telegram — ` +
+          `ephemeral wins (always-fresh, die-after-reply); a human telegram dialogue should not be ephemeral`,
+      )
+    }
+    if (isInfraRuntime(opts.runtime)) {
+      opts.warn?.(
+        `peer "${profile.personality}" declares wake_policy:"ephemeral" on always-on infra runtime ` +
+          `"${opts.runtime}" — launchd owns the session (H4), the daemon never wakes/reaps it, the policy is inert`,
+      )
+    }
+  }
   // 2) registry entry — without it the daemon does not see the peer (tool-list,
   //    caller resolution, wake-on-miss findPeer all read peers-profiles.json).
   await upsertPeer(

package/src/provision/provision.test.ts

@@ -3,7 +3,7 @@
 // IAPEER_LAUNCHAGENTS_DIR temp dirs so the suite never touches the live fleet.
 
 import { afterEach, describe, expect, test } from 'bun:test'
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { provisionPeer } from './index.ts'
@@ -102,3 +102,59 @@ describe('provisionPeer', () => {
     expect(findPeer(readPeersIndex({ env }), 'timer')?.cwd).toBe(cwd)
   })
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// wake_policy:"ephemeral" provision warnings (M2 edge cases — warn, not refuse)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('provisionPeer ephemeral warnings', () => {
+  test('ephemeral + interfaces.telegram → WARN (ephemeral wins; human dialogue should not die-after-reply)', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const cwd = join(root, 'wtg')
+    // pre-existing profile (provision returns it unchanged) carrying the bad combo
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({
+        personality: 'wtg',
+        runtime: 'claude',
+        intelligence: 'natural',
+        interfaces: { telegram: { user_id: 1 } },
+        wake_policy: 'ephemeral',
+      }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(warns.some(w => /ephemeral/.test(w) && /telegram/.test(w))).toBe(true)
+  })
+
+  test('plain ephemeral worker (claude, no telegram) → NO ephemeral warn', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const cwd = join(root, 'weph')
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({ personality: 'weph', runtime: 'claude', wake_policy: 'ephemeral' }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(warns.filter(w => /ephemeral/.test(w))).toEqual([])
+  })
+
+  test('ephemeral + always-on infra runtime → WARN (H4: launchd owns it, the policy is inert)', async () => {
+    const root = mkTmp()
+    const { dir: bindir } = fakeBinDir()
+    const env = envFor(root, bindir)
+    const cwd = join(root, 'winf')
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({ personality: 'winf', runtime: 'notifier', wake_policy: 'ephemeral' }),
+    )
+    const warns: string[] = []
+    await provisionPeer({ cwd, runtime: 'notifier', env, warn: m => warns.push(m) })
+    expect(warns.some(w => /ephemeral/.test(w) && /inert|launchd/i.test(w))).toBe(true)
+  })
+})

package/src/status/index.ts

@@ -0,0 +1,119 @@
+// Status — the host-snapshot verb: installed-binary version, daemon health, and
+// the MEMORY SLOT line (docs/Слот памяти — контракт memory provider.md). The slot
+// is DECLARATIVE: a root file `~/.iapeer/memory-provider.json` written (atomically)
+// by the PROVIDER's own init/uninstall — the core only ever READS it. An absent or
+// unreadable file is the EMPTY slot — a fully valid state (bare core), never an
+// error (fail-open). The core never acts on heartbeat staleness — it only REPORTS
+// it (healing the provider's daemon is the provider's job, their ADR-010).
+
+import { readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import { IAPEER_VERSION } from '../core/version.ts'
+import { resolveGlobalRoot } from '../storage/index.ts'
+import { daemonDiscoveryPath } from '../daemon/index.ts'
+import { waitForDaemonHealthy } from '../update/index.ts'
+
+/** The slot-declaration filename in the storage root (next to peers-profiles.json). */
+export const MEMORY_PROVIDER_FILE = 'memory-provider.json'
+
+export interface MemoryProvider {
+  /** Provider name occupying the slot (e.g. "iapeer-memory"). */
+  provider: string
+  /** npm package of the provider (e.g. "@agfpd/iapeer-memory"). */
+  package: string
+  version: string
+  registeredAt: string
+  /** Optional liveness proxy: an absolute path whose mtime the provider's daemon
+   *  refreshes. status reports its age; the core takes NO action on staleness. */
+  heartbeat?: string
+}
+
+export function memoryProviderPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveGlobalRoot(env), MEMORY_PROVIDER_FILE)
+}
+
+/**
+ * Read the memory-slot declaration. null = EMPTY slot (absent / unreadable /
+ * schema-invalid file) — a valid state, so this NEVER throws (fail-open to bare).
+ */
+export function readMemoryProvider(env: NodeJS.ProcessEnv = process.env): MemoryProvider | null {
+  try {
+    const raw = JSON.parse(readFileSync(memoryProviderPath(env), 'utf8')) as unknown
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+    const o = raw as Record<string, unknown>
+    if (typeof o.provider !== 'string' || !o.provider.trim()) return null
+    if (typeof o.package !== 'string' || !o.package.trim()) return null
+    if (typeof o.version !== 'string' || !o.version.trim()) return null
+    return {
+      provider: o.provider.trim(),
+      package: o.package.trim(),
+      version: o.version.trim(),
+      registeredAt: typeof o.registeredAt === 'string' ? o.registeredAt : '',
+      ...(typeof o.heartbeat === 'string' && o.heartbeat.trim() ? { heartbeat: o.heartbeat.trim() } : {}),
+    }
+  } catch {
+    return null // empty slot — bare core is valid
+  }
+}
+
+/** Age (s) of the provider's heartbeat file, or null (none declared / unreadable). */
+export function heartbeatAgeSecs(provider: MemoryProvider, nowMs: number = Date.now()): number | null {
+  if (!provider.heartbeat) return null
+  try {
+    return Math.max(0, Math.floor((nowMs - statSync(provider.heartbeat).mtimeMs) / 1000))
+  } catch {
+    return null
+  }
+}
+
+export interface HostStatus {
+  version: string
+  daemon: { healthy: boolean; url: string | null; sock: string | null }
+  memory: { provider: MemoryProvider | null; heartbeatAgeSecs: number | null }
+}
+
+export interface HostStatusOptions {
+  env?: NodeJS.ProcessEnv
+  /** Injectable daemon probe (tests). Default: the real socket probe. */
+  probe?: () => Promise<boolean>
+}
+
+/** Assemble the host snapshot: baked version + daemon probe + memory slot. */
+export async function hostStatus(opts: HostStatusOptions = {}): Promise<HostStatus> {
+  const env = opts.env ?? process.env
+  let url: string | null = null
+  let sock: string | null = null
+  try {
+    const d = JSON.parse(readFileSync(daemonDiscoveryPath({ env }), 'utf8')) as { tcp?: string | null; sock?: string | null }
+    url = d.tcp ?? null
+    sock = d.sock ?? null
+  } catch {
+    /* no discovery file → daemon down or never started; addresses stay null */
+  }
+  const health = await waitForDaemonHealthy({ env, timeoutMs: 2500, needConsecutive: 1, probe: opts.probe })
+  const provider = readMemoryProvider(env)
+  return {
+    version: IAPEER_VERSION,
+    daemon: { healthy: health.healthy, url, sock },
+    memory: { provider, heartbeatAgeSecs: provider ? heartbeatAgeSecs(provider) : null },
+  }
+}
+
+/** Render the human status block (one fact per line; `memory:` per the slot contract). */
+export function formatHostStatus(s: HostStatus): string {
+  const daemon = s.daemon.healthy
+    ? `healthy${s.daemon.url ? ` @ ${s.daemon.url}` : ''}${s.daemon.sock ? ` + ${s.daemon.sock}` : ''}`
+    : 'NOT healthy (socket not accepting connections)'
+  // Heartbeat interpretation (slot contract, provider semantics agreed 10.06):
+  // file REMOVED on graceful shutdown → declared-but-absent = daemon not running;
+  // present = age shown. The core only REPORTS — staleness healing is the
+  // provider's own job (its verify/repair), never the core's.
+  let hb = ''
+  if (s.memory.provider?.heartbeat) {
+    hb = s.memory.heartbeatAgeSecs !== null
+      ? ` (heartbeat ${s.memory.heartbeatAgeSecs}s ago)`
+      : ' (daemon not running — no heartbeat file)'
+  }
+  const memory = s.memory.provider ? `${s.memory.provider.provider} ${s.memory.provider.version}${hb}` : 'none'
+  return `iapeer ${s.version}\ndaemon: ${daemon}\nmemory: ${memory}\n`
+}