@agfpd/iapeer 0.2.11 → 0.2.13

package/package.json

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

package/src/cli/index.ts

@@ -352,7 +352,8 @@ const USAGE = `usage: iapeer <verb> [args]
   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)
+  onboard [--dry-run] [--infra <csv>] [--no-memory] [--memory <pkg>]   register the agfpd marketplace (+ infra runtimes; + default memory provider, 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)
   create <personality> [--runtime r] [--path dir] [--bin abs]   create a peer anywhere (default ~/.iapeer/peers/<p>) + provision
@@ -367,6 +368,7 @@ const USAGE = `usage: iapeer <verb> [args]
   interrupt <peer> [runtime]                                     interrupt the current turn (Escape) — context intact
   compact <peer> [runtime]                                       compact the peer's context (/compact)
   self-fresh                                                     (agent self-call) mark /new eager-fresh + self-kill — the daemon relaunches fresh
+  native-memory <off|on> (--peer <p> | --all)                    gate/restore runtimes' native memory (canonized lever; контракт «Слот памяти»)
 `
 
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
@@ -406,8 +408,61 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         } else if (infra.length) {
           out(`onboard --dry-run: would onboard infra runtimes: ${infra.join(', ')}\n`)
         }
+        // Memory slot (контракт «Слот памяти», 10.06): optional DEFAULT-YES install of
+        // the default provider; its own init runs with INHERITED stdio (the provider
+        // owns the install questions). The step is REPORT-ONLY for the exit code — an
+        // empty slot is a valid state regardless of why.
+        const { onboardMemoryProvider } = await import('../onboard/memory.ts')
+        const mem = await onboardMemoryProvider({
+          skip: flags['no-memory'] === true,
+          package: typeof flags.memory === 'string' ? flags.memory : undefined,
+          dryRun: flags['dry-run'] === true,
+          env,
+        })
+        const memLabel = mem.provider ? `${mem.provider.provider} ${mem.provider.version}` : 'none'
+        out(`memory: ${mem.state}${mem.detail ? ` — ${mem.detail}` : ''} (slot: ${memLabel})\n`)
         return r.marketplaces.some(m => m.state === 'failed') || infraFailed ? 1 : 0
       }
+      case 'native-memory': {
+        // The canonized runtime-memory lever (контракт «Слот памяти» §Native-память):
+        // off = explicit disable merged into the peer's runtime config files; on =
+        // remove the key (restore the runtime's own default). Consumers: the operator
+        // and the memory provider's install-time sweep (`--all`). NOT slot-gated here —
+        // an explicit operator/provider action; only the BIRTH-time hook is slot-gated.
+        const state = positionals[0]
+        if (state !== 'off' && state !== 'on') return usage(errOut)
+        const peerName = typeof flags.peer === 'string' ? flags.peer : undefined
+        if (flags.all !== true && !peerName) return usage(errOut)
+        const { applyNativeMemory } = await import('../launch/nativeMemory.ts')
+        const index = readPeersIndex({ env })
+        const targets = flags.all === true ? index.peers : index.peers.filter(p => p.personality === peerName)
+        if (targets.length === 0) {
+          errOut(`peer "${peerName ?? ''}" is not in the iapeer peers index\n`)
+          return 1
+        }
+        let failed = false
+        for (const p of targets) {
+          const outcomes = applyNativeMemory(p.cwd, p.runtimes, state)
+          if (outcomes.length === 0) {
+            out(`${p.personality}: no claude/codex runtime — skipped\n`)
+            continue
+          }
+          for (const o of outcomes) {
+            out(`${p.personality} (${o.runtime}): ${o.state}${o.detail ? ` — ${o.detail}` : ''}\n`)
+            if (o.state === 'failed') failed = true
+          }
+        }
+        return failed ? 1 : 0
+      }
+      case 'status': {
+        // Host snapshot (контракт «Слот памяти» §status): version + daemon health +
+        // the memory-slot line. Exit 1 iff the daemon is unhealthy (usable as a
+        // health gate); an EMPTY memory slot is a valid state and never fails.
+        const { hostStatus, formatHostStatus } = await import('../status/index.ts')
+        const s = await hostStatus({ env })
+        out(formatHostStatus(s))
+        return s.daemon.healthy ? 0 : 1
+      }
       case 'install-runtime': {
         // §6 onboard a runtime END-TO-END: npx-install the package (auto-resolved from
         // the built-in runtime→package registry, or --package; self-deploys bin +

package/src/index.ts

@@ -25,5 +25,10 @@ export * from './install/index.ts'
 export * from './update/index.ts'
 // Onboard — the host-phase (idempotent marketplace registration in claude + codex).
 export * from './onboard/index.ts'
+// Memory slot — the declarative provider slot (контракт «Слот памяти»): status read + onboard step.
+export * from './status/index.ts'
+export * from './onboard/memory.ts'
+// Native runtime-memory levers (slot contract §Native-память): canonized forms + verb mechanics.
+export * from './launch/nativeMemory.ts'
 export { composeSystemPrompt, gatherPromptInput } from './launch/composeSystemPrompt.ts'
 export type { GatherPromptOptions } from './launch/composeSystemPrompt.ts'

package/src/launch/nativeMemory.test.ts

@@ -0,0 +1,150 @@
+// Native runtime-memory levers — the canonized forms (slot contract §Native-
+// память). The HARD requirement pinned here: NO-CLOBBER — both target files
+// carry foreign blocks (plugin enables, statusline wrappers) that every lever
+// write must preserve byte-meaningfully.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  applyNativeMemory,
+  claudeSettingsPath,
+  codexProjectConfigPath,
+  codexGlobalConfigPath,
+  preTrustCodexCwd,
+} from './nativeMemory.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-natmem-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+describe('claude lever (settings.json merge)', () => {
+  test('absent file → created with ONLY the lever key', () => {
+    const cwd = mkTmp()
+    const [o] = applyNativeMemory(cwd, ['claude'], 'off')
+    expect(o?.state).toBe('written')
+    expect(JSON.parse(readFileSync(claudeSettingsPath(cwd), 'utf8'))).toEqual({ autoMemoryEnabled: false })
+  })
+
+  test('NO-CLOBBER: foreign keys (plugins, statusline) survive off AND on', () => {
+    const cwd = mkTmp()
+    mkdirSync(join(cwd, '.claude'), { recursive: true })
+    const foreign = { enabledPlugins: { 'MergeMind@agfpd': true }, statusLine: { type: 'command', command: 'x' } }
+    writeFileSync(claudeSettingsPath(cwd), JSON.stringify(foreign))
+    applyNativeMemory(cwd, ['claude'], 'off')
+    const afterOff = JSON.parse(readFileSync(claudeSettingsPath(cwd), 'utf8'))
+    expect(afterOff).toEqual({ ...foreign, autoMemoryEnabled: false })
+    const [on] = applyNativeMemory(cwd, ['claude'], 'on')
+    expect(on?.state).toBe('written')
+    expect(JSON.parse(readFileSync(claudeSettingsPath(cwd), 'utf8'))).toEqual(foreign) // key REMOVED, default restored
+  })
+
+  test('idempotent: already-false → already; on with no key → already', () => {
+    const cwd = mkTmp()
+    applyNativeMemory(cwd, ['claude'], 'off')
+    expect(applyNativeMemory(cwd, ['claude'], 'off')[0]?.state).toBe('already')
+    applyNativeMemory(cwd, ['claude'], 'on')
+    expect(applyNativeMemory(cwd, ['claude'], 'on')[0]?.state).toBe('already')
+  })
+
+  test('non-object settings.json → failed (refuses to clobber), file untouched', () => {
+    const cwd = mkTmp()
+    mkdirSync(join(cwd, '.claude'), { recursive: true })
+    writeFileSync(claudeSettingsPath(cwd), '"just a string"')
+    const [o] = applyNativeMemory(cwd, ['claude'], 'off')
+    expect(o?.state).toBe('failed')
+    expect(readFileSync(claudeSettingsPath(cwd), 'utf8')).toBe('"just a string"')
+  })
+})
+
+describe('codex lever (config.toml [features] merge)', () => {
+  test('absent file → [features] section with the lever line', () => {
+    const cwd = mkTmp()
+    const [o] = applyNativeMemory(cwd, ['codex'], 'off')
+    expect(o?.state).toBe('written')
+    expect(readFileSync(codexProjectConfigPath(cwd), 'utf8')).toBe('[features]\nmemories = false\n')
+  })
+
+  test('NO-CLOBBER: plugin blocks survive; [features] appended after them (fleet-file shape)', () => {
+    const cwd = mkTmp()
+    mkdirSync(join(cwd, '.codex'), { recursive: true })
+    const fleet = '[plugins."Inter-Agent-Protocol@agfpd"]\nenabled = true\n\n[plugins."MergeMind@agfpd"]\nenabled = true\n'
+    writeFileSync(codexProjectConfigPath(cwd), fleet)
+    applyNativeMemory(cwd, ['codex'], 'off')
+    const text = readFileSync(codexProjectConfigPath(cwd), 'utf8')
+    expect(text).toContain('[plugins."Inter-Agent-Protocol@agfpd"]\nenabled = true')
+    expect(text).toContain('[plugins."MergeMind@agfpd"]\nenabled = true')
+    expect(text).toContain('[features]\nmemories = false')
+  })
+
+  test('existing [features] WITHOUT memories (followed by another section) → inserted INSIDE the section', () => {
+    const cwd = mkTmp()
+    mkdirSync(join(cwd, '.codex'), { recursive: true })
+    writeFileSync(codexProjectConfigPath(cwd), '[features]\nother = true\n\n[plugins."X@y"]\nenabled = true\n')
+    applyNativeMemory(cwd, ['codex'], 'off')
+    const text = readFileSync(codexProjectConfigPath(cwd), 'utf8')
+    // the lever line lands in [features], NOT in [plugins."X@y"]
+    expect(text.indexOf('memories = false')).toBeLessThan(text.indexOf('[plugins."X@y"]'))
+    expect(text).toContain('other = true')
+  })
+
+  test('memories = true → replaced with false; already false → already', () => {
+    const cwd = mkTmp()
+    mkdirSync(join(cwd, '.codex'), { recursive: true })
+    writeFileSync(codexProjectConfigPath(cwd), '[features]\nmemories = true\n')
+    expect(applyNativeMemory(cwd, ['codex'], 'off')[0]?.state).toBe('written')
+    expect(readFileSync(codexProjectConfigPath(cwd), 'utf8')).toContain('memories = false')
+    expect(applyNativeMemory(cwd, ['codex'], 'off')[0]?.state).toBe('already')
+  })
+
+  test('on → the memories line is REMOVED (default restored), section + foreign lines kept', () => {
+    const cwd = mkTmp()
+    mkdirSync(join(cwd, '.codex'), { recursive: true })
+    writeFileSync(codexProjectConfigPath(cwd), '[features]\nmemories = false\nother = true\n')
+    const [o] = applyNativeMemory(cwd, ['codex'], 'on')
+    expect(o?.state).toBe('written')
+    const text = readFileSync(codexProjectConfigPath(cwd), 'utf8')
+    expect(text).not.toContain('memories')
+    expect(text).toContain('other = true')
+    expect(applyNativeMemory(cwd, ['codex'], 'on')[0]?.state).toBe('already')
+  })
+})
+
+describe('applyNativeMemory runtime dispatch', () => {
+  test('both runtimes → both levers; router-only runtimes → no outcomes', () => {
+    const cwd = mkTmp()
+    const both = applyNativeMemory(cwd, ['claude', 'codex'], 'off')
+    expect(both.map(o => o.runtime).sort()).toEqual(['claude', 'codex'])
+    expect(applyNativeMemory(mkTmp(), ['telegram', 'notifier'], 'off')).toEqual([])
+  })
+})
+
+describe('preTrustCodexCwd (birth-time trust, codex global config)', () => {
+  test('appends a [projects] block once; NO-CLOBBER of existing content; idempotent', () => {
+    const home = mkTmp()
+    const env = { HOME: home } as NodeJS.ProcessEnv
+    mkdirSync(join(home, '.codex'), { recursive: true })
+    const existing = '[projects."/already/trusted"]\ntrust_level = "trusted"\n'
+    writeFileSync(codexGlobalConfigPath(env), existing)
+    const first = preTrustCodexCwd('/peers/newborn', env)
+    expect(first.state).toBe('written')
+    const text = readFileSync(codexGlobalConfigPath(env), 'utf8')
+    expect(text).toContain(existing.trim())
+    expect(text).toContain('[projects."/peers/newborn"]\ntrust_level = "trusted"')
+    expect(preTrustCodexCwd('/peers/newborn', env).state).toBe('already')
+  })
+
+  test('absent global config → created with just the block', () => {
+    const home = mkTmp()
+    const env = { HOME: home } as NodeJS.ProcessEnv
+    expect(preTrustCodexCwd('/peers/first', env).state).toBe('written')
+    expect(readFileSync(codexGlobalConfigPath(env), 'utf8')).toBe('[projects."/peers/first"]\ntrust_level = "trusted"\n')
+  })
+})

package/src/launch/nativeMemory.ts

@@ -0,0 +1,185 @@
+// Native runtime-memory levers (контракт «Слот памяти» §Native-память рантаймов
+// при занятом слоте, agreed 10.06). The CORE canonizes the lever FORMS — runtime
+// knowledge lives in the runtime layer, like deliveryMarkers/buildArgv:
+//
+//   claude: merge `"autoMemoryEnabled": false` into `<cwd>/.claude/settings.json`
+//   codex:  merge `memories = false` into the `[features]` section of
+//           `<cwd>/.codex/config.toml`
+//
+// Both files CARRY FOREIGN BLOCKS (plugin enables, statusline wrappers, …) —
+// every write here is a NO-CLOBBER merge (parse/patch + atomic temp+rename),
+// never a rewrite. Forms verified live on the fleet (12/12 + behavioral smoke
+// 09.06; codex reads project-local config when the cwd is TRUSTED — see
+// preTrustCodexCwd).
+//
+// `off` writes the explicit disable; `on` REMOVES the key (restores the
+// runtime's own default rather than baking an explicit enable — the core has
+// no opinion beyond "parallel store off while a memory provider owns the host").
+//
+// Consumers: the operator verb `iapeer native-memory <off|on>`, the provider's
+// install-time sweep (calls the verb), and provisionPeer's birth-time hook
+// (slot-gated, see provision/index.ts).
+
+import { existsSync, mkdirSync, readFileSync, realpathSync } from 'fs'
+import { dirname, join } from 'path'
+import { homedir } from 'os'
+import type { Runtime } from '../core/constants.ts'
+import { writeFileAtomic } from '../storage/index.ts'
+
+export type NativeMemoryState = 'off' | 'on'
+
+export interface LeverOutcome {
+  runtime: 'claude' | 'codex'
+  path: string
+  state: 'written' | 'already' | 'failed'
+  detail?: string
+}
+
+// ─── claude: <cwd>/.claude/settings.json — JSON merge ───────────────────────
+
+export function claudeSettingsPath(cwd: string): string {
+  return join(cwd, '.claude', 'settings.json')
+}
+
+function applyClaudeLever(cwd: string, state: NativeMemoryState): LeverOutcome {
+  const path = claudeSettingsPath(cwd)
+  try {
+    let obj: Record<string, unknown> = {}
+    if (existsSync(path)) {
+      const raw = JSON.parse(readFileSync(path, 'utf8')) as unknown
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { runtime: 'claude', path, state: 'failed', detail: 'settings.json is not a JSON object — refusing to clobber' }
+      }
+      obj = raw as Record<string, unknown>
+    }
+    if (state === 'off') {
+      if (obj.autoMemoryEnabled === false) return { runtime: 'claude', path, state: 'already' }
+      obj.autoMemoryEnabled = false
+    } else {
+      if (!('autoMemoryEnabled' in obj)) return { runtime: 'claude', path, state: 'already' }
+      delete obj.autoMemoryEnabled // restore the runtime's own default
+    }
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileAtomic(path, `${JSON.stringify(obj, null, 2)}\n`)
+    return { runtime: 'claude', path, state: 'written' }
+  } catch (e) {
+    return { runtime: 'claude', path, state: 'failed', detail: e instanceof Error ? e.message : String(e) }
+  }
+}
+
+// ─── codex: <cwd>/.codex/config.toml — section-scoped line merge ─────────────
+
+export function codexProjectConfigPath(cwd: string): string {
+  return join(cwd, '.codex', 'config.toml')
+}
+
+/** Locate the `[features]` section bounds: [startLine, endLine) of its BODY
+ *  (after the header, up to the next `[…]` header or EOF). null = no section. */
+function featuresBounds(lines: string[]): { header: number; start: number; end: number } | null {
+  const header = lines.findIndex(l => l.trim() === '[features]')
+  if (header < 0) return null
+  let end = lines.length
+  for (let i = header + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i]!)) {
+      end = i
+      break
+    }
+  }
+  return { header, start: header + 1, end }
+}
+
+function applyCodexLever(cwd: string, state: NativeMemoryState): LeverOutcome {
+  const path = codexProjectConfigPath(cwd)
+  try {
+    const text = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    const lines = text.length ? text.split('\n') : []
+    const bounds = featuresBounds(lines)
+    const memRe = /^\s*memories\s*=/
+    if (state === 'off') {
+      if (bounds) {
+        const idx = lines.slice(bounds.start, bounds.end).findIndex(l => memRe.test(l))
+        if (idx >= 0) {
+          const abs = bounds.start + idx
+          if (/^\s*memories\s*=\s*false\s*$/.test(lines[abs]!)) return { runtime: 'codex', path, state: 'already' }
+          lines[abs] = 'memories = false'
+        } else {
+          lines.splice(bounds.start, 0, 'memories = false')
+        }
+      } else {
+        if (lines.length && lines[lines.length - 1]!.trim() !== '') lines.push('')
+        lines.push('[features]', 'memories = false')
+      }
+    } else {
+      if (!bounds) return { runtime: 'codex', path, state: 'already' }
+      const idx = lines.slice(bounds.start, bounds.end).findIndex(l => memRe.test(l))
+      if (idx < 0) return { runtime: 'codex', path, state: 'already' }
+      lines.splice(bounds.start + idx, 1) // restore the runtime's own default
+    }
+    mkdirSync(dirname(path), { recursive: true })
+    const outText = lines.join('\n')
+    writeFileAtomic(path, outText.endsWith('\n') ? outText : `${outText}\n`)
+    return { runtime: 'codex', path, state: 'written' }
+  } catch (e) {
+    return { runtime: 'codex', path, state: 'failed', detail: e instanceof Error ? e.message : String(e) }
+  }
+}
+
+// ─── codex trust (birth-time only) ───────────────────────────────────────────
+
+/** The codex GLOBAL config (`~/.codex/config.toml`) — where trust lives as
+ *  `[projects."<path>"] trust_level = "trusted"` blocks. */
+export function codexGlobalConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+  const home = env.HOME?.trim() || homedir()
+  return join(home, '.codex', 'config.toml')
+}
+
+/**
+ * Pre-trust a NEWBORN codex peer's cwd by appending its `[projects."<cwd>"]`
+ * block to the codex global config (no-clobber: only when no block for this
+ * path exists). Closes the contract requirement «рычаг действует с ПЕРВОЙ
+ * сессии» DETERMINISTICALLY: codex reads project-local config only for a
+ * trusted cwd, and without pre-trust the first session's trust is granted
+ * mid-boot by the adapter's dialog auto-accept — whether the project config is
+ * (re)read after that grant within the same run is codex-internal. Birth-time
+ * only — existing peers are already trusted through their boot history.
+ */
+export function preTrustCodexCwd(cwd: string, env: NodeJS.ProcessEnv = process.env): LeverOutcome {
+  const path = codexGlobalConfigPath(env)
+  try {
+    // Codex keys trust on the RESOLVED real path (live fact, 10.06 acceptance: the
+    // /tmp → /private/tmp symlink made a literal-path entry MISS and left the lever
+    // inert — trust entries written by codex itself are all /private/tmp/...).
+    let real = cwd
+    try {
+      real = realpathSync(cwd)
+    } catch {
+      /* cwd not on disk yet → keep as given */
+    }
+    const text = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    if (text.includes(`[projects."${real}"]`)) return { runtime: 'codex', path, state: 'already' }
+    const block = `${text.length && !text.endsWith('\n') ? '\n' : ''}${text.trim().length ? '\n' : ''}[projects."${real}"]\ntrust_level = "trusted"\n`
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileAtomic(path, text + block)
+    return { runtime: 'codex', path, state: 'written' }
+  } catch (e) {
+    return { runtime: 'codex', path, state: 'failed', detail: e instanceof Error ? e.message : String(e) }
+  }
+}
+
+// ─── public entry ────────────────────────────────────────────────────────────
+
+/**
+ * Apply the native-memory lever for one peer cwd across its declared runtimes
+ * (∩ {claude, codex} — other runtimes carry no native memory). Idempotent;
+ * every outcome is reported (a 'failed' lever never throws).
+ */
+export function applyNativeMemory(
+  cwd: string,
+  runtimes: readonly Runtime[],
+  state: NativeMemoryState,
+): LeverOutcome[] {
+  const out: LeverOutcome[] = []
+  if (runtimes.includes('claude')) out.push(applyClaudeLever(cwd, state))
+  if (runtimes.includes('codex')) out.push(applyCodexLever(cwd, state))
+  return out
+}

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,40 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
     runtimeBin,
     warn: opts.warn,
   })
+  // Birth-time native-memory lever (контракт «Слот памяти» §Native-память рантаймов):
+  // an OCCUPIED memory slot gates the AUTOMATIC lever at peer birth — zero window of
+  // a parallel, uncurated native store (the criterion). Empty slot → native memory is
+  // legitimate, untouched. Best-effort with a LOUD warn (a lever hiccup must not kill
+  // the provision — the operator verb `iapeer native-memory off` is the repair).
+  try {
+    const { readMemoryProvider } = await import('../status/index.ts')
+    if (readMemoryProvider(env)) {
+      const { applyNativeMemory, preTrustCodexCwd } = await import('../launch/nativeMemory.ts')
+      for (const o of applyNativeMemory(cwd, profile.runtimes, 'off')) {
+        if (o.state === 'failed') {
+          opts.warn?.(
+            `native-memory lever (${o.runtime}) FAILED for "${profile.personality}": ${o.detail} — ` +
+              `the peer may accumulate a parallel native store; repair: iapeer native-memory off --peer ${profile.personality}`,
+          )
+        }
+      }
+      // Codex reads project-local config only for a TRUSTED cwd — pre-trust the
+      // newborn so the lever acts from the FIRST session (contract requirement),
+      // not from whenever the boot dialog's trust grant takes effect.
+      if (profile.runtimes.includes('codex')) {
+        const t = preTrustCodexCwd(cwd, env)
+        if (t.state === 'failed') {
+          opts.warn?.(
+            `codex pre-trust FAILED for "${profile.personality}": ${t.detail} — ` +
+              `the lever may be inert until the first boot's trust dialog`,
+          )
+        }
+      }
+    }
+  } catch (e) {
+    opts.warn?.(`native-memory birth-time hook failed: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
   // 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

package/src/provision/provision.test.ts

@@ -158,3 +158,44 @@ describe('provisionPeer ephemeral warnings', () => {
     expect(warns.some(w => /ephemeral/.test(w) && /inert|launchd/i.test(w))).toBe(true)
   })
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Birth-time native-memory lever (slot contract §Native-память): an OCCUPIED
+// slot gates the automatic lever at provision; empty slot → untouched.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('provisionPeer birth-time native-memory lever', () => {
+  test('slot OCCUPIED → claude+codex levers written + codex cwd pre-trusted', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    // occupy the slot (as the provider's init would)
+    mkdirSync(join(root, 'iapeer'), { recursive: true })
+    writeFileSync(
+      join(root, 'iapeer', 'memory-provider.json'),
+      JSON.stringify({ provider: 'iapeer-memory', package: '@agfpd/iapeer-memory', version: '0.1.0', registeredAt: 'x' }),
+    )
+    const cwd = join(root, 'wnat')
+    mkdirSync(join(cwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      peerProfilePath(cwd),
+      JSON.stringify({ personality: 'wnat', runtime: 'claude', runtimes: ['claude', 'codex'] }),
+    )
+    await provisionPeer({ cwd, runtime: 'claude', env })
+    expect(JSON.parse(readFileSync(join(cwd, '.claude', 'settings.json'), 'utf8')).autoMemoryEnabled).toBe(false)
+    expect(readFileSync(join(cwd, '.codex', 'config.toml'), 'utf8')).toContain('memories = false')
+    // codex newborn pre-trusted in the GLOBAL codex config (HOME-scoped → temp root).
+    // Codex keys trust on the RESOLVED real path (macOS /var → /private/var), so the
+    // entry must carry realpath(cwd) — the literal-path miss was a live-caught bug.
+    const { realpathSync } = await import('fs')
+    expect(readFileSync(join(root, '.codex', 'config.toml'), 'utf8')).toContain(`[projects."${realpathSync(cwd)}"]`)
+  })
+
+  test('slot EMPTY → native memory untouched (legitimate without a provider)', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const cwd = join(root, 'wbare')
+    await provisionPeer({ cwd, runtime: 'claude', env })
+    expect(existsSync(join(cwd, '.claude', 'settings.json'))).toBe(false)
+    expect(existsSync(join(cwd, '.codex', 'config.toml'))).toBe(false)
+  })
+})

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`
+}

package/src/status/status.test.ts

@@ -0,0 +1,125 @@
+// Memory slot — the DECLARATIVE provider slot (docs/Слот памяти — контракт
+// memory provider.md): the core only READS the root declaration; absent /
+// unreadable / invalid → EMPTY slot (bare core, valid state, never an error).
+// Plus the host-status assembly + rendering (memory: <provider> | none).
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  formatHostStatus,
+  heartbeatAgeSecs,
+  hostStatus,
+  memoryProviderPath,
+  readMemoryProvider,
+  type HostStatus,
+  type MemoryProvider,
+} from './index.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-slot-'))
+  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 VALID = {
+  provider: 'iapeer-memory',
+  package: '@agfpd/iapeer-memory',
+  version: '0.1.0',
+  registeredAt: '2026-06-10T00:00:00Z',
+}
+
+describe('readMemoryProvider (slot declaration, fail-open)', () => {
+  test('absent file → null (EMPTY slot — valid bare state)', () => {
+    expect(readMemoryProvider(envFor(mkTmp()))).toBeNull()
+  })
+
+  test('valid declaration → parsed provider; heartbeat optional', () => {
+    const root = mkTmp()
+    writeFileSync(memoryProviderPath(envFor(root)), JSON.stringify({ ...VALID, heartbeat: '/tmp/hb' }))
+    const p = readMemoryProvider(envFor(root))
+    expect(p).toMatchObject({ ...VALID, heartbeat: '/tmp/hb' })
+    // without heartbeat — field absent, not empty-string
+    writeFileSync(memoryProviderPath(envFor(root)), JSON.stringify(VALID))
+    expect(readMemoryProvider(envFor(root))?.heartbeat).toBeUndefined()
+  })
+
+  test('garbage / wrong shape / missing required fields → null, NEVER throws', () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    for (const bad of ['NOT JSON {{{', '[]', '{}', JSON.stringify({ provider: 'x' }), JSON.stringify({ ...VALID, version: 42 })]) {
+      writeFileSync(memoryProviderPath(env), bad)
+      expect(readMemoryProvider(env)).toBeNull()
+    }
+  })
+})
+
+describe('heartbeatAgeSecs', () => {
+  test('no heartbeat declared → null; declared but absent file → null; present → age', () => {
+    const root = mkTmp()
+    expect(heartbeatAgeSecs({ ...VALID } as MemoryProvider)).toBeNull()
+    const hb = join(root, 'memoryd.heartbeat')
+    expect(heartbeatAgeSecs({ ...VALID, heartbeat: hb } as MemoryProvider)).toBeNull() // not running
+    writeFileSync(hb, '')
+    const old = (Date.now() - 45_000) / 1000
+    utimesSync(hb, old, old)
+    const age = heartbeatAgeSecs({ ...VALID, heartbeat: hb } as MemoryProvider)
+    expect(age).toBeGreaterThanOrEqual(44)
+    expect(age).toBeLessThanOrEqual(60)
+  })
+})
+
+describe('hostStatus + formatHostStatus', () => {
+  test('empty slot → memory: none; daemon health from the injected probe', async () => {
+    const root = mkTmp()
+    const s = await hostStatus({ env: envFor(root), probe: async () => true })
+    expect(s.daemon.healthy).toBe(true)
+    expect(s.memory.provider).toBeNull()
+    expect(formatHostStatus(s)).toContain('memory: none')
+  })
+
+  test('occupied slot + fresh heartbeat → provider line with age', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const hb = join(root, 'memoryd.heartbeat')
+    writeFileSync(hb, '')
+    writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, heartbeat: hb }))
+    const s = await hostStatus({ env, probe: async () => true })
+    expect(formatHostStatus(s)).toMatch(/memory: iapeer-memory 0\.1\.0 \(heartbeat \d+s ago\)/)
+  })
+
+  test('occupied slot, heartbeat declared but file ABSENT → "daemon not running" (graceful-shutdown semantics)', () => {
+    const s: HostStatus = {
+      version: '0.0.0',
+      daemon: { healthy: false, url: null, sock: null },
+      memory: {
+        provider: { ...VALID, heartbeat: '/nope/hb' } as MemoryProvider,
+        heartbeatAgeSecs: null,
+      },
+    }
+    const text = formatHostStatus(s)
+    expect(text).toContain('memory: iapeer-memory 0.1.0 (daemon not running — no heartbeat file)')
+    expect(text).toContain('daemon: NOT healthy')
+  })
+
+  test('discovery file addresses surface in the daemon line', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const stateDir = join(root, 'state', 'iapeer')
+    mkdirSync(stateDir, { recursive: true })
+    writeFileSync(join(stateDir, 'router.json'), JSON.stringify({ sock: '/x/router.sock', tcp: 'http://127.0.0.1:8765/mcp' }))
+    const s = await hostStatus({ env, probe: async () => true })
+    const text = formatHostStatus(s)
+    expect(text).toContain('@ http://127.0.0.1:8765/mcp')
+    expect(text).toContain('+ /x/router.sock')
+  })
+})