@agfpd/iapeer 0.2.26 → 0.2.28

package/package.json

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

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 } : {}),
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -764,6 +816,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/launch/canary.test.ts

@@ -10,7 +10,9 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import {
   canaryChannel,
+  canaryProcessPattern,
   canaryScript,
+  dismissCanary,
   ensureServerCanary,
   exitLogPath,
   serverDeathsDir,
@@ -53,7 +55,7 @@ describe('canary script (pure)', () => {
     expect(exitLogPath('/r/logs/iapeer')).toBe('/r/logs/iapeer/exits.log')
   })
 
-  test('script carries the protocol: wait-for channel, silent-exit guards, record line, forensics', () => {
+  test('script carries the v2 protocol: wait-for channel, deliberate-silence guards, liveness probe, record line, forensics', () => {
     const s = canaryScript({
       identity: 'claude-bob',
       sock: '/tmp/x.sock',
@@ -62,8 +64,15 @@ describe('canary script (pure)', () => {
       forensicsDir: '/r/logs/iapeer/server-deaths',
     })
     expect(s).toContain(`wait-for 'iap-canary-claude-bob'`) // the blocking client
-    expect(s).toContain(`trap 'exit 0' HUP INT TERM`) // signaled canary = silent
-    expect(s).toContain(`[ "$rc" -eq 0 ] || [ "$rc" -ge 128 ]`) // clean/signaled guards
+    expect(s).toContain(`trap 'exit 0' HUP INT TERM`) // dismissed sh = silent (the ONLY deliberate silencer)
+    // v2: NO exit code is trusted as deliberate (a TERMed client returns rc=0 —
+    // proven live); the SERVER's liveness decides, after a dismissal grace sleep.
+    expect(s).not.toContain(`[ "$rc" -eq 0 ] || [ "$rc" -ge 128 ]; then exit 0`) // the v1 hole
+    expect(s).toContain('sleep 2') // dismissal grace window
+    expect(s).toContain(`has-session 2>/dev/null; then exit 0`) // server alive → nothing to record
+    expect(s).toContain('cause=server-vanished') // connection drop (SIGKILL/OOM class)
+    expect(s).toContain('cause=signaled-server-gone') // rc=0: channel/client-TERM, server died
+    expect(s).toContain('cause=client-killed-server-gone') // rc≥128: client took a hard kill
     expect(s).toContain('ev=server-exit identity=claude-bob') // the exits.log record
     expect(s).toContain(`>> '/r/logs/iapeer/exits.log'`)
     expect(s).toContain('/r/logs/iapeer/server-deaths/claude-bob') // forensics file
@@ -74,6 +83,19 @@ describe('canary script (pure)', () => {
   test('ensureServerCanary without exitLogDir → skipped (observability off)', () => {
     expect(ensureServerCanary({ identity: 'claude-none', sock: '/tmp/none.sock' })).toBe('skipped')
   })
+
+  test('canaryProcessPattern is identity-anchored (no prefix bleed) and matches both canary processes', () => {
+    const p = canaryProcessPattern('claude-iap')
+    expect(p).toBe('iap-canary-claude-iap([^a-z0-9-]|$)')
+    const re = new RegExp(p)
+    expect(re.test(`/opt/homebrew/bin/tmux -S /tmp/x.sock wait-for iap-canary-claude-iap`)).toBe(true) // client argv
+    expect(re.test(`/bin/sh -c ... wait-for 'iap-canary-claude-iap'\n...`)).toBe(true) // sh -c script (quoted channel)
+    expect(re.test(`tmux wait-for iap-canary-claude-iap-memory`)).toBe(false) // prefix identity must NOT match
+  })
+
+  test('dismissCanary is a harmless no-op when no canary runs', () => {
+    expect(() => dismissCanary('claude-nobody-here')).not.toThrow()
+  })
 })
 
 describe.if(tmuxAvailable)('canary live (sandbox tmux servers)', () => {
@@ -90,11 +112,22 @@ describe.if(tmuxAvailable)('canary live (sandbox tmux servers)', () => {
     return { sock, logDir: join(dir, `logs-${identity}`) }
   }
 
+  const allIds = [
+    'claude-canadirty',
+    'claude-canaclean',
+    'claude-canakill',
+    'notifier-canatear',
+    'claude-canasweep',
+    'claude-canaclient',
+  ]
+
   afterAll(() => {
     for (const sock of socks) {
-      // teardown is DELIBERATE → signal each canary before killing its server
-      for (const id of ['claude-canadirty', 'claude-canaclean', 'claude-canakill', 'notifier-canatear']) {
+      // teardown is DELIBERATE → silence each canary (signal + dismiss) before
+      // killing its server — the v2 contract for every deliberate path.
+      for (const id of allIds) {
         signalCanaryClean(sock, id)
+        dismissCanary(id)
       }
       spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
     }
@@ -197,4 +230,59 @@ describe.if(tmuxAvailable)('canary live (sandbox tmux servers)', () => {
     },
     20000,
   )
+
+  test(
+    'death-#4 shape: external killer sweeps server AND canary client → ev=server-exit cause=client-signaled',
+    async () => {
+      const identity = 'claude-canasweep'
+      const { sock, logDir } = bringUp(identity)
+      const pid = serverPid(sock)
+      expect(ensureServerCanary({ identity, sock, exitLogDir: logDir })).toBe('spawned')
+      expect(await waitFor(() => canaryRunning(identity), 3000)).toBe(true)
+      await sleep(500)
+
+      // The pre-clean-shaped external killer: one pattern takes the server AND
+      // the canary CLIENT (both argv contain `tmux -S <sock> `), the sh recorder
+      // survives. The TERMed client returns rc=0 (proven live) — v1 read that as
+      // a clean channel signal and stayed silent; exactly how deaths #4–#6
+      // (10.06) left zero records. v2 probes the server instead: dead → record.
+      spawnSync('pkill', ['-f', `tmux -S ${sock} `], { stdio: 'ignore' })
+      const log = exitLogPath(logDir)
+      expect(
+        await waitFor(() => existsSync(log) && readFileSync(log, 'utf8').includes('ev=server-exit'), 10000),
+      ).toBe(true)
+      const line = readFileSync(log, 'utf8')
+      expect(line).toContain(`ev=server-exit identity=${identity}`)
+      expect(line).toContain('cause=signaled-server-gone') // rc=0 shape, server found dead
+      expect(line).toContain(`server_pid=${pid}`)
+      expect(readdirSync(serverDeathsDir(logDir)).length).toBe(1) // forensics captured
+    },
+    20000,
+  )
+
+  test(
+    'canary client killed while server lives → silent (no false record), canary gone for the retrofit to re-arm',
+    async () => {
+      const identity = 'claude-canaclient'
+      const { sock, logDir } = bringUp(identity)
+      expect(ensureServerCanary({ identity, sock, exitLogDir: logDir })).toBe('spawned')
+      expect(await waitFor(() => canaryRunning(identity), 3000)).toBe(true)
+      await sleep(500)
+
+      // TERM the CLIENT only (argv ends with the bare channel — the sh's quoted
+      // form does not match this $-anchored pattern), server stays up.
+      spawnSync('pkill', ['-f', `wait-for ${canaryChannel(identity)}$`], { stdio: 'ignore' })
+      // the sh probes (≈2 s), finds the server ALIVE → exits silently
+      expect(await waitFor(() => !canaryRunning(identity), 6000)).toBe(true)
+      await sleep(300)
+      expect(
+        existsSync(exitLogPath(logDir)) && readFileSync(exitLogPath(logDir), 'utf8').includes('ev=server-exit'),
+      ).toBe(false) // no false server-death while the server lives
+      // server must still be alive — and ensure re-arms a fresh canary (the
+      // retrofit path; in prod the supervise tick does this and logs it)
+      expect(spawnSync('tmux', ['-S', sock, 'has-session', '-t', identity], { stdio: 'ignore' }).status).toBe(0)
+      expect(ensureServerCanary({ identity, sock, exitLogDir: logDir })).toBe('spawned')
+    },
+    20000,
+  )
 })

package/src/launch/canary.ts

@@ -8,17 +8,32 @@
 // Mechanism: one tiny detached `sh` per LIVE tmux server, holding a blocking
 // client `tmux -S <sock> wait-for iap-canary-<identity>` — a process OUTSIDE the
 // dying server, connected via its socket, so the server's death (any cause,
-// including SIGKILL) is observed the moment the connection drops. Protocol:
-//   • clean teardown (idle-reap / stop / pre-clean / killServerIfEmpty) SIGNALS
-//     the channel first (`wait-for -S`) → the canary exits 0, silently;
-//   • the canary itself signaled (TERM/HUP/INT, e.g. launch pre-clean pkill) →
-//     rc ≥ 128 / trap → exit silently (someone manages it deliberately);
-//   • anything else (wait-for returns an error = the server vanished under us)
-//     → ONE logfmt line `ev=server-exit` into exits.log (the per-peer death-cause
-//     home, next to pane-died's `ev=session-exit`) + a forensics snapshot file
-//     (vm_stat / swap / top-RSS ps / fresh DiagnosticReports) captured WITHIN
-//     SECONDS of the death — the evidence the 60 s supervise tick can never
+// including SIGKILL) is observed the moment the connection drops. Protocol (v2 —
+// death #4 10.06 15:42Z proved v1's exit-code trust wrong twice over: the killer
+// took the SERVER and the canary CLIENT together, AND a TERMed tmux client
+// returns rc=0 — indistinguishable from a clean channel signal — so the rc-based
+// `0 || ≥128 → silent` guard silenced a real death):
+//   • DELIBERATE silence is an explicit act, never an exit-code inference:
+//     every deliberate teardown (idle-reap / stop / pre-clean / pane-died hook /
+//     bootout teardown) signals the channel (`wait-for -S`) AND dismisses the
+//     sh recorder (`dismissCanary` → TERM → trap → silent exit). POSIX trap
+//     semantics make this race-free: the trap runs before any recording.
+//   • When wait-for returns — ANY code — the script sleeps 2 s (a concurrent
+//     dismissal TERM wins here), then probes SERVER LIVENESS: alive → exit
+//     silently (a lost canary is re-armed and logged by the supervise retrofit
+//     within a tick); dead with nobody having dismissed us → the death is real
+//     and unclaimed → ONE logfmt line `ev=server-exit` into exits.log (the
+//     per-peer death-cause home, next to pane-died's `ev=session-exit`) + a
+//     forensics snapshot (vm_stat / swap / top-RSS ps / fresh DiagnosticReports)
+//     captured within seconds — the evidence the 60 s supervise tick can never
 //     recover ("системных следов ноль" was the recurring investigation outcome).
+//     The raw wait_rc still ATTRIBUTES the death (cause=server-vanished /
+//     signaled-server-gone / client-killed-server-gone).
+// Residual blind spot (structural): a killer that SIGKILLs the sh recorder
+// itself leaves no in-process way to record. With v2 the ABSENCE of a record on
+// a server-dead reap narrows the diagnosis to exactly that shape; the canary
+// ensure-state lines in lifecycle.log (origin=launch/retrofit) evidence the
+// churn post-hoc.
 //
 // The canary is pure observability: it never wakes, reaps, restarts or otherwise
 // manages anything (H4-compatible by construction), it fires at most once, and
@@ -69,24 +84,45 @@ export function canaryScript(o: CanaryScriptOptions): string {
   return [
     // Server PID captured while alive — the postmortem grep key for system logs.
     `SPID="$('${o.tmuxBin}' -S '${o.sock}' display-message -p '#{pid}' 2>/dev/null)"`,
-    // A signal to the CANARY is deliberate management (pre-clean pkill) → silent.
+    // A signal to the SH WRAPPER is deliberate dismissal (dismissCanary) or host
+    // shutdown → silent. POSIX: the trap runs after the foreground command
+    // completes — so a TERM delivered during wait-for/sleep always exits us
+    // BEFORE any recording below (the race-free deliberate-silence guarantee).
     `trap 'exit 0' HUP INT TERM`,
     `'${o.tmuxBin}' -S '${o.sock}' wait-for '${ch}'`,
     `rc=$?`,
-    // rc=0 → clean-teardown signal; rc≥128 → the tmux client itself was signaled.
-    `if [ "$rc" -eq 0 ] || [ "$rc" -ge 128 ]; then exit 0; fi`,
-    // The server vanished under us — record, within seconds of the death.
+    // NO wait-for exit code is trusted as "deliberate" by itself — PROVEN live
+    // (death-#4 postmortem): a TERM to the tmux CLIENT returns rc=0, identical
+    // to a clean channel signal, so an external killer sweeping server+client
+    // rides the clean-looking code straight past any rc-based guard (v1's
+    // `rc=0 || rc>=128 → silent` was exactly that hole). v2 contract instead:
+    //   • deliberate teardowns DISMISS this sh (TERM → trap above) — the sleep
+    //     below gives a concurrently-delivered dismissal time to win;
+    //   • then the SERVER's liveness, not the exit code, decides: alive →
+    //     nothing to record (a lost canary is re-armed and logged by the
+    //     supervise retrofit within a tick); dead and nobody dismissed us →
+    //     the death is real and unclaimed → record it.
+    `sleep 2`,
+    `if '${o.tmuxBin}' -S '${o.sock}' has-session 2>/dev/null; then exit 0; fi`,
+    // The exit code still ATTRIBUTES the recorded death (raw wait_rc is kept):
+    //   rc=0   → signaled-server-gone   (channel signal or client-TERM, server died)
+    //   rc≥128 → client-killed-server-gone (client took a non-TERM kill)
+    //   else   → server-vanished        (connection drop — SIGKILL/OOM class)
+    `cause=server-vanished`,
+    `if [ "$rc" -eq 0 ]; then cause=signaled-server-gone; fi`,
+    `if [ "$rc" -ge 128 ]; then cause=client-killed-server-gone; fi`,
+    // The server is gone under us — record, within seconds of the death.
     `ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
     `f='${o.forensicsDir}/${o.identity}'-"$(date +%s)".txt`,
     `{`,
-    `  echo "server-death identity=${o.identity} ts=$ts server_pid=$SPID wait_rc=$rc"`,
+    `  echo "server-death identity=${o.identity} ts=$ts server_pid=$SPID wait_rc=$rc cause=$cause"`,
     `  echo '--- vm_stat'; vm_stat`,
     `  echo '--- swapusage'; sysctl -n vm.swapusage`,
     `  echo '--- ps-top-rss'; ps axo pid,ppid,rss,etime,command | sort -rn -k3 | head -25`,
     `  echo '--- diagnosticreports-user'; ls -t "$HOME/Library/Logs/DiagnosticReports" 2>/dev/null | head`,
     `  echo '--- diagnosticreports-system'; ls -t /Library/Logs/DiagnosticReports 2>/dev/null | head`,
     `} > "$f" 2>&1`,
-    `printf 'ts=%s ev=server-exit identity=${o.identity} server_pid=%s wait_rc=%s forensics=%s\\n' "$ts" "$SPID" "$rc" "$f" >> '${o.exitLogFile}'`,
+    `printf 'ts=%s ev=server-exit identity=${o.identity} server_pid=%s wait_rc=%s cause=%s forensics=%s\\n' "$ts" "$SPID" "$rc" "$cause" "$f" >> '${o.exitLogFile}'`,
   ].join('\n')
 }
 
@@ -150,3 +186,27 @@ export function signalCanaryClean(sock: string, identity: string): void {
     /* best-effort */
   }
 }
+
+/** The pgrep/pkill ERE matching BOTH canary processes of ONE identity — the sh
+ *  wrapper (its -c script quotes the channel: `…'iap-canary-<id>'…`) and the
+ *  tmux client (argv ends with the bare channel). Anchored so an identity can
+ *  never match another identity's prefix (claude-iapeer ≠ claude-iapeer-memory). */
+export function canaryProcessPattern(identity: string): string {
+  return `${canaryChannel(identity)}([^a-z0-9-]|$)`
+}
+
+/**
+ * Dismiss this identity's canary BEFORE a deliberate server teardown: TERM the
+ * sh wrapper (trap → silent exit, race-free — the trap always runs before the
+ * v2 recording branch) and the tmux client. The explicit counterpart of the
+ * channel signal: with v2 a signaled CLIENT alone is no longer read as
+ * deliberate, so every deliberate path must dismiss the RECORDER (the sh).
+ * Best-effort: no canary running → harmless no-op (pkill exits 1).
+ */
+export function dismissCanary(identity: string): void {
+  try {
+    spawnSync('pkill', ['-f', canaryProcessPattern(identity)], { stdio: 'ignore' })
+  } catch {
+    /* best-effort */
+  }
+}

package/src/launch/index.ts

@@ -19,7 +19,8 @@ import { dirname } from 'path'
 import { spawnSync } from 'child_process'
 import { CODEX_BEARER_ENV_VAR, CODEX_DUMMY_BEARER, type Runtime } from '../core/constants.ts'
 import { readLaunchEnv } from '../storage/index.ts'
-import { ensureServerCanary, exitLogPath, signalCanaryClean } from './canary.ts'
+import { canaryChannel, dismissCanary, ensureServerCanary, exitLogPath, signalCanaryClean } from './canary.ts'
+import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { claudeAdapter } from './adapters/claude.ts'
 import { codexAdapter } from './adapters/codex.ts'
 import { telegramAdapter } from './adapters/telegram.ts'
@@ -155,7 +156,18 @@ export function exitCauseHook(identity: string, exitLogFile: string): string {
     `dead_status=#{pane_dead_status} dead_signal=#{pane_dead_signal}\\n`
   const log =
     `printf "${line}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "${exitLogFile}"`
-  return `run-shell '${log}' ; kill-session -t "${identity}"`
+  // Silence the server-death canary BEFORE kill-session: with a single-session
+  // server the kill empties the server and exit-empty takes it down — without
+  // explicit silence the canary would append a second, muddier `ev=server-exit`
+  // record for a death this very hook just captured (the session-exit line is
+  // the richer, authoritative one: it has the exit code/signal). v2 contract:
+  // deliberate = channel signal (tmux-NATIVE wait-for -S) + DISMISS the sh
+  // recorder (abs-path /usr/bin/pkill — survives the minimal launchd PATH;
+  // `\$` keeps the regex anchor literal through the sh double-quote layer; the
+  // `[i]` class keeps the pattern from matching its OWN occurrence in this
+  // hook-sh's cmdline — the pgrep self-match classic).
+  const dismiss = `/usr/bin/pkill -f "[i]${canaryChannel(identity).slice(1)}([^a-z0-9-]|\\$)"`
+  return `run-shell '${log} ; ${dismiss}' ; wait-for -S "${canaryChannel(identity)}" ; kill-session -t "${identity}"`
 }
 
 /** Install the exit-cause observability on a freshly-created session: ensure the
@@ -212,11 +224,15 @@ export const launch: LaunchFn = async (
   mkdirSync(dirname(sock), { recursive: true })
 
   // (1) Pre-clean any stale tmux server on this socket, then launch detached.
-  //     Signal the server-death canary FIRST: this teardown is deliberate, the
-  //     canary must exit silently, not record a false server-death (the pkill
-  //     below also matches the canary's cmdline — by design, it sweeps a stale
-  //     canary along with the stale server; a signaled canary is already gone).
+  //     Silence the server-death canary EXPLICITLY first — this teardown is
+  //     deliberate: signal the channel (client exits 0) AND dismiss the sh
+  //     recorder (TERM → trap → silent; canary v2 no longer reads a signaled
+  //     client alone as deliberate — an external killer sweeping server+client
+  //     was exactly the death-#4 silence). Only then sweep the server processes
+  //     (the pkill also matches a leftover canary client — harmless, both
+  //     canary processes are already dismissed).
   signalCanaryClean(sock, identity)
+  dismissCanary(identity)
   spawnSync('pkill', ['-f', `tmux -S ${sock} `], { stdio: 'ignore' })
   tmux(sock, 'kill-server')
 
@@ -268,7 +284,14 @@ export const launch: LaunchFn = async (
   //       that records `ev=server-exit` + a forensics snapshot when the whole
   //       server dies dirty (SIGKILL/OOM class). Same gate as the exit hook;
   //       best-effort by construction (every failure → a state, never a throw).
-  ensureServerCanary({ identity, sock, exitLogDir: cfg.exitLogDir, env })
+  //       The ensure-state is logged (origin=launch) so the arming trail is
+  //       complete in lifecycle.log: 'spawned' is the newborn-server norm here,
+  //       'failed' a newborn server starting its life UNWATCHED (death-#4
+  //       postmortem hinged on this very question being unanswerable).
+  const canaryState = ensureServerCanary({ identity, sock, exitLogDir: cfg.exitLogDir, env })
+  if (canaryState !== 'skipped') {
+    appendLifecycleEvent(cfg.exitLogDir, { ev: 'canary', identity, state: canaryState, origin: 'launch' }, { env })
+  }
 
   // (3) pipe-pane the session output to the per-identity log.
   mkdirSync(cfg.logDir, { recursive: true, mode: 0o700 })

package/src/launch/launch.test.ts

@@ -227,6 +227,14 @@ describe('exitCauseHook (exit-cause observability)', () => {
     // tmux-NATIVE kill-session (no shell `tmux`) → needs no PATH (launchd minimal env).
     expect(hook).toContain('kill-session -t "claude-iapeer"')
   })
+  test('silences the server-death canary (native wait-for -S) BEFORE kill-session — no double record', () => {
+    // kill-session on a single-session server → exit-empty takes the server down;
+    // without the signal the canary would add a second `ev=server-exit` record for
+    // a death this hook just captured (session-exit carries the code/signal).
+    expect(hook).toContain('wait-for -S "iap-canary-claude-iapeer"')
+    expect(hook.indexOf('wait-for -S')).toBeLessThan(hook.indexOf('kill-session'))
+    expect(hook.indexOf('run-shell')).toBeLessThan(hook.indexOf('wait-for -S')) // log first
+  })
   test('quoting: single-quoted run-shell arg (tmux layer) wrapping double-quoted sh', () => {
     expect(hook).toMatch(/run-shell '.*'/)
     expect(hook).not.toContain("''") // no empty/again-collapsed single-quote pair

package/src/launch/launchdRun.ts

@@ -23,7 +23,7 @@ import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
 import { peerLogsDir, pluginLogsDir } from '../storage/index.ts'
 import { readPeerProfile } from '../identity/index.ts'
 import { getAdapter, launch } from './index.ts'
-import { signalCanaryClean } from './canary.ts'
+import { dismissCanary, signalCanaryClean } from './canary.ts'
 import type { LaunchConfig, LaunchSpec } from './types.ts'
 
 /** Block-watch poll cadence — seconds, deliberately NOT a tight loop (the session
@@ -55,7 +55,10 @@ function sessionAlive(sock: string, identity: string): boolean {
  * both paths now converge on the same end state.
  */
 export function teardownAlwaysOnSession(sock: string, identity: string): void {
+  // Explicit canary silence (v2): channel signal (client exits 0) + dismiss the
+  // sh recorder — a signaled client alone is no longer read as deliberate.
   signalCanaryClean(sock, identity)
+  dismissCanary(identity)
   spawnSync('tmux', ['-S', sock, 'kill-session', '-t', identity], { stdio: 'ignore' })
   const ls = spawnSync('tmux', ['-S', sock, 'list-sessions', '-F', '#{session_name}'], { encoding: 'utf8' })
   if (!(ls.stdout ?? '').trim()) {

package/src/lifecycle/index.ts

@@ -46,7 +46,7 @@ import {
   type LaunchSpec,
 } from '../launch/index.ts'
 import { composeSystemPrompt, gatherPromptInput } from '../launch/composeSystemPrompt.ts'
-import { ensureServerCanary, signalCanaryClean } from '../launch/canary.ts'
+import { dismissCanary, ensureServerCanary, signalCanaryClean } from '../launch/canary.ts'
 import { appendLifecycleEvent, superviseLogVerbose } from './eventlog.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1009,9 +1009,11 @@ export function killSession(sock: string, identity: string): void {
   tmux(sock, 'kill-session', '-t', identity)
   const sessions = tmux(sock, 'list-sessions', '-F', '#{session_name}').out
   if (!sessions.trim()) {
-    // Deliberate server teardown → signal the server-death canary FIRST so it
-    // exits silently instead of recording a false `ev=server-exit` (canary.ts).
+    // Deliberate server teardown → silence the canary EXPLICITLY first: signal
+    // the channel (client exits 0) AND dismiss the sh recorder (canary v2 no
+    // longer reads a signaled client alone as deliberate — see canary.ts).
     signalCanaryClean(sock, identity)
+    dismissCanary(identity)
     tmux(sock, 'kill-server')
     try {
       rmSync(sock, { force: true })
@@ -1190,7 +1192,15 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       // every ALIVE daemon-owned server — covers a fleet launched by older code
       // within one tick of a deploy, no session restarts. Idempotent (pgrep on
       // the per-identity wait-for channel), best-effort, pure observability.
-      ensureServerCanary({ identity: s.identity, sock, exitLogDir: cfg.eventLogDir, env })
+      // A non-'already' state IS a decision-grade event (not verbose-gated):
+      // post-0.2.22 every launch arms a canary, so a retrofit 'spawned' on an
+      // alive server means the previous canary VANISHED mid-watch (the death-#4
+      // blind spot was exactly this churn being invisible); 'failed' means the
+      // server is currently UNWATCHED. At most one line per loss, not per tick.
+      const canaryState = ensureServerCanary({ identity: s.identity, sock, exitLogDir: cfg.eventLogDir, env })
+      if (canaryState !== 'already') {
+        trace({ identity: s.identity, action: 'canary', state: canaryState, origin: 'retrofit' })
+      }
       out.push({ identity: s.identity, action: 'alive' })
       if (verbose) trace({ identity: s.identity, action: 'alive', age: `${ageSecs}s` })
     }

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', () => {