@agfpd/iapeer 0.2.32 → 0.2.34

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

@@ -97,15 +97,28 @@ describe('composeSystemPrompt — layer 4 (other domains)', () => {
     expect(out).not.toMatch(/\n{4,}/) // no 3+ blank lines = no empty block injected
   })
 
-  test('within a domain, global precedes local (general → specific)', () => {
+  test('within a domain, global precedes local (general → specific), each its own section', () => {
     const out = composeSystemPrompt({
       ...base,
       pluginDomains: [dom({ domain: 'MM', global: 'mm-global', local: 'mm-local' })],
     })
-    expect(out).toContain('mm-global\nmm-local')
+    // per-file now: global and local are SEPARATE sections (blank line between),
+    // not a tight single-newline merge
+    expect(out).toContain('mm-global\n\nmm-local')
     expect(out.indexOf('mm-global')).toBeLessThan(out.indexOf('mm-local'))
   })
 
+  test('per-file path markers: each half carries its <!-- path --> marker', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      pluginDomains: [
+        dom({ domain: 'MM', global: 'mm-global\n', globalPath: '~/.iapeer/MERGEMIND.md', local: 'mm-local\n', localPath: '~/p/.iapeer/MERGEMIND.md' }),
+      ],
+    })
+    expect(out).toContain('<!-- ~/.iapeer/MERGEMIND.md -->\nmm-global')
+    expect(out).toContain('<!-- ~/p/.iapeer/MERGEMIND.md -->\nmm-local')
+  })
+
   test('layer 4 sits after layer 3; domains kept in the order given', () => {
     const out = composeSystemPrompt({
       ...base,
@@ -156,7 +169,7 @@ describe('composeSystemPrompt — layer 5 (doctrine fragments)', () => {
       ...base,
       promptFragments: [frag({ domain: 'MEM', global: 'mem-guide', local: 'mem-index' })],
     })
-    expect(out).toContain('mem-guide\nmem-index')
+    expect(out).toContain('mem-guide\n\nmem-index') // per-file: separate sections
     expect(out.indexOf('mem-guide')).toBeLessThan(out.indexOf('mem-index'))
   })
 
@@ -268,13 +281,19 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect((input.pluginDomains ?? []).map(d => d.domain)).toEqual(['AAA', 'MARKER', 'MERGEMIND', 'ZZZ'])
   })
 
