@agfpd/iapeer 0.2.27 → 0.2.29

package/package.json

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

package/src/cli/cli.test.ts

@@ -40,6 +40,60 @@ async function register(personality: string, runtime = 'claude', intelligence: '
   await upsertPeer({ personality, runtime, cwd: `/tmp/${personality}`, intelligence }, { rootDir: root })
 }
 
+// ─── v1.2 provision-инверсия at the CLI joints (memory-plugin printer + remove) ───
+
+describe('memory-plugin / remove with a v1.2 provision slot', () => {
+  function declareV12Slot(): string {
+    const journal = join(root, 'journal.txt')
+    const script = join(root, 'fake-provider.sh')
+    writeFileSync(script, `#!/bin/sh\nprintf '%s\\n' "$@" >> '${journal}'\n`, { mode: 0o755 })
+    writeFileSync(
+      join(root, 'memory-provider.json'),
+      JSON.stringify({
+        provider: 'fake-mem',
+        package: '@x/fake',
+        version: '0.0.1',
+        registeredAt: 'x',
+        provision: { command: script, args: ['provision-peer', '--occasion', '{occasion}'] },
+        unprovision: { command: script, args: ['unprovision-peer', '--cwd', '{cwd}', '--occasion', '{occasion}'] },
+      }),
+    )
+    return journal
+  }
+
+  test('memory-plugin on --peer: printer survives plugin=null (v1.2 path), exit 0 (live-caught 11.06 smoke)', async () => {
+    declareV12Slot()
+    await register('alpha')
+    let captured = ''
+    const origWrite = process.stdout.write
+    process.stdout.write = ((s: string | Uint8Array) => {
+      captured += typeof s === 'string' ? s : Buffer.from(s).toString('utf8')
+      return true
+    }) as typeof process.stdout.write
+    try {
+      const code = await runCli(['memory-plugin', 'on', '--peer', 'alpha'], env())
+      expect(code).toBe(0)
+      expect(captured).toContain('provision: provider command')
+      expect(captured).toContain('alpha (claude): ok')
+    } finally {
+      process.stdout.write = origWrite
+    }
+  })
+
+  test('remove: unprovision runs with occasion=remove BEFORE the purge, outcome reported', async () => {
+    const journal = declareV12Slot()
+    await register('beta')
+    const o = await removePeerCli('beta', { env: env() })
+    expect(o.action).toBe('removed')
+    expect(o.unprovision).toEqual(['claude:ok'])
+    const { readFileSync } = await import('fs')
+    const j = readFileSync(journal, 'utf8')
+    expect(j).toContain('unprovision-peer')
+    expect(j).toContain('--cwd\n/tmp/beta')
+    expect(j).toContain('remove')
+  })
+})
+
 describe('list', () => {
   test('lists registered peers with per-runtime liveness (asleep / stopped)', async () => {
     await register('alpha')

package/src/cli/index.ts

@@ -48,6 +48,9 @@ import { resolveCallerIdentity, resolveIdentity } from '../identity/index.ts'
 import { runAlwaysOn } from '../launch/launchdRun.ts'
 import { installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
 import { MARKETPLACE_NAME, onboardHost } from '../onboard/index.ts'
+import { readMemoryProvider } from '../status/index.ts'
+import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
+import { pluginLogsDir } from '../storage/index.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // list — registry + per-runtime liveness (contract Примитивы §list)
@@ -274,6 +277,9 @@ export interface RemoveOutcome {
    *  deliberately keeps the folder — user data is never deleted by a registry reap
    *  (boris's finding 10.06: say so in the output instead of leaving silent orphans). */
   cwd?: string
+  /** v1.2: per-runtime unprovision outcomes (`<rt>:<state>`), present when the
+   *  slot declares an unprovision command (occasion=remove ran before the purge). */
+  unprovision?: string[]
   /** Identity-keyed lifecycle artifacts purged with the record (state/lifecycle/
    *  `<identity>.*` per runtime). Without this purge a NEWBORN peer reusing the
    *  personality inherits the dead namesake's parking (live defect, boris 10.06:
@@ -309,13 +315,59 @@ export async function removePeerCli(
     }
   }
   await removePeer(personality, { env })
+  // v1.2 UNPROVISION joint (контракт §Provision провайдера): a provision-declaring
+  // slot gets its unprovision command per agentic runtime with occasion=remove —
+  // BEFORE purgeIdentityState, so the provider sees the peer's last consistent
+  // state while unwinding its surfaces. Best-effort: a provider hiccup must not
+  // block the reap (the outcome line says what happened; repair is the provider's
+  // verify sweep).
+  const unprovisionOutcomes: string[] = []
+  try {
+    const slot = readMemoryProvider(env)
+    if (slot?.unprovision) {
+      const { runProvisionCommand } = await import('../enable/provisionCommand.ts')
+      const agentic = peer.runtimes.filter((r): r is 'claude' | 'codex' => r === 'claude' || r === 'codex')
+      for (const rt of agentic) {
+        const o = runProvisionCommand({
+          block: slot.unprovision,
+          cwd: peer.cwd,
+          runtime: rt,
+          personality,
+          occasion: 'remove',
+          env,
+        })
+        appendLifecycleEvent(
+          pluginLogsDir('iapeer', { env }),
+          {
+            ev: 'memory-provision',
+            identity: `${rt}-${personality}`,
+            occasion: 'remove',
+            state: o.state,
+            exit: o.exitCode ?? undefined,
+            ms: o.durationMs,
+            detail: o.detail,
+          },
+          { env },
+        )
+        unprovisionOutcomes.push(`${rt}:${o.state}${o.state !== 'ok' && o.detail ? ` (${o.detail})` : ''}`)
+      }
+    }
+  } catch (e) {
+    unprovisionOutcomes.push(`failed: ${e instanceof Error ? e.message : String(e)}`)
+  }
   // Purge identity-keyed lifecycle state WITH the record (per runtime): stale
   // .stopped/.idle-reaped/... must never outlive the peer and ambush a future
   // namesake (purgeIdentityState doc). After the registry write, so a failed
   // remove never half-purges a still-registered peer.
   const cfg = loadLifecycleConfig(env)
   const purgedState = peer.runtimes.flatMap(rt => purgeIdentityState(cfg, buildProcessAddress(rt, personality)))
-  return { personality, action: 'removed', cwd: peer.cwd, purgedState }
+  return {
+    personality,
+    action: 'removed',
+    cwd: peer.cwd,
+    purgedState,
+    ...(unprovisionOutcomes.length ? { unprovision: unprovisionOutcomes } : {}),
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -616,7 +668,13 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
           errOut(`memory-plugin: ${r.error}\n`)
           return 1
         }
-        out(`plugin: ${r.plugin!.name}@${r.plugin!.marketplace} (provider-declared)\n`)
+        // v1.2: a provision-declaring slot routes through the provider's commands —
+        // r.plugin is null then (there is no marketplace plugin in play to print).
+        out(
+          r.plugin
+            ? `plugin: ${r.plugin.name}@${r.plugin.marketplace} (provider-declared)\n`
+            : `provision: provider command (declaration v1.2, occasion=${state === 'on' ? 'sweep-on' : flags.all === true ? 'off-all' : 'off-peer'})\n`,
+        )
         for (const o of r.outcomes) {
           out(`${o.personality} (${o.runtime}): ${o.state}${o.detail ? ` — ${o.detail}` : ''}\n`)
         }
@@ -764,6 +822,10 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         const o = await removePeerCli(positionals[0], { force: flags.force === true, env })
         if (o.action === 'removed') {
           out(`removed "${o.personality}" from the registry\n`)
+          // v1.2: the provider unwound its surfaces (occasion=remove) — say how it went.
+          if (o.unprovision?.length) {
+            out(`memory unprovision: ${o.unprovision.join(', ')}\n`)
+          }
           // Stale identity-keyed markers must die with the record (boris 10.06: a
           // namesake newborn inherited a dead peer's .stopped → refused to wake).
           if (o.purgedState?.length) {

package/src/enable/memoryPlugin.test.ts

@@ -101,3 +101,97 @@ describe('memory-plugin gating (slot-derived)', () => {
     expect(codexOutcomes.filter(x => x.state === 'already').length).toBe(1)
   })
 })
+
+// ─── v1.2 provision-инверсия (контракт §Provision провайдера, ADR-009) ───────
+
+import { chmodSync, readFileSync, existsSync } from 'fs'
+
+/** Declare a v1.2 slot whose provision/unprovision are fake journaling scripts. */
+function declareProvisionSlot(o: { provision?: boolean; unprovision?: boolean; alsoPlugin?: boolean; failing?: boolean }): {
+  journal: string
+} {
+  const journal = join(root, 'journal.txt')
+  const script = join(root, 'fake-provider.sh')
+  writeFileSync(
+    script,
+    o.failing ? `#!/bin/sh\necho provider broken >&2\nexit 7\n` : `#!/bin/sh\nprintf '%s\\n' "$@" >> '${journal}'\n`,
+  )
+  chmodSync(script, 0o755)
+  const block = (occ: string) => ({
+    command: script,
+    args: [occ, '--cwd', '{cwd}', '--runtime', '{runtime}', '--personality', '{personality}', '--occasion', '{occasion}'],
+  })
+  writeFileSync(
+    memoryProviderPath(env()),
+    JSON.stringify({
+      ...DECLARATION,
+      ...(o.alsoPlugin ? { plugin: PLUGIN } : {}),
+      ...(o.provision !== false ? { provision: block('provision-peer') } : {}),
+      ...(o.unprovision !== false ? { unprovision: block('unprovision-peer') } : {}),
+    }),
+  )
+  return { journal }
+}
+
+describe('memory-plugin v1.2 provision routing', () => {
+  test('on --peer: provision command invoked per agentic runtime with occasion=sweep-on, substituted argv', async () => {
+    const { journal } = declareProvisionSlot({})
+    await upsertPeer({ personality: 'alpha', runtime: 'claude', cwd: join(root, 'alpha'), intelligence: 'artificial' }, { rootDir: root })
+    const r = memoryPluginApply('on', { peer: 'alpha', env: env() })
+    expect(r.ok).toBe(true)
+    expect(r.outcomes).toEqual([{ personality: 'alpha', runtime: 'claude', state: 'ok', detail: undefined }])
+    const j = readFileSync(journal, 'utf8').split('\n')
+    expect(j[0]).toBe('provision-peer')
+    expect(j.slice(1, 9)).toEqual(['--cwd', join(root, 'alpha'), '--runtime', 'claude', '--personality', 'alpha', '--occasion', 'sweep-on'])
+  })
+
+  test('PRECEDENCE: slot with BOTH blocks routes to provision; the plugin path is never touched', async () => {
+    const { journal } = declareProvisionSlot({ alsoPlugin: true })
+    await upsertPeer({ personality: 'beta', runtime: 'claude', cwd: join(root, 'beta'), intelligence: 'artificial' }, { rootDir: root })
+    const r = memoryPluginApply('on', { peer: 'beta', env: env() })
+    expect(r.ok).toBe(true)
+    // plugin path on this sandbox would yield 'runtime-missing' (bins at /nonexistent);
+    // 'ok' from the journaling script proves the provision command ran instead.
+    expect(r.outcomes[0]?.state).toBe('ok')
+    expect(readFileSync(journal, 'utf8')).toContain('provision-peer')
+  })
+
+  test('provision failure → ok=false with detail, NO fallback to the plugin path', async () => {
+    declareProvisionSlot({ failing: true, alsoPlugin: true })
+    await upsertPeer({ personality: 'gamma', runtime: 'claude', cwd: join(root, 'gamma'), intelligence: 'artificial' }, { rootDir: root })
+    const r = memoryPluginApply('on', { peer: 'gamma', env: env() })
+    expect(r.ok).toBe(false)
+    expect(r.outcomes[0]?.state).toBe('failed')
+    expect(r.outcomes[0]?.detail).toContain('provider broken')
+  })
+
+  test('off --peer → unprovision occasion=off-peer; off --all → off-all; codex has NO host-global special-casing', async () => {
+    const { journal } = declareProvisionSlot({})
+    await upsertPeer({ personality: 'cx', runtime: 'codex', cwd: join(root, 'cx'), intelligence: 'artificial' }, { rootDir: root })
+    const r1 = memoryPluginApply('off', { peer: 'cx', env: env() })
+    expect(r1.ok).toBe(true)
+    expect(r1.outcomes[0]).toEqual({ personality: 'cx', runtime: 'codex', state: 'ok', detail: undefined })
+    const r2 = memoryPluginApply('off', { all: true, env: env() })
+    expect(r2.ok).toBe(true)
+    const j = readFileSync(journal, 'utf8')
+    expect(j).toContain('off-peer')
+    expect(j).toContain('off-all')
+    expect(j).toContain('unprovision-peer')
+  })
+
+  test('missing direction block → explicit refusal (no silent skip, no plugin fallback)', async () => {
+    declareProvisionSlot({ unprovision: false, alsoPlugin: true })
+    await upsertPeer({ personality: 'delta', runtime: 'claude', cwd: join(root, 'delta'), intelligence: 'artificial' }, { rootDir: root })
+    const r = memoryPluginApply('off', { peer: 'delta', env: env() })
+    expect(r.ok).toBe(false)
+    expect(r.error).toContain('declares no unprovision command')
+  })
+
+  test('non-agentic peer → explicit skip (provision never invoked)', async () => {
+    const { journal } = declareProvisionSlot({})
+    await upsertPeer({ personality: 'tim2', runtime: 'notifier', cwd: join(root, 'tim2'), intelligence: 'absent' }, { rootDir: root })
+    const r = memoryPluginApply('on', { peer: 'tim2', env: env() })
+    expect(r.outcomes[0]?.state).toBe('skipped-no-agentic-runtime')
+    expect(existsSync(journal)).toBe(false)
+  })
+})

package/src/enable/memoryPlugin.ts

@@ -12,14 +12,17 @@
 // the declaration — agreed AUTO-removal: a dead provider's plugin actively
 // errors in every session, unlike the native-memory restore asymmetry).
 
+import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { findPeer, readPeersIndex } from '../registry/index.ts'
-import { readMemoryProvider, type MemoryProviderPlugin } from '../status/index.ts'
+import { readMemoryProvider, type MemoryProviderPlugin, type MemoryProviderProvision } from '../status/index.ts'
+import { pluginLogsDir } from '../storage/index.ts'
 import {
   enableCapabilityForCwd,
   removeClaudeForCwd,
   removeCodexGlobal,
   type CapabilityRuntime,
 } from './index.ts'
+import { runProvisionCommand, type ProvisionOccasion } from './provisionCommand.ts'
 
 export interface MemoryPluginOutcome {
   personality: string
@@ -58,6 +61,13 @@ export function memoryPluginApply(state: 'on' | 'off', opts: MemoryPluginOptions
   if (!slot) {
     return { ok: false, plugin: null, error: 'memory slot is EMPTY — no provider declared, nothing to install', outcomes: [] }
   }
+  // v1.2 PRECEDENCE (контракт §Provision провайдера): a provision-declaring slot
+  // routes BOTH verb directions through the provider's commands; the deprecated
+  // v1.1 plugin block is ignored entirely (no fallback — masking a provision
+  // failure would hide a broken provider behind a stale plugin install).
+  if (slot.provision || slot.unprovision) {
+    return memoryProvisionApply(state, slot.provision, slot.unprovision, slot.provider, opts, env)
+  }
   if (!slot.plugin) {
     return {
       ok: false,
@@ -131,3 +141,70 @@ export function memoryPluginApply(state: 'on' | 'off', opts: MemoryPluginOptions
   const failed = outcomes.some(o => o.state === 'failed' || o.state === 'setup-failed')
   return { ok: !failed, plugin, outcomes }
 }
+
+/**
+ * v1.2 verb routing through the provider's provision/unprovision commands
+ * (occasion: on → sweep-on; off --peer → off-peer; off --all → off-all). One
+ * invocation per target peer × agentic runtime — NO host-global special-casing
+ * here: ref-counting of host-global surfaces (codex) moved to the PROVIDER with
+ * the inversion (contract requirement 4). A direction whose command block is
+ * absent is an explicit refusal (never silently skipped, never plugin-fallback).
+ */
+function memoryProvisionApply(
+  state: 'on' | 'off',
+  provision: MemoryProviderProvision | undefined,
+  unprovision: MemoryProviderProvision | undefined,
+  provider: string,
+  opts: MemoryPluginOptions,
+  env: NodeJS.ProcessEnv,
+): MemoryPluginResult {
+  const block = state === 'on' ? provision : unprovision
+  if (!block) {
+    return {
+      ok: false,
+      plugin: null,
+      error:
+        `provider "${provider}" declares no ${state === 'on' ? 'provision' : 'unprovision'} command ` +
+        `(declaration v1.2 requires both directions) — fix the provider's declaration`,
+      outcomes: [],
+    }
+  }
+  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: null,
+      error: opts.peer ? `peer "${opts.peer}" is not in the iapeer peers index` : 'no targets — pass --peer <p> or --all',
+      outcomes: [],
+    }
+  }
+  const occasion: ProvisionOccasion = state === 'on' ? 'sweep-on' : opts.all === true ? 'off-all' : 'off-peer'
+  const outcomes: MemoryPluginOutcome[] = []
+  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
+    }
+    for (const rt of agentic) {
+      const o = runProvisionCommand({ block, cwd: p.cwd, runtime: rt, personality: p.personality, occasion, env })
+      appendLifecycleEvent(
+        pluginLogsDir('iapeer', { env }),
+        {
+          ev: 'memory-provision',
+          identity: `${rt}-${p.personality}`,
+          occasion,
+          state: o.state,
+          exit: o.exitCode ?? undefined,
+          ms: o.durationMs,
+          detail: o.detail,
+        },
+        { env },
+      )
+      outcomes.push({ personality: p.personality, runtime: rt, state: o.state, detail: o.detail })
+    }
+  }
+  const failed = outcomes.some(o => o.state !== 'ok' && o.state !== 'skipped-no-agentic-runtime')
+  return { ok: !failed, plugin: null, outcomes }
+}

package/src/enable/provisionCommand.test.ts

@@ -0,0 +1,107 @@
+// Provision-command executor — the v1.2 inversion joint. Pins the four contract
+// requirements: per-arg placeholder substitution WITHOUT a shell (injection
+// class), absolute command, timeout, structured outcomes. The fake provider is
+// a tmp shell script that journals its argv — no real provider involved.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { runProvisionCommand } from './provisionCommand.ts'
+
+let dir: string
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'iapeer-provcmd-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+/** A fake provider command journaling each argv element on its own line. */
+function fakeProvider(name: string, body?: string): string {
+  const p = join(dir, name)
+  writeFileSync(p, `#!/bin/sh\n${body ?? `printf '%s\\n' "$@" > '${dir}/journal.txt'`}\n`)
+  chmodSync(p, 0o755)
+  return p
+}
+
+describe('runProvisionCommand (v1.2 executor)', () => {
+  test('per-arg substitution of {cwd}/{runtime}/{personality}/{occasion}, argv passed verbatim (no shell)', () => {
+    const cmd = fakeProvider('prov.sh')
+    const o = runProvisionCommand({
+      block: {
+        command: cmd,
+        // both shapes: bare placeholder arg and embedded `--k={v}`; plus an arg
+        // full of shell metacharacters that MUST stay literal (no shell layer)
+        args: ['provision-peer', '--cwd', '{cwd}', '--runtime={runtime}', '--occasion', '{occasion}', '$(reboot) `id` ; rm -rf /'],
+      },
+      cwd: '/tmp/some peer dir',
+      runtime: 'claude',
+      personality: 'tw-prov',
+      occasion: 'birth',
+    })
+    expect(o.state).toBe('ok')
+    expect(o.exitCode).toBe(0)
+    const journal = readFileSync(join(dir, 'journal.txt'), 'utf8').split('\n')
+    expect(journal[0]).toBe('provision-peer')
+    expect(journal[1]).toBe('--cwd')
+    expect(journal[2]).toBe('/tmp/some peer dir') // spaces survive — single argv element
+    expect(journal[3]).toBe('--runtime=claude') // embedded substitution
+    expect(journal[4]).toBe('--occasion')
+    expect(journal[5]).toBe('birth')
+    expect(journal[6]).toBe('$(reboot) `id` ; rm -rf /') // LITERAL — never shell-parsed
+  })
+
+  test('{personality} placeholder is supported (optional for the provider)', () => {
+    const cmd = fakeProvider('prov.sh')
+    const o = runProvisionCommand({
+      block: { command: cmd, args: ['{personality}'] },
+      cwd: '/x',
+      runtime: 'codex',
+      personality: 'boris',
+      occasion: 'sweep-on',
+    })
+    expect(o.state).toBe('ok')
+    expect(readFileSync(join(dir, 'journal.txt'), 'utf8').trim()).toBe('boris')
+  })
+
+  test('non-zero exit → failed with exit code and stderr tail', () => {
+    const cmd = fakeProvider('prov.sh', `echo 'no such peer' >&2; exit 3`)
+    const o = runProvisionCommand({
+      block: { command: cmd, args: [] },
+      cwd: '/x',
+      runtime: 'claude',
+      personality: 'p',
+      occasion: 'off-peer',
+    })
+    expect(o.state).toBe('failed')
+    expect(o.exitCode).toBe(3)
+    expect(o.detail).toContain('no such peer')
+  })
+
+  test('timeout → state=timeout, never hangs the joint', () => {
+    const cmd = fakeProvider('prov.sh', 'sleep 30')
+    const o = runProvisionCommand({
+      block: { command: cmd, args: [] },
+      cwd: '/x',
+      runtime: 'claude',
+      personality: 'p',
+      occasion: 'remove',
+      timeoutMs: 300,
+    })
+    expect(o.state).toBe('timeout')
+    expect(o.durationMs).toBeLessThan(5000)
+  })
+
+  test('missing/non-executable command → not-executable (never throws)', () => {
+    const o = runProvisionCommand({
+      block: { command: join(dir, 'nope.sh'), args: [] },
+      cwd: '/x',
+      runtime: 'claude',
+      personality: 'p',
+      occasion: 'birth',
+    })
+    expect(o.state).toBe('not-executable')
+    expect(o.exitCode).toBeNull()
+  })
+})

package/src/enable/provisionCommand.ts

@@ -0,0 +1,112 @@
+// Provision-command executor — the v1.2 inversion joint (контракт «Слот памяти»
+// §Provision провайдера; ADR-009, решение Артура 10.06, схема сверена с
+// iapeer-memory 11.06). The slot declares provision/unprovision COMMANDS; the
+// core shells into them at the lifecycle joints and knows NOTHING about surface
+// forms. The four contract requirements live here:
+//   1. argv-form {command, args[]} with PER-ARG placeholder substitution —
+//      spawned WITHOUT a shell (injection/quoting class; бэктик-грабли 10.06).
+//   2. `command` is ABSOLUTE (parser refuses relative — launchd minimal PATH).
+//   3. Timeout 120 s; best-effort semantics live at the CALL SITES (LOUD warn,
+//      the birth/remove flow continues) — this module only reports structurally.
+//   4. {occasion} vocabulary: birth | sweep-on | off-peer | off-all | remove —
+//      ref-counting of host-global surfaces is the PROVIDER's business.
+// Idempotency is the provider's obligation by construction; the provider holds
+// its own lock against concurrent provisions.
+
+import { spawnSync } from 'child_process'
+import { accessSync, constants as FS } from 'fs'
+import type { MemoryProviderProvision } from '../status/index.ts'
+
+/** The agreed occasion vocabulary (финален, сверено с iapeer-memory). */
+export type ProvisionOccasion = 'birth' | 'sweep-on' | 'off-peer' | 'off-all' | 'remove'
+
+export const PROVISION_TIMEOUT_MS = 120_000
+
+export interface ProvisionCommandSpec {
+  /** The declared command block (provision or unprovision). */
+  block: MemoryProviderProvision
+  /** Placeholder values — substituted PER-ARG, substring-level (so both
+   *  `--cwd {cwd}` and `--cwd={cwd}` argv shapes work). */
+  cwd: string
+  runtime: string
+  personality: string
+  occasion: ProvisionOccasion
+  env?: NodeJS.ProcessEnv
+  timeoutMs?: number
+}
+
+export interface ProvisionCommandOutcome {
+  state: 'ok' | 'failed' | 'timeout' | 'not-executable'
+  exitCode: number | null
+  /** stderr tail (last ~400 chars) — the structured detail for eventlog/warns. */
+  detail?: string
+  durationMs: number
+  /** The fully substituted argv (command first) — logged for postmortems. */
+  argv: string[]
+}
+
+function substitute(arg: string, s: ProvisionCommandSpec): string {
+  return arg
+    .replaceAll('{cwd}', s.cwd)
+    .replaceAll('{runtime}', s.runtime)
+    .replaceAll('{personality}', s.personality)
+    .replaceAll('{occasion}', s.occasion)
+}
+
+function tail(text: string, max = 400): string | undefined {
+  const t = text.trim()
+  if (!t) return undefined
+  return t.length <= max ? t : `…${t.slice(-max)}`
+}
+
+/**
+ * Run ONE provider provision/unprovision command for ONE peer × runtime ×
+ * occasion. Synchronous (the call sites are the synchronous provision/remove
+ * flows), no shell, bounded by timeout. NEVER throws — every failure is a
+ * structured outcome the call site warns about (best-effort: a provider hiccup
+ * must not kill a birth or a remove).
+ */
+export function runProvisionCommand(spec: ProvisionCommandSpec): ProvisionCommandOutcome {
+  const env = spec.env ?? process.env
+  const argv = [spec.block.command, ...spec.block.args.map(a => substitute(a, spec))]
+  const started = Date.now()
+  try {
+    accessSync(spec.block.command, FS.X_OK)
+  } catch {
+    return {
+      state: 'not-executable',
+      exitCode: null,
+      detail: `command not found or not executable: ${spec.block.command}`,
+      durationMs: Date.now() - started,
+      argv,
+    }
+  }
+  try {
+    const r = spawnSync(argv[0]!, argv.slice(1), {
+      env: env as Record<string, string>,
+      encoding: 'utf8',
+      timeout: spec.timeoutMs ?? PROVISION_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const durationMs = Date.now() - started
+    // node/bun signal a timeout via error.code ETIMEDOUT + signal SIGTERM
+    if (r.error && (r.error as NodeJS.ErrnoException).code === 'ETIMEDOUT') {
+      return { state: 'timeout', exitCode: null, detail: `timed out after ${spec.timeoutMs ?? PROVISION_TIMEOUT_MS} ms`, durationMs, argv }
+    }
+    if (r.error) {
+      return { state: 'failed', exitCode: null, detail: r.error.message, durationMs, argv }
+    }
+    if (r.status !== 0) {
+      return { state: 'failed', exitCode: r.status, detail: tail(r.stderr ?? ''), durationMs, argv }
+    }
+    return { state: 'ok', exitCode: 0, detail: tail(r.stderr ?? ''), durationMs, argv }
+  } catch (e) {
+    return {
+      state: 'failed',
+      exitCode: null,
+      detail: e instanceof Error ? e.message : String(e),
+      durationMs: Date.now() - started,
+      argv,
+    }
+  }
+}

package/src/provision/index.ts

@@ -121,13 +121,59 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
           )
         }
       }
+      // Provider PROVISION command (контракт §Provision провайдера, declaration
+      // v1.2 — ADR-009 inversion; решение Артура 10.06, схема сверена с
+      // iapeer-memory 11.06): an occupied slot WITH a provision block shells into
+      // the PROVIDER's command per agentic runtime (occasion=birth) — the core
+      // knows nothing about surface forms. PRECEDENCE: provision WINS over the
+      // deprecated v1.1 plugin block, with NO runtime fallback to plugin on
+      // failure (masking a provision refusal would hide a broken provider —
+      // LOUD warn + repair-hint instead). Runs AFTER preTrustCodexCwd above, so
+      // the provider's per-peer codex surfaces land in an already-trusted cwd.
+      if (slot.provision) {
+        const { runProvisionCommand } = await import('../enable/provisionCommand.ts')
+        const { appendLifecycleEvent } = await import('../lifecycle/eventlog.ts')
+        const { pluginLogsDir } = await import('../storage/index.ts')
+        const agentic = profile.runtimes.filter((r): r is 'claude' | 'codex' => r === 'claude' || r === 'codex')
+        for (const rt of agentic) {
+          const o = runProvisionCommand({
+            block: slot.provision,
+            cwd,
+            runtime: rt,
+            personality: profile.personality,
+            occasion: 'birth',
+            env,
+          })
+          appendLifecycleEvent(
+            pluginLogsDir('iapeer', { env }),
+            {
+              ev: 'memory-provision',
+              identity: `${rt}-${profile.personality}`,
+              occasion: 'birth',
+              state: o.state,
+              exit: o.exitCode ?? undefined,
+              ms: o.durationMs,
+              detail: o.detail,
+            },
+            { env },
+          )
+          if (o.state !== 'ok') {
+            opts.warn?.(
+              `memory provision (${rt}) ${o.state.toUpperCase()} for "${profile.personality}"` +
+                `${o.detail ? `: ${o.detail}` : ''} — память пира не подключена; ` +
+                `repair: iapeer memory-plugin on --peer ${profile.personality}`,
+            )
+          }
+        }
+      }
       // 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.
+      // v1.1, DEPRECATED by §Provision; agreed iapeer-memory + boris 10.06): an
+      // occupied slot WITH a plugin block and WITHOUT a provision 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) {
+      else 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) {

package/src/provision/provision.test.ts

@@ -223,4 +223,67 @@ describe('provisionPeer birth-time native-memory lever', () => {
     // the native lever still applied (same slot-gated block)
     expect(JSON.parse(readFileSync(join(cwd, '.claude', 'settings.json'), 'utf8')).autoMemoryEnabled).toBe(false)
   })
+
+  test('v1.2: slot with provision command → birth shells into it per runtime (occasion=birth), plugin path NOT taken', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    mkdirSync(join(root, 'iapeer'), { recursive: true })
+    const journal = join(root, 'journal.txt')
+    const script = join(root, 'fake-provider.sh')
+    const { chmodSync } = await import('fs')
+    writeFileSync(script, `#!/bin/sh\nprintf '%s\\n' "$@" >> '${journal}'\n`)
+    chmodSync(script, 0o755)
+    writeFileSync(
+      join(root, 'iapeer', 'memory-provider.json'),
+      JSON.stringify({
+        provider: 'iapeer-memory',
+        package: '@agfpd/iapeer-memory',
+        version: '0.2.0',
+        registeredAt: 'x',
+        // BOTH blocks declared → provision must WIN (precedence, no plugin attempt)
+        plugin: { name: 'iapeer-memory', marketplace: 'agfpd', marketplaceRef: 'agfpd/agfpd-marketplace' },
+        provision: {
+          command: script,
+          args: ['provision-peer', '--cwd', '{cwd}', '--runtime', '{runtime}', '--personality', '{personality}', '--occasion', '{occasion}'],
+        },
+      }),
+    )
+    const cwd = join(root, 'wprov')
+    const warns: string[] = []
+    const r = await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(r.personality).toBe('wprov')
+    expect(warns).toEqual([]) // provision ok → no warn at all
+    const j = readFileSync(journal, 'utf8').split('\n')
+    expect(j[0]).toBe('provision-peer')
+    expect(j.slice(1, 9)).toEqual(['--cwd', cwd, '--runtime', 'claude', '--personality', 'wprov', '--occasion', 'birth'])
+  })
+
+  test('v1.2: provision command FAILS → LOUD warn with repair-hint, provision of the peer still SUCCEEDS (best-effort)', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    mkdirSync(join(root, 'iapeer'), { recursive: true })
+    const script = join(root, 'fake-provider.sh')
+    const { chmodSync } = await import('fs')
+    writeFileSync(script, `#!/bin/sh\necho 'vault offline' >&2\nexit 9\n`)
+    chmodSync(script, 0o755)
+    writeFileSync(
+      join(root, 'iapeer', 'memory-provider.json'),
+      JSON.stringify({
+        provider: 'iapeer-memory',
+        package: '@agfpd/iapeer-memory',
+        version: '0.2.0',
+        registeredAt: 'x',
+        provision: { command: script, args: ['{occasion}'] },
+      }),
+    )
+    const cwd = join(root, 'wfail')
+    const warns: string[] = []
+    const r = await provisionPeer({ cwd, runtime: 'claude', env, warn: m => warns.push(m) })
+    expect(r.personality).toBe('wfail') // birth completed despite the provider hiccup
+    const w = warns.find(x => x.includes('memory provision'))
+    expect(w).toBeDefined()
+    expect(w).toContain('FAILED')
+    expect(w).toContain('vault offline')
+    expect(w).toContain('memory-plugin on --peer wfail') // repair-hint
+  })
 })

package/src/status/index.ts

@@ -32,6 +32,21 @@ export interface MemoryProviderPlugin {
   marketplaceRef: string
 }
 
+/** The provider's provision command (declaration v1.2, контракт §Provision
+ *  провайдера — ADR-009 inversion, решение Артура 10.06 + дизайн-консенсус
+ *  сторон). The slot declares not surfaces but a COMMAND the core shells into at
+ *  the lifecycle joints (birth / verb sweeps / remove); surface forms and their
+ *  uninstall accounting live entirely with the provider. The `command` must be
+ *  ABSOLUTE (the daemon runs under launchd's minimal PATH); `args` get PER-ARG
+ *  placeholder substitution ({cwd}/{runtime}/{personality}/{occasion}) and are
+ *  spawned WITHOUT a shell (injection/quoting class — бэктик-грабли 10.06). */
+export interface MemoryProviderProvision {
+  /** Absolute path to the provider's executable. */
+  command: string
+  /** Argv tail; placeholders are substituted per-argument, never shell-parsed. */
+  args: string[]
+}
+
 export interface MemoryProvider {
   /** Provider name occupying the slot (e.g. "iapeer-memory"). */
   provider: string
@@ -42,8 +57,15 @@ 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. */
+  /** Optional marketplace-plugin declaration (v1.1) — see MemoryProviderPlugin.
+   *  DEPRECATED by v1.2: when `provision` is also present, provision WINS and
+   *  the plugin block is ignored (no runtime fallback — an explicit precedence,
+   *  agreed iapeer-memory 11.06). */
   plugin?: MemoryProviderPlugin
+  /** Optional v1.2 provision command (peer-birth / sweep-on joints). */
+  provision?: MemoryProviderProvision
+  /** Optional v1.2 unprovision command (off-peer / off-all / remove joints). */
+  unprovision?: MemoryProviderProvision
 }
 
 /** Parse the optional v1.1 `plugin` block; anything short of three non-empty
@@ -57,6 +79,18 @@ function parsePluginBlock(raw: unknown): MemoryProviderPlugin | undefined {
   return { name: o.name.trim(), marketplace: o.marketplace.trim(), marketplaceRef: o.marketplaceRef.trim() }
 }
 
+/** Parse an optional v1.2 `provision`/`unprovision` block. Fail-open like the
+ *  plugin block: anything short of an ABSOLUTE command string + an array of
+ *  strings → undefined (treated as absent). A relative command is INVALID by
+ *  contract (launchd minimal PATH would resolve it differently per caller). */
+function parseProvisionBlock(raw: unknown): MemoryProviderProvision | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+  const o = raw as Record<string, unknown>
+  if (typeof o.command !== 'string' || !o.command.trim().startsWith('/')) return undefined
+  if (!Array.isArray(o.args) || o.args.some(a => typeof a !== 'string')) return undefined
+  return { command: o.command.trim(), args: (o.args as string[]).slice() }
+}
+
 export function memoryProviderPath(env: NodeJS.ProcessEnv = process.env): string {
   return join(resolveGlobalRoot(env), MEMORY_PROVIDER_FILE)
 }
@@ -74,6 +108,8 @@ export function readMemoryProvider(env: NodeJS.ProcessEnv = process.env): Memory
     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)
