@agfpd/iapeer 0.2.6 → 0.2.8

package/package.json

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

package/src/cli/cli.test.ts

@@ -128,7 +128,7 @@ describe('send validation', () => {
     await register('alpha')
     await expect(
       sendMessage({ from: 'claude-alpha', target: 'nobody', message: 'hi', env: env() }),
-    ).rejects.toThrow(/not in the IAPeer peers index|self/)
+    ).rejects.toThrow(/not in the iapeer peers index|self/)
   })
 })
 

package/src/core/constants.ts

@@ -1,4 +1,4 @@
-// Canonical constants for the IAPeer foundation.
+// Canonical constants for the iapeer foundation.
 // Consolidated from inter-agent-protocol/src/lib/constants.ts (wins as-is) and
 // extended with storage-layer path names (blueprint §1 core/constants).
 
@@ -131,6 +131,14 @@ export function resolveSockDir(env: NodeJS.ProcessEnv = process.env): string {
 // === per-peer cwd scope ===
 export const IAPEER_DIR = '.iapeer'
 export const PEER_PROFILE_FILE = 'peer-profile.json'
+// Doctrine-fragments layer (Канал A, слой 5): a primitive-owned `.iapeer/fragments/`
+// subdir under BOTH the global root (`~/.iapeer/fragments/`, host-wide) and the
+// per-peer cwd (`<cwd>/.iapeer/fragments/`, per-peer). Holds machine-regenerated
+// `*.md` fragments that an ecosystem primitive writes + rotates itself (e.g.
+// iapeer-memory's guide + per-peer note index) — merged into the system prompt so
+// the context survives compaction, yet kept OUT of the hand-authored IAPEER.md
+// doctrine (two writers, mutual-rollback). See composeSystemPrompt Layer 5.
+export const FRAGMENTS_DIR = 'fragments'
 
 // === global scope ~/.iapeer/ ===
 export const IAP_PLUGIN_DIR = 'iap'

package/src/daemon/daemon.test.ts

@@ -93,7 +93,7 @@ describe('callTool (no wake passed → Ф1 offline behaviour, never spawns)', ()
     const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
     const r = await callTool(caller, 'send_to_peer', { personality: 'nobody', message: 'hi' })
     expect(r.isError).toBe(true)
-    expect(r.content[0].text).toMatch(/not in the IAPeer peers index/)
+    expect(r.content[0].text).toMatch(/not in the iapeer peers index/)
   })
 
   test('unknown tool → error', async () => {

package/src/daemon/index.ts

@@ -77,7 +77,7 @@ export function resolveCallerFromHeader(value: string | undefined, index: PeersI
 
 export function buildSendDescription(index: PeersIndex): string {
   const lines = [
-    'Send a message to a known IAPeer peer through Inter-Agent-Protocol.',
+    'Send a message to a known iapeer peer through Inter-Agent-Protocol.',
     'Peers can be agents, humans, or services. Runtime is the delivery surface, not the peer type.',
     'Current delivery supports any runtime endpoint that follows the IAP tmux socket convention. Claude/Codex are built-in local runtimes; external runtimes such as telegram can be exposed by runtime-router packages.',
     '',

package/src/launch/adapters/claude.ts

@@ -10,7 +10,7 @@
 //     (the dev-channels "I am using this for local development" Enter, 335-345).
 //   - Spawned-Peer/src/spawner.ts — buildClaudeArgv (759-787: same flags +
 //     optional --resume <uuid>) and findLatestTranscript (522-538: resume uuid).
-//   - IAPeer/src/lifecycle/index.ts — claudeInputReady / claudeBootDialog /
+//   - iapeer/src/lifecycle/index.ts — claudeInputReady / claudeBootDialog /
 //     newestClaudeTranscriptMtime / findLatestClaudeTranscript. This is the
 //     canonical port: the slug is realpath(cwd).replace(/[^a-zA-Z0-9]/g,'-') —
 //     claude encodes EVERY non-alphanumeric char (not just '/'); the old

package/src/launch/composeSystemPrompt.layers.test.ts

@@ -130,6 +130,65 @@ describe('composeSystemPrompt — layer 4 (other domains)', () => {
   })
 })
 
+describe('composeSystemPrompt — layer 5 (doctrine fragments)', () => {
+  const frag = (over: Partial<PromptDomainBlock>): PromptDomainBlock => ({ domain: 'F', ...over })
+
+  test('empty/omitted fragments add NOTHING (legacy bytes preserved)', () => {
+    const legacy = composeSystemPrompt(base)
+    expect(composeSystemPrompt({ ...base, promptFragments: [] })).toBe(legacy)
+    expect(composeSystemPrompt({ ...base, promptFragments: undefined })).toBe(legacy)
+  })
+
+  test('a presence-marker fragment (empty halves) emits no text and no dangling separator', () => {
+    const legacy = composeSystemPrompt(base)
+    expect(composeSystemPrompt({ ...base, promptFragments: [frag({ local: '' })] })).toBe(legacy)
+    expect(composeSystemPrompt({ ...base, promptFragments: [frag({ global: '', local: '' })] })).toBe(legacy)
+    const out = composeSystemPrompt({
+      ...base,
+      promptFragments: [frag({ domain: 'EMPTY', local: '' }), frag({ domain: 'REAL', local: 'idx-content\n' })],
+    })
+    expect(out).toContain('idx-content')
+    expect(out).not.toMatch(/\n{4,}/)
+  })
+
+  test('within a fragment stem, global (host-wide guide) precedes local (per-peer index)', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      promptFragments: [frag({ domain: 'MEM', global: 'mem-guide', local: 'mem-index' })],
+    })
+    expect(out).toContain('mem-guide\nmem-index')
+    expect(out.indexOf('mem-guide')).toBeLessThan(out.indexOf('mem-index'))
+  })
+
+  test('layer 5 sits AFTER layer 4 (most-volatile last), separated by a blank line', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      pluginDomains: [{ domain: 'D', global: 'domain-text' }],
+      promptFragments: [{ domain: 'MEM', local: 'fragment-text' }],
+    })
+    expect(out.indexOf('domain-text')).toBeLessThan(out.indexOf('fragment-text'))
+    expect(out).toContain('domain-text\n\nfragment-text')
+  })
+
+  test('full 5-layer ordering: YAML → doctrine → registry → domains → fragments', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      peers: [peerA],
+      pluginDomains: [{ domain: 'D', global: 'domain-text' }],
+      promptFragments: [{ domain: 'MEM', global: 'fragment-text' }],
+    })
+    const order = [
+      out.indexOf('personality:'),
+      out.indexOf('Be the implementer.'),
+      out.indexOf('## Known peers'),
+      out.indexOf('domain-text'),
+      out.indexOf('fragment-text'),
+    ]
+    expect(order.every(i => i >= 0)).toBe(true)
+    expect(order).toEqual([...order].sort((a, b) => a - b))
+  })
+})
+
 // ─────────────────────────────────────────────────────────────────────────────
 // gatherPromptInput — FS discovery over ~/.iapeer + <cwd>/.iapeer
 // ─────────────────────────────────────────────────────────────────────────────
