@agfpd/iapeer 0.2.32 → 0.2.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.32",
+  "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/canary.ts

@@ -117,7 +117,7 @@ export function canaryScript(o: CanaryScriptOptions): string {
     `{`,
     `  echo "server-death identity=${o.identity} ts=$ts server_pid=$SPID wait_rc=$rc cause=$cause"`,
     `  echo '--- vm_stat'; vm_stat`,
-    `  echo '--- swapusage'; sysctl -n vm.swapusage`,
+    `  echo '--- swapusage'; /usr/sbin/sysctl -n vm.swapusage`,
     `  echo '--- ps-top-rss'; ps axo pid,ppid,rss,etime,command | sort -rn -k3 | head -25`,
     `  echo '--- diagnosticreports-user'; ls -t "$HOME/Library/Logs/DiagnosticReports" 2>/dev/null | head`,
     `  echo '--- diagnosticreports-system'; ls -t /Library/Logs/DiagnosticReports 2>/dev/null | head`,