@agfpd/iapeer 0.2.24 → 0.2.25

package/package.json

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

package/src/cli/index.ts

@@ -433,6 +433,7 @@ const USAGE = `usage: iapeer <verb> [args]
   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; контракт «Слот памяти»)
+  memory-plugin <on|off> (--peer <p> | --all)                    install/remove the slot-declared provider plugin (claude per-peer, codex host-global)
 `
 
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
@@ -562,6 +563,29 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         }
         return failed ? 1 : 0
       }
+      case 'memory-plugin': {
+        // Slot-derived provider-plugin install/removal (контракт «Слот памяти»
+        // §Плагин провайдера; agreed iapeer-memory + boris 10.06). The plugin
+        // identity comes from the slot declaration's v1.1 plugin block — empty
+        // slot / v1 declaration → explicit refusal (generic `enable` exists for
+        // arbitrary plugins). Forms live in enable/ (ONE home); codex off is
+        // host-global (only --all removes; --peer reports it explicitly).
+        const state = positionals[0]
+        if (state !== 'on' && state !== 'off') return usage(errOut)
+        const peerName = typeof flags.peer === 'string' ? flags.peer : undefined
+        if (flags.all !== true && !peerName) return usage(errOut)
+        const { memoryPluginApply } = await import('../enable/memoryPlugin.ts')
+        const r = memoryPluginApply(state, { peer: peerName, all: flags.all === true, env })
+        if (r.error) {
+          errOut(`memory-plugin: ${r.error}\n`)
+          return 1
+        }
+        out(`plugin: ${r.plugin!.name}@${r.plugin!.marketplace} (provider-declared)\n`)
+        for (const o of r.outcomes) {
+          out(`${o.personality} (${o.runtime}): ${o.state}${o.detail ? ` — ${o.detail}` : ''}\n`)
+        }
+        return r.ok ? 0 : 1
+      }
       case 'status': {
         // Host snapshot (контракт «Слот памяти» §status): version + daemon health +
         // the memory-slot line. Exit 1 iff the daemon is unhealthy (usable as a

package/src/enable/index.ts

@@ -23,7 +23,7 @@ import { spawnSync } from 'child_process'
 import { existsSync, readFileSync, realpathSync } from 'fs'
 import { basename, join } from 'path'
 import { homedir } from 'os'
-import { MARKETPLACE_NAME } from '../onboard/index.ts'
+import { MARKETPLACE_NAME, isMarketplaceRegisteredAs, refreshMarketplace, registerMarketplace } from '../onboard/index.ts'
 import { findPeer, readPeersIndex } from '../registry/index.ts'
 import { IapError } from '../core/errors.ts'
 import { normalizeNameCandidate } from '../core/normalize.ts'
@@ -214,14 +214,20 @@ function isExecutable(bin: string, env: NodeJS.ProcessEnv): boolean {
  *  live — the same entry lists enabled=false from another dir, true from its own), so
  *  the list MUST run with cwd = the peer cwd to read the authoritative enabled-state.
  *  maxBuffer is raised — a configured host's plugin list exceeds the 1 MB default. */
-function claudeEntry(bin: string, plugin: string, peerCwd: string, env: NodeJS.ProcessEnv): InstalledEntry | null {
+function claudeEntry(
+  bin: string,
+  plugin: string,
+  marketplace: string,
+  peerCwd: string,
+  env: NodeJS.ProcessEnv,
+): InstalledEntry | null {
   const list = spawnSync(bin, ['plugin', 'list', '--json'], {
     cwd: peerCwd,
     encoding: 'utf8',
     env: env as Record<string, string>,
     maxBuffer: 64 * 1024 * 1024,
   })
-  return findPeerScopedEntry(parseInstalledPlugins(list.stdout ?? ''), plugin, MARKETPLACE_NAME, peerCwd)
+  return findPeerScopedEntry(parseInstalledPlugins(list.stdout ?? ''), plugin, marketplace, peerCwd)
 }
 
 /**
@@ -232,11 +238,11 @@ function claudeEntry(bin: string, plugin: string, peerCwd: string, env: NodeJS.P
  * enabled"). Idempotent + fleet-safe: the entry is keyed by THIS peer's projectPath
  * (realpath), so it never reads or mutates another peer's install.
  */
-function enableClaude(plugin: string, peerCwd: string, env: NodeJS.ProcessEnv): RuntimeEnableResult {
+function enableClaude(plugin: string, marketplace: string, peerCwd: string, env: NodeJS.ProcessEnv): RuntimeEnableResult {
   const bin = claudeBin(env)
   if (!isExecutable(bin, env)) return { runtime: 'claude', state: 'runtime-missing' }
-  const id = `${plugin}@${MARKETPLACE_NAME}`
-  const existing = claudeEntry(bin, plugin, peerCwd, env)
+  const id = `${plugin}@${marketplace}`
+  const existing = claudeEntry(bin, plugin, marketplace, peerCwd, env)
   if (existing?.enabled) return { runtime: 'claude', state: 'already-enabled', installPath: existing.installPath }
 
   if (!existing) {
@@ -251,14 +257,14 @@ function enableClaude(plugin: string, peerCwd: string, env: NodeJS.ProcessEnv):
   }
   // the entry now exists but is DISABLED (fresh install) or was pre-existing-disabled →
   // enable it (and ONLY then; an already-enabled entry would error).
-  const after = claudeEntry(bin, plugin, peerCwd, env)
+  const after = claudeEntry(bin, plugin, marketplace, peerCwd, env)
   if (after && !after.enabled) {
     const en = spawnSync(bin, ['plugin', 'enable', id, '--scope', 'project'], {
       cwd: peerCwd,
       encoding: 'utf8',
       env: env as Record<string, string>,
     })
-    const confirmed = claudeEntry(bin, plugin, peerCwd, env)
+    const confirmed = claudeEntry(bin, plugin, marketplace, peerCwd, env)
     if (!confirmed?.enabled) {
       return { runtime: 'claude', state: 'failed', detail: (en.stderr || en.stdout || `exit ${en.status}`).trim() }
     }
@@ -293,10 +299,10 @@ function codexState(bin: string, id: string, env: NodeJS.ProcessEnv): 'enabled'
  *  ENABLES (verified live: config.toml `[plugins."<id>"] enabled = true`) and is
  *  idempotent (re-add exits 0). Idempotency: skip when already enabled. installPath is
  *  parsed from the add output so setup-detection works for a codex-only peer. */
-function enableCodex(plugin: string, env: NodeJS.ProcessEnv): RuntimeEnableResult {
+function enableCodex(plugin: string, marketplace: string, env: NodeJS.ProcessEnv): RuntimeEnableResult {
   const bin = codexBin(env)
   if (!isExecutable(bin, env)) return { runtime: 'codex', state: 'runtime-missing' }
-  const id = `${plugin}@${MARKETPLACE_NAME}`
+  const id = `${plugin}@${marketplace}`
   const before = codexState(bin, id, env)
   if (before === 'enabled') return { runtime: 'codex', state: 'already-enabled' }
   const add = spawnSync(bin, ['plugin', 'add', id], { encoding: 'utf8', env: env as Record<string, string> })
@@ -338,19 +344,76 @@ function callSetup(
   return { ok: true }
 }
 
+/** Registry-free enable input — the cwd-level core (контракт §Плагин провайдера:
+ *  birth-time hook runs BEFORE the registry upsert, so it cannot resolve a peer). */
+export interface CwdEnableOptions {
+  plugin: string
+  /** Marketplace NAME the plugin id keys on (default: agfpd). */
+  marketplace?: string
+  /** Source ref: when given, the path ENSURES the marketplace is registered for the
+   *  runtime (add on missing) before installing — the third-party-provider path. */
+  marketplaceRef?: string
+  cwd: string
+  personality: string
+  runtimes: CapabilityRuntime[]
+  noSetup?: boolean
+  env?: NodeJS.ProcessEnv
+}
+
+/** One install attempt for one runtime, WITH the stale-snapshot resilience the
+ *  contract requires (просьба iapeer-memory): a failed attempt refreshes the
+ *  runtime's local marketplace snapshot (claude `marketplace update` / codex
+ *  `marketplace upgrade`) and retries ONCE — a plugin registered in the
+ *  marketplace after the host's last pull reads as «unknown plugin» until then. */
+function enableRuntimeWithRetry(
+  rt: CapabilityRuntime,
+  plugin: string,
+  marketplace: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): RuntimeEnableResult {
+  const attempt = (): RuntimeEnableResult =>
+    rt === 'claude' ? enableClaude(plugin, marketplace, cwd, env) : enableCodex(plugin, marketplace, env)
+  const first = attempt()
+  if (first.state !== 'failed') return first
+  const refresh = refreshMarketplace(rt, marketplace, env)
+  if (!refresh.ok) {
+    return { ...first, detail: `${first.detail ?? 'failed'}; marketplace refresh also failed: ${refresh.detail ?? ''}` }
+  }
+  const second = attempt()
+  return second.state === 'failed'
+    ? { ...second, detail: `${second.detail ?? 'failed'} (after marketplace refresh)` }
+    : second
+}
+
 /**
- * Enable a capability plugin on a peer (contract Установка §3): install per-runtime
- * (claude project-scope / codex global) + enable + call `setup` ONLY if the plugin
- * declares it. Idempotent and fleet-safe — a peer already enabled is a no-op; the
- * claude path is keyed by the peer's projectPath so it never touches another peer.
+ * The registry-FREE enable core: install per-runtime (claude project-scope IN cwd /
+ * codex global) + enable + `setup` ONLY if declared — with marketplace ensure
+ * (marketplaceRef given + not registered → add) and the stale-snapshot retry.
+ * Consumers: enableCapability (peer-resolved verb), provisionPeer's birth-time
+ * memory-plugin hook, and the `memory-plugin` verb — ONE home of the install forms.
  */
-export function enableCapability(opts: EnableOptions): EnableResult {
-  const env = opts.env ?? process.env
-  const peer = resolvePeer(opts)
-  const targetRuntimes = opts.runtimes ?? peer.runtimes
+export function enableCapabilityForCwd(o: CwdEnableOptions): EnableResult {
+  const env = o.env ?? process.env
+  const marketplace = o.marketplace ?? MARKETPLACE_NAME
   const results: RuntimeEnableResult[] = []
-  for (const rt of targetRuntimes) {
-    results.push(rt === 'claude' ? enableClaude(opts.plugin, peer.cwd, env) : enableCodex(opts.plugin, env))
+  for (const rt of o.runtimes) {
+    // runtime-missing wins FIRST (before any marketplace work): a host without
+    // the runtime binary is a clean skip, not a marketplace-add failure.
+    if (!isExecutable(rt === 'claude' ? claudeBin(env) : codexBin(env), env)) {
+      results.push({ runtime: rt, state: 'runtime-missing' })
+      continue
+    }
+    // Marketplace ensure — only when the caller supplied a source ref (the slot's
+    // marketplaceRef); the generic agfpd path is guaranteed by onboard already.
+    if (o.marketplaceRef && !isMarketplaceRegisteredAs(rt, marketplace, o.marketplaceRef, env)) {
+      const reg = registerMarketplace(rt, env, o.marketplaceRef)
+      if (!reg.ok) {
+        results.push({ runtime: rt, state: 'failed', detail: `marketplace add ${o.marketplaceRef} failed: ${reg.detail ?? ''}` })
+        continue
+      }
+    }
+    results.push(enableRuntimeWithRetry(rt, o.plugin, marketplace, o.cwd, env))
   }
 
   // setup: read the manifest from whichever runtime gave us an installPath (the source
@@ -361,21 +424,98 @@ export function enableCapability(opts: EnableOptions): EnableResult {
   const setup = readSetupDescriptor(installPath)
   const anyOk = results.some(r => r.state === 'installed' || r.state === 'enabled' || r.state === 'already-enabled')
   if (setup && anyOk) {
-    if (opts.noSetup) {
+    if (o.noSetup) {
       setupState = 'skipped'
     } else {
-      const s = callSetup(setup, installPath as string, peer, env)
+      const s = callSetup(setup, installPath as string, { personality: o.personality, cwd: o.cwd }, env)
       setupState = s.ok ? 'called' : 'failed'
       setupDetail = s.detail
     }
   }
 
   return {
-    plugin: opts.plugin,
-    personality: peer.personality,
-    cwd: peer.cwd,
+    plugin: o.plugin,
+    personality: o.personality,
+    cwd: o.cwd,
     runtimes: results,
     setup: setupState,
     setupDetail,
   }
 }
+
+/**
+ * Enable a capability plugin on a peer (contract Установка §3): install per-runtime
+ * (claude project-scope / codex global) + enable + call `setup` ONLY if the plugin
+ * declares it. Idempotent and fleet-safe — a peer already enabled is a no-op; the
+ * claude path is keyed by the peer's projectPath so it never touches another peer.
+ * Thin peer-resolving wrapper over enableCapabilityForCwd (the ONE forms home).
+ */
+export function enableCapability(opts: EnableOptions): EnableResult {
+  const env = opts.env ?? process.env
+  const peer = resolvePeer(opts)
+  return enableCapabilityForCwd({
+    plugin: opts.plugin,
+    cwd: peer.cwd,
+    personality: peer.personality,
+    runtimes: opts.runtimes ?? peer.runtimes,
+    noSetup: opts.noSetup,
+    env,
+  })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Removal forms (контракт §Плагин провайдера, off-direction) — verb names
+// verified live 10.06: claude `plugin uninstall <id> --scope project` (run in the
+// peer cwd), codex `plugin remove <id>` (host-global).
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type RuntimeRemoveState = 'removed' | 'absent' | 'runtime-missing' | 'failed'
+
+export interface RuntimeRemoveResult {
+  runtime: CapabilityRuntime
+  state: RuntimeRemoveState
+  detail?: string
+}
+
+/** claude: uninstall the peer-scoped (projectPath-keyed) entry — fleet-safe by the
+ *  same key enable uses; a peer without an entry is 'absent' (idempotent). */
+export function removeClaudeForCwd(
+  plugin: string,
+  marketplace: string,
+  peerCwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): RuntimeRemoveResult {
+  const bin = claudeBin(env)
+  if (!isExecutable(bin, env)) return { runtime: 'claude', state: 'runtime-missing' }
+  const id = `${plugin}@${marketplace}`
+  const existing = claudeEntry(bin, plugin, marketplace, peerCwd, env)
+  if (!existing) return { runtime: 'claude', state: 'absent' }
+  const r = spawnSync(bin, ['plugin', 'uninstall', id, '--scope', 'project'], {
+    cwd: peerCwd,
+    encoding: 'utf8',
+    env: env as Record<string, string>,
+  })
+  const after = claudeEntry(bin, plugin, marketplace, peerCwd, env)
+  if (after) {
+    return { runtime: 'claude', state: 'failed', detail: (r.stderr || r.stdout || `exit ${r.status}`).trim() }
+  }
+  return { runtime: 'claude', state: 'removed' }
+}
+
+/** codex: remove the HOST-GLOBAL plugin (codex has no project scope) — callers gate
+ *  this on an explicit fleet-wide intent (`memory-plugin off --all`). */
+export function removeCodexGlobal(
+  plugin: string,
+  marketplace: string,
+  env: NodeJS.ProcessEnv = process.env,
+): RuntimeRemoveResult {
+  const bin = codexBin(env)
+  if (!isExecutable(bin, env)) return { runtime: 'codex', state: 'runtime-missing' }
+  const id = `${plugin}@${marketplace}`
+  if (codexState(bin, id, env) === 'absent') return { runtime: 'codex', state: 'absent' }
+  const r = spawnSync(bin, ['plugin', 'remove', id], { encoding: 'utf8', env: env as Record<string, string> })
+  if (codexState(bin, id, env) !== 'absent') {
+    return { runtime: 'codex', state: 'failed', detail: (r.stderr || r.stdout || `exit ${r.status}`).trim() }
+  }
+  return { runtime: 'codex', state: 'removed' }
+}

package/src/enable/memoryPlugin.test.ts

@@ -0,0 +1,103 @@
+// memory-plugin — slot-derived gating + target resolution + codex host-global
+// semantics (контракт §Плагин провайдера). Install forms are NOT exercised here
+// (they spawn runtime CLIs); the bins are pointed at /nonexistent so every
+// runtime resolves 'runtime-missing' — the orchestration around them is what
+// these tests pin.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { upsertPeer } from '../registry/index.ts'
+import { memoryProviderPath } from '../status/index.ts'
+import { memoryPluginApply } from './memoryPlugin.ts'
+
+let root: string
+function env(): NodeJS.ProcessEnv {
+  const e: NodeJS.ProcessEnv = {
+    ...process.env,
+    IAPEER_ROOT: root,
+    IAPEER_CLAUDE_BIN: '/nonexistent/claude',
+    IAPEER_CODEX_BIN: '/nonexistent/codex',
+  }
+  delete e.PEER_PERSONALITY
+  delete e.PEER_IDENTITY
+  delete e.PEER_RUNTIME
+  return e
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'iapeer-memplugin-'))
+})
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true })
+})
+
+const DECLARATION = {
+  provider: 'iapeer-memory',
+  package: '@agfpd/iapeer-memory',
+  version: '0.1.0',
+  registeredAt: '2026-06-10T00:00:00Z',
+}
+const PLUGIN = { name: 'iapeer-memory', marketplace: 'agfpd', marketplaceRef: 'agfpd/agfpd-marketplace' }
+
+function declareSlot(withPlugin: boolean): void {
+  writeFileSync(memoryProviderPath(env()), JSON.stringify(withPlugin ? { ...DECLARATION, plugin: PLUGIN } : DECLARATION))
+}
+
+describe('memory-plugin gating (slot-derived)', () => {
+  test('EMPTY slot → explicit refusal, no outcomes', () => {
+    const r = memoryPluginApply('on', { all: true, env: env() })
+    expect(r.ok).toBe(false)
+    expect(r.error).toContain('EMPTY')
+    expect(r.outcomes).toEqual([])
+  })
+
+  test('v1 declaration (no plugin block) → explicit refusal pointing at generic enable', () => {
+    declareSlot(false)
+    const r = memoryPluginApply('on', { all: true, env: env() })
+    expect(r.ok).toBe(false)
+    expect(r.error).toContain('declares no plugin block')
+  })
+
+  test('unknown --peer → explicit refusal', async () => {
+    declareSlot(true)
+    const r = memoryPluginApply('on', { peer: 'ghost', env: env() })
+    expect(r.ok).toBe(false)
+    expect(r.error).toContain('not in the iapeer peers index')
+  })
+
+  test('on --all: plugin derived from the slot; runtime-missing host → clean per-runtime outcomes, ok', async () => {
+    declareSlot(true)
+    await upsertPeer({ personality: 'alpha', runtime: 'claude', cwd: join(root, 'alpha'), intelligence: 'artificial' }, { rootDir: root })
+    await upsertPeer({ personality: 'tim', runtime: 'notifier', cwd: join(root, 'tim'), intelligence: 'absent' }, { rootDir: root })
+    const r = memoryPluginApply('on', { all: true, env: env() })
+    expect(r.plugin).toEqual(PLUGIN)
+    expect(r.ok).toBe(true) // runtime-missing is a skip, not a failure
+    const alpha = r.outcomes.find(o => o.personality === 'alpha')
+    expect(alpha?.state).toBe('runtime-missing')
+    // a peer with NO agentic runtime is skipped explicitly
+    const tim = r.outcomes.find(o => o.personality === 'tim')
+    expect(tim?.state).toBe('skipped-no-agentic-runtime')
+  })
+
+  test('off --peer on a codex peer → explicit host-global message, NOT a silent skip', async () => {
+    declareSlot(true)
+    await upsertPeer({ personality: 'cx', runtime: 'codex', cwd: join(root, 'cx'), intelligence: 'artificial' }, { rootDir: root })
+    const r = memoryPluginApply('off', { peer: 'cx', env: env() })
+    const o = r.outcomes.find(x => x.personality === 'cx' && x.runtime === 'codex')
+    expect(o?.state).toBe('skipped-host-global')
+    expect(o?.detail).toContain('--all')
+  })
+
+  test('off --all: codex host-global remove runs ONCE across the fleet', async () => {
+    declareSlot(true)
+    await upsertPeer({ personality: 'cx1', runtime: 'codex', cwd: join(root, 'cx1'), intelligence: 'artificial' }, { rootDir: root })
+    await upsertPeer({ personality: 'cx2', runtime: 'codex', cwd: join(root, 'cx2'), intelligence: 'artificial' }, { rootDir: root })
+    const r = memoryPluginApply('off', { all: true, env: env() })
+    const codexOutcomes = r.outcomes.filter(x => x.runtime === 'codex')
+    // one real attempt (runtime-missing on this sandbox) + one 'already' dedupe
+    expect(codexOutcomes.filter(x => x.state === 'runtime-missing').length).toBe(1)
+    expect(codexOutcomes.filter(x => x.state === 'already').length).toBe(1)
+  })
+})

package/src/enable/memoryPlugin.ts

@@ -0,0 +1,133 @@
+// memory-plugin — the slot-derived operator verb (контракт «Слот памяти»
+// §Плагин провайдера — авто-установка при рождении; agreed iapeer-memory + boris
+// 10.06). By analogy with native-memory: `iapeer memory-plugin <on|off>
+// (--peer <p> | --all)`. The plugin identity is DERIVED from the slot
+// declaration's v1.1 `plugin` block — an empty slot or a v1 declaration without
+// the block is an EXPLICIT refusal (for arbitrary plugins the generic `iapeer
+// enable` exists). Install/removal forms live in enable/index.ts (the ONE home);
+// this module only orchestrates targets and the codex host-global semantics.
+//
+// Consumers: the operator, the provider's init-sweep (`on --all` after writing
+// the declaration), and the provider's uninstall (`off --all` BEFORE deleting
+// the declaration — agreed AUTO-removal: a dead provider's plugin actively
+// errors in every session, unlike the native-memory restore asymmetry).
+
+import { findPeer, readPeersIndex } from '../registry/index.ts'
+import { readMemoryProvider, type MemoryProviderPlugin } from '../status/index.ts'
+import {
+  enableCapabilityForCwd,
+  removeClaudeForCwd,
+  removeCodexGlobal,
+  type CapabilityRuntime,
+} from './index.ts'
+
+export interface MemoryPluginOutcome {
+  personality: string
+  runtime: CapabilityRuntime | 'none'
+  /** enable states (on) | remove states (off) | orchestration-level skips. */
+  state: string
+  detail?: string
+}
+
+export interface MemoryPluginResult {
+  ok: boolean
+  /** The derived plugin (null when the slot refused — see error). */
+  plugin: MemoryProviderPlugin | null
+  /** Refusal reason (empty slot / v1 declaration / no targets). */
+  error?: string
+  outcomes: MemoryPluginOutcome[]
+}
+
+export interface MemoryPluginOptions {
+  peer?: string
+  all?: boolean
+  env?: NodeJS.ProcessEnv
+}
+
+/**
+ * Apply the slot-declared provider plugin across targets. `on` = install per the
+ * canonical forms (claude project-scope per peer cwd; codex host-global once —
+ * idempotent). `off` = claude per-peer project-scope uninstall; codex is
+ * HOST-GLOBAL, so off with `--peer` on a codex runtime reports an explicit
+ * «host-global — use --all» (no silent skip, сверка boris) and the global remove
+ * runs only under `--all` (once).
+ */
+export function memoryPluginApply(state: 'on' | 'off', opts: MemoryPluginOptions = {}): MemoryPluginResult {
+  const env = opts.env ?? process.env
+  const slot = readMemoryProvider(env)
+  if (!slot) {
+    return { ok: false, plugin: null, error: 'memory slot is EMPTY — no provider declared, nothing to install', outcomes: [] }
+  }
+  if (!slot.plugin) {
+    return {
+      ok: false,
+      plugin: null,
+      error: `provider "${slot.provider}" declares no plugin block (declaration v1) — for arbitrary plugins use \`iapeer enable\``,
+      outcomes: [],
+    }
+  }
+  const plugin = slot.plugin
+  const index = readPeersIndex({ env })
+  const targets = opts.all === true ? index.peers : opts.peer ? (p => (p ? [p] : []))(findPeer(index, opts.peer)) : []
+  if (targets.length === 0) {
+    return {
+      ok: false,
+      plugin,
+      error: opts.peer ? `peer "${opts.peer}" is not in the iapeer peers index` : 'no targets — pass --peer <p> or --all',
+      outcomes: [],
+    }
+  }
+
+  const outcomes: MemoryPluginOutcome[] = []
+  let codexHandledGlobally = false
+  for (const p of targets) {
+    const agentic = p.runtimes.filter((r): r is CapabilityRuntime => r === 'claude' || r === 'codex')
+    if (agentic.length === 0) {
+      outcomes.push({ personality: p.personality, runtime: 'none', state: 'skipped-no-agentic-runtime' })
+      continue
+    }
+    if (state === 'on') {
+      const r = enableCapabilityForCwd({
+        plugin: plugin.name,
+        marketplace: plugin.marketplace,
+        marketplaceRef: plugin.marketplaceRef,
+        cwd: p.cwd,
+        personality: p.personality,
+        runtimes: agentic,
+        env,
+      })
+      for (const rr of r.runtimes) {
+        outcomes.push({ personality: p.personality, runtime: rr.runtime, state: rr.state, detail: rr.detail })
+      }
+      if (r.setup !== 'absent') {
+        outcomes.push({ personality: p.personality, runtime: agentic[0]!, state: `setup-${r.setup}`, detail: r.setupDetail })
+      }
+    } else {
+      for (const rt of agentic) {
+        if (rt === 'claude') {
+          const rr = removeClaudeForCwd(plugin.name, plugin.marketplace, p.cwd, env)
+          outcomes.push({ personality: p.personality, runtime: 'claude', state: rr.state, detail: rr.detail })
+        } else {
+          // codex plugin is HOST-GLOBAL: per-peer off is impossible — explicit
+          // message (сверка boris), the actual remove runs ONCE under --all.
+          if (opts.all !== true) {
+            outcomes.push({
+              personality: p.personality,
+              runtime: 'codex',
+              state: 'skipped-host-global',
+              detail: 'codex plugin is host-global — use `memory-plugin off --all`',
+            })
+          } else if (!codexHandledGlobally) {
+            codexHandledGlobally = true
+            const rr = removeCodexGlobal(plugin.name, plugin.marketplace, env)
+            outcomes.push({ personality: p.personality, runtime: 'codex', state: rr.state, detail: rr.detail })
+          } else {
+            outcomes.push({ personality: p.personality, runtime: 'codex', state: 'already', detail: 'host-global remove already done this run' })
+          }
+        }
+      }
+    }
+  }
+  const failed = outcomes.some(o => o.state === 'failed' || o.state === 'setup-failed')
+  return { ok: !failed, plugin, outcomes }
+}

package/src/onboard/index.ts

@@ -105,25 +105,71 @@ export function isMarketplaceRegistered(runtime: OnboardRuntime, env: NodeJS.Pro
 }
 
 /**
- * Pure detector over a `plugin marketplace list` output: is OUR marketplace present?
- * Matches the agfpd GitHub source-ref (claude renders it) OR a standalone agfpd name
- * entry (both runtimes render the name). The name match is anchored to a line start
+ * Pure detector over a `plugin marketplace list` output: is a marketplace present?
+ * Matches the GitHub source-ref (claude renders it) OR a standalone name entry
+ * (both runtimes render the name). The name match is anchored to a line start
  * (optionally after the `❯` selection glyph) and followed by whitespace/EOL, so a
- * different `agfpd-<something>` token never false-positives. Pure → unit-testable
+ * different `<name>-<something>` token never false-positives. Pure → unit-testable
  * against real claude/codex samples (the fleet-guard hinges on it).
  */
+export function isMarketplaceInList(listOutput: string, name: string, ref?: string): boolean {
+  if (ref && new RegExp(ref.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')).test(listOutput)) return true
+  const esc = name.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+  return new RegExp(`(^|\\n)\\s*(❯\\s*)?${esc}(\\s|$)`).test(listOutput)
+}
+
+/** The OUR-marketplace specialization (the original onboard detector). */
 export function isAgfpdInList(listOutput: string): boolean {
-  if (new RegExp(MARKETPLACE_REF.replace('/', '\\/')).test(listOutput)) return true
-  return /(^|\n)\s*(❯\s*)?agfpd(\s|$)/.test(listOutput)
+  return isMarketplaceInList(listOutput, MARKETPLACE_NAME, MARKETPLACE_REF)
 }
 
-/** Register OUR marketplace for this runtime (`<runtime> plugin marketplace add <ref>`). */
-function registerMarketplace(runtime: OnboardRuntime, env: NodeJS.ProcessEnv): { ok: boolean; detail?: string } {
+/** Register a marketplace for this runtime (`<runtime> plugin marketplace add <ref>`).
+ *  Exported for the memory-plugin install path (контракт §Плагин провайдера: a
+ *  third-party provider's marketplaceRef must self-register on a fresh host). */
+export function registerMarketplace(
+  runtime: OnboardRuntime,
+  env: NodeJS.ProcessEnv,
+  ref: string = MARKETPLACE_REF,
+): { ok: boolean; detail?: string } {
   const bin = runtimeBin(runtime, env)
   // Same hard timeout as the list probe (the pre-main wedge class — known live
   // representative: macOS launch-approval pending after a cask update) — a wedged
   // add degrades to a loud 'failed' line instead of freezing the host phase.
-  const r = spawnSync(bin, ['plugin', 'marketplace', 'add', MARKETPLACE_REF], { encoding: 'utf8', timeout: 120_000 })
+  const r = spawnSync(bin, ['plugin', 'marketplace', 'add', ref], { encoding: 'utf8', timeout: 120_000 })
+  return r.status === 0
+    ? { ok: true }
+    : { ok: false, detail: (r.stderr ?? '').trim() || (r.status === null ? 'timed out (wedged runtime CLI?)' : `exit ${r.status}`) }
+}
+
+/** Is a marketplace (by name/ref) registered for this runtime? Generalized form of
+ *  isMarketplaceRegistered for the memory-plugin install path. */
+export function isMarketplaceRegisteredAs(
+  runtime: OnboardRuntime,
+  name: string,
+  ref: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  const bin = runtimeBin(runtime, env)
+  const r = spawnSync(bin, ['plugin', 'marketplace', 'list'], { encoding: 'utf8', timeout: 60_000 })
+  if (r.status !== 0) return false
+  return isMarketplaceInList(`${r.stdout ?? ''}`, name, ref)
+}
+
+/**
+ * Refresh a runtime's local marketplace SNAPSHOT (контракт §Плагин провайдера,
+ * просьба iapeer-memory): a plugin registered in the marketplace AFTER the host's
+ * last pull reads as «unknown plugin» until the snapshot updates. Verb names
+ * verified live 10.06: claude `plugin marketplace update <name>`, codex
+ * `plugin marketplace upgrade <name>`.
+ */
+export function refreshMarketplace(
+  runtime: OnboardRuntime,
+  name: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { ok: boolean; detail?: string } {
+  const bin = runtimeBin(runtime, env)
+  const verb = runtime === 'claude' ? 'update' : 'upgrade'
+  const r = spawnSync(bin, ['plugin', 'marketplace', verb, name], { encoding: 'utf8', timeout: 120_000 })
   return r.status === 0
     ? { ok: true }
     : { ok: false, detail: (r.stderr ?? '').trim() || (r.status === null ? 'timed out (wedged runtime CLI?)' : `exit ${r.status}`) }

package/src/provision/index.ts

@@ -98,7 +98,8 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
   // the provision — the operator verb `iapeer native-memory off` is the repair).
   try {
     const { readMemoryProvider } = await import('../status/index.ts')
-    if (readMemoryProvider(env)) {
+    const slot = readMemoryProvider(env)
+    if (slot) {
       const { applyNativeMemory, preTrustCodexCwd } = await import('../launch/nativeMemory.ts')
       for (const o of applyNativeMemory(cwd, profile.runtimes, 'off')) {
         if (o.state === 'failed') {
@@ -120,9 +121,41 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
           )
         }
       }
+      // Provider PLUGIN auto-install (контракт §Плагин провайдера, declaration
+      // v1.1; agreed iapeer-memory + boris 10.06): an occupied slot WITH a plugin
+      // block installs the provider's marketplace plugin into the newborn's scope
+      // (claude project-scope in cwd; codex host-global, idempotent) — «создал
+      // пира — память работает». A v1 declaration (no block) installs nothing.
+      // Best-effort with a LOUD warn; repair = `iapeer memory-plugin on --peer`.
+      if (slot.plugin) {
+        const { enableCapabilityForCwd } = await import('../enable/index.ts')
+        const agentic = profile.runtimes.filter((r): r is 'claude' | 'codex' => r === 'claude' || r === 'codex')
+        if (agentic.length > 0) {
+          const r = enableCapabilityForCwd({
+            plugin: slot.plugin.name,
+            marketplace: slot.plugin.marketplace,
+            marketplaceRef: slot.plugin.marketplaceRef,
+            cwd,
+            personality: profile.personality,
+            runtimes: agentic,
+            env,
+          })
+          for (const rr of r.runtimes) {
+            if (rr.state === 'failed') {
+              opts.warn?.(
+                `memory-plugin install (${rr.runtime}) FAILED for "${profile.personality}": ${rr.detail} — ` +
+                  `repair: iapeer memory-plugin on --peer ${profile.personality}`,
+              )
+            }
+          }
+          if (r.setup === 'failed') {
+            opts.warn?.(`memory-plugin setup FAILED for "${profile.personality}": ${r.setupDetail ?? ''}`)
+          }
+        }
+      }
     }
   } catch (e) {
-    opts.warn?.(`native-memory birth-time hook failed: ${e instanceof Error ? e.message : String(e)}`)
+    opts.warn?.(`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

package/src/provision/provision.test.ts

@@ -198,4 +198,29 @@ describe('provisionPeer birth-time native-memory lever', () => {
     expect(existsSync(join(cwd, '.claude', 'settings.json'))).toBe(false)
     expect(existsSync(join(cwd, '.codex', 'config.toml'))).toBe(false)
   })
+
+  test('slot with v1.1 plugin block → birth hook attempts the plugin install; runtime-missing host stays silent and provision SUCCEEDS', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    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',
+        plugin: { name: 'iapeer-memory', marketplace: 'agfpd', marketplaceRef: 'agfpd/agfpd-marketplace' },
+      }),
+    )
+    const cwd = join(root, 'wplug')
+    const warns: string[] = []
+    // HOME-scoped claude bin + no codex on PATH → both runtimes 'runtime-missing':
+    // a clean skip (host without the runtime), NOT a failure warn, and never a throw.
+    const r = await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(r.personality).toBe('wplug')
+    expect(warns.filter(w => w.includes('memory-plugin install'))).toEqual([])
+    // the native lever still applied (same slot-gated block)
+    expect(JSON.parse(readFileSync(join(cwd, '.claude', 'settings.json'), 'utf8')).autoMemoryEnabled).toBe(false)
+  })
 })

package/src/status/index.ts

@@ -16,6 +16,22 @@ 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'
 
+/** The provider's marketplace plugin (declaration v1.1, контракт §Плагин
+ *  провайдера — agreed with iapeer-memory + boris 10.06). Declares WHAT the core
+ *  auto-installs into a newborn peer's scope (and what `memory-plugin` targets).
+ *  All three fields are required when the block is present; an invalid block is
+ *  treated as ABSENT (fail-open, like the whole file) = v1 behavior, no install. */
+export interface MemoryProviderPlugin {
+  /** Plugin id in the marketplace (forms `<name>@<marketplace>` for installs). */
+  name: string
+  /** Marketplace NAME the plugin id keys on (e.g. "agfpd"). */
+  marketplace: string
+  /** Source ref for `plugin marketplace add` when the marketplace is not yet
+   *  registered on the host (owner/repo or URL) — the third-party-provider path;
+   *  for the distribution default it matches what onboard already adds. */
+  marketplaceRef: string
+}
+
 export interface MemoryProvider {
   /** Provider name occupying the slot (e.g. "iapeer-memory"). */
   provider: string
@@ -26,6 +42,19 @@ export interface MemoryProvider {
   /** 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
+  /** Optional marketplace-plugin declaration (v1.1) — see MemoryProviderPlugin. */
+  plugin?: MemoryProviderPlugin
+}
+
+/** Parse the optional v1.1 `plugin` block; anything short of three non-empty
+ *  strings → undefined (treated as absent — v1 declaration, core installs nothing). */
+function parsePluginBlock(raw: unknown): MemoryProviderPlugin | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+  const o = raw as Record<string, unknown>
+  if (typeof o.name !== 'string' || !o.name.trim()) return undefined
+  if (typeof o.marketplace !== 'string' || !o.marketplace.trim()) return undefined
+  if (typeof o.marketplaceRef !== 'string' || !o.marketplaceRef.trim()) return undefined
+  return { name: o.name.trim(), marketplace: o.marketplace.trim(), marketplaceRef: o.marketplaceRef.trim() }
 }
 
 export function memoryProviderPath(env: NodeJS.ProcessEnv = process.env): string {
@@ -44,12 +73,14 @@ export function readMemoryProvider(env: NodeJS.ProcessEnv = process.env): Memory
     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
+    const plugin = parsePluginBlock(o.plugin)
     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() } : {}),
+      ...(plugin ? { plugin } : {}),
     }
   } catch {
     return null // empty slot — bare core is valid

package/src/status/status.test.ts

@@ -61,6 +61,26 @@ describe('readMemoryProvider (slot declaration, fail-open)', () => {
       expect(readMemoryProvider(env)).toBeNull()
     }
   })
+
+  test('v1.1 plugin block: parsed when complete; INVALID block = absent (v1 behavior), declaration still valid', () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const plugin = { name: 'iapeer-memory', marketplace: 'agfpd', marketplaceRef: 'agfpd/agfpd-marketplace' }
+    writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, plugin }))
+    expect(readMemoryProvider(env)?.plugin).toEqual(plugin)
+    // incomplete / wrong-shape blocks → treated as ABSENT, the declaration itself stays valid
+    for (const bad of [
+      { name: 'x', marketplace: 'agfpd' }, // missing marketplaceRef
+      { name: '', marketplace: 'agfpd', marketplaceRef: 'r' }, // empty name
+      'iapeer-memory', // not an object
+      ['x'], // array
+    ]) {
+      writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, plugin: bad }))
+      const p = readMemoryProvider(env)
+      expect(p).not.toBeNull()
+      expect(p?.plugin).toBeUndefined()
+    }
+  })
 })
 
 describe('heartbeatAgeSecs', () => {