zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/compute-workflow-shape.ts

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync } from "node:fs";
+import { sha256 } from "./utils/hashing.js";
+import { resolveRepoPath } from "./utils/paths.js";
+import { isRecord } from "./utils/records.js";
+import { resolveComputeProfile, type ComputeDomain, type ComputeEffectiveProfile, type ComputePreviewInput, type ComputeRequestedProfile } from "./compute-profile.js";
+
+export interface ComputeWorkflowShapeInput extends ComputePreviewInput {
+  resolutionPath?: string;
+}
+
+const PROFILE_LANES: Record<ComputeEffectiveProfile, Array<{ id: string; agent: string; maxWorkers: number; tools: string[]; outputContract: string; validation: string }>> = {
+  low: [
+    { id: "deterministic_preview", agent: "agent", maxWorkers: 1, tools: ["read", "grep", "find", "ls"], outputContract: "metadata.v1", validation: "narrow" },
+  ],
+  medium: [
+    { id: "deterministic_preview", agent: "agent", maxWorkers: 1, tools: ["read", "grep", "find", "ls"], outputContract: "metadata.v1", validation: "targeted" },
+    { id: "targeted_validation", agent: "qa", maxWorkers: 1, tools: ["read", "grep", "find", "ls", "bash"], outputContract: "oracle.v1", validation: "smoke" },
+  ],
+  high: [
+    { id: "architecture", agent: "explore", maxWorkers: 2, tools: ["read", "grep", "find", "ls"], outputContract: "explore.v1", validation: "cited" },
+    { id: "implementation", agent: "implementer", maxWorkers: 2, tools: ["read", "grep", "find", "ls"], outputContract: "implement.v1", validation: "full_local" },
+    { id: "validation", agent: "oracle", maxWorkers: 1, tools: ["read", "grep", "find", "ls", "bash"], outputContract: "oracle.v1", validation: "required" },
+  ],
+  xhigh: [
+    { id: "architecture", agent: "explore", maxWorkers: 3, tools: ["read", "grep", "find", "ls"], outputContract: "explore.v1", validation: "cited" },
+    { id: "safety", agent: "oracle", maxWorkers: 2, tools: ["read", "grep", "find", "ls"], outputContract: "oracle.v1", validation: "adversarial" },
+    { id: "implementation", agent: "implementer", maxWorkers: 4, tools: ["read", "grep", "find", "ls"], outputContract: "implement.v1", validation: "full_plus_adversarial" },
+    { id: "benchmark", agent: "qa", maxWorkers: 2, tools: ["read", "grep", "find", "ls", "bash"], outputContract: "qa.v1", validation: "suite" },
+  ],
+  max: [
+    { id: "architecture", agent: "explore", maxWorkers: 4, tools: ["read", "grep", "find", "ls"], outputContract: "explore.v1", validation: "cited" },
+    { id: "safety", agent: "oracle", maxWorkers: 4, tools: ["read", "grep", "find", "ls"], outputContract: "oracle.v1", validation: "multi_oracle" },
+    { id: "implementation", agent: "implementer", maxWorkers: 8, tools: ["read", "grep", "find", "ls"], outputContract: "implement.v1", validation: "exhaustive_within_scope" },
+    { id: "benchmark", agent: "qa", maxWorkers: 4, tools: ["read", "grep", "find", "ls", "bash"], outputContract: "qa.v1", validation: "suite_plus_regression" },
+    { id: "human_approval_packet", agent: "planner", maxWorkers: 1, tools: ["read", "grep", "find", "ls"], outputContract: "plan.v1", validation: "human_required" },
+  ],
+};
+
+function readResolution(repoRoot: string, repoPath: string | undefined): Record<string, unknown> | undefined {
+  if (!repoPath) return undefined;
+  const resolved = resolveRepoPath(repoRoot, repoPath);
+  if (resolved.errors.length > 0 || !existsSync(resolved.path)) return undefined;
+  const parsed = JSON.parse(readFileSync(resolved.path, "utf8")) as unknown;
+  return isRecord(parsed) ? parsed : undefined;
+}
+
+function numberFrom(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export function buildComputeWorkflowShape(repoRoot: string, input: ComputeWorkflowShapeInput = {}): Record<string, unknown> {
+  const resolution = readResolution(repoRoot, input.resolutionPath) ?? resolveComputeProfile(repoRoot, input);
+  const effectiveProfile = resolution.effectiveProfile as ComputeEffectiveProfile;
+  const caps = isRecord(resolution.caps) ? resolution.caps : {};
+  const maxParallel = numberFrom(caps.maxParallel, 1);
+  const maxDepth = numberFrom(caps.maxDelegationDepth, 0);
+  const maxAgents = numberFrom(caps.maxAgents, 1);
+  const lanes = (PROFILE_LANES[effectiveProfile] ?? PROFILE_LANES.low).map((lane) => ({
+    ...lane,
+    maxWorkers: Math.min(lane.maxWorkers, maxAgents, maxParallel),
+    parentOwnedDispatch: true,
+    childDirectDispatch: false,
+  }));
+  const highScale = effectiveProfile === "max" || maxAgents > 20;
+  const scalePolicy = {
+    schema: "zob.adaptive-scale-policy.v1",
+    requestedScale: highScale ? "large" : "default",
+    maxTotalAgents: maxAgents,
+    maxParallelAgents: maxParallel,
+    maxAgentsPerWave: Math.max(1, Math.min(maxParallel, maxAgents)),
+    maxWaves: Math.max(1, Math.ceil(maxAgents / Math.max(1, Math.min(maxParallel, maxAgents)))),
+    requiresBudget: caps.strictBudgetRequired === true,
+    requiresScaleApproval: highScale,
+    requiresOracleAfterWave: highScale || caps.oracleRequired === true,
+    duplicateDetectionRequired: true,
+    stalePeerBlocksCompletion: true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const modelPolicy = {
+    schema: "zob.adaptive-model-policy.v1",
+    downgradePolicy: "blocked_for_oracle_security",
+    laneAssignments: lanes.map((lane) => ({ laneId: lane.id, agent: lane.agent, outputContract: lane.outputContract, modelClass: lane.agent === "oracle" ? "strong_oracle" : lane.agent === "planner" || lane.id === "architecture" ? "strong_reasoning" : lane.agent === "agent" || lane.agent === "explore" ? "cheap_scout" : "balanced_worker", reasonHash: sha256(JSON.stringify({ laneId: lane.id, agent: lane.agent, outputContract: lane.outputContract })) })),
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const promptPolicy = {
+    schema: "zob.adaptive-prompt-policy-hint.v1",
+    rootCanWriteDirectly: false,
+    rootDirectWriteToolsBlocked: ["bash", "edit", "write"],
+    promptStackHashRequired: true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const documentationPolicy = {
+    schema: "zob.adaptive-documentation-policy-hint.v1",
+    required: true,
+    rootDocs: ["AGENTS.md", "README.md"],
+    layerDocsRequired: true,
+    roleDocPacksRequired: true,
+    writebackPolicy: "human_approval_required",
+    maxDocsPerAgent: 12,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  return {
+    schema: "zob.compute-workflow-shape.v1",
+    runId: input.runId,
+    domain: (resolution.domain as ComputeDomain | undefined) ?? input.domain ?? "generic",
+    requestedProfile: (resolution.requestedProfile as ComputeRequestedProfile | undefined) ?? input.requestedProfile ?? "auto",
+    effectiveProfile,
+    resolutionHash: sha256(JSON.stringify(resolution)),
+    resolutionEmbedded: false,
+    caps: { maxAgents, maxDelegationDepth: maxDepth, maxParallel, maxIterations: caps.maxIterations, maxDurationMs: caps.maxDurationMs, maxContextTokens: caps.maxContextTokens },
+    lanes,
+    promptPolicy,
+    modelPolicy,
+    scalePolicy,
+    documentationPolicy,
+    validationLevel: caps.validationLevel,
+    oraclePolicy: caps.oraclePolicy,
+    benchmarkLevel: caps.benchmarkLevel,
+    adaptiveDelegationPolicyHint: resolution.adaptiveDelegationPolicyHint,
+    parentOwnedDispatch: true,
+    childDirectDispatch: false,
+    liveDispatchEnabled: false,
+    noExecution: true,
+    networkAccessed: false,
+    sourceProjectModified: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    noShip: resolution.noShip === true,
+    blockers: Array.isArray(resolution.blockers) ? resolution.blockers : [],
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+export function validateComputeWorkflowShape(shape: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(shape)) return ["workflow shape must be a JSON object"];
+  if (shape.schema !== "zob.compute-workflow-shape.v1") errors.push("workflow shape schema must be zob.compute-workflow-shape.v1");
+  if (shape.parentOwnedDispatch !== true) errors.push("workflow shape parentOwnedDispatch must be true");
+  if (shape.childDirectDispatch !== false) errors.push("workflow shape childDirectDispatch must be false");
+  if (shape.liveDispatchEnabled !== false) errors.push("workflow shape liveDispatchEnabled must be false");
+  if (shape.noExecution !== true) errors.push("workflow shape noExecution must be true");
+  if (!Array.isArray(shape.lanes) || shape.lanes.length < 1) errors.push("workflow shape requires at least one lane");
+  if (!isRecord(shape.promptPolicy) || shape.promptPolicy.rootCanWriteDirectly !== false) errors.push("workflow shape promptPolicy must keep rootCanWriteDirectly=false");
+  if (!isRecord(shape.modelPolicy) || shape.modelPolicy.downgradePolicy !== "blocked_for_oracle_security") errors.push("workflow shape modelPolicy must block oracle/security downgrade");
+  if (!isRecord(shape.scalePolicy) || shape.scalePolicy.stalePeerBlocksCompletion !== true || shape.scalePolicy.duplicateDetectionRequired !== true) errors.push("workflow shape scalePolicy must require stale and duplicate safeguards");
+  if (!isRecord(shape.documentationPolicy) || shape.documentationPolicy.roleDocPacksRequired !== true || shape.documentationPolicy.writebackPolicy !== "human_approval_required") errors.push("workflow shape documentationPolicy must require role doc packs and human-approved writeback");
+  if (Array.isArray(shape.lanes)) {
+    for (const [index, lane] of shape.lanes.entries()) {
+      if (!isRecord(lane)) {
+        errors.push(`lane ${index} must be an object`);
+        continue;
+      }
+      if (lane.parentOwnedDispatch !== true) errors.push(`lane ${index} parentOwnedDispatch must be true`);
+      if (lane.childDirectDispatch !== false) errors.push(`lane ${index} childDirectDispatch must be false`);
+      if (!Array.isArray(lane.tools)) errors.push(`lane ${index} tools must be an array`);
+    }
+  }
+  return errors;
+}

package/.pi/extensions/zob-harness/src/coms-v2/AGENTS.md

@@ -0,0 +1,16 @@
+# ZOB Coms v2 module instructions
+
+Scope: observe-only/live communication runtime primitives for ZOB.
+
+MUST DO:
+- Preserve hash-only ledger semantics.
+- Keep persisted records metadata-only and body-free.
+- Keep transport dispatch disabled unless an explicit later phase enables it.
+- Prefer additive compatibility with existing `zob_coms_*` tools.
+- Treat stale/offline peers as blockers, never completion evidence.
+
+MUST NOT:
+- Do not persist raw prompt, task, output, content, text, rationale, diff, or patch bodies.
+- Do not introduce worker-to-worker free chat.
+- Do not enable network transport without auth/locality policy.
+- Do not make append-only ledger writes count as live delivery.

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

@@ -0,0 +1,121 @@
+import { sha256 } from "../utils/hashing.js";
+import { isRecord } from "../utils/records.js";
+
+const FORBIDDEN_PERSISTED_KEYS = new Set(["body", "task", "prompt", "output", "content", "message", "rationale", "text", "diff", "patch"]);
+const ENVELOPE_TYPES = new Set(["ping", "pong", "prompt", "ack", "response", "error"]);
+
+export type ZobLiveEnvelopeType = "ping" | "pong" | "prompt" | "ack" | "response" | "error";
+
+export interface ZobLiveEnvelope {
+  schema: "zob.live-envelope.v1";
+  type: ZobLiveEnvelopeType;
+  msgId: string;
+  runId?: string;
+  sender?: string;
+  receiver?: string;
+  team?: string;
+  hops: number;
+  taskHash?: string;
+  contextHash?: string;
+  outputHash?: string;
+  artifactRefs?: string[];
+  artifactHashes?: string[];
+  replyEndpoint?: string;
+  replyEndpointHash?: string;
+  transientPrompt?: string;
+  transientResponse?: string;
+  errorCode?: string;
+  errorHash?: string;
+  timestamp: string;
+  bodyStored: false;
+}
+
+function hasForbiddenExactKey(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasForbiddenExactKey);
+  return Object.entries(value).some(([key, child]) => FORBIDDEN_PERSISTED_KEYS.has(key) || hasForbiddenExactKey(child));
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+export function buildZobLiveEnvelope(input: Omit<ZobLiveEnvelope, "schema" | "timestamp" | "bodyStored" | "hops"> & { hops?: number }): ZobLiveEnvelope {
+  return {
+    schema: "zob.live-envelope.v1",
+    hops: input.hops ?? 0,
+    timestamp: new Date().toISOString(),
+    bodyStored: false,
+    ...input,
+  };
+}
+
+export function buildZobLiveAckEnvelope(request: ZobLiveEnvelope): ZobLiveEnvelope {
+  return buildZobLiveEnvelope({
+    type: "ack",
+    msgId: request.msgId,
+    runId: request.runId,
+    sender: request.receiver,
+    receiver: request.sender,
+    team: request.team,
+    hops: request.hops,
+    taskHash: request.taskHash,
+  });
+}
+
+export function buildZobLivePongEnvelope(request: ZobLiveEnvelope): ZobLiveEnvelope {
+  return buildZobLiveEnvelope({
+    type: "pong",
+    msgId: request.msgId,
+    runId: request.runId,
+    sender: request.receiver,
+    receiver: request.sender,
+    team: request.team,
+    hops: request.hops,
+  });
+}
+
+export function buildZobLiveErrorEnvelope(request: Partial<ZobLiveEnvelope>, error: string, code = "transport_error"): ZobLiveEnvelope {
+  return buildZobLiveEnvelope({
+    type: "error",
+    msgId: typeof request.msgId === "string" ? request.msgId : `error-${Date.now()}`,
+    runId: request.runId,
+    sender: request.receiver,
+    receiver: request.sender,
+    team: request.team,
+    hops: typeof request.hops === "number" ? request.hops : 0,
+    errorCode: code,
+    errorHash: sha256(error),
+  });
+}
+
+export function validateZobLiveEnvelope(value: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(value)) return ["ZOB live envelope must be an object"];
+  if (value.schema !== "zob.live-envelope.v1") errors.push("ZOB live envelope schema must be zob.live-envelope.v1");
+  if (typeof value.type !== "string" || !ENVELOPE_TYPES.has(value.type)) errors.push("ZOB live envelope type is invalid");
+  if (typeof value.msgId !== "string" || value.msgId.trim().length === 0) errors.push("ZOB live envelope requires msgId");
+  if (typeof value.hops !== "number" || !Number.isFinite(value.hops) || value.hops < 0 || value.hops > 5) errors.push("ZOB live envelope hops must be 0..5");
+  if (value.bodyStored !== false) errors.push("ZOB live envelope bodyStored must be false");
+  if (typeof value.timestamp !== "string") errors.push("ZOB live envelope requires timestamp");
+  if (hasForbiddenExactKey(value)) errors.push("ZOB live envelope must not use persisted raw-body key names");
+  if (value.artifactRefs !== undefined && !isStringArray(value.artifactRefs)) errors.push("ZOB live envelope artifactRefs must be string[] when provided");
+  if (value.artifactHashes !== undefined && !isStringArray(value.artifactHashes)) errors.push("ZOB live envelope artifactHashes must be string[] when provided");
+  if (value.type === "prompt") {
+    if (typeof value.sender !== "string" || typeof value.receiver !== "string") errors.push("ZOB live prompt envelope requires sender and receiver");
+    if (typeof value.taskHash !== "string") errors.push("ZOB live prompt envelope requires taskHash");
+    if (typeof value.transientPrompt !== "string" || value.transientPrompt.length === 0) errors.push("ZOB live prompt envelope requires transientPrompt");
+  }
+  if (value.type === "response" && typeof value.outputHash !== "string" && typeof value.transientResponse !== "string") errors.push("ZOB live response envelope requires outputHash or transientResponse");
+  return errors;
+}
+
+export function parseZobLiveEnvelopeLine(line: string): { envelope?: ZobLiveEnvelope; errors: string[] } {
+  try {
+    const parsed = JSON.parse(line) as unknown;
+    const errors = validateZobLiveEnvelope(parsed);
+    return errors.length === 0 ? { envelope: parsed as ZobLiveEnvelope, errors } : { errors };
+  } catch (error) {
+    return { errors: [`Could not parse ZOB live envelope: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+}

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

@@ -0,0 +1,53 @@
+import { basename } from "node:path";
+
+import type { TeamDefinition, TeamLead, TeamWorker } from "../types.js";
+import { sha256 } from "../utils/hashing.js";
+import { safeFileStem } from "../utils/paths.js";
+import type { ZobComsV2Policy, ZobLivePeerCard, ZobLiveRoleType } from "./types.js";
+
+const PROCESS_STARTED_AT = new Date().toISOString();
+const PROCESS_SESSION_ID = safeFileStem(process.env.ZOB_COMS_SESSION_ID ?? `session-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+
+export function buildZobComsProjectId(repoRoot: string): string {
+  return safeFileStem(`${basename(repoRoot)}-${sha256(repoRoot).slice(0, 12)}`);
+}
+
+function roleFromTeam(definition: TeamDefinition, requestedRoleId: string): { roleId: string; roleType: ZobLiveRoleType; leadId?: string; agent: string } {
+  if (definition.orchestrator.id === requestedRoleId) return { roleId: definition.orchestrator.id, roleType: "orchestrator", agent: definition.orchestrator.agent };
+  const lead = definition.leads.find((candidate: TeamLead) => candidate.id === requestedRoleId);
+  if (lead) return { roleId: lead.id, roleType: "lead", agent: lead.agent };
+  const worker = definition.workers.find((candidate: TeamWorker) => candidate.id === requestedRoleId);
+  if (worker) return { roleId: worker.id, roleType: "worker", leadId: worker.leadId, agent: worker.agent };
+  return { roleId: definition.orchestrator.id, roleType: "orchestrator", agent: definition.orchestrator.agent };
+}
+
+export function buildCurrentZobLivePeerCard(repoRoot: string, definition: TeamDefinition, policy: ZobComsV2Policy): ZobLivePeerCard {
+  const requestedRoleId = process.env.ZOB_COMS_ROLE_ID ?? definition.orchestrator.id;
+  const role = roleFromTeam(definition, requestedRoleId);
+  const sessionId = PROCESS_SESSION_ID;
+  const endpoint = policy.mode === "observe_only" ? "observe-only" : `pending-${policy.mode}`;
+  return {
+    schema: "zob.live-peer-card.v1",
+    projectId: buildZobComsProjectId(repoRoot),
+    team: definition.name,
+    roleId: role.roleId,
+    roleType: role.roleType,
+    leadId: role.leadId,
+    agent: role.agent,
+    sessionId,
+    sessionHash: sha256(sessionId),
+    transport: policy.mode === "required_network" ? "sse" : policy.mode === "required_local" ? "local_socket" : "observe_only",
+    endpoint,
+    endpointHash: sha256(endpoint),
+    cwdHash: sha256(repoRoot),
+    pid: typeof process.pid === "number" ? process.pid : undefined,
+    startedAt: PROCESS_STARTED_AT,
+    heartbeatAt: new Date().toISOString(),
+    contextUsedPct: 0,
+    queueDepth: 0,
+    status: policy.mode === "off" ? "offline" : "online",
+    staleAfterMs: policy.heartbeat.staleAfterMs,
+    offlineAfterMs: policy.heartbeat.offlineAfterMs,
+    bodyStored: false,
+  };
+}

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

@@ -0,0 +1,67 @@
+import type { TeamDefinition } from "../types.js";
+import { appendZobComsMessage, replyZobComsMessage, transitionZobComsStatus } from "../topology/coms.js";
+import type { ZobLiveEnvelope } from "./envelope.js";
+
+export function appendLiveSendRequestedRef(repoRoot: string, definition: TeamDefinition, envelope: ZobLiveEnvelope): Record<string, unknown> {
+  return appendZobComsMessage(repoRoot, definition, {
+    runId: envelope.runId ?? "unknown-run",
+    sender: envelope.sender ?? definition.orchestrator.id,
+    receiver: envelope.receiver ?? definition.orchestrator.id,
+    kind: "live_handoff_ref",
+    taskId: envelope.msgId,
+    taskHash: envelope.taskHash,
+    status: "send_requested",
+    ack: "not_sent",
+    metadata: {
+      schema: "zob.coms-live-ref.v1",
+      transport: "local_socket",
+      liveDelivery: "send_requested",
+      hops: envelope.hops,
+      transientBodyTransport: true,
+      persistBodies: false,
+      artifactRefs: envelope.artifactRefs ?? [],
+      artifactHashes: envelope.artifactHashes ?? [],
+      captureBodyStored: false,
+    },
+  });
+}
+
+export function appendLiveDeliveredStatus(repoRoot: string, msgId: string, actor: string): Record<string, unknown> {
+  return transitionZobComsStatus(repoRoot, msgId, actor, "delivered");
+}
+
+export function appendLiveRunningStatus(repoRoot: string, msgId: string, actor: string): Record<string, unknown> {
+  return transitionZobComsStatus(repoRoot, msgId, actor, "running");
+}
+
+export function appendLiveCompletedRef(repoRoot: string, definition: TeamDefinition, parentMsgId: string, envelope: ZobLiveEnvelope): Record<string, unknown> {
+  return replyZobComsMessage(repoRoot, definition, parentMsgId, {
+    sender: envelope.sender ?? definition.orchestrator.id,
+    receiver: envelope.receiver ?? definition.orchestrator.id,
+    kind: "live_response_ref",
+    taskId: `${envelope.msgId}:response`,
+    taskHash: envelope.taskHash,
+    outputHash: envelope.outputHash ?? null,
+    status: "completed",
+    ack: "received",
+    metadata: {
+      schema: "zob.coms-live-ref.v1",
+      transport: "local_socket",
+      liveDelivery: "completed",
+      hops: envelope.hops,
+      transientBodyTransport: true,
+      persistBodies: false,
+      artifactRefs: envelope.artifactRefs ?? [],
+      artifactHashes: envelope.artifactHashes ?? [],
+      captureBodyStored: false,
+    },
+  });
+}
+
+export function appendLiveErrorStatus(repoRoot: string, msgId: string, actor: string): Record<string, unknown> {
+  return transitionZobComsStatus(repoRoot, msgId, actor, "error");
+}
+
+export function appendPeerStaleStatus(repoRoot: string, msgId: string, actor: string): Record<string, unknown> {
+  return transitionZobComsStatus(repoRoot, msgId, actor, "stale_blocked");
+}

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

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createConnection, createServer, type Server, type Socket } from "node:net";
+
+import { safeFileStem } from "../utils/paths.js";
+import { buildZobLiveErrorEnvelope, parseZobLiveEnvelopeLine, validateZobLiveEnvelope, type ZobLiveEnvelope } from "./envelope.js";
+
+export interface ZobLocalTransportServer {
+  endpoint: string;
+  close(): Promise<void>;
+}
+
+export interface ZobLocalTransportOptions {
+  timeoutMs?: number;
+  maxLineBytes?: number;
+}
+
+export type ZobLocalEnvelopeHandler = (envelope: ZobLiveEnvelope) => Promise<ZobLiveEnvelope> | ZobLiveEnvelope;
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_LINE_BYTES = 256 * 1024;
+
+export function makeZobLocalEndpoint(sessionId: string): string {
+  return join(tmpdir(), "zob-coms-v2", `${safeFileStem(sessionId)}.sock`);
+}
+
+function safeUnlinkSocket(endpoint: string): void {
+  if (!endpoint.endsWith(".sock") || !existsSync(endpoint)) return;
+  unlinkSync(endpoint);
+}
+
+function boundedTimeout(value: number | undefined): number {
+  return Math.max(25, Math.min(30_000, Math.floor(value ?? DEFAULT_TIMEOUT_MS)));
+}
+
+function boundedMaxLineBytes(value: number | undefined): number {
+  return Math.max(1024, Math.min(1024 * 1024, Math.floor(value ?? DEFAULT_MAX_LINE_BYTES)));
+}
+
+async function writeEnvelope(socket: Socket, envelope: ZobLiveEnvelope): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    socket.write(`${JSON.stringify(envelope)}\n`, "utf8", (error) => error ? reject(error) : resolve());
+  });
+}
+
+export async function bindZobLocalEndpoint(endpoint: string, handler: ZobLocalEnvelopeHandler, options: ZobLocalTransportOptions = {}): Promise<ZobLocalTransportServer> {
+  mkdirSync(dirname(endpoint), { recursive: true });
+  safeUnlinkSocket(endpoint);
+  const maxLineBytes = boundedMaxLineBytes(options.maxLineBytes);
+  const server = createServer((socket) => {
+    let buffer = "";
+    socket.setEncoding("utf8");
+    socket.on("data", async (chunk) => {
+      buffer += chunk;
+      if (Buffer.byteLength(buffer, "utf8") > maxLineBytes) {
+        await writeEnvelope(socket, buildZobLiveErrorEnvelope({}, "max line bytes exceeded", "max_line_bytes"));
+        socket.end();
+        return;
+      }
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex < 0) return;
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = buffer.slice(newlineIndex + 1);
+      const parsed = parseZobLiveEnvelopeLine(line);
+      if (!parsed.envelope) {
+        await writeEnvelope(socket, buildZobLiveErrorEnvelope({}, parsed.errors.join("; "), "invalid_envelope"));
+        socket.end();
+        return;
+      }
+      try {
+        const response = await handler(parsed.envelope);
+        const responseErrors = validateZobLiveEnvelope(response);
+        await writeEnvelope(socket, responseErrors.length === 0 ? response : buildZobLiveErrorEnvelope(parsed.envelope, responseErrors.join("; "), "invalid_response"));
+      } catch (error) {
+        await writeEnvelope(socket, buildZobLiveErrorEnvelope(parsed.envelope, error instanceof Error ? error.message : String(error), "handler_error"));
+      } finally {
+        socket.end();
+      }
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(endpoint, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  return {
+    endpoint,
+    async close() {
+      await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+      safeUnlinkSocket(endpoint);
+    },
+  };
+}
+
+export async function sendZobLocalEnvelope(endpoint: string, envelope: ZobLiveEnvelope, options: ZobLocalTransportOptions = {}): Promise<ZobLiveEnvelope> {
+  const requestErrors = validateZobLiveEnvelope(envelope);
+  if (requestErrors.length > 0) throw new Error(requestErrors.join("; "));
+  const timeoutMs = boundedTimeout(options.timeoutMs);
+  const maxLineBytes = boundedMaxLineBytes(options.maxLineBytes);
+  return await new Promise<ZobLiveEnvelope>((resolve, reject) => {
+    const socket = createConnection(endpoint);
+    let buffer = "";
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`ZOB local transport timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    const finish = (fn: () => void): void => {
+      clearTimeout(timeout);
+      socket.removeAllListeners();
+      fn();
+    };
+    socket.setEncoding("utf8");
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify(envelope)}\n`, "utf8");
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      if (Buffer.byteLength(buffer, "utf8") > maxLineBytes) {
+        finish(() => reject(new Error("ZOB local transport response exceeded max line bytes")));
+        socket.destroy();
+        return;
+      }
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex < 0) return;
+      const parsed = parseZobLiveEnvelopeLine(buffer.slice(0, newlineIndex).trim());
+      finish(() => parsed.envelope ? resolve(parsed.envelope) : reject(new Error(parsed.errors.join("; "))));
+      socket.end();
+    });
+    socket.on("error", (error) => finish(() => reject(error)));
+  });
+}
+
+export async function pingZobLocalEndpoint(endpoint: string, msgId = `ping-${Date.now()}`): Promise<ZobLiveEnvelope> {
+  return sendZobLocalEnvelope(endpoint, {
+    schema: "zob.live-envelope.v1",
+    type: "ping",
+    msgId,
+    hops: 0,
+    timestamp: new Date().toISOString(),
+    bodyStored: false,
+  });
+}
+
+export { safeUnlinkSocket as pruneZobLocalEndpoint };

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

@@ -0,0 +1,80 @@
+import type { ZobLiveEnvelope } from "./envelope.js";
+
+export interface ZobPendingReplyResult {
+  msgId: string;
+  status: "completed" | "error" | "timeout";
+  envelope?: ZobLiveEnvelope;
+  errorHash?: string;
+}
+
+interface PendingReply {
+  msgId: string;
+  createdAt: number;
+  resolve: (result: ZobPendingReplyResult) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class ZobPendingReplies {
+  private readonly pending = new Map<string, PendingReply>();
+  private readonly completed = new Map<string, ZobPendingReplyResult>();
+
+  wait(msgId: string, timeoutMs: number): Promise<ZobPendingReplyResult> {
+    const completed = this.completed.get(msgId);
+    if (completed) {
+      this.completed.delete(msgId);
+      return Promise.resolve(completed);
+    }
+    const boundedTimeout = Math.max(25, Math.min(30 * 60 * 1000, Math.floor(timeoutMs)));
+    this.cancel(msgId);
+    return new Promise<ZobPendingReplyResult>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(msgId);
+        resolve({ msgId, status: "timeout" });
+      }, boundedTimeout);
+      timer.unref?.();
+      this.pending.set(msgId, { msgId, createdAt: Date.now(), resolve, timer });
+    });
+  }
+
+  complete(msgId: string, envelope: ZobLiveEnvelope): boolean {
+    const result: ZobPendingReplyResult = { msgId, status: "completed", envelope };
+    const item = this.pending.get(msgId);
+    if (!item) {
+      this.completed.set(msgId, result);
+      return false;
+    }
+    clearTimeout(item.timer);
+    this.pending.delete(msgId);
+    item.resolve(result);
+    return true;
+  }
+
+  fail(msgId: string, errorHash: string): boolean {
+    const result: ZobPendingReplyResult = { msgId, status: "error", errorHash };
+    const item = this.pending.get(msgId);
+    if (!item) {
+      this.completed.set(msgId, result);
+      return false;
+    }
+    clearTimeout(item.timer);
+    this.pending.delete(msgId);
+    item.resolve(result);
+    return true;
+  }
+
+  cancel(msgId: string): boolean {
+    const item = this.pending.get(msgId);
+    if (!item) return false;
+    clearTimeout(item.timer);
+    this.pending.delete(msgId);
+    return true;
+  }
+
+  snapshot(): Array<Record<string, unknown>> {
+    const now = Date.now();
+    return [
+      ...[...this.pending.values()].map((item) => ({ msgId: item.msgId, ageMs: now - item.createdAt, status: "pending", bodyStored: false })),
+      ...[...this.completed.values()].map((item) => ({ msgId: item.msgId, status: item.status, bodyStored: false })),
+    ];
+  }
+}