+    const provision = parseProvisionBlock(o.provision)
+    const unprovision = parseProvisionBlock(o.unprovision)
     return {
       provider: o.provider.trim(),
       package: o.package.trim(),
@@ -81,6 +117,8 @@ export function readMemoryProvider(env: NodeJS.ProcessEnv = process.env): Memory
       registeredAt: typeof o.registeredAt === 'string' ? o.registeredAt : '',
       ...(typeof o.heartbeat === 'string' && o.heartbeat.trim() ? { heartbeat: o.heartbeat.trim() } : {}),
       ...(plugin ? { plugin } : {}),
+      ...(provision ? { provision } : {}),
+      ...(unprovision ? { unprovision } : {}),
     }
   } catch {
     return null // empty slot — bare core is valid

package/src/status/status.test.ts

@@ -81,6 +81,33 @@ describe('readMemoryProvider (slot declaration, fail-open)', () => {
       expect(p?.plugin).toBeUndefined()
     }
   })
+
+  test('v1.2 provision/unprovision blocks: parsed when valid; relative command or bad args = absent (fail-open)', () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const provision = { command: '/usr/local/bin/iapeer-memory', args: ['provision-peer', '--cwd', '{cwd}'] }
+    const unprovision = { command: '/usr/local/bin/iapeer-memory', args: ['unprovision-peer'] }
+    writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, provision, unprovision }))
+    const p = readMemoryProvider(env)
+    expect(p?.provision).toEqual(provision)
+    expect(p?.unprovision).toEqual(unprovision)
+    // empty args array is VALID (command alone)
+    writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, provision: { command: '/x/y', args: [] } }))
+    expect(readMemoryProvider(env)?.provision).toEqual({ command: '/x/y', args: [] })
+    // invalid shapes → block absent, declaration itself stays valid
+    for (const bad of [
+      { command: 'iapeer-memory', args: [] }, // RELATIVE command (launchd minimal PATH) — contract-invalid
+      { command: '/x/y' }, // args missing
+      { command: '/x/y', args: ['ok', 42] }, // non-string arg
+      { args: ['provision-peer'] }, // command missing
+      'provision-me', // not an object
+    ]) {
+      writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, provision: bad }))
+      const r = readMemoryProvider(env)
+      expect(r).not.toBeNull()
+      expect(r?.provision).toBeUndefined()
+    }
+  })
 })
 
 describe('heartbeatAgeSecs', () => {