@agfpd/iapeer 0.2.33 → 0.2.34

package/package.json

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

package/src/cli/index.ts

@@ -45,6 +45,13 @@ import {
 import { getAdapter } from '../launch/index.ts'
 import { isFoundationOwnedPlist, kickstartDaemon, launchctlBootstrap, launchdLabel, launchdPlistPath } from '../launch/launchd.ts'
 import { resolveCallerIdentity, resolveIdentity } from '../identity/index.ts'
+import { peerProfilePath } from '../storage/index.ts'
+import {
+  isConformant,
+  reconcileIndex,
+  reindexFromLocals,
+  validateProfileStandard,
+} from '../identity/profileStandard.ts'
 import { runAlwaysOn } from '../launch/launchdRun.ts'
 import { installDaemonPlist, startConfiguredDaemon } from '../daemon/main.ts'
 import { MARKETPLACE_NAME, onboardHost } from '../onboard/index.ts'
@@ -544,6 +551,7 @@ const USAGE = `usage: iapeer <verb> [args]
   init [cwd] [--personality p] [--runtime r] [--description d]   onboard the CURRENT folder as a peer (identity + MCP + doctrine)
   create <personality> [--runtime r] [--path dir] [--bin abs]   create a peer anywhere (default ~/.iapeer/peers/<p>) + provision
   list [--json]                                                  registered peers + per-runtime liveness
+  verify [--json] [--fix]                                        profile-standard conformance + index↔local drift (--fix self-heals the index)
   stop <peer> [runtime] | --all                                  durable-stop a warm peer / bootout an always-on one
   start <peer> [runtime]                                         re-enable a stopped peer / bootstrap an always-on one
   remove <peer> [--force]                                        delete a peer's registry record (locked writer); refuses a LIVE peer unless --force
@@ -871,6 +879,61 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(flags.json ? JSON.stringify(rows, null, 2) + '\n' : formatListTable(rows))
         return 0
       }
+      case 'verify': {
+        // Profile conformance + index↔local self-heal reconciliation. Read-only by
+        // default; --fix self-heals the index (reindex from local profiles). A drift
+        // is a signal that the index self-heal lapsed — caught by construction here.
+        const index = readPeersIndex({ env })
+        let errors = 0
+        let driftCount = 0
+        const lines: string[] = []
+        for (const peer of index.peers) {
+          const path = peerProfilePath(peer.cwd)
+          if (!existsSync(path)) {
+            errors++
+            lines.push(`✗ ${peer.personality}: no local profile at ${path}`)
+            continue
+          }
+          let raw: unknown
+          try {
+            raw = JSON.parse(readFileSync(path, 'utf8'))
+          } catch (e) {
+            errors++
+            lines.push(`✗ ${peer.personality}: profile is invalid JSON — ${e instanceof Error ? e.message : String(e)}`)
+            continue
+          }
+          const issues = validateProfileStandard(raw, peer.cwd)
+          const errs = issues.filter(i => i.severity === 'error')
+          const warns = issues.filter(i => i.severity === 'warn')
+          if (errs.length > 0) errors += errs.length
+          if (!isConformant(issues)) {
+            lines.push(`✗ ${peer.personality}: ${errs.map(i => `${i.field} — ${i.message}`).join('; ')}`)
+          } else if (warns.length > 0 && flags.json !== true) {
+            lines.push(`⚠ ${peer.personality}: ${warns.map(i => i.field).join(', ')}`)
+          }
+        }
+        const reconcile = reconcileIndex({ env })
+        for (const r of reconcile) {
+          if (r.drift === null) {
+            // missing local profile already reported above as an error
+          } else if (r.drift.length > 0) {
+            driftCount++
+            lines.push(`↯ ${r.personality}: index↔local drift on ${r.drift.join(', ')}`)
+          }
+        }
+        if (flags.json === true) {
+          out(JSON.stringify({ peers: index.peers.length, errors, drift: driftCount, reconcile }, null, 2) + '\n')
+        } else {
+          for (const l of lines) out(l + '\n')
+          out(`\n${index.peers.length} peers · ${errors} error(s) · ${driftCount} index↔local drift(s)\n`)
+        }
+        if (flags.fix === true && (driftCount > 0 || errors === 0)) {
+          const { healed, missing } = await reindexFromLocals({ env })
+          if (healed.length > 0) out(`self-healed index from local profiles:\n  ${healed.join('\n  ')}\n`)
+          if (missing.length > 0) errOut(`peers with no local profile (left untouched): ${missing.join(', ')}\n`)
+        }
+        return errors > 0 || (driftCount > 0 && flags.fix !== true) ? 1 : 0
+      }
       case 'stop': {
         // --all stops every registered peer (the fleet guard still refuses foreign
         // persistent-peer plists, so the live fleet stays untouched).

package/src/enable/enable.test.ts

@@ -44,21 +44,24 @@ describe('findPeerScopedEntry (per-peer, fleet-safe)', () => {
   })
 })
 
-// the real `codex plugin list` table shape (whitespace-aligned columns)
-const CODEX_LIST = `Marketplace \`agfpd\`
-
-PLUGIN                      STATUS              VERSION  PATH
-spawned-peer@agfpd          not installed                https://github.com/agfpd/Spawned-Peer.git
-peer-voice@agfpd            installed, enabled  0.1.8    https://github.com/agfpd/Peer-Voice.git
-MergeMind@agfpd             installed, disabled 0.14.70  https://github.com/agfpd/MergeMind.git`
+// the real `codex plugin list --json` shape (codex-cli 0.138, live-captured fields)
+const CODEX_LIST = JSON.stringify({
+  installed: [
+    { pluginId: 'peer-voice@agfpd', installed: true, enabled: true },
+    { pluginId: 'MergeMind@agfpd', installed: true, enabled: false },
+    { pluginId: 'spawned-peer@agfpd', installed: false, enabled: false }, // marketplace-known, not installed
+  ],
+})
 
 describe('parseCodexPluginStatus', () => {
-  test('reads the STATUS column per plugin id', () => {
+  test('reads the installed/enabled flags per plugin id', () => {
     expect(parseCodexPluginStatus(CODEX_LIST, 'peer-voice@agfpd')).toBe('enabled')
-    expect(parseCodexPluginStatus(CODEX_LIST, 'spawned-peer@agfpd')).toBe('absent') // "not installed"
-    expect(parseCodexPluginStatus(CODEX_LIST, 'MergeMind@agfpd')).toBe('disabled')
-    expect(parseCodexPluginStatus(CODEX_LIST, 'totp-presence@agfpd')).toBe('absent') // not in list
-    expect(parseCodexPluginStatus('', 'x@agfpd')).toBe('absent')
+    expect(parseCodexPluginStatus(CODEX_LIST, 'spawned-peer@agfpd')).toBe('absent') // installed:false
+    expect(parseCodexPluginStatus(CODEX_LIST, 'MergeMind@agfpd')).toBe('disabled') // installed, not enabled
+    expect(parseCodexPluginStatus(CODEX_LIST, 'totp-presence@agfpd')).toBe('absent') // not in array
+    expect(parseCodexPluginStatus('', 'x@agfpd')).toBe('absent') // empty
+    expect(parseCodexPluginStatus('not json', 'x@agfpd')).toBe('absent') // malformed → fail-safe
+    expect(parseCodexPluginStatus('{"no":"installed-array"}', 'x@agfpd')).toBe('absent')
   })
 })
 

package/src/enable/index.ts

@@ -274,24 +274,32 @@ function enableClaude(plugin: string, marketplace: string, peerCwd: string, env:
   return { runtime: 'claude', state: existing ? 'enabled' : 'installed', installPath: after.installPath }
 }
 
-/** Parse a `codex plugin list` STATUS column for one plugin id. The table is
- *  whitespace-aligned: `<id>  <status>  <version>  <path>`; status is `not installed`
- *  / `installed, enabled` / `installed, disabled`. PURE → unit-testable. */
-export function parseCodexPluginStatus(listOutput: string, id: string): 'enabled' | 'disabled' | 'absent' {
-  for (const line of listOutput.split('\n')) {
-    const cols = line.split(/\s{2,}/).map(c => c.trim())
-    if (cols[0] !== id) continue
-    const status = (cols[1] ?? '').toLowerCase()
-    if (status.includes('not installed')) return 'absent'
-    if (status.includes('enabled')) return 'enabled'
-    if (status.includes('installed')) return 'disabled'
+/** Parse `codex plugin list --json` for one plugin id's status. Shape (codex-cli
+ *  0.138, live-verified): `{ installed: [{ pluginId, installed, enabled }, …] }`.
+ *  A plugin absent from the array OR with `installed:false` → 'absent'; `enabled:true`
+ *  → 'enabled'; installed-but-not-enabled → 'disabled'. Replaces the prior whitespace-
+ *  table parse (brittle to column re-alignment / status-string wording) — the codex
+ *  counterpart of the claude path's `parseInstalledPlugins`. Malformed/empty input →
+ *  'absent' (same fail-safe). PURE → unit-testable. */
+export function parseCodexPluginStatus(jsonOutput: string, id: string): 'enabled' | 'disabled' | 'absent' {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(jsonOutput)
+  } catch {
     return 'absent'
   }
-  return 'absent'
+  const installed = (parsed as { installed?: unknown } | null)?.installed
+  if (!Array.isArray(installed)) return 'absent'
+  const entry = installed.find(
+    (e): e is { pluginId: string; installed?: boolean; enabled?: boolean } =>
+      !!e && typeof e === 'object' && (e as { pluginId?: unknown }).pluginId === id,
+  )
+  if (!entry || entry.installed === false) return 'absent'
+  return entry.enabled === true ? 'enabled' : 'disabled'
 }
 
 function codexState(bin: string, id: string, env: NodeJS.ProcessEnv): 'enabled' | 'disabled' | 'absent' {
-  const r = spawnSync(bin, ['plugin', 'list'], { encoding: 'utf8', env: env as Record<string, string>, maxBuffer: 64 * 1024 * 1024 })
+  const r = spawnSync(bin, ['plugin', 'list', '--json'], { encoding: 'utf8', env: env as Record<string, string>, maxBuffer: 64 * 1024 * 1024 })
   return parseCodexPluginStatus(r.stdout ?? '', id)
 }
 

package/src/identity/index.ts

@@ -206,8 +206,16 @@ export function readPeerProfile(cwd: string = process.cwd()): PeerProfile | null
   if (typeof obj.personality !== 'string' || !obj.personality.trim()) {
     throw new IapError(`${IAPEER_DIR}/${PEER_PROFILE_FILE} personality is required`)
   }
+  // personality is a SYSTEM MIRROR (contract Идентичность): the canonical value is
+  // normalize(basename(cwd)). The stored field is read+normalized here; a mismatch
+  // with the cwd-derived name is SURFACED by validateProfileStandard (a self-heal WARN)
+  // rather than silently overridden on read — the read-time override conflicts with
+  // the `iapeer init --personality` override (a deliberately-named peer in a folder
+  // whose basename differs), so the heal stays a flagged drift, not a silent rewrite.
   const personality = validatePersonality(obj.personality, 'peer-profile personality')
-  const runtime = validateRuntime(obj.runtime, 'peer-profile runtime')
+  // default_runtime is the contract field name (the routing/wake/first-launch default);
+  // `runtime` is the legacy field. Dual-read accepts both during the staged migration.
+  const runtime = validateRuntime(obj.default_runtime ?? obj.runtime, 'peer-profile default_runtime')
   const interfaces = normalizeInterfaces(obj.interfaces, `${IAPEER_DIR}/${PEER_PROFILE_FILE}`)
   const intelligence = normalizeIntelligence(obj.intelligence, runtime)
   return {

package/src/identity/profileStandard.test.ts

@@ -0,0 +1,116 @@
+// Profile-standard validator + index↔local self-heal (reconcile / reindex).
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { isConformant, reconcileIndex, reindexFromLocals, validateProfileStandard } from './profileStandard.ts'
+import { readPeersIndex } from '../registry/index.ts'
+
+describe('validateProfileStandard', () => {
+  const cwd = '/Users/x/Peers/boris' // basename normalizes to "boris"
+
+  test('a conformant profile (contract field default_runtime) has no issues', () => {
+    const issues = validateProfileStandard(
+      { personality: 'boris', default_runtime: 'claude', runtimes: ['claude'], description: 'PM', intelligence: 'artificial' },
+      cwd,
+    )
+    expect(issues).toEqual([])
+    expect(isConformant(issues)).toBe(true)
+  })
+
+  test('legacy `runtime` field → WARN (not error), still conformant', () => {
+    const issues = validateProfileStandard(
+      { personality: 'boris', runtime: 'claude', runtimes: ['claude'], description: '', intelligence: 'artificial' },
+      cwd,
+    )
+    expect(isConformant(issues)).toBe(true)
+    expect(issues.find(i => i.field === 'default_runtime')?.severity).toBe('warn')
+  })
+
+  test('top-level aliases → WARN (owner migration pending), still conformant', () => {
+    const issues = validateProfileStandard(
+      { personality: 'boris', runtime: 'claude', runtimes: ['claude'], description: '', intelligence: 'artificial', aliases: { '/new': 'x' } },
+      cwd,
+    )
+    expect(isConformant(issues)).toBe(true)
+    expect(issues.some(i => i.field === 'aliases' && i.severity === 'warn')).toBe(true)
+  })
+
+  test('personality mirror disagreeing with cwd → WARN (self-heal), not error', () => {
+    const issues = validateProfileStandard(
+      { personality: 'WRONG', runtime: 'claude', runtimes: ['claude'], description: '', intelligence: 'artificial' },
+      cwd,
+    )
+    expect(isConformant(issues)).toBe(true)
+    expect(issues.some(i => i.field === 'personality' && i.severity === 'warn')).toBe(true)
+  })
+
+  test('ERRORS: bad runtime, runtimes missing the default, bad intelligence', () => {
+    // runtime ids carry NO hyphen (/^[a-z][a-z0-9]{0,31}$/) → a hyphenated value is an error
+    expect(isConformant(validateProfileStandard({ default_runtime: 'no-dash', runtimes: ['claude'], intelligence: 'artificial' }, cwd))).toBe(false)
+    const e1 = validateProfileStandard({ default_runtime: 'claude', runtimes: ['codex'], intelligence: 'artificial' }, cwd)
+    expect(isConformant(e1)).toBe(false) // runtimes does not include the default
+    const e2 = validateProfileStandard({ default_runtime: 'claude', runtimes: ['claude'], intelligence: 'bogus' }, cwd)
+    expect(isConformant(e2)).toBe(false)
+    const e3 = validateProfileStandard({ runtimes: ['claude'], intelligence: 'artificial' }, cwd)
+    expect(isConformant(e3)).toBe(false) // no runtime/default_runtime at all
+  })
+
+  test('intelligence accepts the live vocab + legacy on read', () => {
+    for (const v of ['artificial', 'natural', 'absent', 'human', 'scripted']) {
+      const issues = validateProfileStandard({ default_runtime: 'claude', runtimes: ['claude'], intelligence: v }, cwd)
+      expect(issues.some(i => i.field === 'intelligence')).toBe(false)
+    }
+  })
+})
+
+describe('reconcileIndex / reindexFromLocals (self-heal)', () => {
+  let root: string
+  const prevRoot = process.env.IAPEER_ROOT
+  let borisCwd: string
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'iapeer-ps-'))
+    process.env.IAPEER_ROOT = root
+    // a local profile (source of truth) with a FRESH description + narrowed runtimes
+    borisCwd = join(root, 'peers', 'boris')
+    mkdirSync(join(borisCwd, '.iapeer'), { recursive: true })
+    writeFileSync(
+      join(borisCwd, '.iapeer', 'peer-profile.json'),
+      JSON.stringify({ personality: 'boris', runtime: 'claude', runtimes: ['claude'], description: 'FRESH local desc', intelligence: 'artificial' }),
+    )
+    // a STALE index: old description + an extra runtime the local no longer declares
+    writeFileSync(
+      join(root, 'peers-profiles.json'),
+      JSON.stringify({
+        version: 2,
+        peers: [{ personality: 'boris', runtime: 'claude', runtimes: ['claude', 'codex'], description: 'STALE index desc', intelligence: 'artificial', cwd: borisCwd }],
+      }),
+    )
+  })
+  afterEach(() => {
+    if (prevRoot === undefined) delete process.env.IAPEER_ROOT
+    else process.env.IAPEER_ROOT = prevRoot
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  test('reconcile DETECTS the drift (description + runtimes) read-only', () => {
+    const r = reconcileIndex({ env: process.env })
+    const boris = r.find(e => e.personality === 'boris')
+    expect(boris?.drift).toContain('description')
+    expect(boris?.drift).toContain('runtimes')
+    // read-only: the index file is untouched
+    expect(readPeersIndex({ env: process.env }).peers[0].description).toBe('STALE index desc')
+  })
+
+  test('reindex SELF-HEALS the index from the local profile (REPLACE, not union)', async () => {
+    const { healed } = await reindexFromLocals({ env: process.env })
+    expect(healed.some(h => h.startsWith('boris:'))).toBe(true)
+    const rec = readPeersIndex({ env: process.env }).peers[0]
+    expect(rec.description).toBe('FRESH local desc')
+    expect(rec.runtimes).toEqual(['claude']) // codex DROPPED (reindex replaces, unlike upsert union)
+    // after the heal, reconcile is clean
+    expect(reconcileIndex({ env: process.env }).find(e => e.personality === 'boris')?.drift).toEqual([])
+  })
+})

package/src/identity/profileStandard.ts

@@ -0,0 +1,218 @@
+// Profile standard — the CODE-formalized schema of peer-profile.json, the source
+// of truth being the contract zone "Идентичность пира — модель, профиль, реестр".
+//
+// Two classes of fields (contract §"структура — два класса полей, не плоская каша"):
+//   • CORE identity (foundation-owned, validated here): personality (system mirror,
+//     self-heal = normalize(basename(cwd))), default_runtime (contract field; legacy
+//     `runtime` accepted during the staged migration), runtimes[] (incl. the default,
+//     ORDER = preference, first = primary), description, intelligence ∈
+//     {artificial|natural|absent}. Optional lifecycle: initial_prompt, wake_policy.
+//   • OWNER sections (validated only as well-typed, NEVER restructured here): interfaces
+//     (telegram/capability passport), aliases (legacy persistent-peer → contract
+//     relocates to interfaces.telegram.aliases, telegram-runtime owns the migration),
+//     notifier (notifier-runtime), <plugin> sections — each plugin writes only its own
+//     field via atomic merge.
+//
+// peers-profiles.json is a regenerable self-heal PROJECTION of the local profiles —
+// projectProfileToRecord builds the record the index SHOULD hold; verify compares the
+// live index against it, reindex rewrites it. The index is never the source of truth.
+
+import { basename } from 'path'
+import { isRuntime, normalizeIntelligenceValue, normalizeNameCandidate } from '../core/constants.ts'
+import {
+  clampDescription,
+  readPeersIndex,
+  updatePeersIndex,
+  type PeerRecord,
+  type PeersUpdateOptions,
+} from '../registry/index.ts'
+import { readPeerProfile } from './index.ts'
+
+export type IssueSeverity = 'error' | 'warn'
+export interface ProfileIssue {
+  severity: IssueSeverity
+  field: string
+  message: string
+}
+
+/**
+ * Validate a RAW peer-profile.json object (already JSON-parsed) against the standard.
+ * `cwd` is required for the personality self-heal check (the mirror must equal
+ * normalize(basename(cwd))). Returns every issue found; an `error` means the profile
+ * is non-conformant, a `warn` is a transition/owner note that self-heal or a later
+ * owner migration resolves (a profile with only warnings still PASSES — `isConformant`).
+ */
+export function validateProfileStandard(raw: unknown, cwd: string): ProfileIssue[] {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return [{ severity: 'error', field: '<root>', message: 'peer-profile.json must be a JSON object' }]
+  }
+  const obj = raw as Record<string, unknown>
+  const issues: ProfileIssue[] = []
+
+  // personality — system mirror, self-healed from the cwd (never a source). A stored
+  // value that disagrees is a WARN (self-heal rewrites it), not an error.
+  const expected = normalizeNameCandidate(basename(cwd))
+  if (typeof obj.personality !== 'string' || obj.personality !== expected) {
+    issues.push({
+      severity: 'warn',
+      field: 'personality',
+      message: `mirror "${String(obj.personality ?? '')}" ≠ normalize(basename(cwd)) "${expected}" — self-heal will rewrite`,
+    })
+  }
+
+  // default_runtime (contract) / runtime (legacy, staged migration).
+  const dr = obj.default_runtime ?? obj.runtime
+  if (!isRuntime(dr)) {
+    issues.push({ severity: 'error', field: 'default_runtime', message: `must be a valid runtime id, got "${String(dr ?? '')}"` })
+  } else if (obj.default_runtime === undefined) {
+    issues.push({ severity: 'warn', field: 'default_runtime', message: 'legacy field name `runtime` — standard is `default_runtime` (staged migration)' })
+  }
+
+  // runtimes[] — array of valid runtime ids that includes the default_runtime.
+  if (!Array.isArray(obj.runtimes)) {
+    issues.push({ severity: 'error', field: 'runtimes', message: 'must be an array of runtime ids' })
+  } else {
+    for (const r of obj.runtimes) {
+      if (!isRuntime(r)) issues.push({ severity: 'error', field: 'runtimes', message: `invalid runtime "${String(r)}"` })
+    }
+    if (isRuntime(dr) && !(obj.runtimes as unknown[]).includes(dr)) {
+      issues.push({ severity: 'error', field: 'runtimes', message: `must include the default_runtime "${dr}"` })
+    }
+  }
+
+  // description — string (may be empty).
+  if (obj.description !== undefined && typeof obj.description !== 'string') {
+    issues.push({ severity: 'error', field: 'description', message: 'must be a string' })
+  }
+
+  // intelligence — artificial|natural|absent (legacy human|scripted accepted on read).
+  if (obj.intelligence !== undefined && !normalizeIntelligenceValue(obj.intelligence)) {
+    issues.push({
+      severity: 'error',
+      field: 'intelligence',
+      message: `must be artificial|natural|absent (legacy human|scripted accepted), got "${String(obj.intelligence)}"`,
+    })
+  }
+
+  // Optional lifecycle fields (foundation-owned).
+  if (obj.initial_prompt !== undefined && typeof obj.initial_prompt !== 'string') {
+    issues.push({ severity: 'error', field: 'initial_prompt', message: 'must be a string' })
+  }
+  if (obj.wake_policy !== undefined && obj.wake_policy !== 'ephemeral') {
+    issues.push({ severity: 'warn', field: 'wake_policy', message: `unknown value "${String(obj.wake_policy)}" — only 'ephemeral' is honored` })
+  }
+
+  // Owner sections — well-typed only; foundation never restructures them.
+  if (obj.interfaces !== undefined && (typeof obj.interfaces !== 'object' || obj.interfaces === null || Array.isArray(obj.interfaces))) {
+    issues.push({ severity: 'error', field: 'interfaces', message: 'must be a JSON object' })
+  }
+  // Legacy top-level aliases — contract relocates to interfaces.telegram.aliases with
+  // the /alias-* namespace (clean slash-keys are reserved for the control layer).
+  // telegram-runtime owns that migration; flagged, not an error.
+  if (obj.aliases !== undefined) {
+    issues.push({
+      severity: 'warn',
+      field: 'aliases',
+      message: 'legacy top-level `aliases` — contract relocates to interfaces.telegram.aliases (/alias-* namespace); telegram-runtime migration pending',
+    })
+  }
+
+  return issues
+}
+
+/** A profile passes the standard when it has no `error`-severity issues. */
+export function isConformant(issues: readonly ProfileIssue[]): boolean {
+  return !issues.some(i => i.severity === 'error')
+}
+
+/**
+ * The PeerRecord the index SHOULD hold for the peer at `cwd`, projected from its LOCAL
+ * profile (the self-heal source of truth) — readPeerProfile already self-heals the
+ * personality mirror and dual-reads default_runtime/runtime. null when the cwd has no
+ * profile. Used by verify (compare against the live index) and reindex (rewrite it).
+ */
+export function projectProfileToRecord(cwd: string): PeerRecord | null {
+  const profile = readPeerProfile(cwd)
+  if (!profile) return null
+  return {
+    personality: profile.personality,
+    runtime: profile.runtime,
+    runtimes: profile.runtimes,
+    // The registry clamps the description to MAX_DESCRIPTION_LEN on read; project the
+    // SAME clamp so a long local description (timer/watcher run ~1000 chars) does not
+    // read back as a perpetual drift the index can never physically close.
+    description: clampDescription(profile.description).description,
+    intelligence: profile.intelligence,
+    cwd,
+    ...(profile.interfaces ? { interfaces: profile.interfaces } : {}),
+  }
+}
+
+/** The index↔local drift for one peer: the fields where the live registry record
+ *  disagrees with the projection from the local profile (the self-heal source). Empty
+ *  array = in sync. cwd is the registry pointer, never compared. */
+export function recordDrift(indexRecord: PeerRecord, projected: PeerRecord): string[] {
+  const drift: string[] = []
+  if (indexRecord.personality !== projected.personality) drift.push('personality')
+  if (indexRecord.runtime !== projected.runtime) drift.push('default_runtime')
+  if (indexRecord.runtimes.join(',') !== projected.runtimes.join(',')) drift.push('runtimes')
+  if (indexRecord.description !== projected.description) drift.push('description')
+  if (indexRecord.intelligence !== projected.intelligence) drift.push('intelligence')
+  return drift
+}
+
+export interface ReconcileEntry {
+  personality: string
+  cwd: string
+  /** null when the local profile is absent (the registry points at a gone cwd). */
+  drift: string[] | null
+}
+
+/** READ-ONLY index↔local reconciliation: per registry entry, the drift vs its local
+ *  profile projection (drift=null → local profile missing). The read-only half of the
+ *  self-heal invariant — verify reports it, reindex repairs it. */
+export function reconcileIndex(options: PeersUpdateOptions = {}): ReconcileEntry[] {
+  const index = readPeersIndex(options)
+  return index.peers.map(rec => {
+    const projected = projectProfileToRecord(rec.cwd)
+    return {
+      personality: rec.personality,
+      cwd: rec.cwd,
+      drift: projected ? recordDrift(rec, projected) : null,
+    }
+  })
+}
+
+/**
+ * Self-heal the index: REPLACE every registry record with the projection from its
+ * local profile (the source of truth). Unlike upsertPeer (which UNIONs runtimes so a
+ * boot never drops one), reindex is a deliberate REWRITE — it is how a local profile's
+ * narrowed runtimes (e.g. arthur dropped to [telegram]) propagate to the index. A peer
+ * whose local profile is missing is left untouched (and surfaced in `missing`). The
+ * legacy-safe intelligenceRaw is preserved when the nature is unchanged (never silently
+ * migrate the live vocab — the human→natural incident class).
+ */
+export async function reindexFromLocals(
+  options: PeersUpdateOptions = {},
+): Promise<{ healed: string[]; missing: string[] }> {
+  const healed: string[] = []
+  const missing: string[] = []
+  await updatePeersIndex(index => {
+    const peers = index.peers.map(rec => {
+      const projected = projectProfileToRecord(rec.cwd)
+      if (!projected) {
+        missing.push(rec.personality)
+        return rec
+      }
+      const drift = recordDrift(rec, projected)
+      if (drift.length > 0) healed.push(`${rec.personality}: ${drift.join(', ')}`)
+      const intelligenceRaw =
+        rec.intelligenceRaw !== undefined && normalizeIntelligenceValue(rec.intelligenceRaw) === projected.intelligence
+          ? rec.intelligenceRaw
+          : undefined
+      return { ...projected, ...(intelligenceRaw !== undefined ? { intelligenceRaw } : {}) }
+    })
+    return { ...index, peers }
+  }, options)
+  return { healed, missing }
+}

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/registry/index.ts

@@ -158,14 +158,17 @@ function normalizePeer(raw: unknown): PeerRecord {
       )}"`,
     )
   }