-  test('layer 4: per-domain global/local halves resolved correctly', () => {
+  test('layer 4: per-domain global/local halves resolved correctly, each with its display path', () => {
     const input = gather()
     const byName = Object.fromEntries((input.pluginDomains ?? []).map(d => [d.domain, d]))
-    expect(byName.MERGEMIND).toEqual({ domain: 'MERGEMIND', global: 'mm-global\n', local: 'mm-local\n' })
-    expect(byName.AAA).toEqual({ domain: 'AAA', global: 'aaa-global-only\n' })
-    expect(byName.ZZZ).toEqual({ domain: 'ZZZ', local: 'zzz-local-only\n' })
-    expect(byName.MARKER).toEqual({ domain: 'MARKER', local: '' }) // present but empty
+    expect(byName.MERGEMIND).toEqual({
+      domain: 'MERGEMIND',
+      global: 'mm-global\n',
+      globalPath: join(globalRoot, 'MERGEMIND.md'),
+      local: 'mm-local\n',
+      localPath: join(localRoot, 'MERGEMIND.md'),
+    })
+    expect(byName.AAA).toEqual({ domain: 'AAA', global: 'aaa-global-only\n', globalPath: join(globalRoot, 'AAA.md') })
+    expect(byName.ZZZ).toEqual({ domain: 'ZZZ', local: 'zzz-local-only\n', localPath: join(localRoot, 'ZZZ.md') })
+    expect(byName.MARKER).toEqual({ domain: 'MARKER', local: '', localPath: join(localRoot, 'MARKER.md') }) // present but empty
   })
 
   test('layer 5: fragments/ subdir scanned, paired by stem (guide global + index local), sorted', () => {
@@ -282,8 +301,16 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     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' })
+    const gfrag = join(globalRoot, 'fragments')
+    const lfrag = join(localRoot, 'fragments')
+    expect(byName['iapeer-memory']).toEqual({
+      domain: 'iapeer-memory',
+      global: 'mem-guide\n',
+      globalPath: join(gfrag, 'iapeer-memory.md'),
+      local: 'mem-index\n',
+      localPath: join(lfrag, 'iapeer-memory.md'),
+    })
+    expect(byName['other-primitive']).toEqual({ domain: 'other-primitive', global: 'other-frag\n', globalPath: join(gfrag, 'other-primitive.md') })
     // the non-.md notes.txt never became a fragment
     expect(frags.map(f => f.domain)).not.toContain('notes')
   })
@@ -320,12 +347,15 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(prompt).toContain('## Known peers')
     expect(prompt).toContain('- arthur — owner')
     expect(prompt).toContain('- boris — PM')
-    // Layer 4 (markers excluded, others merged, sorted)
+    // Layer 4 (presence-marker file excluded, others per-file with path markers, sorted)
     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')
+    // global half then a fresh marker then the local half (each its own marked section)
+    expect(prompt).toContain(`<!-- ${join(globalRoot, 'MERGEMIND.md')} -->\nmm-global`)
+    expect(prompt).toContain(`mm-global\n\n<!-- ${join(localRoot, 'MERGEMIND.md')} -->\nmm-local`)
+    // Layer 5 (fragments: guide+index paired as separate marked sections, global-only fragment)
+    expect(prompt).toContain(`<!-- ${join(globalRoot, 'fragments', 'iapeer-memory.md')} -->\nmem-guide`)
+    expect(prompt).toContain(`mem-guide\n\n<!-- ${join(localRoot, 'fragments', 'iapeer-memory.md')} -->\nmem-index`)
     expect(prompt).toContain('other-frag')
 
     const order = [
@@ -357,10 +387,13 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     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
+    // composes to just the YAML block (no doctrine, no layers); the per-file
+    // assembly normalizes the single section's trailing newlines to exactly one.
     const prompt = composeSystemPrompt(input)
     expect(prompt).not.toContain('## Known peers')
-    expect(prompt.endsWith('---\n\n')).toBe(true)
+    expect(prompt).not.toContain('<!--') // no files → no markers
+    expect(prompt.endsWith('---\n')).toBe(true)
+    expect(prompt.endsWith('---\n\n')).toBe(false)
   })
 
   test('doctrine excluded from Layer 4 case-INSENSITIVELY; .MD ext picked up (verify edge-lens fix)', () => {

package/src/launch/composeSystemPrompt.test.ts

@@ -1,8 +1,8 @@
-// Golden-equivalence test: composeSystemPrompt MUST produce byte-for-byte the
-// same output as the real jq doctrine-merge in claude-start.sh:264-290. Each
-// case runs the ACTUAL jq pipeline (extracted verbatim) and the TS function,
-// then byte-compares. This is the durable form of the Ф3 adversarial-verify
-// (which caught a 1-byte divergence on the empty-global-file case).
+// composeSystemPrompt — the YAML identity block (Layer 1) stays byte-for-byte the
+// claude-start.sh:264-290 jq layout (the durable golden); the file-sourced layers
+// (2/4/5) are now rendered PER FILE, each prefixed by a `<!-- <path> -->` marker.
+// This test pins BOTH: the jq-equivalent YAML prefix, and the marker format /
+// empty-file-drops rules of the per-file assembly.
 
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
 import { spawnSync } from 'child_process'
@@ -15,7 +15,7 @@ import type { ComposePromptInput } from './types.ts'
 let dir: string
 let jqProg: string
 
-// The jq program verbatim from claude-start.sh:274-284.
+// The jq program verbatim from claude-start.sh:274-284 — the YAML identity block.
 const JQ_PROGRAM = `"---",
 "personality: \\($personality | @json)",
 "description: \\($description | @json)",
@@ -39,16 +39,9 @@ beforeAll(() => {
 })
 afterAll(() => rmSync(dir, { recursive: true, force: true }))
 
-/** Run the exact bash/jq pipeline; `globalDoctrine` undefined = file absent. */
-function bashReference(input: ComposePromptInput): string {
-  const peerPath = join(dir, 'peer.md')
-  writeFileSync(peerPath, input.peerDoctrine)
-  let globalBlock = ''
-  if (input.globalDoctrine !== undefined) {
-    const gp = join(dir, 'global.md')
-    writeFileSync(gp, input.globalDoctrine)
-    globalBlock = `if [ -f ${shq(gp)} ]; then cat ${shq(gp)}; printf "\\n"; fi`
-  }
+/** The jq YAML identity block alone (no doctrine appended) — the byte-for-byte
+ *  Layer-1 golden every composed prompt must START with. */
+function jqYamlBlock(input: ComposePromptInput): string {
   const script = `set -e
 jq -n --raw-output \
   --arg personality ${shq(input.personality)} \
@@ -59,9 +52,7 @@ jq -n --raw-output \
   --arg user ${shq(input.user)} \
   --arg hostname ${shq(input.hostname)} \
   --arg today ${shq(input.today)} \
-  -f ${shq(jqProg)}
-${globalBlock}
-cat ${shq(peerPath)}`
+  -f ${shq(jqProg)}`
   const r = spawnSync('bash', ['-c', script], { encoding: 'utf8' })
   if (r.status !== 0) throw new Error(`bash reference failed: ${r.stderr}`)
   return r.stdout
@@ -77,22 +68,78 @@ const base = {
   today: '2026-06-06',
 }
 
-const cases: Array<{ name: string; input: ComposePromptInput }> = [
-  { name: 'basic, no global', input: { ...base, description: 'owner', peerDoctrine: 'Be helpful.\n' } },
-  { name: 'present non-empty global', input: { ...base, description: 'owner', peerDoctrine: 'peer\n', globalDoctrine: 'GLOBAL\n' } },
-  { name: 'EMPTY-but-present global (the 1-byte divergence the verify caught)', input: { ...base, description: 'owner', peerDoctrine: 'peer', globalDoctrine: '' } },
-  { name: 'hostile description: colon + quote + newline', input: { ...base, description: 'a: "b"\nc', peerDoctrine: 'doc\n' } },
-  { name: 'unicode + emoji description', input: { ...base, description: 'Артур 🦊 №2', peerDoctrine: 'док\n', globalDoctrine: 'гл\n' } },
-  { name: 'multiline peer doctrine, no trailing newline', input: { ...base, description: 'd', peerDoctrine: 'line1\nline2' } },
-  { name: 'description with backslash and slash', input: { ...base, description: 'a\\b/c', peerDoctrine: 'x\n' } },
-]
-
-describe('composeSystemPrompt golden-equivalence vs claude-start.sh jq', () => {
+// ─────────────────────────────────────────────────────────────────────────────
+// Layer 1 — the YAML identity block is byte-for-byte the jq layout
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('composeSystemPrompt — Layer 1 YAML block is byte-for-byte the jq layout', () => {
+  const cases: Array<{ name: string; input: ComposePromptInput }> = [
+    { name: 'basic', input: { ...base, description: 'owner', peerDoctrine: 'Be helpful.\n' } },
+    { name: 'hostile description: colon + quote + newline', input: { ...base, description: 'a: "b"\nc', peerDoctrine: 'doc\n' } },
+    { name: 'unicode + emoji description', input: { ...base, description: 'Артур 🦊 №2', peerDoctrine: 'док\n' } },
+    { name: 'description with backslash and slash', input: { ...base, description: 'a\\b/c', peerDoctrine: 'x\n' } },
+    { name: 'empty description', input: { ...base, description: '', peerDoctrine: 'x\n' } },
+  ]
   for (const c of cases) {
     test(c.name, () => {
-      const ref = bashReference(c.input)
-      const got = composeSystemPrompt(c.input)
-      expect(got).toBe(ref)
+      const yaml = jqYamlBlock(c.input)
+      // the composed prompt opens with the exact jq YAML block (the `---…---\n\n`)
+      expect(composeSystemPrompt(c.input).startsWith(yaml)).toBe(true)
     })
   }
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Layer 2 — IAPEER.md doctrine is rendered per-file with a path marker
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('composeSystemPrompt — per-file path markers (Layer 2 doctrine)', () => {
+  const input: ComposePromptInput = {
+    ...base,
+    description: 'owner',
+    peerDoctrine: 'Be the implementer.\n',
+    peerDoctrinePath: '~/Peers/arthur/.iapeer/IAPEER.md',
+    globalDoctrine: 'Host rules.\n',
+    globalDoctrinePath: '~/.iapeer/IAPEER.md',
+  }
+
+  test('each doctrine file is prefixed by its <!-- path --> marker, global before local', () => {
+    const out = composeSystemPrompt(input)
+    expect(out).toContain('<!-- ~/.iapeer/IAPEER.md -->\nHost rules.')
+    expect(out).toContain('<!-- ~/Peers/arthur/.iapeer/IAPEER.md -->\nBe the implementer.')
+    expect(out.indexOf('<!-- ~/.iapeer/IAPEER.md -->')).toBeLessThan(
+      out.indexOf('<!-- ~/Peers/arthur/.iapeer/IAPEER.md -->'),
+    )
+  })
+
+  test('marker sits AFTER the YAML block (one blank line between)', () => {
+    const out = composeSystemPrompt(input)
+    expect(out).toContain('---\n\n<!-- ~/.iapeer/IAPEER.md -->')
+  })
+
+  test('a path-less content (pure-renderer caller) renders WITHOUT a marker', () => {
+    const out = composeSystemPrompt({ ...base, description: 'd', peerDoctrine: 'no marker here\n' })
+    expect(out).toContain('no marker here')
+    expect(out).not.toContain('<!--')
+  })
+
+  test('an EMPTY doctrine file contributes no section and no dangling marker', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      description: 'd',
+      peerDoctrine: 'real\n',
+      peerDoctrinePath: '~/p/IAPEER.md',
+      globalDoctrine: '', // present but empty → dropped
+      globalDoctrinePath: '~/.iapeer/IAPEER.md',
+    })
+    expect(out).not.toContain('~/.iapeer/IAPEER.md') // empty global marker absent
+    expect(out).toContain('<!-- ~/p/IAPEER.md -->\nreal')
+  })
+
+  test('output ends with exactly one newline; no 3+ blank-line gaps', () => {
+    const out = composeSystemPrompt(input)
+    expect(out.endsWith('\n')).toBe(true)
+    expect(out.endsWith('\n\n')).toBe(false)
+    expect(out).not.toMatch(/\n{3,}/)
+  })
+})

package/src/launch/composeSystemPrompt.ts

@@ -55,10 +55,33 @@ function jqJson(value: string): string {
     .replace(new RegExp(String.fromCharCode(0x00), 'g'), '\\u0000')
 }
 
+/** A per-file section: a path marker line, then the file content. The marker is an
+ *  HTML comment — inert in rendered markdown yet plainly visible in the raw system-
+ *  prompt the model reads (verified: the model's context surfaces HTML comments) —
+ *  so a reader (human or agent) can tell, per file, exactly which path each chunk of
+ *  the assembled prompt came from. No marker when `path` is absent (a pure-renderer
+ *  caller, or the synthesized Layer-1 YAML / Layer-3 registry which are not files). */
+function markedSection(path: string | undefined, content: string): string {
+  return path ? `<!-- ${path} -->\n${content}` : content
+}
+
+/** Trailing-newline-trimmed length test: a 0-byte or newline-only file is "empty"
+ *  and contributes no section (and so no dangling marker). */
+function hasContent(s: string | undefined): s is string {
+  return s !== undefined && s.replace(/\n+$/, '').length > 0
+}
+
 /**
- * Compose the merged system prompt (YAML identity block + optional global
- * doctrine + per-peer doctrine), GOLDEN byte-for-byte equivalent to the
- * claude-start.sh:264-290 jq pipeline.
+ * Compose the merged system prompt: the YAML identity block (Layer 1) followed by
+ * every file-sourced layer rendered PER FILE — each injected `.md` prefixed by a
+ * path marker (`<!-- <path> -->`). Layers, general → specific:
+ *   1. YAML identity block (synthesized, no marker) — byte-for-byte the jq layout.
+ *   2. IAPEER.md doctrine: global then local, each its own marked section.
+ *   3. Normalized peer registry (generated, no marker).
+ *   4. Other `<DOMAIN>.md` at the .iapeer root — each half (global, local) marked.
+ *   5. fragments/ `*.md` — each half marked. Most-volatile, sits LAST.
+ * Empty files contribute nothing (no section, no marker). Sections are joined by a
+ * single blank line and the output ends with exactly one newline.
  */
 export function composeSystemPrompt(input: ComposePromptInput): string {
   // The eight identity lines, in the bash's exact key order. Keys verbatim:
@@ -77,38 +100,37 @@ export function composeSystemPrompt(input: ComposePromptInput): string {
     // jq's final "" array element → the bare blank line after the closing '---'.
     '\n'
 
-  // Global doctrine sits between the YAML block and the per-peer doctrine so
-  // per-peer rules override global (specific over general). Bash gates on file
-  // EXISTENCE (`[ -f "$GLOBAL_DOCTRINE" ]`), NOT non-emptiness — a present but
-  // EMPTY global file still emits `cat "" + printf "\n"` = "\n". So the contract
-  // is: a present file → globalDoctrine is the string (possibly ""), absent file
-  // → undefined. Guard on `!== undefined` (NOT truthiness) to match bash exactly;
-  // an empty "" then yields "" + "\n" = "\n" (the 1-byte golden divergence the
-  // adversarial verify caught). The trailing "\n" mirrors the unconditional
-  // `printf "\n"` after `cat "$GLOBAL"`.
-  const global = input.globalDoctrine !== undefined ? input.globalDoctrine + '\n' : ''
+  // The YAML identity block is the only Layer-1 section (synthesized, no marker).
+  const sections: string[] = [yaml]
+
+  // Layer 2 — IAPEER.md doctrine, GLOBAL then LOCAL (general → specific), each its
+  // OWN marked file-section. The bash existence-gate (present-but-empty global → a
+  // bare "\n") is dropped deliberately: an empty doctrine file now contributes no
+  // section (and no dangling marker), like every other empty file. IAPEER.md carries
+  // the only FIXED semantics in the assembly (host = general peer rules, local = this
+  // peer's rules — the CLAUDE.md analogue); its meaning is conveyed by the well-known
+  // filename + path, so the marker stays a bare path like every other file's.
+  if (hasContent(input.globalDoctrine)) {
+    sections.push(markedSection(input.globalDoctrinePath, input.globalDoctrine))
+  }
+  if (hasContent(input.peerDoctrine)) {
+    sections.push(markedSection(input.peerDoctrinePath, input.peerDoctrine))
+  }
 
-  // Layers 1+2: YAML block + global doctrine + per-peer doctrine verbatim
-  // (`cat "$DOCTRINE"`), no trailing newline added. BYTE-IDENTICAL to the legacy
-  // jq output — the golden test pins this exactly.
-  const layer12 = yaml + global + input.peerDoctrine
+  // Layer 3 — normalized peer registry (generated from the index, not a file → no
+  // marker). Empty list → nothing.
+  const registry = renderRegistry(input.peers ?? [])
+  if (registry.length > 0) sections.push(registry)
 
-  // 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 = renderMergedBlocks(input.pluginDomains ?? [])
-  const layer5 = renderMergedBlocks(input.promptFragments ?? [])
-  const sections = [layer12, layer3, layer4, layer5].filter(section => section.length > 0)
+  // Layers 4 (other <DOMAIN>.md) then 5 (fragments/, most-volatile, LAST) — each
+  // file half (global, local) is its own marked section. Empty halves drop out.
+  pushMarkedBlocks(sections, input.pluginDomains ?? [])
+  pushMarkedBlocks(sections, input.promptFragments ?? [])
 
-  // ONE section (no registry, no extra domains) → the legacy bytes, UNTOUCHED —
-  // the golden test pins layer12 exactly (peerDoctrine verbatim, incl. its own
-  // trailing-newline-or-not). MULTIPLE sections → normalize every seam to exactly
-  // one blank line: strip each section's trailing newlines, join with '\n\n', end
-  // with a single '\n'. This makes the output robust to whether the source files
-  // carried trailing newlines (a present-but-newline-only tail never widens a gap).
-  if (sections.length === 1) return sections[0]
+  // Normalize every seam to exactly one blank line: strip each section's trailing
+  // newlines, join with '\n\n', end with a single '\n'. Robust to whether source
+  // files carried trailing newlines. A bare-doctrine peer is now [YAML, local
+  // IAPEER.md] → two sections, so it always carries its doctrine's path marker.
   return sections.map(section => section.replace(/\n+$/, '')).join('\n\n') + '\n'
 }
 
@@ -132,32 +154,23 @@ function renderRegistry(peers: readonly PublicPeerSummary[]): string {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Layers 4 & 5 — merged global/local blocks. Shared renderer:
+// Layers 4 & 5 — per-file marked sections:
 //   • 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.
+// Each block contributes its GLOBAL half then its LOCAL half (general → specific),
+// EACH as its own marked file-section (a 0-byte / newline-only file → no section,
+// no dangling marker). Blocks are appended in the order given (the gatherer sorts
+// by filename for determinism); the stem (`domain`) is used only for that ordering,
+// never emitted.
 // ─────────────────────────────────────────────────────────────────────────────
 
-function renderMergedBlocks(blocks: readonly PromptDomainBlock[]): string {
-  const out: string[] = []
+function pushMarkedBlocks(sections: string[], blocks: readonly PromptDomainBlock[]): void {
   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 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) out.push(halves.join('\n'))
+    if (hasContent(b.global)) sections.push(markedSection(b.globalPath, b.global))
+    if (hasContent(b.local)) sections.push(markedSection(b.localPath, b.local))
   }
-  return out.join('\n\n')
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -218,16 +231,28 @@ function listDomainFiles(root: string): string[] {
   return listMdFiles(root).filter(name => name.toLowerCase() !== doctrineLower)
 }
 
+/** Display path for a marker: an absolute path with a leading HOME abbreviated to
+ *  `~` (the form a human scanning the assembled prompt expects). HOME unset / path
+ *  outside HOME → the absolute path verbatim. */
+function displayPath(absPath: string, env: NodeJS.ProcessEnv): string {
+  const home = env.HOME?.trim()
+  if (home && (absPath === home || absPath.startsWith(home + '/'))) {
+    return '~' + absPath.slice(home.length)
+  }
+  return absPath
+}
+
 /** 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. */
+ *  takes every fragment. Each present half carries its display path for the marker.
+ *  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,
+  env: NodeJS.ProcessEnv,
   lister: (dir: string) => string[] = listMdFiles,
 ): PromptDomainBlock[] {
   const names = new Set<string>([...lister(globalDir), ...lister(localDir)])
@@ -235,8 +260,14 @@ function gatherMergedBlocks(
     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
+    if (global !== undefined) {
+      block.global = global
+      block.globalPath = displayPath(join(globalDir, name), env)
+    }
+    if (local !== undefined) {
+      block.local = local
+      block.localPath = displayPath(join(localDir, name), env)
+    }
     return block
   })
 }
@@ -246,16 +277,19 @@ export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput
   const globalRoot = opts.globalRoot ?? resolveGlobalRoot(env)
   const localRoot = join(opts.cwd, IAPEER_DIR)
 
-  // Layer 2 — IAPEER.md merge. Global is existence-gated (undefined when absent,
-  // '' when present-but-empty — golden parity). Local defaults to '' when absent.
-  const globalDoctrine = readFileIfPresent(join(globalRoot, IAPEER_DOCTRINE_FILE))
-  const peerDoctrine = readFileIfPresent(join(localRoot, IAPEER_DOCTRINE_FILE)) ?? ''
+  // Layer 2 — IAPEER.md merge. Each half carries its display path for the marker.
+  // Existence-gated: undefined when absent, '' when present-but-empty (an empty
+  // doctrine now contributes no section — no bare-"\n" legacy quirk).
+  const globalDoctrineFile = join(globalRoot, IAPEER_DOCTRINE_FILE)
+  const peerDoctrineFile = join(localRoot, IAPEER_DOCTRINE_FILE)
+  const globalDoctrine = readFileIfPresent(globalDoctrineFile)
+  const peerDoctrine = readFileIfPresent(peerDoctrineFile) ?? ''
 
   // Layer 4 — union of every non-IAPEER domain present globally and/or locally,
   // 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)
+  const pluginDomains = gatherMergedBlocks(globalRoot, localRoot, env, 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
@@ -264,6 +298,7 @@ export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput
   const promptFragments = gatherMergedBlocks(
     join(globalRoot, FRAGMENTS_DIR),
     join(localRoot, FRAGMENTS_DIR),
+    env,
   )
 
   // Layer 3 — peers projected through the shared normalizer, sorted by personality
@@ -285,7 +320,10 @@ export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput
     hostname: opts.hostname,
     today: opts.today,
     peerDoctrine,
-    ...(globalDoctrine !== undefined ? { globalDoctrine } : {}),
+    peerDoctrinePath: displayPath(peerDoctrineFile, env),
+    ...(globalDoctrine !== undefined
+      ? { globalDoctrine, globalDoctrinePath: displayPath(globalDoctrineFile, env) }
+      : {}),
     peers,
     pluginDomains,
     promptFragments,

package/src/launch/types.ts

@@ -42,14 +42,21 @@ export type { PublicPeerSummary } from '../registry/index.ts'
 /** 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). */
+ *  for stable ordering — it is NOT emitted. Within a block global precedes local
+ *  (general → specific), and each half is rendered as its OWN per-file section
+ *  prefixed by a path marker (`globalPath` / `localPath`) — the assembly is now
+ *  per-file, not an organic stem-merge. */
 export interface PromptDomainBlock {
   domain: string
   /** Global half content (general): ~/.iapeer/<DOMAIN>.md or ~/.iapeer/fragments/<STEM>.md. */
   global?: string
   /** Local half content (specific — overrides global): <cwd>/.iapeer/… counterpart. */
   local?: string
+  /** Display path for the global half's marker (HOME abbreviated to ~). Absent →
+   *  no marker (pure-renderer callers). */
+  globalPath?: string
+  /** Display path for the local half's marker. */
+  localPath?: string
 }
 
 export interface ComposePromptInput {
@@ -64,10 +71,14 @@ export interface ComposePromptInput {
   today: string
   /** Layer 2 local: <cwd>/.iapeer/IAPEER.md content. '' when absent. */
   peerDoctrine: string
+  /** Display path for the local IAPEER.md marker (HOME abbreviated to ~). */
+  peerDoctrinePath?: string
   /** Layer 2 global, OPTIONAL: ~/.iapeer/IAPEER.md content (sits between the YAML
    *  block and the per-peer doctrine so per-peer overrides global). Existence-
    *  gated: a present-but-empty file → '', an absent file → undefined. */
   globalDoctrine?: string
+  /** Display path for the global IAPEER.md marker. */
+  globalDoctrinePath?: string
   /** Layer 3: the normalized peer registry. Empty/omitted → the layer emits
    *  nothing (and the output stays byte-identical to the legacy YAML+doctrine). */
   peers?: PublicPeerSummary[]

package/src/lifecycle/index.ts

@@ -654,7 +654,7 @@ export function classifyGoneSession(sock: string): { death: 'server-dead' | 'ses
   // proves the server is alive and merely lost this session.
   return tmux(sock, 'list-sessions').ok
     ? { death: 'session-gone', reason: 'session gone, tmux server alive (exit cause should be in exits.log)' }
-    : { death: 'server-dead', reason: 'tmux server dead — stale socket (SIGKILL/OOM class; check exits.log ev=server-exit canary record)' }
+    : { death: 'server-dead', reason: 'tmux server dead — stale socket (SIGKILL class — OOM only if a matching JetsamEvent report exists; check exits.log ev=server-exit canary record)' }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -790,6 +790,13 @@ export interface WakeResult {
    *  deliberate halt, distinct from offline/wake-failure). The sender is told the
    *  peer is stopped, not that delivery failed transiently. */
   stopped?: boolean
+  /** Was `task` actually delivered by this wake? true on the launch path (the
+   *  task rode as the boot first-message); FALSE on the idempotent live-session
+   *  fast path — a CONCURRENT sender's boot won the lock and only ITS envelope
+   *  was delivered; this caller's task was NOT. The caller (routeSend) must then
+   *  deliver the envelope itself via the live path, or the second sender's
+   *  message is silently lost behind a false ok (contract forbids silent loss). */
+  taskDelivered?: boolean
 }
 
 export interface WakeDeps {
@@ -890,7 +897,9 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     // wake already brought it up) — no second spawn.
     if (sessionAlive(sock, identity)) {
       writeSessionState(cfg, { identity, runtime, personality: args.personality, cwd, wokeAt: Date.now() })
-      return { status: 'READY', woke: false, runtime, process_address: identity }
+      // taskDelivered:false — the winning concurrent wake delivered ITS OWN task as
+      // the boot first-message; THIS caller's task was not delivered by anything.
+      return { status: 'READY', woke: false, runtime, process_address: identity, taskDelivered: false }
     }
     if (!existsSync(cwd)) {
       return { status: 'FAILED', woke: false, runtime, reason: `peer cwd does not exist: ${cwd}` }
@@ -997,7 +1006,7 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     // ring — a successful wake means this is NOT a tight crash loop. Best-effort.
     writeTopic(cfg, identity, args.topic?.trim() ?? '')
     trimDeaths(cfg, identity, cfg.crashLoopWindowSecs, Date.now())
-    return { status: 'READY', woke: true, runtime, process_address: identity }
+    return { status: 'READY', woke: true, runtime, process_address: identity, taskDelivered: true }
   })
 }