zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/coms-v2/policy.ts

@@ -0,0 +1,125 @@
+import { join } from "node:path";
+
+import type { ZobComsTranscriptMode, ZobComsTranscriptRetentionClass, ZobComsTransportMode, ZobComsV2Policy } from "./types.js";
+import { sha256 } from "../utils/hashing.js";
+import { readJsonObjectIfPresent } from "../utils/json.js";
+import { isRecord } from "../utils/records.js";
+
+const TRANSPORT_POLICY_RELATIVE_PATH = ".pi/mission-control/zob_coms_transport.json";
+const MODES = new Set<ZobComsTransportMode>(["off", "observe_only", "required_local", "required_network", "break_glass_ledger_only"]);
+const TRANSCRIPT_MODES = new Set<ZobComsTranscriptMode>(["off", "redacted_report", "encrypted_vault", "raw_opt_in"]);
+const RETENTION_CLASSES = new Set<ZobComsTranscriptRetentionClass>(["ephemeral", "session", "short", "project", "manual_delete"]);
+
+function numberFromRecord(record: Record<string, unknown>, key: string, fallback: number): number {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+
+function bool(value: unknown, fallback = false): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function modeFromRaw(raw: Record<string, unknown>): ZobComsTransportMode {
+  const envMode = process.env.ZOB_COMS_MODE;
+  if (envMode && MODES.has(envMode as ZobComsTransportMode)) return envMode as ZobComsTransportMode;
+  if (typeof raw.mode === "string" && MODES.has(raw.mode as ZobComsTransportMode)) return raw.mode as ZobComsTransportMode;
+  if (raw.networkEnabled === true || raw.globalActivation === true) return "required_network";
+  if (raw.enabled === true || raw.localDispatchEnabled === true || raw.dispatchAllowed === true) return "required_local";
+  return "observe_only";
+}
+
+function transcriptModeFromRaw(raw: Record<string, unknown>, transcriptCapture: Record<string, unknown>): ZobComsTranscriptMode {
+  const envMode = process.env.ZOB_COMS_TRANSCRIPT_MODE ?? process.env.ZOB_COMS_CAPTURE_MODE;
+  if (envMode && TRANSCRIPT_MODES.has(envMode as ZobComsTranscriptMode)) return envMode as ZobComsTranscriptMode;
+  if (process.env.ZOB_COMS_SAVE_TRANSCRIPTS === "1") return "redacted_report";
+  if (typeof transcriptCapture.mode === "string" && TRANSCRIPT_MODES.has(transcriptCapture.mode as ZobComsTranscriptMode)) return transcriptCapture.mode as ZobComsTranscriptMode;
+  if (typeof raw.transcriptMode === "string" && TRANSCRIPT_MODES.has(raw.transcriptMode as ZobComsTranscriptMode)) return raw.transcriptMode as ZobComsTranscriptMode;
+  return "off";
+}
+
+function retentionClassFromRaw(transcriptCapture: Record<string, unknown>): ZobComsTranscriptRetentionClass {
+  const envRetention = process.env.ZOB_COMS_TRANSCRIPT_RETENTION;
+  if (envRetention && RETENTION_CLASSES.has(envRetention as ZobComsTranscriptRetentionClass)) return envRetention as ZobComsTranscriptRetentionClass;
+  if (typeof transcriptCapture.retentionClass === "string" && RETENTION_CLASSES.has(transcriptCapture.retentionClass as ZobComsTranscriptRetentionClass)) return transcriptCapture.retentionClass as ZobComsTranscriptRetentionClass;
+  return "short";
+}
+
+export function readZobComsV2Policy(repoRoot: string): ZobComsV2Policy {
+  const raw = readJsonObjectIfPresent(join(repoRoot, TRANSPORT_POLICY_RELATIVE_PATH)) ?? {};
+  const heartbeat = isRecord(raw.heartbeat) ? raw.heartbeat : {};
+  const responseCapture = isRecord(raw.responseCapture) ? raw.responseCapture : {};
+  const network = isRecord(raw.network) ? raw.network : {};
+  const legacy = isRecord(raw.legacy) ? raw.legacy : {};
+  const transcriptCapture = isRecord(raw.transcriptCapture) ? raw.transcriptCapture : {};
+  const envMode = process.env.ZOB_COMS_MODE;
+  const envModeOverride = Boolean(envMode && MODES.has(envMode as ZobComsTransportMode));
+  const mode = modeFromRaw(raw);
+  const transcriptMode = transcriptModeFromRaw(raw, transcriptCapture);
+  const transcriptEnvEnabled = typeof process.env.ZOB_COMS_TRANSCRIPT_MODE === "string" || typeof process.env.ZOB_COMS_CAPTURE_MODE === "string" || process.env.ZOB_COMS_SAVE_TRANSCRIPTS === "1";
+  const localDispatchEnabled = envModeOverride ? mode === "required_local" : bool(raw.localDispatchEnabled) || mode === "required_local";
+  const networkEnabled = envModeOverride ? mode === "required_network" : bool(raw.networkEnabled) || mode === "required_network";
+  const dispatchAllowed = envModeOverride ? mode === "required_local" || mode === "required_network" : bool(raw.dispatchAllowed) || mode === "required_local" || mode === "required_network";
+  return {
+    schema: raw.schema === "zob.coms-transport-policy.v2" ? "zob.coms-transport-policy.v2" : "zob.coms-transport-policy.v1",
+    name: "zob_coms_transport",
+    enabled: envModeOverride ? dispatchAllowed : bool(raw.enabled) || dispatchAllowed,
+    mode,
+    localDispatchEnabled,
+    networkEnabled,
+    dispatchAllowed,
+    globalActivation: bool(raw.globalActivation),
+    canonicalLedger: ".pi/coms/messages.jsonl",
+    statusLedger: ".pi/coms/status.jsonl",
+    bodyPolicy: "hash_only",
+    persistBodies: false,
+    transientBodyTransport: mode === "required_local" || mode === "required_network",
+    topologyGuardRequired: true,
+    workerToWorkerFreeChat: false,
+    agenticWorkflowsRequireLive: true,
+    breakGlassApprovalRequired: true,
+    heartbeat: {
+      enabled: mode !== "off",
+      intervalMs: numberFromRecord(heartbeat, "intervalMs", 10_000),
+      staleAfterMs: numberFromRecord(heartbeat, "staleAfterMs", 30_000),
+      offlineAfterMs: numberFromRecord(heartbeat, "offlineAfterMs", 60_000),
+      stalePeerCountsAsCompletion: false,
+    },
+    responseCapture: {
+      enabled: bool(responseCapture.enabled, mode === "required_local" || mode === "required_network"),
+      storeBodies: false,
+      storeOutputHashOnly: true,
+      artifactRefsAllowed: true,
+    },
+    network: {
+      enabled: networkEnabled,
+      requiresBearerToken: true,
+      loopbackDefaultOnly: true,
+      tlsRequiredOutsideTrustedLan: bool(network.tlsRequiredOutsideTrustedLan, true),
+      logToken: false,
+    },
+    legacy: {
+      appendOnlySendEnabled: bool(legacy.appendOnlySendEnabled, false),
+      breakGlassLedgerOnlyRequiresApproval: true,
+    },
+    transcriptCapture: {
+      enabled: transcriptMode !== "off" && (transcriptEnvEnabled || bool(transcriptCapture.enabled, false)),
+      mode: transcriptMode,
+      artifactRoot: typeof process.env.ZOB_COMS_TRANSCRIPT_ARTIFACT_ROOT === "string" ? process.env.ZOB_COMS_TRANSCRIPT_ARTIFACT_ROOT : typeof transcriptCapture.artifactRoot === "string" ? transcriptCapture.artifactRoot : "reports/coms-captures",
+      artifactRefsOnlyInLedger: true,
+      persistBodiesInComsLedger: false,
+      redactionRequired: true,
+      encryptionRequiredForVault: true,
+      rawOptInRequired: true,
+      retentionClass: retentionClassFromRaw(transcriptCapture),
+      maxArtifactBytes: numberFromRecord(transcriptCapture, "maxArtifactBytes", 32_768),
+      redactionProfile: typeof transcriptCapture.redactionProfile === "string" ? transcriptCapture.redactionProfile : "zob-default-v1",
+    },
+    sourcePolicyHash: sha256(JSON.stringify(raw)),
+  };
+}
+
+export function zobComsRegistryEnabled(policy: ZobComsV2Policy): boolean {
+  return policy.mode !== "off";
+}
+
+export { TRANSPORT_POLICY_RELATIVE_PATH };

package/.pi/extensions/zob-harness/src/coms-v2/presence.ts

@@ -0,0 +1,55 @@
+import { sha256 } from "../utils/hashing.js";
+import { readZobLiveRegistrySnapshot } from "./registry.js";
+import { readZobComsV2Policy } from "./policy.js";
+import type { ZobLivePeerCard, ZobLivePresenceSummary } from "./types.js";
+import { activeZpeerRoomId, zpeerMembershipsForPeer } from "./zpeer.js";
+
+export function buildZobLivePresenceSummary(repoRoot: string, teamName?: string): ZobLivePresenceSummary {
+  const policy = readZobComsV2Policy(repoRoot);
+  const snapshot = readZobLiveRegistrySnapshot(repoRoot, teamName);
+  return {
+    schema: "zob.live-presence-summary.v1",
+    available: policy.mode !== "off",
+    mode: policy.mode,
+    registry: snapshot.registry,
+    team: teamName,
+    peerCount: snapshot.peers.length,
+    online: snapshot.counts.online,
+    stale: snapshot.counts.stale,
+    offline: snapshot.counts.offline,
+    stalePeerCountsAsCompletion: false,
+    dispatchEnabled: policy.dispatchAllowed,
+    networkEnabled: policy.networkEnabled,
+    bodyStored: false,
+  };
+}
+
+export function redactZobLivePeerForMissionControl(peer: ZobLivePeerCard): Record<string, unknown> {
+  const memberships = zpeerMembershipsForPeer(peer);
+  return {
+    team: peer.team,
+    roleId: peer.roleId,
+    roleType: peer.roleType,
+    leadId: peer.leadId,
+    agent: peer.agent,
+    sessionHash: peer.sessionHash,
+    transport: peer.transport,
+    endpointHash: peer.endpointHash,
+    cwdHash: peer.cwdHash,
+    startedAt: peer.startedAt,
+    heartbeatAt: peer.heartbeatAt,
+    contextUsedPct: peer.contextUsedPct,
+    queueDepth: peer.queueDepth,
+    status: peer.status,
+    zpeerRoomIdHash: peer.zpeerRoomId ? sha256(peer.zpeerRoomId) : undefined,
+    zpeerAliasHash: peer.zpeerAlias ? sha256(peer.zpeerAlias) : undefined,
+    zpeerActiveRoomIdHash: sha256(activeZpeerRoomId(peer)),
+    zpeerMembershipCount: memberships.length,
+    zpeerMembershipRoomHashes: memberships.map((membership) => sha256(membership.roomId)),
+    zpeerMembershipAliasHashes: memberships.map((membership) => sha256(membership.alias)),
+    zpeerLocalOnly: peer.zpeerLocalOnly === true ? true : undefined,
+    staleAfterMs: peer.staleAfterMs,
+    offlineAfterMs: peer.offlineAfterMs,
+    bodyStored: false,
+  };
+}

package/.pi/extensions/zob-harness/src/coms-v2/registry.ts

@@ -0,0 +1,113 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { loadTeamDefinition, validateTeamDefinition } from "../topology/teams.js";
+import { isRecord } from "../utils/records.js";
+import { safeFileStem } from "../utils/paths.js";
+import { buildCurrentZobLivePeerCard, buildZobComsProjectId } from "./identity.js";
+import { readZobComsV2Policy, zobComsRegistryEnabled } from "./policy.js";
+import type { ZobLivePeerCard, ZobLivePeerStatus, ZobLiveRegistrySnapshot } from "./types.js";
+
+const FORBIDDEN_PERSISTED_KEYS = new Set(["body", "task", "prompt", "output", "content", "message", "rationale", "text", "diff", "patch"]);
+
+function registryRoot(): { path: string; kind: "user_runtime" | "env_override" } {
+  const override = process.env.ZOB_COMS_REGISTRY_ROOT;
+  if (override && override.trim().length > 0) return { path: override, kind: "env_override" };
+  return { path: join(homedir(), ".pi", "zob-coms"), kind: "user_runtime" };
+}
+
+function hasForbiddenPersistedKey(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasForbiddenPersistedKey);
+  return Object.entries(value).some(([key, child]) => FORBIDDEN_PERSISTED_KEYS.has(key) || hasForbiddenPersistedKey(child));
+}
+
+function projectAgentsDir(repoRoot: string): { dir: string; projectId: string; kind: "user_runtime" | "env_override" } {
+  const root = registryRoot();
+  const projectId = buildZobComsProjectId(repoRoot);
+  return { dir: join(root.path, "projects", projectId, "agents"), projectId, kind: root.kind };
+}
+
+function peerPath(repoRoot: string, peer: Pick<ZobLivePeerCard, "roleId" | "sessionHash">): string {
+  const { dir } = projectAgentsDir(repoRoot);
+  return join(dir, `${safeFileStem(`${peer.roleId}-${peer.sessionHash.slice(0, 12)}`)}.json`);
+}
+
+function parsePeerCard(value: unknown): ZobLivePeerCard | undefined {
+  if (!isRecord(value) || value.schema !== "zob.live-peer-card.v1") return undefined;
+  if (hasForbiddenPersistedKey(value) || value.bodyStored !== false) return undefined;
+  if (typeof value.roleId !== "string" || typeof value.team !== "string" || typeof value.sessionHash !== "string") return undefined;
+  return value as unknown as ZobLivePeerCard;
+}
+
+function derivePeerStatus(peer: ZobLivePeerCard, nowMs: number): ZobLivePeerStatus {
+  if (peer.status === "offline") return "offline";
+  const heartbeatMs = Date.parse(peer.heartbeatAt);
+  if (!Number.isFinite(heartbeatMs)) return "stale";
+  if (nowMs - heartbeatMs >= peer.offlineAfterMs) return "offline";
+  if (nowMs - heartbeatMs >= peer.staleAfterMs) return "stale";
+  return "online";
+}
+
+export function writeZobLivePeerCard(repoRoot: string, peer: ZobLivePeerCard): ZobLivePeerCard {
+  if (hasForbiddenPersistedKey(peer)) throw new Error("Refusing to persist ZOB live peer card with forbidden body-like keys");
+  if (peer.bodyStored !== false) throw new Error("ZOB live peer card bodyStored must be false");
+  const { dir } = projectAgentsDir(repoRoot);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(peerPath(repoRoot, peer), `${JSON.stringify(peer, null, 2)}\n`, "utf8");
+  return peer;
+}
+
+export function registerCurrentZobLivePeer(repoRoot: string, teamName = "zob-core"): ZobLivePeerCard | undefined {
+  const policy = readZobComsV2Policy(repoRoot);
+  if (!zobComsRegistryEnabled(policy)) return undefined;
+  const team = loadTeamDefinition(repoRoot, teamName);
+  const errors = [...team.errors, ...validateTeamDefinition(repoRoot, team.definition)];
+  if (errors.length > 0 || !team.definition) throw new Error(`Cannot register ZOB live peer: ${errors.join("; ")}`);
+  return writeZobLivePeerCard(repoRoot, buildCurrentZobLivePeerCard(repoRoot, team.definition, policy));
+}
+
+export function touchCurrentZobLivePeer(repoRoot: string, teamName = "zob-core"): ZobLivePeerCard | undefined {
+  const peer = registerCurrentZobLivePeer(repoRoot, teamName);
+  return peer ? writeZobLivePeerCard(repoRoot, { ...peer, heartbeatAt: new Date().toISOString(), status: "online" }) : undefined;
+}
+
+export function unregisterCurrentZobLivePeer(repoRoot: string, teamName = "zob-core"): ZobLivePeerCard | undefined {
+  const policy = readZobComsV2Policy(repoRoot);
+  const team = loadTeamDefinition(repoRoot, teamName);
+  if (!team.definition || !zobComsRegistryEnabled(policy)) return undefined;
+  const peer = buildCurrentZobLivePeerCard(repoRoot, team.definition, policy);
+  return writeZobLivePeerCard(repoRoot, { ...peer, heartbeatAt: new Date().toISOString(), status: "offline" });
+}
+
+export function readZobLiveRegistrySnapshot(repoRoot: string, teamName?: string): ZobLiveRegistrySnapshot {
+  const { dir, projectId, kind } = projectAgentsDir(repoRoot);
+  const nowMs = Date.now();
+  const peers = existsSync(dir)
+    ? readdirSync(dir)
+      .filter((entry) => entry.endsWith(".json"))
+      .map((entry) => {
+        try {
+          return parsePeerCard(JSON.parse(readFileSync(join(dir, entry), "utf8")) as unknown);
+        } catch {
+          return undefined;
+        }
+      })
+      .filter((peer): peer is ZobLivePeerCard => Boolean(peer))
+      .filter((peer) => !teamName || peer.team === teamName)
+      .map((peer) => ({ ...peer, status: derivePeerStatus(peer, nowMs) }))
+    : [];
+  const counts: Record<ZobLivePeerStatus, number> = { online: 0, stale: 0, offline: 0 };
+  for (const peer of peers) counts[peer.status] += 1;
+  return {
+    schema: "zob.live-registry-snapshot.v1",
+    projectId,
+    registry: kind,
+    team: teamName,
+    generatedAt: new Date().toISOString(),
+    peers,
+    counts,
+    bodyStored: false,
+  };
+}