-  if (!isRuntime(obj.runtime)) {
+  // default_runtime is the contract field; `runtime` is legacy. Dual-read accepts
+  // both during the staged migration (write still emits `runtime` until Phase 2).
+  const defaultRuntime = obj.default_runtime ?? obj.runtime
+  if (!isRuntime(defaultRuntime)) {
     throw new IapError(
-      `peers-profiles.json corrupted: peer "${obj.personality}" runtime must match /^[a-z][a-z0-9]{0,31}$/`,
+      `peers-profiles.json corrupted: peer "${obj.personality}" default_runtime must match /^[a-z][a-z0-9]{0,31}$/`,
     )
   }
   const runtimes = Array.isArray(obj.runtimes)
-    ? ensureRuntimes(obj.runtimes.filter(item => typeof item === 'string') as string[], obj.runtime)
-    : [obj.runtime]
+    ? ensureRuntimes(obj.runtimes.filter(item => typeof item === 'string') as string[], defaultRuntime)
+    : [defaultRuntime]
   const { description } = clampDescription(typeof obj.description === 'string' ? obj.description : '')
   if (typeof obj.cwd !== 'string' || !obj.cwd.trim()) {
     throw new IapError(`peers-profiles.json corrupted: peer "${obj.personality}" cwd is required`)
@@ -177,7 +180,7 @@ function normalizePeer(raw: unknown): PeerRecord {
   let intelligence: Intelligence
   let intelligenceRaw: string | undefined
   if (obj.intelligence === undefined || obj.intelligence === null || obj.intelligence === '') {
-    intelligence = defaultIntelligenceForRuntime(obj.runtime)
+    intelligence = defaultIntelligenceForRuntime(defaultRuntime)
     // no raw on disk → a healed default will be persisted
   } else {
     const normalized = normalizeIntelligenceValue(obj.intelligence)
@@ -192,7 +195,7 @@ function normalizePeer(raw: unknown): PeerRecord {
   const interfaces = normalizeInterfaces(obj.interfaces, obj.personality)
   return {
     personality: obj.personality,
-    runtime: obj.runtime,
+    runtime: defaultRuntime,
     runtimes,
     description,
     intelligence,