@@ -161,6 +220,17 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     // a non-.md file must be ignored
     writeFileSync(join(localRoot, 'peer-profile.json'), '{}')
 
+    // Layer 5 — fragments/ subdir of both roots: a paired stem (host-wide guide +
+    // per-peer index) and a global-only fragment; a non-.md file must be ignored.
+    const globalFrags = join(globalRoot, 'fragments')
+    const localFrags = join(localRoot, 'fragments')
+    mkdirSync(globalFrags, { recursive: true })
+    mkdirSync(localFrags, { recursive: true })
+    writeFileSync(join(globalFrags, 'iapeer-memory.md'), 'mem-guide\n') // host-wide guide
+    writeFileSync(join(localFrags, 'iapeer-memory.md'), 'mem-index\n') // per-peer index
+    writeFileSync(join(globalFrags, 'other-primitive.md'), 'other-frag\n')
+    writeFileSync(join(localFrags, 'notes.txt'), 'ignored') // non-.md, must be ignored
+
     // Layer 3 — registry at the global root (deliberately UNSORTED on disk)
     const index = {
       version: 2,
@@ -207,6 +277,23 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(byName.MARKER).toEqual({ domain: 'MARKER', local: '' }) // present but empty
   })
 
+  test('layer 5: fragments/ subdir scanned, paired by stem (guide global + index local), sorted', () => {
+    const input = gather()
+    const frags = input.promptFragments ?? []
+    expect(frags.map(f => f.domain)).toEqual(['iapeer-memory', 'other-primitive'])
+    const byName = Object.fromEntries(frags.map(f => [f.domain, f]))
+    expect(byName['iapeer-memory']).toEqual({ domain: 'iapeer-memory', global: 'mem-guide\n', local: 'mem-index\n' })
+    expect(byName['other-primitive']).toEqual({ domain: 'other-primitive', global: 'other-frag\n' })
+    // the non-.md notes.txt never became a fragment
+    expect(frags.map(f => f.domain)).not.toContain('notes')
+  })
+
+  test('layer 5: fragments are NOT confused with the root-level Layer-4 domains', () => {
+    const input = gather()
+    // the fragments dir itself is a directory, not a `.md` file → never a Layer-4 domain
+    expect((input.pluginDomains ?? []).map(d => d.domain)).not.toContain('fragments')
+  })
+
   test('layer 3: registry projected to EXACTLY 5 fields, sorted by personality', () => {
     const input = gather()
     expect((input.peers ?? []).map(p => p.personality)).toEqual(['arthur', 'boris'])
@@ -237,14 +324,19 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(prompt).toContain('aaa-global-only')
     expect(prompt).toContain('mm-global\nmm-local')
     expect(prompt).toContain('zzz-local-only')
+    // Layer 5 (fragments: guide+index paired, global-only fragment)
+    expect(prompt).toContain('mem-guide\nmem-index')
+    expect(prompt).toContain('other-frag')
 
     const order = [
       prompt.indexOf('personality: "iapeer"'),
       prompt.indexOf('LOCAL ROLE'),
       prompt.indexOf('## Known peers'),
       prompt.indexOf('aaa-global-only'),
+      prompt.indexOf('mem-guide'), // Layer 5 — after every Layer-4 domain
     ]
     expect(order).toEqual([...order].sort((a, b) => a - b))
+    expect(prompt.indexOf('zzz-local-only')).toBeLessThan(prompt.indexOf('mem-guide'))
     // marker file produced no content and no blank-block artifact
     expect(prompt).not.toContain('MARKER')
     expect(prompt).not.toMatch(/\n{4,}/)
@@ -263,6 +355,7 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(input.peerDoctrine).toBe('')
     expect(input.globalDoctrine).toBeUndefined()
     expect(input.pluginDomains).toEqual([])
+    expect(input.promptFragments).toEqual([]) // no fragments/ subdir → empty layer
     expect(input.peers).toEqual([])
     // composes to just the YAML block (+ empty doctrine), no extra layers
     const prompt = composeSystemPrompt(input)

package/src/launch/composeSystemPrompt.ts

@@ -10,7 +10,7 @@
 
 import { readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
-import { IAPEER_DIR } from '../core/constants.ts'
+import { FRAGMENTS_DIR, IAPEER_DIR } from '../core/constants.ts'
 import { publicPeerSummary, readPeersIndex, type PublicPeerSummary } from '../registry/index.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
 import type { ComposePromptInput, PromptDomainBlock } from './types.ts'
@@ -93,11 +93,14 @@ export function composeSystemPrompt(input: ComposePromptInput): string {
   // jq output — the golden test pins this exactly.
   const layer12 = yaml + global + input.peerDoctrine
 
-  // Layer 3 (registry) and Layer 4 (other domains) are appended ONLY when they
-  // have content.
+  // Layer 3 (registry), Layer 4 (operator/plugin domains) and Layer 5 (primitive
+  // doctrine fragments) are appended ONLY when they have content. Layer 5 sits LAST
+  // — it is the most volatile (machine-regenerated on every source change), so it
+  // never disturbs the stable prefix (YAML + doctrine + registry + domains) above it.
   const layer3 = renderRegistry(input.peers ?? [])
-  const layer4 = renderDomains(input.pluginDomains ?? [])
-  const sections = [layer12, layer3, layer4].filter(section => section.length > 0)
+  const layer4 = renderMergedBlocks(input.pluginDomains ?? [])
+  const layer5 = renderMergedBlocks(input.promptFragments ?? [])
+  const sections = [layer12, layer3, layer4, layer5].filter(section => section.length > 0)
 
   // ONE section (no registry, no extra domains) → the legacy bytes, UNTOUCHED —
   // the golden test pins layer12 exactly (peerDoctrine verbatim, incl. its own
@@ -129,36 +132,42 @@ function renderRegistry(peers: readonly PublicPeerSummary[]): string {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Layer 4 — every non-IAPEER `<DOMAIN>.md` pair at the .iapeer/ root, merged
-// general → specific (global then local). The merge is ORGANIC: domain stems are
-// used only for stable ordering (done by the gatherer), never emitted — custom
-// operator files (SPAWNER_INSTRUCTIONS.md, …) flow in as ordinary domains. An
-// empty file is a presence marker (Канал B) and contributes no text here.
+// Layers 4 & 5 — merged global/local blocks. Shared renderer:
+//   • Layer 4: every non-IAPEER `<DOMAIN>.md` pair at the .iapeer/ root (operator /
+//     plugin user-settings; SPAWNER_INSTRUCTIONS.md, … flow in organically).
+//   • Layer 5: every `<STEM>.md` pair in .iapeer/fragments/ (primitive-owned,
+//     machine-regenerated doctrine fragments — iapeer-memory's guide + note index).
+// Both merge general → specific (global then local). The merge is ORGANIC: stems
+// are used only for stable ordering (done by the gatherer), never emitted. An empty
+// file is a presence marker (Канал B) and contributes no text — so a fragment dir
+// that drops to a 0-byte placeholder, or whose file vanishes mid-rotation, yields
+// nothing here rather than a dangling separator.
 // ─────────────────────────────────────────────────────────────────────────────
 
-function renderDomains(domains: readonly PromptDomainBlock[]): string {
-  const blocks: string[] = []
-  for (const d of domains) {
-    // Per domain: global then local (general → specific), each trimmed of its
+function renderMergedBlocks(blocks: readonly PromptDomainBlock[]): string {
+  const out: string[] = []
+  for (const b of blocks) {
+    // Per stem: global then local (general → specific), each trimmed of its
     // trailing newlines so a 0-byte marker (or a newline-only file) drops out and
-    // the spacing is uniform. Halves of one domain are kept tight (single '\n');
-    // distinct domains are separated by a blank line below.
-    const halves = [d.global, d.local]
+    // the spacing is uniform. Halves of one stem are kept tight (single '\n');
+    // distinct stems are separated by a blank line below.
+    const halves = [b.global, b.local]
       .filter((s): s is string => s !== undefined)
       .map(s => s.replace(/\n+$/, ''))
       .filter(s => s.length > 0)
-    if (halves.length > 0) blocks.push(halves.join('\n'))
+    if (halves.length > 0) out.push(halves.join('\n'))
   }
-  return blocks.join('\n\n')
+  return out.join('\n\n')
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // gatherPromptInput — the FS-discovery half: scan ~/.iapeer/*.md (global) and
 // <cwd>/.iapeer/*.md (local), split IAPEER.md (Layer 2) from every other domain
-// (Layer 4), and project the live registry through publicPeerSummary (Layer 3),
-// into a ready-to-render ComposePromptInput. Layer-1 identity/host facts are
-// supplied by the caller (lifecycle gathers them via sw_vers/hostname/etc).
-// This is the ONLY FS-touching part; composeSystemPrompt itself stays pure.
+// (Layer 4), scan the fragments/ subdir of both roots (Layer 5), and project the
+// live registry through publicPeerSummary (Layer 3), into a ready-to-render
+// ComposePromptInput. Layer-1 identity/host facts are supplied by the caller
+// (lifecycle gathers them via sw_vers/hostname/etc). This is the ONLY FS-touching
+// part; composeSystemPrompt itself stays pure.
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface GatherPromptOptions {
@@ -187,28 +196,51 @@ function readFileIfPresent(path: string): string | undefined {
   }
 }
 
-/** `*.md` files directly at a `.iapeer` root (NOT recursing), excluding IAPEER.md
- *  (Layer 2) — the domain candidates for Layer 4. Missing dir → [].
- *  The `.md` test and the doctrine exclusion are CASE-INSENSITIVE: the Layer-2
- *  read (join(root,'IAPEER.md')) resolves a lowercase `iapeer.md` on a case-
- *  insensitive FS (macOS APFS), so a byte-exact exclusion here would let that same
- *  file ALSO surface as a Layer-4 domain and duplicate the doctrine. Lowercasing
- *  both also picks up an uppercase-extension `NOTES.MD` (spec: no root MD ignored). */
-function listDomainFiles(root: string): string[] {
-  const doctrineLower = IAPEER_DOCTRINE_FILE.toLowerCase()
+/** `*.md` files directly in `dir` (NOT recursing). Missing dir → []. The `.md`
+ *  test is CASE-INSENSITIVE so an uppercase-extension `NOTES.MD` is picked up too. */
+function listMdFiles(dir: string): string[] {
   try {
-    return readdirSync(root, { withFileTypes: true })
-      .filter(e => {
-        if (!e.isFile()) return false
-        const lower = e.name.toLowerCase()
-        return lower.endsWith('.md') && lower !== doctrineLower
-      })
+    return readdirSync(dir, { withFileTypes: true })
+      .filter(e => e.isFile() && e.name.toLowerCase().endsWith('.md'))
       .map(e => e.name)
   } catch {
     return []
   }
 }
 
+/** Layer-4 domain candidates: `*.md` directly at a `.iapeer` root, excluding
+ *  IAPEER.md (Layer 2). The doctrine exclusion is CASE-INSENSITIVE: the Layer-2
+ *  read (join(root,'IAPEER.md')) resolves a lowercase `iapeer.md` on a case-
+ *  insensitive FS (macOS APFS), so a byte-exact exclusion here would let that same
+ *  file ALSO surface as a Layer-4 domain and duplicate the doctrine. */
+function listDomainFiles(root: string): string[] {
+  const doctrineLower = IAPEER_DOCTRINE_FILE.toLowerCase()
+  return listMdFiles(root).filter(name => name.toLowerCase() !== doctrineLower)
+}
+
+/** Build a list of merged global/local blocks (Layer 4 OR Layer 5) from the
+ *  union of `*.md` stems present in the global and/or local dir, sorted by
+ *  filename (plain codepoint order) for a deterministic prompt. `lister` selects
+ *  the candidate `.md` files — Layer 4 excludes the IAPEER.md doctrine, Layer 5
+ *  takes every fragment. A read that races a rotation (file removed between listdir
+ *  and read) → that half is undefined and drops out; a 0-byte file → '' and is
+ *  dropped by the renderer. */
+function gatherMergedBlocks(
+  globalDir: string,
+  localDir: string,
+  lister: (dir: string) => string[] = listMdFiles,
+): PromptDomainBlock[] {
+  const names = new Set<string>([...lister(globalDir), ...lister(localDir)])
+  return [...names].sort().map(name => {
+    const block: PromptDomainBlock = { domain: name.slice(0, -3) } // strip ".md"
+    const global = readFileIfPresent(join(globalDir, name))
+    const local = readFileIfPresent(join(localDir, name))
+    if (global !== undefined) block.global = global
+    if (local !== undefined) block.local = local
+    return block
+  })
+}
+
 export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput {
   const env = opts.env ?? process.env
   const globalRoot = opts.globalRoot ?? resolveGlobalRoot(env)
@@ -220,20 +252,19 @@ export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput
   const peerDoctrine = readFileIfPresent(join(localRoot, IAPEER_DOCTRINE_FILE)) ?? ''
 
   // Layer 4 — union of every non-IAPEER domain present globally and/or locally,
-  // sorted by filename for a deterministic prompt (plain codepoint order). Empty
-  // (0-byte) files stay as presence markers — readFileIfPresent returns '', and
-  // renderDomains drops empty halves, so a marker contributes no text/separator.
-  const domainNames = new Set<string>([...listDomainFiles(globalRoot), ...listDomainFiles(localRoot)])
-  const pluginDomains: PromptDomainBlock[] = [...domainNames]
-    .sort()
-    .map(name => {
-      const block: PromptDomainBlock = { domain: name.slice(0, -3) } // strip ".md"
-      const global = readFileIfPresent(join(globalRoot, name))
-      const local = readFileIfPresent(join(localRoot, name))
-      if (global !== undefined) block.global = global
-      if (local !== undefined) block.local = local
-      return block
-    })
+  // sorted by filename for a deterministic prompt. Empty (0-byte) files stay as
+  // presence markers — readFileIfPresent returns '', and the renderer drops empty
+  // halves, so a marker contributes no text/separator.
+  const pluginDomains = gatherMergedBlocks(globalRoot, localRoot, listDomainFiles)
+
+  // Layer 5 — doctrine fragments: every `*.md` in the fragments/ subdir of both
+  // roots, merged per stem (global guide → per-peer specifics). Primitive-owned and
+  // machine-regenerated; an atomic rotation that briefly removes/replaces a file is
+  // tolerated (a racing read just drops that half — no partial bytes, no throw).
+  const promptFragments = gatherMergedBlocks(
+    join(globalRoot, FRAGMENTS_DIR),
+    join(localRoot, FRAGMENTS_DIR),
+  )
 
   // Layer 3 — peers projected through the shared normalizer, sorted by personality
   // (determinism even if the on-disk file was hand-edited). `opts.peers` lets a
@@ -257,5 +288,6 @@ export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput
     ...(globalDoctrine !== undefined ? { globalDoctrine } : {}),
     peers,
     pluginDomains,
+    promptFragments,
   }
 }

package/src/launch/index.ts

@@ -107,6 +107,72 @@ function ready(identity: string): LaunchResult {
   return { status: 'READY', identity, process_address: identity }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Exit-cause observability — capture WHY a session's process died, AT THE MOMENT
+// of death. The daemon's 60 s supervise tick only learns of a death post-factum
+// (reaped-gone), by which time the exit code/signal — and often the whole tmux
+// server — is gone (the boris-fresh-style blind spot one level deeper than the
+// supervise log). A tmux `pane-died` hook closes it: it fires the instant the
+// pane's leader process exits (with `remain-on-exit on` retaining the dead pane so
+// `#{pane_dead_status}`/`#{pane_dead_signal}` are populated), logs one logfmt line,
+// then kill-sessions the now-dead pane so the daemon's `has-session` death
+// detection (and the always-on KeepAlive block-watch) stay intact.
+//
+// Scope — verified live on tmux 3.6a (3 death modes + the daemon-reap path):
+//   • graceful exit  → `dead_status=<code> dead_signal=`   (code, no signal)
+//   • SIGTERM/SIGKILL/crash to the PROCESS → `dead_status= dead_signal=<name>`
+//   • daemon-initiated `kill-session` (idle-reap / self-TTL / stop) does NOT fire
+//     pane-died → NO line here (those are already in lifecycle.log — no double-log).
+// IRREDUCIBLE GAP: SIGKILL to the tmux SERVER process itself runs no hook (the
+//   event loop is gone); only the daemon's post-factum reaped-gone catches that.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The exit-cause log file inside `exitLogDir` (sibling to lifecycle.log). */
+export function exitLogPath(exitLogDir: string): string {
+  return `${exitLogDir}/exits.log`
+}
+
+/**
+ * Build the tmux `pane-died` hook command string (the value of `set-hook -t <id>
+ * pane-died <value>`). On the pane leader's death it appends ONE logfmt line —
+ *   `ts=<ISO> ev=session-exit identity=<id> dead_status=#{…} dead_signal=#{…}`
+ * — to `exitLogFile`, then runs a tmux-NATIVE `kill-session` (no shell `tmux`, so
+ * it needs no PATH — launchd gives always-on servers a minimal one). Pure (no I/O)
+ * so the exact string is unit-testable. Quoting: the `run-shell` arg is wrapped in
+ * tmux SINGLE quotes (literal at the tmux layer, still `#{}`-format-expanded) with
+ * sh DOUBLE quotes inside — the two levels never collide; `\n`/`$(…)` pass through
+ * tmux untouched to sh. `identity`/`exitLogFile` are assumed free of single quotes
+ * (runtime-personality identities and the ~/.iapeer/logs path always are). */
+export function exitCauseHook(identity: string, exitLogFile: string): string {
+  const line =
+    `ts=%s ev=session-exit identity=${identity} ` +
+    `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}"`
+}
+
+/** Install the exit-cause observability on a freshly-created session: ensure the
+ *  exit-log dir exists, turn `remain-on-exit` on (so pane-died can read the dead
+ *  pane's status/signal) and register the hook. Best-effort — a tmux/FS hiccup
+ *  here must never fail the launch (observability is never load-bearing). No-op
+ *  when `exitLogDir` is falsy (a partial/test cfg): `remain-on-exit` stays OFF so
+ *  behavior is byte-identical to before (and no dead pane can linger un-reaped). */
+function installExitHook(sock: string, identity: string, exitLogDir: string | undefined): void {
+  if (!exitLogDir) return
+  try {
+    mkdirSync(exitLogDir, { recursive: true, mode: 0o700 })
+    // remain-on-exit must be ON before the process can die, else pane-died won't
+    // retain the dead pane and the status/signal are lost. Set it (and the hook)
+    // immediately after new-session — the only un-coverable window is the few ms
+    // before this runs, irrelevant for a runtime that takes seconds to initialize.
+    tmux(sock, 'set-option', '-t', identity, 'remain-on-exit', 'on')
+    tmux(sock, 'set-hook', '-t', identity, 'pane-died', exitCauseHook(identity, exitLogPath(exitLogDir)))
+  } catch {
+    /* observability is best-effort — never block a wake on a hook-install hiccup */
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // launch — bring up ONE session (runtime-agnostic via the adapter)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -178,6 +244,14 @@ export const launch: LaunchFn = async (
     return fail(identity, `tmux new-session failed: ${(start.stderr ?? '').trim() || 'exit ' + start.status}`)
   }
 
+  // (2.5) Exit-cause observability: a `pane-died` hook that records WHY this
+  //       session's process dies (status/signal) at the moment of death into
+  //       <exitLogDir>/exits.log, then kill-sessions the dead pane (so the
+  //       daemon's has-session death detection + always-on KeepAlive stay intact).
+  //       Installed ASAP — before pipe-pane — so even a runtime that dies during
+  //       boot leaves a cause. No-op without cfg.exitLogDir (remain-on-exit off).
+  installExitHook(sock, identity, cfg.exitLogDir)
+
   // (3) pipe-pane the session output to the per-identity log.
   mkdirSync(cfg.logDir, { recursive: true, mode: 0o700 })
   const paneLog = `${cfg.logDir}/${identity}.log`

package/src/launch/launch.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { getAdapter, launch } from './index.ts'
+import { exitCauseHook, exitLogPath, getAdapter, launch } from './index.ts'
 import { claudeAdapter } from './adapters/claude.ts'
 import { codexAdapter } from './adapters/codex.ts'
 import { telegramAdapter } from './adapters/telegram.ts'
@@ -187,6 +187,39 @@ describe('claudeAdapter', () => {
   })
 })
 
+// ─── exit-cause observability: the pane-died hook builder (pure string) ──────
+describe('exitCauseHook (exit-cause observability)', () => {
+  const hook = exitCauseHook('claude-iapeer', '/r/logs/iapeer/exits.log')
+
+  test('exitLogPath → exits.log sibling to lifecycle.log', () => {
+    expect(exitLogPath('/r/logs/iapeer')).toBe('/r/logs/iapeer/exits.log')
+  })
+  test('reads pane_dead_status AND pane_dead_signal (both death classes)', () => {
+    // graceful exit populates #{pane_dead_status}; a signal populates #{pane_dead_signal}.
+    expect(hook).toContain('dead_status=#{pane_dead_status}')
+    expect(hook).toContain('dead_signal=#{pane_dead_signal}')
+  })
+  test('one logfmt line: ts + ev=session-exit + identity, appended to the exit log', () => {
+    expect(hook).toContain('ev=session-exit')
+    expect(hook).toContain('identity=claude-iapeer')
+    expect(hook).toContain('ts=%s')
+    expect(hook).toContain('>> "/r/logs/iapeer/exits.log"')
+    expect(hook).toContain('\\n') // literal backslash-n for sh printf, not a real newline
+  })
+  test('logs BEFORE it reaps: run-shell (sync, no -b) then tmux-native kill-session', () => {
+    // run-shell must NOT be backgrounded (-b) — the printf has to finish before the
+    // kill tears the server down, else the line is lost to the race (verified live).
+    expect(hook).not.toContain('run-shell -b')
+    expect(hook.indexOf('run-shell')).toBeLessThan(hook.indexOf('kill-session'))
+    // tmux-NATIVE kill-session (no shell `tmux`) → needs no PATH (launchd minimal env).
+    expect(hook).toContain('kill-session -t "claude-iapeer"')
+  })
+  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
+  })
+})
+
 // ─── Ф-A #2: deliveryMarkers OWNED by the adapter (07.06 refactor) ───────────
 describe('deliveryMarkers (adapter-owned, was transport PROMPT_GLYPHS)', () => {
   test('claude: ❯ glyph + paste patterns', () => {

package/src/launch/launchdRun.ts

@@ -20,7 +20,7 @@ import { spawnSync } from 'child_process'
 import { join } from 'path'
 import { INFRA_RUNTIME_BIN_ENV, isInfraRuntime, resolveSockDir } from '../core/constants.ts'
 import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
-import { peerLogsDir } from '../storage/index.ts'
+import { peerLogsDir, pluginLogsDir } from '../storage/index.ts'
 import { readPeerProfile } from '../identity/index.ts'
 import { getAdapter, launch } from './index.ts'
 import type { LaunchConfig, LaunchSpec } from './types.ts'
@@ -102,6 +102,12 @@ export async function runAlwaysOn(personality: string, runtime: string, cwd: str
     // GLOBAL infra logs (Фаза §8): ~/.iapeer/logs/<personality>/ — match the plist's
     // stdout/stderr dir (installAlwaysOnPlist), not per-peer <cwd>/.iapeer/logs/.
     logDir: peerLogsDir(personality, { env }),
+    // Exit-cause log → the shared ~/.iapeer/logs/iapeer (== lifecycle eventLogDir),
+    // so an infra peer's self-death is recorded next to lifecycle.log too. The hook
+    // also reaps the dead pane: without it remain-on-exit would linger a dead pane,
+    // keeping sessionAlive() true so runAlwaysOn block-watches forever and KeepAlive
+    // never respawns — the hook prevents that regression as well as logging the cause.
+    exitLogDir: pluginLogsDir('iapeer', { env }),
     env,
     alwaysOn: true,
   }

package/src/launch/types.ts

@@ -20,7 +20,7 @@ export type { PublicPeerSummary } from '../registry/index.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // composeSystemPrompt — the layered Канал-A merge (docs/Сборка системного
-// промпта — слои и каналы.md). Four layers, general → specific (local overrides
+// промпта — слои и каналы.md). Five layers, general → specific (local overrides
 // global):
 //   1. System YAML (identity + host facts) — jq-GOLDEN, byte-for-byte.
 //   2. iapeer doctrine: ~/.iapeer/IAPEER.md (global) + <cwd>/.iapeer/IAPEER.md (local).
@@ -28,19 +28,27 @@ export type { PublicPeerSummary } from '../registry/index.ts'
 //   4. Plugin user-settings: every OTHER <DOMAIN>.md at the .iapeer/ root, global
 //      + local merged per domain. Custom files (SPAWNER_INSTRUCTIONS.md, …) flow
 //      in organically here — no special-casing.
+//   5. Doctrine fragments: every `*.md` in the `.iapeer/fragments/` subdir, global
+//      (~/.iapeer/fragments/) + local (<cwd>/.iapeer/fragments/) merged per stem.
+//      PRIMITIVE-owned, machine-regenerated (iapeer-memory's guide + note index, …)
+//      — a dedicated namespace kept OUT of the hand-authored IAPEER.md doctrine so
+//      the auto-writer and the human writer never share a file. Sits LAST: the most
+//      volatile layer, so edits to it never disturb the stable prefix above.
 // composeSystemPrompt is a PURE renderer over already-gathered data; the FS
 // discovery lives in gatherPromptInput (mirrors the bash split: shell read the
 // files, the renderer just laid out bytes).
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** One Layer-4 domain: the global + local halves of a single `<DOMAIN>.md` pair
- *  (either may be absent). `domain` is the filename stem, used only for stable
- *  ordering — it is NOT emitted (the merge is organic, per the contract). */
+/** One merged block: the global + local halves of a single stem (either may be
+ *  absent), used for BOTH Layer 4 (`<DOMAIN>.md` at the .iapeer/ root) and Layer 5
+ *  (`<STEM>.md` in .iapeer/fragments/). `domain` is the filename stem, used only
+ *  for stable ordering — it is NOT emitted (the merge is organic). Within a block
+ *  global precedes local (general → specific). */
 export interface PromptDomainBlock {
   domain: string
-  /** ~/.iapeer/<DOMAIN>.md content (general). */
+  /** Global half content (general): ~/.iapeer/<DOMAIN>.md or ~/.iapeer/fragments/<STEM>.md. */
   global?: string
-  /** <cwd>/.iapeer/<DOMAIN>.md content (specific — overrides global). */
+  /** Local half content (specific — overrides global): <cwd>/.iapeer/… counterpart. */
   local?: string
 }
 
@@ -66,6 +74,10 @@ export interface ComposePromptInput {
   /** Layer 4: every non-IAPEER `<DOMAIN>.md` pair at the .iapeer/ root. Empty/
    *  omitted → the layer emits nothing. */
   pluginDomains?: PromptDomainBlock[]
+  /** Layer 5: every `<STEM>.md` pair in the .iapeer/fragments/ subdir (global +
+   *  local), primitive-owned and machine-regenerated. Empty/omitted → the layer
+   *  emits nothing. Appended LAST (after Layer 4). */
+  promptFragments?: PromptDomainBlock[]
 }
 
 /**
@@ -87,10 +99,12 @@ export interface ComposePromptInput {
  *   peerDoctrine
  *   [\n\n + registry section  — only when peers.length > 0]
  *   [\n\n + merged domains    — only when pluginDomains is non-empty]
+ *   [\n\n + merged fragments  — only when promptFragments is non-empty]
  *
- * Layers 1+2 are byte-for-byte the legacy jq output; layers 3+4 are appended
+ * Layers 1+2 are byte-for-byte the legacy jq output; layers 3+4+5 are appended
  * (each as a `\n\n`-separated section) ONLY when they have content, so a peer
- * with no registry and no extra domains produces the exact legacy bytes.
+ * with no registry, no extra domains and no fragments produces the exact legacy
+ * bytes.
  *
  * Each YAML value is a JSON string literal (jq @json: JSON.stringify), which is
  * also a valid YAML double-quoted scalar — safe against colons/quotes/newlines.
@@ -266,6 +280,17 @@ export interface LaunchConfig extends LaunchAdapterConfig {
   maxAgeSecs: number
   /** Log dir for pipe-pane output. */
   logDir: string
+  /**
+   * Durable EXIT-CAUSE log dir (~/.iapeer/logs/iapeer — next to lifecycle.log,
+   * where the investigator looks). When set, launch installs a tmux `pane-died`
+   * hook that records WHY the session's process died (exit status / signal) AT THE
+   * MOMENT of death, into `<exitLogDir>/exits.log` — the blind spot the daemon's
+   * 60 s supervise tick (reaped-gone) can only see post-factum, after the exit code
+   * is already lost. Routed through cfg (NOT re-resolved from env) so it is isolated
+   * by the same sandbox as the rest of launch; a FALSY dir → no hook installed and
+   * `remain-on-exit` stays off (original behavior — a partial/test cfg never writes
+   * and never lingers a dead pane). See exitCauseHook in index.ts. */
+  exitLogDir?: string
   env?: NodeJS.ProcessEnv
   /**
    * Always-on bring-up (infra runtimes held by launchd KeepAlive): SKIP the

package/src/lifecycle/index.ts

@@ -805,6 +805,10 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
       readyGateSecs: cfg.readyGateSecs,
       maxAgeSecs: cfg.maxAgeSecs,
       logDir: cfg.logDir,
+      // Exit-cause log → next to lifecycle.log (~/.iapeer/logs/iapeer), where the
+      // investigator already looks: a self-death now leaves `exits.log` with the
+      // status/signal the daemon's post-factum reaped-gone could never recover.
+      exitLogDir: cfg.eventLogDir,
       env,
     }
     // C2 — initial_prompt (launch-seed): on a FRESH wake, seed the first turn with

package/src/transport/index.ts

@@ -469,7 +469,7 @@ export async function routeSend(
   const index = readPeersIndex()
   const peer = findPeer(index, personality)
   if (!peer) {
-    return err(`peer "${personality}" is not in the IAPeer peers index; message NOT delivered`)
+    return err(`peer "${personality}" is not in the iapeer peers index; message NOT delivered`)
   }
 
   // Built once — it is both the live-delivery payload and, on a miss, the wake