package/.pi/extensions/zob-harness/src/coms-v2/response-capture.ts

@@ -0,0 +1,50 @@
+import { sha256 } from "../utils/hashing.js";
+import { buildZobLiveEnvelope, type ZobLiveEnvelope } from "./envelope.js";
+
+export interface ZobLiveResponseCapture {
+  schema: "zob.live-response-capture.v1";
+  msgId: string;
+  outputHash: string;
+  artifactRefs: string[];
+  artifactHashes: string[];
+  responseBytes: number;
+  bodyStored: false;
+}
+
+function safeArtifactRefs(refs: string[] | undefined): string[] {
+  return (refs ?? []).filter((ref) => ref.length > 0 && !ref.startsWith("/") && !ref.includes("..") && !ref.includes("\\") && !ref.includes(".env"));
+}
+
+function safeArtifactHashes(hashes: string[] | undefined): string[] {
+  return (hashes ?? []).filter((hash) => /^[a-f0-9]{64}$/i.test(hash));
+}
+
+export function buildZobLiveResponseCapture(msgId: string, transientResponse: string, artifactRefs?: string[], artifactHashes?: string[]): ZobLiveResponseCapture {
+  return {
+    schema: "zob.live-response-capture.v1",
+    msgId,
+    outputHash: sha256(transientResponse),
+    artifactRefs: safeArtifactRefs(artifactRefs),
+    artifactHashes: safeArtifactHashes(artifactHashes),
+    responseBytes: Buffer.byteLength(transientResponse, "utf8"),
+    bodyStored: false,
+  };
+}
+
+export function buildZobLiveResponseEnvelope(request: ZobLiveEnvelope, transientResponse: string, artifactRefs?: string[], artifactHashes?: string[]): ZobLiveEnvelope {
+  const capture = buildZobLiveResponseCapture(request.msgId, transientResponse, artifactRefs, artifactHashes);
+  return buildZobLiveEnvelope({
+    type: "response",
+    msgId: request.msgId,
+    runId: request.runId,
+    sender: request.receiver,
+    receiver: request.sender,
+    team: request.team,
+    hops: request.hops,
+    taskHash: request.taskHash,
+    outputHash: capture.outputHash,
+    artifactRefs: capture.artifactRefs,
+    artifactHashes: capture.artifactHashes,
+    transientResponse,
+  });
+}

