@cryptolibertus/pi-peer 0.3.2

package/src/peers/message-store.mjs

@@ -0,0 +1,114 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, resolve as resolvePath } from "node:path";
+
+import { redactPeerAuditValue } from "./protocol.mjs";
+
+export const PEER_MESSAGE_STORE_RELATIVE_PATH = ".pi/peer-messages.json";
+
+export function createPeerMessageStore(root, options = {}) {
+  const path = options.path || messageStorePath(root);
+  const homeDir = options.homeDir || process.env.HOME || "";
+  let pendingSave = Promise.resolve();
+  return {
+    path,
+    async load() {
+      try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return normalizePeerMessageStore(parsed);
+      } catch (error) {
+        if (error?.code === "ENOENT") return normalizePeerMessageStore({});
+        throw error;
+      }
+    },
+    async save(state = {}) {
+      pendingSave = pendingSave.catch(() => {}).then(async () => {
+        const normalized = normalizePeerMessageStore(redactPeerAuditValue(state, { homeDir }));
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.${process.hrtime.bigint().toString(36)}.tmp`;
+        try {
+          await writeFile(tmp, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+          await rename(tmp, path);
+        } catch (error) {
+          await unlink(tmp).catch(() => {});
+          throw error;
+        }
+        return normalized;
+      });
+      return pendingSave;
+    },
+    async flush() {
+      return pendingSave.catch(() => undefined);
+    },
+  };
+}
+
+export function normalizePeerMessageStore(state = {}) {
+  const messages = Array.isArray(state.messages) ? state.messages : Object.values(state.messages || {});
+  const conversations = Array.isArray(state.conversations) ? state.conversations : Object.values(state.conversations || {});
+  return {
+    version: 1,
+    updatedAt: typeof state.updatedAt === "string" && state.updatedAt ? state.updatedAt : new Date().toISOString(),
+    messages: messages.filter(isPlainObject).map(normalizeMessageSnapshot).filter(Boolean),
+    conversations: conversations.filter(isPlainObject).map(normalizeConversationSnapshot).filter(Boolean),
+  };
+}
+
+function normalizeMessageSnapshot(message) {
+  const messageId = cleanText(message.messageId);
+  const conversationId = cleanText(message.conversationId);
+  if (!messageId || !conversationId) return undefined;
+  return stripEmpty({
+    messageId,
+    conversationId,
+    peerId: cleanText(message.peerId),
+    status: cleanText(message.status || "unknown"),
+    request: isPlainObject(message.request) ? message.request : undefined,
+    response: isPlainObject(message.response) ? message.response : null,
+    responseEnvelope: isPlainObject(message.responseEnvelope) ? message.responseEnvelope : null,
+    events: Array.isArray(message.events) ? message.events.filter(isPlainObject).slice(-50) : [],
+    error: isPlainObject(message.error) ? message.error : null,
+    createdAt: cleanText(message.createdAt),
+    updatedAt: cleanText(message.updatedAt || message.createdAt),
+    lastEvent: isPlainObject(message.lastEvent) ? message.lastEvent : undefined,
+    lastHeartbeatAt: cleanText(message.lastHeartbeatAt),
+    recoveredAt: cleanText(message.recoveredAt),
+  });
+}
+
+function normalizeConversationSnapshot(conversation) {
+  const conversationId = cleanText(conversation.conversationId);
+  if (!conversationId) return undefined;
+  return stripEmpty({
+    conversationId,
+    peerIds: normalizeStringList(conversation.peerIds),
+    messageIds: normalizeStringList(conversation.messageIds),
+    status: cleanText(conversation.status || "unknown"),
+    createdAt: cleanText(conversation.createdAt),
+    updatedAt: cleanText(conversation.updatedAt || conversation.createdAt),
+  });
+}
+
+function messageStorePath(root) {
+  if (!root) throw new Error("peer message store requires root");
+  return resolvePath(root, PEER_MESSAGE_STORE_RELATIVE_PATH);
+}
+
+function normalizeStringList(value) {
+  return Array.isArray(value) ? [...new Set(value.map(cleanText).filter(Boolean))] : [];
+}
+
+function cleanText(value) {
+  return typeof value === "string" ? value.trim() : value == null ? "" : String(value).trim();
+}
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function stripEmpty(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => {
+    if (value === undefined || value === "") return false;
+    if (Array.isArray(value) && value.length === 0) return false;
+    return true;
+  }));
+}

package/src/peers/protocol.mjs

@@ -0,0 +1,256 @@
+const PEER_PROTOCOL = "pi-peer";
+const PEER_VERSION = 1;
+const PEER_MIN_COMPATIBLE_VERSION = 1;
+const PEER_MAX_COMPATIBLE_VERSION = 1;
+const PEER_AUTH_TYPE_SHARED_TOKEN = "shared-token";
+
+export { PEER_PROTOCOL, PEER_VERSION, PEER_MIN_COMPATIBLE_VERSION, PEER_MAX_COMPATIBLE_VERSION, PEER_AUTH_TYPE_SHARED_TOKEN };
+
+export function peerProtocolMetadata() {
+  return {
+    protocol: PEER_PROTOCOL,
+    protocolVersion: PEER_VERSION,
+    minProtocolVersion: PEER_MIN_COMPATIBLE_VERSION,
+    maxProtocolVersion: PEER_MAX_COMPATIBLE_VERSION,
+  };
+}
+
+export function isPeerProtocolCompatible(source = {}) {
+  const protocol = nonEmptyString(source.protocol) ? source.protocol : PEER_PROTOCOL;
+  const version = Number.isInteger(source.protocolVersion) ? source.protocolVersion : Number.isInteger(source.version) ? source.version : PEER_VERSION;
+  const min = Number.isInteger(source.minProtocolVersion) ? source.minProtocolVersion : version;
+  const max = Number.isInteger(source.maxProtocolVersion) ? source.maxProtocolVersion : version;
+  return protocol === PEER_PROTOCOL && min <= PEER_VERSION && max >= PEER_MIN_COMPATIBLE_VERSION;
+}
+
+export const PEER_MESSAGE_TYPES = Object.freeze([
+  "hello",
+  "registry.query",
+  "registry.update",
+  "message.send",
+  "message.accepted",
+  "message.event",
+  "message.response",
+  "message.cancel",
+  "message.error",
+  "approval.request",
+  "approval.response",
+  "heartbeat",
+  "goodbye",
+]);
+
+const PEER_MESSAGE_TYPE_SET = new Set(PEER_MESSAGE_TYPES);
+
+export function validatePeerEnvelope(envelope) {
+  const errors = [];
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+    return { ok: false, errors: ["envelope must be an object"] };
+  }
+
+  if (envelope.protocol !== PEER_PROTOCOL) errors.push(`protocol must be ${PEER_PROTOCOL}`);
+  if (envelope.version !== PEER_VERSION) errors.push(`version must be ${PEER_VERSION}`);
+  if (!PEER_MESSAGE_TYPE_SET.has(envelope.type)) errors.push(`type must be one of ${PEER_MESSAGE_TYPES.join(", ")}`);
+  if (!nonEmptyString(envelope.id)) errors.push("id must be a non-empty string");
+  if (!nonEmptyString(envelope.conversationId)) errors.push("conversationId must be a non-empty string");
+  errors.push(...validatePeerAddress(envelope.source, "source"));
+  errors.push(...validatePeerAddress(envelope.target, "target"));
+  if (!nonEmptyString(envelope.timestamp) || Number.isNaN(Date.parse(envelope.timestamp))) errors.push("timestamp must be an ISO-like string");
+  if (envelope.correlationId !== undefined && !nonEmptyString(envelope.correlationId)) errors.push("correlationId must be a non-empty string when present");
+  if (envelope.causationId !== undefined && !nonEmptyString(envelope.causationId)) errors.push("causationId must be a non-empty string when present");
+  if (!Number.isInteger(envelope.hopCount) || envelope.hopCount < 0) errors.push("hopCount must be a non-negative integer");
+  if (!Number.isInteger(envelope.maxHopCount) || envelope.maxHopCount < 0) errors.push("maxHopCount must be a non-negative integer");
+  if (Number.isInteger(envelope.hopCount) && Number.isInteger(envelope.maxHopCount) && envelope.hopCount > envelope.maxHopCount) {
+    errors.push("hopCount must not exceed maxHopCount");
+  }
+  errors.push(...validatePeerAuth(envelope.auth));
+  if (!("body" in envelope)) errors.push("body is required");
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function assertValidPeerEnvelope(envelope) {
+  const validation = validatePeerEnvelope(envelope);
+  if (!validation.ok) {
+    const error = new Error(`Invalid Pi peer envelope: ${validation.errors.join("; ")}`);
+    error.code = "PI_PEER_INVALID_ENVELOPE";
+    error.errors = validation.errors;
+    throw error;
+  }
+  return envelope;
+}
+
+export function createPeerEnvelope({
+  type,
+  id = createPeerId(type && type.startsWith("message.") ? "msg" : "evt"),
+  conversationId = createPeerId("conv"),
+  source,
+  target,
+  timestamp = new Date().toISOString(),
+  correlationId,
+  causationId,
+  hopCount = 0,
+  maxHopCount = 1,
+  auth,
+  audit,
+  body = {},
+}) {
+  const envelope = {
+    protocol: PEER_PROTOCOL,
+    version: PEER_VERSION,
+    type,
+    id,
+    conversationId,
+    source,
+    target,
+    timestamp,
+    hopCount,
+    maxHopCount,
+    body,
+  };
+  if (auth !== undefined) envelope.auth = auth;
+  if (correlationId !== undefined) envelope.correlationId = correlationId;
+  if (causationId !== undefined) envelope.causationId = causationId;
+  if (audit !== undefined) envelope.audit = audit;
+  return assertValidPeerEnvelope(envelope);
+}
+
+export function resolvePeerAuthToken(source = {}, options = {}) {
+  const env = options.env || process.env || {};
+  if (nonEmptyString(source.authToken)) return source.authToken;
+  if (nonEmptyString(source.authTokenEnv)) {
+    const token = env[source.authTokenEnv];
+    return nonEmptyString(token) ? token : undefined;
+  }
+  return undefined;
+}
+
+export function createPeerEnvelopeAuth(source = {}, options = {}) {
+  const token = resolvePeerAuthToken(source, options);
+  return token ? { type: PEER_AUTH_TYPE_SHARED_TOKEN, token } : undefined;
+}
+
+export function attachPeerEnvelopeAuth(envelope, source = {}, options = {}) {
+  const auth = createPeerEnvelopeAuth(source, options);
+  return auth ? assertValidPeerEnvelope({ ...envelope, auth }) : envelope;
+}
+
+export function normalizePeerAddress(address, fallback = {}) {
+  const merged = { ...fallback, ...(address && typeof address === "object" ? address : {}) };
+  if (!nonEmptyString(merged.peerId)) throw new Error("peer address requires peerId");
+  return {
+    peerId: merged.peerId,
+    ...(nonEmptyString(merged.sessionId) ? { sessionId: merged.sessionId } : {}),
+    ...(nonEmptyString(merged.sessionFile) ? { sessionFile: merged.sessionFile } : {}),
+    ...(nonEmptyString(merged.cwd) ? { cwd: merged.cwd } : {}),
+    ...(nonEmptyString(merged.role) ? { role: merged.role } : {}),
+    ...(nonEmptyString(merged.transport) ? { transport: merged.transport } : {}),
+  };
+}
+
+export function normalizePeerMessageSendBody(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw new Error("peer message body must be an object");
+  if (!nonEmptyString(body.prompt)) throw new Error("peer message prompt must be a non-empty string");
+  return {
+    ...body,
+    prompt: body.prompt,
+    intent: body.intent || "ask",
+    contextRefs: Array.isArray(body.contextRefs) ? body.contextRefs : [],
+    delivery: {
+      intoReceiverTurn: true,
+      responseMode: "final-assistant-message",
+      ...(body.delivery && typeof body.delivery === "object" ? body.delivery : {}),
+    },
+  };
+}
+
+export function normalizePeerMessageResponseBody(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return { status: "ERROR", summary: "Peer transport returned an invalid response body" };
+  }
+  const status = ["OK", "OK_WITH_NOTES", "NEEDS_CONTEXT", "BLOCKED", "CANCELLED", "ERROR"].includes(body.status) ? body.status : "OK";
+  return { ...body, status };
+}
+
+export function redactPeerAuditValue(value, options = {}) {
+  const homeDir = typeof options.homeDir === "string" && options.homeDir ? options.homeDir.replace(/\/+$/, "") : "";
+  return redactValue(value, homeDir, "");
+}
+
+function validatePeerAddress(address, label) {
+  const errors = [];
+  if (!address || typeof address !== "object" || Array.isArray(address)) return [`${label} must be an object`];
+  if (!nonEmptyString(address.peerId)) errors.push(`${label}.peerId must be a non-empty string`);
+  for (const field of ["sessionId", "sessionFile", "cwd", "role", "transport"]) {
+    if (address[field] !== undefined && !nonEmptyString(address[field])) errors.push(`${label}.${field} must be a non-empty string when present`);
+  }
+  return errors;
+}
+
+function validatePeerAuth(auth) {
+  if (auth === undefined) return [];
+  const errors = [];
+  if (!auth || typeof auth !== "object" || Array.isArray(auth)) return ["auth must be an object when present"];
+  if (auth.type !== PEER_AUTH_TYPE_SHARED_TOKEN) errors.push(`auth.type must be ${PEER_AUTH_TYPE_SHARED_TOKEN}`);
+  if (!nonEmptyString(auth.token)) errors.push("auth.token must be a non-empty string");
+  return errors;
+}
+
+function redactValue(value, homeDir, key) {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") return redactString(value, homeDir);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, homeDir, key));
+  if (typeof value !== "object") return String(value);
+
+  const out = {};
+  for (const [childKey, childValue] of Object.entries(value)) {
+    if (isSensitiveEnvKey(childKey) || isEnvKey(childKey)) {
+      out[childKey] = "[REDACTED_ENV]";
+    } else if (isSensitiveKey(childKey)) {
+      out[childKey] = "[REDACTED]";
+    } else {
+      out[childKey] = redactValue(childValue, homeDir, childKey);
+    }
+  }
+  return out;
+}
+
+function redactString(input, homeDir) {
+  let text = input;
+  if (homeDir) text = text.split(homeDir).join("~");
+  return text
+    .replace(/ghp_[A-Za-z0-9_]{20,}/g, "[REDACTED_TOKEN]")
+    .replace(/github_pat_[A-Za-z0-9_]+/g, "[REDACTED_TOKEN]")
+    .replace(/sk-[A-Za-z0-9][A-Za-z0-9_-]{9,}/g, "[REDACTED_TOKEN]")
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED_TOKEN]")
+    .replace(/(token|secret|password|api[_-]?key)=([^\s&]+)/gi, "$1=[REDACTED]");
+}
+
+function isSensitiveKey(key) {
+  const normalized = String(key || "").toLowerCase().replace(/[-_]/g, "");
+  return normalized.includes("token")
+    || normalized.includes("secret")
+    || normalized.includes("password")
+    || normalized.includes("credential")
+    || normalized.includes("authorization")
+    || normalized.includes("apikey")
+    || normalized === "auth"
+    || normalized.endsWith("auth");
+}
+
+function isEnvKey(key) {
+  return /^env(ironment)?$/i.test(key);
+}
+
+function isSensitiveEnvKey(key) {
+  const normalized = String(key || "").toLowerCase().replace(/[-_]/g, "");
+  return normalized.endsWith("tokenenv") || normalized.endsWith("secretenv") || normalized.endsWith("credentialenv");
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function createPeerId(prefix) {
+  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`;
+}

package/src/peers/role-collaboration-demo.mjs

@@ -0,0 +1,71 @@
+const REQUIRED_ROLES = ['planner', 'worker', 'reviewer'];
+
+function normalizeRoles(roles) {
+  if (Array.isArray(roles)) {
+    return roles.map((entry) => {
+      if (typeof entry === 'string') return entry.trim();
+      if (entry && typeof entry === 'object' && typeof entry.role === 'string') {
+        return entry.role.trim();
+      }
+      return '';
+    });
+  }
+
+  if (roles && typeof roles === 'object') {
+    return Object.entries(roles).map(([role, value]) => {
+      if (typeof value === 'string' && value.trim() === '') return '';
+      return role.trim();
+    });
+  }
+
+  return [];
+}
+
+function validateRequiredRoles(roles) {
+  const normalizedRoles = normalizeRoles(roles);
+
+  if (normalizedRoles.some((role) => role === '')) {
+    throw new Error('Missing required peer role: roles must include non-blank planner, worker, and reviewer entries.');
+  }
+
+  const roleSet = new Set(normalizedRoles);
+  const missingRoles = REQUIRED_ROLES.filter((role) => !roleSet.has(role));
+  if (missingRoles.length > 0) {
+    throw new Error(`Missing required peer role: ${missingRoles.join(', ')}.`);
+  }
+
+  const unexpectedRoles = normalizedRoles.filter((role) => !REQUIRED_ROLES.includes(role));
+  if (unexpectedRoles.length > 0) {
+    throw new Error(`Unexpected peer role: ${unexpectedRoles.join(', ')}. Required roles are planner, worker, and reviewer.`);
+  }
+}
+
+export function buildRoleCollaborationTranscript({ goal, roles } = {}) {
+  const normalizedGoal = typeof goal === 'string' ? goal.trim() : '';
+  if (normalizedGoal === '') {
+    throw new Error('A non-blank collaboration goal is required.');
+  }
+
+  validateRequiredRoles(roles);
+
+  return [
+    {
+      role: 'planner',
+      summary: `Planner defines the goal: ${normalizedGoal}`,
+      goal: normalizedGoal,
+      action: 'scope',
+    },
+    {
+      role: 'worker',
+      summary: `Worker implements the goal: ${normalizedGoal}`,
+      goal: normalizedGoal,
+      action: 'implement',
+    },
+    {
+      role: 'reviewer',
+      summary: `Reviewer verifies the goal: ${normalizedGoal}`,
+      goal: normalizedGoal,
+      action: 'review',
+    },
+  ];
+}

package/src/peers/runtime.mjs

@@ -0,0 +1,200 @@
+import { randomUUID } from "node:crypto";
+
+import { InMemoryPeerTransport, MemoryPeerRegistry, createPeerComms } from "./comms.mjs";
+import { applyLocalPeerIdOverride, loadLocalPeerProfile, loadPeerRuntimeConfig, summarizePeerRuntimeConfig } from "./config.mjs";
+import { deriveGoalState, loadPeerGoalBoard } from "./goal-board.mjs";
+import { createInboundPromptBridge } from "./inbound-bridge.mjs";
+import { LocalPeerTransport, createLocalPeerEndpoint, discoverLocalPeerEndpoints } from "./local-transport.mjs";
+import { createPeerMessageStore } from "./message-store.mjs";
+import { redactPeerAuditValue } from "./protocol.mjs";
+import { collectPeerRuntimeStatus, deriveFanoutSuggestion } from "./status.mjs";
+
+export const PI_PEER_RUNTIME_ENTRY_TYPE = "pi-peer-runtime";
+export const PI_PEER_AUDIT_ENTRY_TYPE = "pi-peer-audit";
+
+export async function createPeerRuntime(cwd, options = {}) {
+  const loadedConfig = options.config || await loadPeerRuntimeConfig(cwd, options);
+  let config = applyLocalPeerIdOverride(loadedConfig, { localPeerId: options.localPeerId, env: options.env || process.env });
+  const persistence = createPiPeerPersistence(options.pi, { homeDir: options.homeDir });
+  const messageStore = options.messageStore || (config.enabled ? createPeerMessageStore(cwd, { homeDir: options.homeDir }) : undefined);
+  const persistedMessages = messageStore ? await messageStore.load().catch(() => undefined) : undefined;
+  const configuredPeers = config.enabled ? config.peers : [];
+  const configuredPeerById = new Map(configuredPeers.map((peer) => [peer.peerId, peer]));
+  const registry = new MemoryPeerRegistry(configuredPeers);
+  const localPeerId = config.localPeerId || `pi-${process.pid}-${randomUUID().slice(0, 8)}`;
+  if (!config.localPeerId) config = { ...config, localPeerId, localPeerIdSource: "generated" };
+  const localPeerProfileResult = await loadLocalPeerProfile(cwd, config, { ...options, localPeerId });
+  const localPeerProfile = localPeerProfileResult.profile;
+  config = { ...config, localPeerProfile, warnings: uniqueStrings([...(config.warnings || []), ...localPeerProfileResult.warnings]) };
+  const memoryTransport = options.memoryTransport || new InMemoryPeerTransport(options.transportOptions || {});
+  const transport = options.transport || new LocalPeerTransport({
+    discoveryDir: options.discoveryDir,
+    env: options.env,
+    fallback: memoryTransport,
+    timeoutMs: options.transportTimeoutMs,
+  });
+  const inboundBridge = options.inboundBridge || (options.pi && typeof options.pi.sendMessage === "function"
+    ? createInboundPromptBridge({ pi: options.pi, cwd, responseTimeoutMs: options.responseTimeoutMs, responderProfile: localPeerProfile, homeDir: options.homeDir })
+    : undefined);
+  const comms = createPeerComms({
+    registry,
+    transport,
+    localPeerId,
+    localAddress: options.localAddress || {},
+    homeDir: options.homeDir || process.env.HOME || "",
+    auditSink(entry) {
+      persistence.appendAudit(entry);
+    },
+    messageStore,
+    persistedState: persistedMessages,
+  });
+  let localEndpoint;
+  let discoveredPeerIds = new Set();
+
+  const runtime = {
+    enabled: config.enabled,
+    source: config.source,
+    config,
+    comms,
+    summary: { ...summarizePeerRuntimeConfig(config), localPeerId },
+    localPeerId,
+    cwd,
+    get localEndpoint() {
+      return localEndpoint?.descriptor;
+    },
+    async refreshLocalPeers() {
+      if (!config.enabled) return [];
+      const peers = await discoverLocalPeerEndpoints({ discoveryDir: options.discoveryDir, excludePeerId: localPeerId });
+      const nextDiscoveredPeerIds = new Set(peers.map((peer) => peer.peerId));
+      for (const peerId of discoveredPeerIds) {
+        if (nextDiscoveredPeerIds.has(peerId)) continue;
+        if (configuredPeerById.has(peerId)) await registry.registerPeer(configuredPeerById.get(peerId));
+        else await registry.unregisterPeer(peerId);
+      }
+      for (const peer of peers) await registry.registerPeer(mergeDiscoveredPeerWithConfiguredAuth(peer, configuredPeerById.get(peer.peerId)));
+      discoveredPeerIds = nextDiscoveredPeerIds;
+      return peers;
+    },
+    async start(ctx = {}) {
+      if (!config.enabled) return runtime;
+      const handler = options.inboundResponder || (inboundBridge ? (envelope, _descriptor, context) => inboundBridge.handleEnvelope(envelope, context) : undefined);
+      if (!localEndpoint && handler) {
+        const endpoint = createLocalPeerEndpoint({
+          peerId: localPeerId,
+          cwd,
+          sessionId: options.sessionId || ctx.sessionId,
+          role: localPeerProfile.role || options.role,
+          persona: localPeerProfile.persona || options.persona,
+          trust: options.trust || config.manifest?.trust || "conversation",
+          maxHopCount: options.maxHopCount,
+          capabilities: options.capabilities || config.manifest?.capabilities,
+          protocolVersion: config.manifest?.protocolVersion,
+          minProtocolVersion: config.manifest?.minProtocolVersion,
+          maxProtocolVersion: config.manifest?.maxProtocolVersion,
+          discoveryDir: options.discoveryDir,
+          authToken: options.authToken,
+          authTokenEnv: options.authTokenEnv,
+          activeHeartbeatIntervalMs: options.activeHeartbeatIntervalMs,
+          presenceHeartbeatIntervalMs: options.presenceHeartbeatIntervalMs,
+          handler,
+        });
+        await endpoint.start();
+        localEndpoint = endpoint;
+      }
+      await runtime.refreshLocalPeers();
+      persistence.appendRuntime({ kind: "runtime.started", at: new Date().toISOString(), localPeerId, endpoint: runtime.localEndpoint });
+      return runtime;
+    },
+    handleAgentEnd(event, ctx) {
+      return inboundBridge ? inboundBridge.handleAgentEnd(event, ctx) : false;
+    },
+    recordInboundProgress(progress) {
+      return inboundBridge ? inboundBridge.recordProgress(progress) : { ok: false, reason: "no active inbound peer task" };
+    },
+    async shutdown() {
+      if (inboundBridge) {
+        inboundBridge.dispose("Peer runtime shutting down");
+        await localEndpoint?.drain?.();
+      }
+      if (localEndpoint) {
+        await localEndpoint.stop();
+        localEndpoint = undefined;
+      }
+      persistence.appendRuntime({ kind: "runtime.stopped", at: new Date().toISOString(), localPeerId });
+    },
+    async dispose() {
+      await runtime.shutdown();
+      await comms.dispose();
+    },
+  };
+  persistence.appendRuntime({ kind: "runtime.loaded", at: new Date().toISOString(), ...runtime.summary });
+  return runtime;
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.trim()))];
+}
+
+function mergeDiscoveredPeerWithConfiguredAuth(peer, configuredPeer) {
+  if (!configuredPeer) return peer;
+  return {
+    ...configuredPeer,
+    ...peer,
+    ...(configuredPeer.authToken !== undefined ? { authToken: configuredPeer.authToken } : {}),
+    ...(configuredPeer.authTokenEnv !== undefined ? { authTokenEnv: configuredPeer.authTokenEnv } : {}),
+  };
+}
+
+export function createPiPeerPersistence(pi, options = {}) {
+  const canAppend = Boolean(pi && typeof pi.appendEntry === "function");
+  const append = (customType, data) => {
+    if (!canAppend) return false;
+    const redacted = redactPeerAuditValue(data, { homeDir: options.homeDir || process.env.HOME || "" });
+    try {
+      const result = pi.appendEntry(customType, redacted);
+      if (result && typeof result.catch === "function") result.catch(() => {});
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  return {
+    supported: canAppend,
+    appendRuntime(data) {
+      return append(PI_PEER_RUNTIME_ENTRY_TYPE, data);
+    },
+    appendAudit(entry) {
+      return append(PI_PEER_AUDIT_ENTRY_TYPE, entry);
+    },
+  };
+}
+
+export async function getPeerRuntimeValue(runtime, id) {
+  if (id === "runtime") return { type: "runtime", value: await collectPeerRuntimeStatus(runtime) };
+  if (id === "goals") return { type: "goals", value: await loadPeerGoalBoard(runtime.cwd) };
+  if (id === "goal" || String(id || "").startsWith("goal_")) {
+    const board = await loadPeerGoalBoard(runtime.cwd);
+    const goalId = id === "goal" ? board.currentGoalId : id;
+    const goal = goalId ? board.goals[goalId] : undefined;
+    return goal ? { type: "goal", value: deriveGoalState(goal) } : { type: "missing", value: undefined };
+  }
+  if (id === "tasks") return { type: "tasks", value: { active: await runtime.comms.listTasks({ active: true }), all: await runtime.comms.listTasks(), note: "Active tasks are queued/running peer messages; disconnected tasks were restored from the local message store and are not awaitable." } };
+  if (id === "fanout") {
+    const peers = await runtime.comms.listPeers();
+    const messages = await runtime.comms.listMessages();
+    const suggestion = deriveFanoutSuggestion(peers, messages);
+    return { type: "fanout", value: { ...suggestion, checklist: ["Run peer_list before multi-lane work", "Create or reuse /peer goal", "Use /peer goal fanout or peer_send goalId+claimedPaths", "Final response must include Fan-out used: yes/no and peer handles"] } };
+  }
+  if (id === "audit") return { type: "audit", value: await runtime.comms.getAuditEntries() };
+
+  const message = await runtime.comms.getMessage(id);
+  if (message) return { type: "message", value: message };
+
+  const conversation = await runtime.comms.getConversation(id);
+  if (conversation) return { type: "conversation", value: conversation };
+
+  const peer = await runtime.comms.getPeer(id);
+  if (peer) return { type: "peer", value: peer };
+
+  return { type: "missing", value: undefined };
+}