package/.pi/extensions/zob-harness/src/coms-v2/transcript-capture.ts

@@ -0,0 +1,164 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ZobComsTranscriptCapturePolicy } from "./types.js";
+import { sha256 } from "../utils/hashing.js";
+import { safeFileStem } from "../utils/paths.js";
+
+export type ZobComsRedactedCaptureKind = "live_prompt" | "live_response" | "live_exchange";
+
+export interface ZobComsRedactedCaptureInput {
+  runId?: string;
+  msgId: string;
+  sender?: string;
+  receiver?: string;
+  team?: string;
+  kind: ZobComsRedactedCaptureKind;
+  taskHash?: string;
+  outputHash?: string;
+  transientPrompt?: string;
+  transientResponse?: string;
+  artifactRefs?: string[];
+}
+
+export interface ZobComsRedactedCaptureRef {
+  schema: "zob.coms-redacted-capture-ref.v1";
+  mode: "redacted_report";
+  artifactRef: string;
+  artifactHash: string;
+  redactionProfileHash: string;
+  retentionClass: ZobComsTranscriptCapturePolicy["retentionClass"];
+  expiresAt?: string;
+  bodyStored: false;
+}
+
+const DEFAULT_ARTIFACT_ROOT = "reports/coms-captures";
+const DEFAULT_REDACTION_PROFILE = "zob-default-v1";
+const SECRET_PATTERNS: Array<{ name: string; pattern: RegExp }> = [
+  { name: "private_key", pattern: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g },
+  { name: "bearer_token", pattern: /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi },
+  { name: "api_key", pattern: /\b(?:sk|ghp|github_pat|xox[baprs])-[-A-Za-z0-9_]{10,}\b/g },
+  { name: "aws_access_key", pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+  { name: "secret_assignment", pattern: /\b[A-Z][A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|API_KEY)[A-Z0-9_]*\s*=\s*[^\s]+/gi },
+  { name: "email", pattern: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi },
+];
+
+function normalizeArtifactRoot(root: string | undefined): string {
+  const candidate = (root ?? DEFAULT_ARTIFACT_ROOT).trim().replace(/^\.\//, "").replace(/\/+$/g, "");
+  if (!candidate || candidate.startsWith("/") || candidate.includes("..") || candidate.includes("\\") || candidate.includes(".env") || candidate.includes("/node_modules") || candidate.includes("/dist") || candidate.includes("/build")) return DEFAULT_ARTIFACT_ROOT;
+  if (candidate !== DEFAULT_ARTIFACT_ROOT && !candidate.startsWith(`${DEFAULT_ARTIFACT_ROOT}/`)) return DEFAULT_ARTIFACT_ROOT;
+  return candidate;
+}
+
+function truncateUtf8(value: string, maxBytes: number): { value: string; truncated: boolean } {
+  const limit = Math.max(256, Math.min(256 * 1024, Math.floor(maxBytes)));
+  let bytes = 0;
+  let output = "";
+  for (const char of value) {
+    const charBytes = Buffer.byteLength(char, "utf8");
+    if (bytes + charBytes > limit) return { value: `${output}\n[...truncated...]`, truncated: true };
+    output += char;
+    bytes += charBytes;
+  }
+  return { value: output, truncated: false };
+}
+
+function retentionExpiresAt(retentionClass: ZobComsTranscriptCapturePolicy["retentionClass"]): string | undefined {
+  const now = Date.now();
+  if (retentionClass === "ephemeral") return new Date(now + 24 * 60 * 60 * 1000).toISOString();
+  if (retentionClass === "short") return new Date(now + 7 * 24 * 60 * 60 * 1000).toISOString();
+  if (retentionClass === "session") return new Date(now + 30 * 24 * 60 * 60 * 1000).toISOString();
+  return undefined;
+}
+
+export function redactZobComsText(input: string, maxBytes = 32_768): { redacted: string; originalBytes: number; savedBytes: number; truncated: boolean; redactionCounts: Record<string, number> } {
+  let redacted = input;
+  const redactionCounts: Record<string, number> = {};
+  for (const item of SECRET_PATTERNS) {
+    let count = 0;
+    redacted = redacted.replace(item.pattern, () => {
+      count += 1;
+      return `[REDACTED:${item.name}]`;
+    });
+    if (count > 0) redactionCounts[item.name] = count;
+  }
+  const truncated = truncateUtf8(redacted, maxBytes);
+  return {
+    redacted: truncated.value,
+    originalBytes: Buffer.byteLength(input, "utf8"),
+    savedBytes: Buffer.byteLength(truncated.value, "utf8"),
+    truncated: truncated.truncated,
+    redactionCounts,
+  };
+}
+
+export function writeZobComsRedactedCapture(repoRoot: string, policy: ZobComsTranscriptCapturePolicy, input: ZobComsRedactedCaptureInput): ZobComsRedactedCaptureRef | undefined {
+  if (!policy.enabled || policy.mode !== "redacted_report") return undefined;
+  const root = normalizeArtifactRoot(policy.artifactRoot);
+  const runStem = safeFileStem(input.runId ?? "unknown-run");
+  const msgStem = safeFileStem(input.msgId);
+  const kindStem = safeFileStem(input.kind);
+  const artifactRef = `${root}/${runStem}/${msgStem}.${kindStem}.redacted.json`;
+  const artifactDir = join(repoRoot, root, runStem);
+  const artifactPath = join(artifactDir, `${msgStem}.${kindStem}.redacted.json`);
+  const maxPerField = Math.max(256, Math.floor(policy.maxArtifactBytes / 2));
+  const request = typeof input.transientPrompt === "string" ? redactZobComsText(input.transientPrompt, maxPerField) : undefined;
+  const answer = typeof input.transientResponse === "string" ? redactZobComsText(input.transientResponse, maxPerField) : undefined;
+  const expiresAt = retentionExpiresAt(policy.retentionClass);
+  const artifact = {
+    schema: "zob.coms-redacted-capture.v1",
+    runId: input.runId ?? "unknown-run",
+    msgId: input.msgId,
+    kind: input.kind,
+    sender: input.sender,
+    receiver: input.receiver,
+    team: input.team,
+    taskHash: input.taskHash,
+    outputHash: input.outputHash,
+    mode: "redacted_report",
+    redactionProfile: policy.redactionProfile,
+    redactionProfileHash: sha256(policy.redactionProfile),
+    retentionClass: policy.retentionClass,
+    expiresAt,
+    sourceBytes: {
+      request: request?.originalBytes ?? 0,
+      answer: answer?.originalBytes ?? 0,
+    },
+    savedBytes: {
+      request: request?.savedBytes ?? 0,
+      answer: answer?.savedBytes ?? 0,
+    },
+    truncated: {
+      request: request?.truncated ?? false,
+      answer: answer?.truncated ?? false,
+    },
+    redactionCounts: {
+      request: request?.redactionCounts ?? {},
+      answer: answer?.redactionCounts ?? {},
+    },
+    redacted: {
+      request: request?.redacted,
+      answer: answer?.redacted,
+    },
+    priorArtifactRefs: input.artifactRefs ?? [],
+    rawBodiesStored: false,
+    redactedBodiesStored: true,
+    comsLedgerBodyStored: false,
+    bodyStored: false,
+    createdAt: new Date().toISOString(),
+  };
+  const serialized = `${JSON.stringify(artifact, null, 2)}\n`;
+  const artifactHash = sha256(serialized);
+  mkdirSync(artifactDir, { recursive: true });
+  writeFileSync(artifactPath, serialized, "utf8");
+  return {
+    schema: "zob.coms-redacted-capture-ref.v1",
+    mode: "redacted_report",
+    artifactRef,
+    artifactHash,
+    redactionProfileHash: sha256(policy.redactionProfile || DEFAULT_REDACTION_PROFILE),
+    retentionClass: policy.retentionClass,
+    expiresAt,
+    bodyStored: false,
+  };
+}

package/.pi/extensions/zob-harness/src/coms-v2/types.ts

@@ -0,0 +1,149 @@
+export type ZobComsTransportMode = "off" | "observe_only" | "required_local" | "required_network" | "break_glass_ledger_only";
+export type ZobComsTranscriptMode = "off" | "redacted_report" | "encrypted_vault" | "raw_opt_in";
+export type ZobComsTranscriptRetentionClass = "ephemeral" | "session" | "short" | "project" | "manual_delete";
+export type ZobLiveTransportKind = "observe_only" | "local_socket" | "named_pipe" | "sse";
+export type ZobLivePeerStatus = "online" | "stale" | "offline";
+export type ZobLiveRoleType = "orchestrator" | "lead" | "worker";
+export type ZpeerRoomMembershipRole = "member" | "bridge" | "observer";
+
+export interface ZpeerRoomMembership {
+  roomId: string;
+  alias: string;
+  role: ZpeerRoomMembershipRole;
+  joinedAt: string;
+  localOnly: true;
+  networkEnabled: false;
+  bodyStored: false;
+}
+
+export interface ZobComsHeartbeatPolicy {
+  enabled: boolean;
+  intervalMs: number;
+  staleAfterMs: number;
+  offlineAfterMs: number;
+  stalePeerCountsAsCompletion: false;
+}
+
+export interface ZobComsResponseCapturePolicy {
+  enabled: boolean;
+  storeBodies: false;
+  storeOutputHashOnly: true;
+  artifactRefsAllowed: boolean;
+}
+
+export interface ZobComsNetworkPolicy {
+  enabled: boolean;
+  requiresBearerToken: true;
+  loopbackDefaultOnly: true;
+  tlsRequiredOutsideTrustedLan: boolean;
+  logToken: false;
+}
+
+export interface ZobComsLegacyPolicy {
+  appendOnlySendEnabled: boolean;
+  breakGlassLedgerOnlyRequiresApproval: true;
+}
+
+export interface ZobComsTranscriptCapturePolicy {
+  enabled: boolean;
+  mode: ZobComsTranscriptMode;
+  artifactRoot: string;
+  artifactRefsOnlyInLedger: true;
+  persistBodiesInComsLedger: false;
+  redactionRequired: true;
+  encryptionRequiredForVault: true;
+  rawOptInRequired: true;
+  retentionClass: ZobComsTranscriptRetentionClass;
+  maxArtifactBytes: number;
+  redactionProfile: string;
+}
+
+export interface ZobComsV2Policy {
+  schema: "zob.coms-transport-policy.v1" | "zob.coms-transport-policy.v2";
+  name: "zob_coms_transport";
+  enabled: boolean;
+  mode: ZobComsTransportMode;
+  localDispatchEnabled: boolean;
+  networkEnabled: boolean;
+  dispatchAllowed: boolean;
+  globalActivation: boolean;
+  canonicalLedger: ".pi/coms/messages.jsonl";
+  statusLedger: ".pi/coms/status.jsonl";
+  bodyPolicy: "hash_only";
+  persistBodies: false;
+  transientBodyTransport: boolean;
+  topologyGuardRequired: true;
+  workerToWorkerFreeChat: false;
+  agenticWorkflowsRequireLive: true;
+  breakGlassApprovalRequired: true;
+  heartbeat: ZobComsHeartbeatPolicy;
+  responseCapture: ZobComsResponseCapturePolicy;
+  network: ZobComsNetworkPolicy;
+  legacy: ZobComsLegacyPolicy;
+  transcriptCapture: ZobComsTranscriptCapturePolicy;
+  sourcePolicyHash?: string;
+}
+
+export interface ZobLivePeerCard {
+  schema: "zob.live-peer-card.v1";
+  projectId: string;
+  team: string;
+  roleId: string;
+  roleType: ZobLiveRoleType;
+  leadId?: string;
+  agent: string;
+  sessionId: string;
+  sessionHash: string;
+  transport: ZobLiveTransportKind;
+  endpoint: string;
+  endpointHash: string;
+  cwdHash: string;
+  pid?: number;
+  startedAt: string;
+  heartbeatAt: string;
+  contextUsedPct: number;
+  queueDepth: number;
+  status: ZobLivePeerStatus;
+  zpeerRoomId?: string;
+  zpeerAlias?: string;
+  zpeerActiveRoomId?: string;
+  zpeerMemberships?: ZpeerRoomMembership[];
+  zpeerLocalOnly?: true;
+  staleAfterMs: number;
+  offlineAfterMs: number;
+  bodyStored: false;
+}
+
+export interface ZobLiveRegistrySnapshot {
+  schema: "zob.live-registry-snapshot.v1";
+  projectId: string;
+  registry: "user_runtime" | "env_override";
+  team?: string;
+  generatedAt: string;
+  peers: ZobLivePeerCard[];
+  counts: Record<ZobLivePeerStatus, number>;
+  bodyStored: false;
+}
+
+export interface ZobComsCaptureRef {
+  artifactRef: string;
+  artifactHash: string;
+  mode: ZobComsTranscriptMode;
+  bodyStored: false;
+}
+
+export interface ZobLivePresenceSummary {
+  schema: "zob.live-presence-summary.v1";
+  available: boolean;
+  mode: ZobComsTransportMode;
+  registry: "user_runtime" | "env_override";
+  team?: string;
+  peerCount: number;
+  online: number;
+  stale: number;
+  offline: number;
+  stalePeerCountsAsCompletion: false;
+  dispatchEnabled: boolean;
+  networkEnabled: boolean;
+  bodyStored: false;
+}