zob-harness 0.15.1 → 0.15.3

package/.pi/extensions/zob-harness/index.ts

@@ -617,6 +617,7 @@ export { ZobPendingReplies } from "./src/domains/coms/coms-v2/pending-replies.js
 export { buildZobLiveResponseCapture, buildZobLiveResponseEnvelope } from "./src/domains/coms/coms-v2/response-capture.js";
 export { appendLiveSendRequestedRef, appendLiveDeliveredStatus, appendLiveRunningStatus, appendLiveCompletedRef, appendLiveErrorStatus, appendPeerStaleStatus } from "./src/domains/coms/coms-v2/ledger-bridge.js";
 export { redactZobComsText, writeZobComsRedactedCapture } from "./src/domains/coms/coms-v2/transcript-capture.js";
+export { annotateZpeerStatus, isZpeerTerminalStatus, shouldAcceptZpeerStatusUpdate, zpeerStatusRank } from "./src/domains/coms/coms-v2/zpeer-status.js";
 export type { ZobLiveEnvelope, ZobLiveEnvelopeType } from "./src/domains/coms/coms-v2/envelope.js";
 export type { ZobComsTranscriptCapturePolicy, ZobComsTranscriptMode, ZobComsTranscriptRetentionClass, ZobComsTransportMode, ZobComsV2Policy, ZobLivePeerCard, ZobLivePeerStatus, ZobLivePresenceSummary, ZobLiveRegistrySnapshot } from "./src/domains/coms/coms-v2/types.js";
 

package/.pi/extensions/zob-harness/src/domains/coms/coms-v2/zpeer-status.ts

@@ -0,0 +1,92 @@
+export interface ZpeerStatusComparable {
+  status?: string;
+  kind?: string;
+  at?: string;
+}
+
+const ZPEER_TERMINAL_STATUSES = new Set([
+  "reply",
+  "completed",
+  "response_sent",
+  "blocked",
+  "error",
+  "timeout",
+  "expired",
+  "required_response_expired",
+]);
+
+const ZPEER_STATUS_RANKS: Record<string, number> = {
+  status: 0,
+  attempt: 5,
+  heartbeat: 5,
+  sent: 10,
+  delivered: 20,
+  urgent_delivered: 25,
+  force_accepted: 25,
+  force_downgraded: 25,
+  required_response_reinject: 30,
+  inbound: 35,
+  prompt_received: 35,
+  waiting: 40,
+  response_sent: 90,
+  reply: 100,
+  completed: 100,
+  blocked: 100,
+  force_blocked: 100,
+  error: 100,
+  timeout: 100,
+  expired: 100,
+  required_response_expired: 100,
+};
+
+function zpeerStatusKey(input: ZpeerStatusComparable): string | undefined {
+  return input.status ?? input.kind;
+}
+
+function parsedTime(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function isZpeerTerminalStatus(status: string | undefined, kind?: string): boolean {
+  const primary = status ?? kind;
+  return Boolean((primary && ZPEER_TERMINAL_STATUSES.has(primary)) || (kind && ZPEER_TERMINAL_STATUSES.has(kind)));
+}
+
+export function zpeerStatusRank(status: string | undefined, kind?: string): number {
+  const primary = status ?? kind;
+  if (primary && ZPEER_STATUS_RANKS[primary] !== undefined) return ZPEER_STATUS_RANKS[primary];
+  if (kind && ZPEER_STATUS_RANKS[kind] !== undefined) return ZPEER_STATUS_RANKS[kind];
+  return 0;
+}
+
+export function shouldAcceptZpeerStatusUpdate(current: ZpeerStatusComparable | undefined, incoming: ZpeerStatusComparable): boolean {
+  if (!current) return true;
+
+  const currentTerminal = isZpeerTerminalStatus(current.status, current.kind);
+  const incomingTerminal = isZpeerTerminalStatus(incoming.status, incoming.kind);
+  if (currentTerminal && !incomingTerminal) return false;
+  if (!currentTerminal && incomingTerminal) return true;
+
+  const currentRank = zpeerStatusRank(current.status, current.kind);
+  const incomingRank = zpeerStatusRank(incoming.status, incoming.kind);
+  if (incomingRank > currentRank) return true;
+  if (incomingRank < currentRank) return false;
+
+  const currentAt = parsedTime(current.at);
+  const incomingAt = parsedTime(incoming.at);
+  if (currentAt !== undefined && incomingAt !== undefined) return incomingAt >= currentAt;
+
+  const currentKey = zpeerStatusKey(current);
+  const incomingKey = zpeerStatusKey(incoming);
+  return currentKey === incomingKey;
+}
+
+export function annotateZpeerStatus<T extends ZpeerStatusComparable>(event: T): T & { terminal: boolean; statusRank: number } {
+  return {
+    ...event,
+    terminal: isZpeerTerminalStatus(event.status, event.kind),
+    statusRank: zpeerStatusRank(event.status, event.kind),
+  };
+}

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

@@ -10,6 +10,7 @@ import { validateZobComsEdge } from "../../topology/coms.js";
 import { loadTeamDefinition, validateTeamDefinition } from "../../topology/teams.js";
 import { loadZteamManifest, zteamAllowsZpeerContact } from "../zagents.js";
 import { sha256 } from "../../../core/utils/hashing.js";
+import { annotateZpeerStatus } from "./zpeer-status.js";
 
 const DEFAULT_ROOM_ID = "default";
 const ALIAS_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{1,31}$/;
@@ -67,6 +68,8 @@ export interface ZpeerSendResult {
   deliveryMethod?: "local_socket" | "tmux_sendkeys";
   fallback_delivery?: boolean;
   best_effort?: boolean;
+  terminal?: boolean;
+  statusRank?: number;
   bodyStored: false;
 }
 
@@ -620,7 +623,7 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
       deliveryMethod: result.deliveryMethod,
       fallbackDelivery: result.fallback_delivery,
     });
-    return { roomId, priority, interruptMode, interruptReasonHash, requireResponse: requireResponse || undefined, responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined, maxReinjects: requireResponse ? maxReinjects : undefined, ...result };
+    return annotateZpeerStatus({ roomId, priority, interruptMode, interruptReasonHash, requireResponse: requireResponse || undefined, responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined, maxReinjects: requireResponse ? maxReinjects : undefined, ...result });
   };
 
   if (priority === "force" && !interruptReasonHash) return finish("attempt", { status: "blocked", reason: "force interrupt requires reason hash", targetAlias: targetAlias ?? undefined, taskHash, interruptStatus: "force_blocked", bodyStored: false });

package/.pi/extensions/zob-harness/src/runtime/commands/zlive.ts

@@ -17,6 +17,7 @@ import { loadActiveZagentScopedMode } from "../events.js";
 import { resolveRuleProfile } from "../../domains/governance/rules.js";
 import type { HarnessRuntimeState } from "../state.js";
 import { applyMode, renderHarnessWidget } from "../widget.js";
+import { recordZpeerRuntimeEvent } from "../zpeer-events.js";
 
 function zpeerCommandProfileId(ctx: ExtensionCommandContext): string {
   const sessionIdentity = ctx.sessionManager.getSessionFile() ?? ctx.sessionManager.getSessionId();
@@ -1140,18 +1141,21 @@ async function executeZteamTmuxActionPlan(_repoRoot: string, plan: ZteamTmuxActi
 }
 
 export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeState): void {
-  const rememberZpeerEvent = (event: { kind: NonNullable<typeof state.zobLive.lastEvent>["kind"]; roomId?: string; fromAlias?: string; toAlias?: string; status: string; reason?: string; msgId?: string; taskHash?: string; outputHash?: string; priority?: ZpeerInterruptPriority; interruptMode?: ZpeerInterruptMode; interruptStatus?: ZpeerInterruptStatus }): void => {
-    state.zobLive.lastEvent = { ...event, at: new Date().toISOString(), localOnly: true, networkEnabled: false, bodyStored: false };
+  const rememberZpeerEvent = (event: { kind: NonNullable<typeof state.zobLive.lastEvent>["kind"]; roomId?: string; fromAlias?: string; toAlias?: string; status: string; reason?: string; msgId?: string; taskHash?: string; outputHash?: string; priority?: ZpeerInterruptPriority; interruptMode?: ZpeerInterruptMode; interruptStatus?: ZpeerInterruptStatus }): NonNullable<typeof state.zobLive.lastEvent> | undefined => {
+    const recorded = recordZpeerRuntimeEvent(state, event);
+    return recorded.accepted ? recorded.event : undefined;
   };
 
-  const emitZpeerEvent = (event: Parameters<typeof rememberZpeerEvent>[0]): void => {
-    rememberZpeerEvent(event);
+  const emitZpeerEvent = (event: Parameters<typeof rememberZpeerEvent>[0]): boolean => {
+    const recorded = rememberZpeerEvent(event);
+    if (!recorded) return false;
     void pi.sendMessage({
       customType: "zob-zpeer-event",
       content: `ZPeer ${event.kind} ${event.fromAlias ? `@${event.fromAlias}` : "?"} → ${event.toAlias ? `@${event.toAlias}` : "?"} ${event.status}`,
       display: true,
-      details: { ...state.zobLive.lastEvent },
-    }, { triggerTurn: false });
+      details: { ...recorded },
+    }, { triggerTurn: false, deliverAs: "nextTurn" });
+    return true;
   };
 
   pi.registerCommand("zagent", {
@@ -1682,6 +1686,7 @@ export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeSta
           maxReinjects: sendMode.maxReinjects,
           onFeedback: (feedback) => {
             feedbackEmittedTerminal = feedback.result.status === "waiting" || feedback.result.status === "reply" || feedback.result.status === "completed" || feedback.result.status === "blocked" || feedback.result.status === "error" || feedback.result.status === "timeout" || feedback.result.status === "expired" || feedback.result.status === "required_response_expired";
+            if (feedback.kind === "waiting" && (sendMode.requireResponse === true || sendMode.mode !== "async")) return;
             const feedbackRoomId = feedback.result.roomId ?? eventRoomId;
             emitZpeerEvent({ kind: feedback.kind, roomId: feedbackRoomId, fromAlias: state.zobLive.peerCard ? peerAliasInRoom(state.zobLive.peerCard, feedbackRoomId) ?? eventFromAlias : eventFromAlias, toAlias: feedback.result.targetAlias ?? targetAlias, status: feedback.result.status, reason: feedback.result.reason, msgId: feedback.result.msgId, taskHash: feedback.result.taskHash, outputHash: feedback.result.outputHash, priority: feedback.result.priority ?? sendMode.priority, interruptMode: feedback.result.interruptMode ?? sendMode.interruptMode, interruptStatus: feedback.result.interruptStatus });
           },

package/.pi/extensions/zob-harness/src/runtime/events.ts

@@ -40,6 +40,7 @@ import { capturePlanArtifact } from "./plan-capture.js";
 import { redactPlanTodosBlockForDisplay } from "../domains/plan/plan-todos.js";
 import { applyMode, renderHarnessWidget } from "./widget.js";
 import { createStopRestoreCandidate, markStopRestoreAssistantMessage, markStopRestoreToolVisible } from "./stop-restore.js";
+import { recordZpeerRuntimeEvent } from "./zpeer-events.js";
 
 function safelyUpdateZobLivePeer(repoRoot: string, action: "register" | "touch" | "unregister"): void {
   try {
@@ -51,14 +52,8 @@ function safelyUpdateZobLivePeer(repoRoot: string, action: "register" | "touch"
   }
 }
 
-function setZpeerLastEvent(state: HarnessRuntimeState, event: Omit<ZobLiveLastEvent, "at" | "localOnly" | "networkEnabled" | "bodyStored"> & { at?: string }): void {
-  state.zobLive.lastEvent = {
-    ...event,
-    at: event.at ?? new Date().toISOString(),
-    localOnly: true,
-    networkEnabled: false,
-    bodyStored: false,
-  };
+function setZpeerLastEvent(state: HarnessRuntimeState, event: Omit<ZobLiveLastEvent, "at" | "localOnly" | "networkEnabled" | "bodyStored" | "terminal" | "statusRank" | "superseded" | "supersededByStatus"> & { at?: string }): ZobLiveLastEvent {
+  return recordZpeerRuntimeEvent(state, event).event;
 }
 
 function clearPassivePeerWaitForResponse(state: HarnessRuntimeState, envelope: { msgId?: string; runId?: string; sender?: string; type?: string }): void {
@@ -244,7 +239,7 @@ function handleInboundZpeerPrompt(pi: ExtensionAPI, state: HarnessRuntimeState,
     content: priority === "normal" ? "ZPeer inbound prompt received (transient body delivered only to agent turn)" : `ZPeer ${priority} inbound prompt received (transient body delivered only to agent turn)`,
     display: true,
     details: { kind: "inbound", roomId, fromAlias: envelope.sender, toAlias: envelope.receiver, status: interruptStatus ?? "prompt_received", msgId: envelope.msgId, taskHash: envelope.taskHash, priority, interruptMode, interruptStatus, bodyStored: false, localOnly: true, networkEnabled: false },
-  }, { triggerTurn: false });
+  }, { triggerTurn: false, deliverAs: "nextTurn" });
   void pi.sendMessage({
     customType: "zob-coms-inbound",
     content: envelope.transientPrompt ?? "",
@@ -620,7 +615,7 @@ function formatZpeerLastEvent(event: ZobLiveLastEvent | undefined): string {
 
 function buildZpeerAwarenessPrompt(state: HarnessRuntimeState, repoRoot: string): string {
   if (!state.zobLive.peerCard) {
-    return "\n\nZPEER AWARENESS\n- local peer endpoint: unavailable this turn\n- Use zpeer_ask with mode=\"async\" or /zpeer only when useful or user-requested for peer coordination; avoid spam/loops and do not invent hidden worker-to-worker chat.";
+    return "\n\nZPEER AWARENESS\n- local peer endpoint: unavailable this turn\n- Use zpeer_ask with mode=\"async\" or /zpeer only when useful or user-requested for peer coordination; avoid spam/loops and do not invent hidden worker-to-worker chat.\n- If the user explicitly asks for a reply, status, or confirmation, use requireResponse=true with mode=\"await\" or mode=\"long\"; status=waiting is delivery-only, not evidence that the peer is working or done.";
   }
   const summaries = buildZpeerPeerRoomSummaries(repoRoot, state.zobLive.peerCard);
   const activeSummary = summaries.find((summary) => summary.active) ?? summaries[0];
@@ -637,7 +632,7 @@ function buildZpeerAwarenessPrompt(state: HarnessRuntimeState, repoRoot: string)
   const activePeerAliases = (activeSummary?.onlineAliases ?? []).filter((alias) => alias !== activeSelfAlias).slice(0, 8).map((alias) => `@${alias}`);
   const activeUnavailable = (activeSummary?.stale ?? 0) + (activeSummary?.offline ?? 0);
   const activeDuplicateLine = activeSummary && activeSummary.duplicateAliases.length > 0 ? `\n- duplicate live aliases: ${activeSummary.duplicateAliases.map((alias) => `@${alias}`).join(", ")}` : "";
-  return `\n\nZPEER AWARENESS (transient, rebuilt each turn)\n- active room: ${activeSummary?.roomId ?? "default"}\n- memberships: ${memberships}\n- self: @${activeSelfAlias}\n- online peers: ${activePeerAliases.join(", ") || "none"}\n- unavailable peers: ${activeUnavailable} (stale=${activeSummary?.stale ?? 0}, offline=${activeSummary?.offline ?? 0})${activeDuplicateLine}\n- rooms:\n${roomLines.join("\n") || "  - none"}\n- Use zpeer_ask with explicit roomId when targeting a non-active room.\n- posture: local_socket-only, room-scoped, hash-only durable ledgers, bodyStored=false, networkEnabled=false\n- For non-trivial review/debug/planning peer coordination, agents may use zpeer_ask with mode=\"async\" so the request is visible, governed, and non-blocking; /zpeer remains the interactive command path.\n- Passive wait rule: if the only remaining action is waiting for ZPeer/coms replies, stop the turn and remain idle; do not poll, call tools, or continue just to wait.\n- Use ZPeer only when useful or user-requested; avoid spam, duplicate asks, and reply loops; do not use it for hidden free chat or to bypass topology/safety gates.\n- Raw ZPeer bodies are transient; durable records must remain hash-only/bodyStored=false.\n- last ZPeer event: ${formatZpeerLastEvent(state.zobLive.lastEvent)}`;
+  return `\n\nZPEER AWARENESS (transient, rebuilt each turn)\n- active room: ${activeSummary?.roomId ?? "default"}\n- memberships: ${memberships}\n- self: @${activeSelfAlias}\n- online peers: ${activePeerAliases.join(", ") || "none"}\n- unavailable peers: ${activeUnavailable} (stale=${activeSummary?.stale ?? 0}, offline=${activeSummary?.offline ?? 0})${activeDuplicateLine}\n- rooms:\n${roomLines.join("\n") || "  - none"}\n- Use zpeer_ask with explicit roomId when targeting a non-active room.\n- posture: local_socket-only, room-scoped, hash-only durable ledgers, bodyStored=false, networkEnabled=false\n- For non-trivial review/debug/planning peer coordination, agents may use zpeer_ask with mode=\"async\" so the request is visible, governed, and non-blocking; /zpeer remains the interactive command path.\n- If the user explicitly asks for a reply, status, or confirmation, use requireResponse=true with mode=\"await\" or mode=\"long\"; status=waiting is delivery-only, not evidence that the peer is working or done.\n- Passive wait rule: if the only remaining action is waiting for ZPeer/coms replies, stop the turn and remain idle; do not poll, call tools, or continue just to wait.\n- Use ZPeer only when useful or user-requested; avoid spam, duplicate asks, and reply loops; do not use it for hidden free chat or to bypass topology/safety gates.\n- Raw ZPeer bodies are transient; durable records must remain hash-only/bodyStored=false.\n- last ZPeer event: ${formatZpeerLastEvent(state.zobLive.lastEvent)}`;
 }
 
 const SAME_AGENT_MODE_INTENT_PROMPT = [
@@ -785,7 +780,7 @@ async function startOrRefreshZobLiveRuntime(pi: ExtensionAPI, state: HarnessRunt
           content: envelope.errorCode === "zpeer_required_response_expired" ? "ZPeer required response expired" : "ZPeer error received",
           display: true,
           details: { kind: state.zobLive.lastEvent?.kind, roomId: state.zobLive.lastEvent?.roomId, fromAlias: envelope.sender, toAlias: envelope.receiver, status: state.zobLive.lastEvent?.status, msgId: envelope.msgId, taskHash: envelope.taskHash, errorHash: envelope.errorHash, bodyStored: false, localOnly: true, networkEnabled: false },
-        }, { triggerTurn: false });
+        }, { triggerTurn: false, deliverAs: "nextTurn" });
         return buildZobLiveAckEnvelope(envelope);
       }
       if (envelope.type === "response") {
@@ -807,7 +802,7 @@ async function startOrRefreshZobLiveRuntime(pi: ExtensionAPI, state: HarnessRunt
           content: "ZPeer reply received (transient response available; durable records remain hash-only)",
           display: true,
           details: { kind: "reply", roomId: state.zobLive.lastEvent?.roomId, fromAlias: envelope.sender, toAlias: envelope.receiver, status: "reply", msgId: envelope.msgId, taskHash: envelope.taskHash, outputHash: envelope.outputHash, bodyStored: false, localOnly: true, networkEnabled: false },
-        }, { triggerTurn: false });
+        }, { triggerTurn: false, deliverAs: "nextTurn" });
         if (!completedActiveWait && envelope.transientResponse) {
           void pi.sendMessage({
             customType: "zob-zpeer-response",
@@ -1060,7 +1055,10 @@ async function sendInboundZobLiveResponse(pi: ExtensionAPI, state: HarnessRuntim
   const activeInbound = activeZpeerInboundForResponse(state);
   const inbound = activeInbound ?? state.zobLive.inbound;
   if (!inbound || inbound.responseSent || !inbound.envelope.replyEndpoint) return;
-  if (activeInbound?.requiredResponseStatus === "expired") return;
+  // ZOB-COMS-GUARDS: a late reply after expiry is now permitted (the watchdog
+  // already stopped reinjecting; sender-side pendingReplies resolves to no-op).
+  // Dropping this early-out recovers nudge/reply paths (e.g. a late oracle
+  // review) without weakening the real anti-abuse (reinject cap + sender expire).
   if (state.zobLive.inboundByMsgId && !activeInbound) return;
   const responseText = latestAssistantText(event);
   if (!responseText.trim()) return;
@@ -1103,7 +1101,7 @@ async function sendInboundZobLiveResponse(pi: ExtensionAPI, state: HarnessRuntim
     content: "ZPeer response sent (transient response delivered over local socket; durable records remain hash-only)",
     display: true,
     details: { kind: "response_sent", roomId: state.zobLive.lastEvent?.roomId, fromAlias: inbound.envelope.receiver, toAlias: inbound.envelope.sender, status: "response_sent", msgId: inbound.envelope.msgId, taskHash: inbound.envelope.taskHash, outputHash: responseEnvelope.outputHash, priority: activeInbound?.priority, interruptMode: activeInbound?.interruptMode, bodyStored: false, localOnly: true, networkEnabled: false },
-  }, { triggerTurn: false });
+  }, { triggerTurn: false, deliverAs: "nextTurn" });
 }
 
 export function registerHarnessEvents(pi: ExtensionAPI, state: HarnessRuntimeState): void {
@@ -1118,7 +1116,7 @@ export function registerHarnessEvents(pi: ExtensionAPI, state: HarnessRuntimeSta
     const taskHash = typeof details.taskHash === "string" ? details.taskHash : undefined;
     const outputHash = typeof details.outputHash === "string" ? details.outputHash : undefined;
     const route = fromAlias || toAlias ? `${fromAlias ? `@${fromAlias}` : "?"} → ${toAlias ? `@${toAlias}` : "?"}` : "room status";
-    const statusColor = status === "completed" || status === "sent" || status === "prompt_received" || status === "response_sent" ? "success" : status === "blocked" || status === "timeout" || status === "error" || status === "required_response_expired" ? "warning" : "muted";
+    const statusColor = status === "reply" || status === "completed" || status === "sent" || status === "delivered" || status === "prompt_received" || status === "response_sent" ? "success" : status === "blocked" || status === "timeout" || status === "error" || status === "expired" || status === "required_response_expired" ? "warning" : "muted";
     const line = [
       theme.fg("accent", "◆ ZPeer"),
       theme.fg("muted", kind),

package/.pi/extensions/zob-harness/src/runtime/schemas.ts

@@ -354,13 +354,13 @@ const ZpeerAskParams = Type.Object({
   targetAlias: Type.String({ description: "ZPeer target alias in the current local room. May include or omit the leading @." }),
   message: Type.String({ description: "Transient peer request body. Used only for local live delivery; never persisted in durable ledgers or reports." }),
   roomId: Type.Optional(Type.String({ description: "Optional ZPeer room id. Defaults to the current active local room." })),
-  mode: Type.Optional(StringEnum(["async", "await", "long"] as const, { description: "Send mode. Default async for agent-initiated coordination.", default: "async" })),
+  mode: Type.Optional(StringEnum(["async", "await", "long"] as const, { description: "Send mode. Default async for non-blocking coordination; when an actual reply/status is required, use await or long with requireResponse=true.", default: "async" })),
   reason: Type.Optional(Type.String({ description: "Optional transient coordination/interrupt reason. Required for force; hashed only in visible metadata; raw value is not persisted." })),
   urgency: Type.Optional(StringEnum(["normal", "urgent", "force"] as const, { description: "ZPeer delivery priority. normal=follow-up, urgent=steer, force=controlled abort+steer when policy allows." })),
   force: Type.Optional(Type.Boolean({ description: "Alias for urgency=force. Requires reason and remains local/hash-only." })),
   interruptMode: Type.Optional(StringEnum(["none", "steer", "abort"] as const, { description: "Requested interrupt mode. Derived from urgency when omitted; invalid broadening is blocked by runtime." })),
   timeoutMs: Type.Optional(Type.Number({ description: "Bounded reply wait timeout for await/long modes, and required-response expiration when requireResponse=true; capped by runtime." })),
-  requireResponse: Type.Optional(Type.Boolean({ description: "Opt in to a real msgId-correlated required response. Default false; when true the sender waits only for the exact msgId reply and expires explicitly." })),
+  requireResponse: Type.Optional(Type.Boolean({ description: "Opt in to a real msgId-correlated required response. Set true whenever the user asks for a reply, status, or confirmation; the sender waits only for the exact msgId reply and expires explicitly." })),
   maxReinjects: Type.Optional(Type.Number({ description: "Bounded receiver reminder budget for requireResponse. Default 1, capped 0..3." })),
 });
 

package/.pi/extensions/zob-harness/src/runtime/state.ts

@@ -49,6 +49,10 @@ export interface ZobLiveLastEvent {
   priority?: ZpeerInterruptPriority;
   interruptMode?: ZpeerInterruptMode;
   interruptStatus?: ZpeerInterruptStatus;
+  terminal?: boolean;
+  statusRank?: number;
+  superseded?: boolean;
+  supersededByStatus?: string;
   at: string;
   localOnly: true;
   networkEnabled: false;
@@ -98,6 +102,7 @@ export interface ZobLiveRuntimeState {
   inboundQueue?: string[];
   activeInboundMsgId?: string;
   lastEvent?: ZobLiveLastEvent;
+  latestZpeerEventByMsgId?: Record<string, ZobLiveLastEvent>;
   passivePeerWait?: ZobPassivePeerWaitState;
   leaseOwned?: boolean;
   leaseStatus?: "owned" | "blocked" | "unavailable";

package/.pi/extensions/zob-harness/src/runtime/tools-coms.ts

@@ -34,11 +34,23 @@ import {
 } from "../domains/topology/coms.js";
 import { loadTeamDefinition, validateTeamDefinition } from "../domains/topology/teams.js";
 import type { HarnessRuntimeState } from "./state.js";
+import { isCurrentZpeerRuntimeEvent, recordZpeerRuntimeEvent } from "./zpeer-events.js";
 
 const SHA256_HEX = /^[a-f0-9]{64}$/i;
-const ZPEER_AGENT_ASK_RATE_LIMIT_PER_MINUTE = 50;
-const ZPEER_AGENT_URGENT_RATE_LIMIT_PER_MINUTE = 10;
-const ZPEER_AGENT_FORCE_RATE_LIMIT_PER_MINUTE = 3;
+// ZOB-COMS-GUARDS: per-agent zpeer rate caps are env-configurable with a finite
+// ceiling (never Infinity) so trusted closed topologies (e.g. project-transposer's
+// 64-agent fan-out) don't trip the default 50/10/3 while real floods are still
+// bounded. Defaults unchanged for open/hostile topologies.
+const clampRate = (v: string | undefined, fallback: number): number => Math.max(1, Math.min(1000, Number.parseInt(v ?? "") || fallback));
+const ZPEER_AGENT_ASK_RATE_LIMIT_PER_MINUTE = clampRate(process.env.ZOB_ZPEER_ASK_RATE_LIMIT_PER_MINUTE, 50);
+const ZPEER_AGENT_URGENT_RATE_LIMIT_PER_MINUTE = clampRate(process.env.ZOB_ZPEER_URGENT_RATE_LIMIT_PER_MINUTE, 10);
+const ZPEER_AGENT_FORCE_RATE_LIMIT_PER_MINUTE = clampRate(process.env.ZOB_ZPEER_FORCE_RATE_LIMIT_PER_MINUTE, 3);
+// ZOB-COMS-GUARDS: the loop-keyword block (reject any zpeer_ask whose message
+// text contains 'zpeer_ask'/'/zpeer') over-fires on trusted topologies whose
+// prompts legitimately quote these tokens. Env-bypassed for trusted topologies;
+// default (unset) keeps current behavior for open/hostile use. Genuine anti-loop
+// (duplicate guard below + reinject cap + sender-side expire) is preserved.
+const ZPEER_RECURSION_KEYWORD_GUARD_DISABLED = /^(1|true|yes|on)$/i.test(process.env.ZOB_ZPEER_DISABLE_RECURSION_KEYWORD_GUARD ?? "");
 
 type ZpeerFallbackHookFn = ZpeerFallbackDelivery;
 
@@ -141,7 +153,7 @@ function zpeerAskGuardBlock(state: HarnessRuntimeState, params: ZpeerAskToolPara
   if (selfAlias && zpeerAliasesEquivalent(targetAlias, selfAlias)) return "cannot send to self";
   const roomId = safeZpeerRoomId(params.roomId) ?? currentRoomId;
   if (params.roomId && !safeZpeerRoomId(params.roomId)) return "invalid room id";
-  if (/\b(zpeer_ask|\/zpeer)\b/i.test(params.message)) return "loop guard blocked recursive ZPeer instruction";
+  if (!ZPEER_RECURSION_KEYWORD_GUARD_DISABLED && /\b(zpeer_ask|\/zpeer)\b/i.test(params.message)) return "loop guard blocked recursive ZPeer instruction";
   const messageHash = sha256(params.message);
   const now = Date.now();
   const windowMs = 60_000;
@@ -263,7 +275,11 @@ export function registerComsTools(pi: ExtensionAPI, state?: HarnessRuntimeState)
     name: "zpeer_ask",
     label: "ZPeer Ask",
     description: "Ask a visible local ZPeer via the governed room-scoped local_socket path. Defaults to mode=async; raw message/reply bodies are transient and durable metadata is hash-only.",
-    promptSnippet: "Use zpeer_ask with mode=\"async\" for useful non-trivial peer review/debug/planning coordination; if it returns waiting and nothing else is actionable, stop/idle instead of polling.",
+    promptSnippet: "Use zpeer_ask with mode=\"async\" for non-blocking coordination; when an actual reply/status is required, set requireResponse=true and use mode=\"await\" or mode=\"long\".",
+    promptGuidelines: [
+      "When the user asks for an actual reply, current status, confirmation, or a response requirement, call zpeer_ask with requireResponse=true and mode=\"await\" or mode=\"long\".",
+      "Treat zpeer_ask status=waiting as delivery-only: it does not prove the peer read the request, is working, or finished. If nothing else is actionable, stop/idle instead of polling.",
+    ],
     parameters: ZpeerAskParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       if (!state?.zobLive.peerCard) return { content: [{ type: "text", text: "zpeer_ask blocked: current session has not registered a local peer endpoint" }], details: { schema: "zob.zpeer-ask-result.v1", status: "blocked", reason: "local_peer_unavailable", bodyStored: false } };
@@ -275,16 +291,29 @@ export function registerComsTools(pi: ExtensionAPI, state?: HarnessRuntimeState)
       const requestedFromAlias = peerAliasInRoom(self, requestedRoomId) ?? self.zpeerAlias;
       const interrupt = normalizeZpeerInterrupt(params);
       const guardReason = interrupt.error ?? zpeerAskGuardBlock(state, params, requestedFromAlias, requestedRoomId, interrupt.priority);
-      const emitZpeerAskEvent = (event: { kind: NonNullable<HarnessRuntimeState["zobLive"]["lastEvent"]>["kind"]; status: string; reason?: string; msgId?: string; roomId?: string; taskHash?: string; outputHash?: string; interruptStatus?: ZpeerInterruptStatus }): void => {
+      const queuedZpeerEvents: Array<{ event: NonNullable<HarnessRuntimeState["zobLive"]["lastEvent"]>; content: string; details: Record<string, unknown> }> = [];
+      const flushZpeerAskEvents = async (): Promise<void> => {
+        for (const queued of queuedZpeerEvents) {
+          if (!isCurrentZpeerRuntimeEvent(state, queued.event)) continue;
+          await Promise.resolve(pi.sendMessage({
+            customType: "zob-zpeer-event",
+            content: queued.content,
+            display: true,
+            details: queued.details,
+          }, { triggerTurn: false, deliverAs: "nextTurn" }));
+        }
+      };
+      const emitZpeerAskEvent = (event: { kind: NonNullable<HarnessRuntimeState["zobLive"]["lastEvent"]>["kind"]; status: string; reason?: string; msgId?: string; roomId?: string; taskHash?: string; outputHash?: string; interruptStatus?: ZpeerInterruptStatus }): boolean => {
         const eventRoomId = event.roomId ?? requestedRoomId;
         const fromAlias = peerAliasInRoom(self, eventRoomId) ?? requestedFromAlias;
-        state.zobLive.lastEvent = { kind: event.kind, roomId: eventRoomId, fromAlias, toAlias: targetAlias, status: event.status, reason: event.reason, msgId: event.msgId, taskHash: event.taskHash, outputHash: event.outputHash, priority: interrupt.priority, interruptMode: interrupt.interruptMode, interruptStatus: event.interruptStatus, at: new Date().toISOString(), localOnly: true, networkEnabled: false, bodyStored: false };
-        void pi.sendMessage({
-          customType: "zob-zpeer-event",
+        const recorded = recordZpeerRuntimeEvent(state, { kind: event.kind, roomId: eventRoomId, fromAlias, toAlias: targetAlias, status: event.status, reason: event.reason, msgId: event.msgId, taskHash: event.taskHash, outputHash: event.outputHash, priority: interrupt.priority, interruptMode: interrupt.interruptMode, interruptStatus: event.interruptStatus });
+        if (!recorded.accepted) return false;
+        queuedZpeerEvents.push({
+          event: recorded.event,
           content: `ZPeer agent-request @${fromAlias ?? "?"} → @${targetAlias} ${event.status}`,
-          display: true,
-          details: { ...state.zobLive.lastEvent, source: "agent-request", mode, priority: interrupt.priority, interruptMode: interrupt.interruptMode, bodyStored: false, localOnly: true, networkEnabled: false },
-        }, { triggerTurn: false });
+          details: { ...recorded.event, source: "agent-request", mode, priority: interrupt.priority, interruptMode: interrupt.interruptMode, bodyStored: false, localOnly: true, networkEnabled: false },
+        });
+        return true;
       };
       const taskHash = params.message.trim() ? sha256(params.message) : undefined;
       if (guardReason) {
@@ -293,6 +322,7 @@ export function registerComsTools(pi: ExtensionAPI, state?: HarnessRuntimeState)
         const result = { schema: "zob.zpeer-ask-result.v1", status: "blocked", reason: guardReason, targetAlias, taskHash, priority: interrupt.priority, interruptMode: interrupt.interruptMode, interruptStatus, bodyStored: false };
         emitZpeerAskEvent({ kind: "blocked", status: "blocked", reason: guardReason, taskHash, interruptStatus });
         pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-ask.v1", action: "agent_request_blocked", mode, status: "blocked", priority: interrupt.priority, interruptMode: interrupt.interruptMode, interruptStatus, reasonHash: sha256(guardReason), targetAliasHash: sha256(targetAlias), roomIdHash: sha256(requestedRoomId), taskHash, reasonInputHash: params.reason ? sha256(params.reason) : undefined, interruptReasonHash: interrupt.interruptReasonHash, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
+        await flushZpeerAskEvents();
         return { content: [{ type: "text", text: `zpeer_ask blocked: ${guardReason}` }], details: result };
       }
       const timeoutMs = boundedZpeerAskTimeoutMs(mode, params.timeoutMs);
@@ -318,11 +348,12 @@ export function registerComsTools(pi: ExtensionAPI, state?: HarnessRuntimeState)
       updatePassivePeerWaitState(state, result, { roomId: requestedRoomId, targetAlias });
       pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-ask.v1", action: "agent_request", mode, status: result.status, priority: interrupt.priority, interruptMode: interrupt.interruptMode, interruptStatus: result.interruptStatus, reasonHash: result.reason ? sha256(result.reason) : undefined, msgId: result.msgId, targetAliasHash: result.targetAlias ? sha256(result.targetAlias) : sha256(targetAlias), roomIdHash: sha256(result.roomId ?? requestedRoomId), taskHash: result.taskHash, outputHash: result.outputHash, reasonInputHash: params.reason ? sha256(params.reason) : undefined, interruptReasonHash: interrupt.interruptReasonHash, requireResponse: requireResponse || undefined, responseRequiredBy: result.responseRequiredBy, responseTimeoutMs: result.responseTimeoutMs, maxReinjects: result.maxReinjects, responseReceived: result.responseReceived, deliveryStatus: result.deliveryStatus, deliveryMethod: result.deliveryMethod, fallbackDelivery: result.fallback_delivery, bestEffort: result.best_effort, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
       const ok = result.status === "reply" || result.status === "completed" || result.status === "waiting" || result.status === "delivered";
-      const passiveWaitSuffix = result.status === "waiting" ? " · idle/passive wait: no follow-up turn queued; stop if no other action is actionable" : "";
+      const passiveWaitSuffix = result.status === "waiting" ? " · delivery-only: no reply received; not evidence the target is working or done · idle/passive wait: no follow-up turn queued; stop if no other action is actionable" : "";
       const transientReplyText = (result.status === "reply" || result.status === "completed") && result.transientResponse
         ? `\n\nTransient ZPeer reply (not stored in .pi/coms):\n${result.transientResponse}`
         : "";
       const interruptSuffix = result.interruptStatus ? ` interrupt=${result.interruptStatus}` : interrupt.priority !== "normal" ? ` priority=${interrupt.priority}` : "";
+      await flushZpeerAskEvents();
       return { content: [{ type: "text", text: ok ? `zpeer_ask ${result.status}: @${result.targetAlias ?? targetAlias}${interruptSuffix}${result.outputHash ? ` outputHash=${result.outputHash}` : ""}${passiveWaitSuffix}${transientReplyText}` : `zpeer_ask ${result.status}: ${result.reason ?? "see metadata"}${interruptSuffix}` }], details: { schema: "zob.zpeer-ask-result.v1", mode, ...result } };
     },
   });
@@ -338,7 +369,13 @@ export function registerComsTools(pi: ExtensionAPI, state?: HarnessRuntimeState)
       const responseText = params.message ?? "";
       const outputHash = responseText.trim() ? sha256(responseText) : undefined;
       const inbound = msgId ? state?.zobLive.inboundByMsgId?.[msgId] : undefined;
-      const block = !state ? "zpeer runtime state unavailable" : !msgId ? "msgId is required" : !responseText.trim() ? "message is required" : !inbound ? "no active inbound ZPeer message for msgId" : inbound.responseSent || inbound.requiredResponseStatus === "replied" ? "ZPeer msgId already answered" : inbound.requiredResponseStatus === "expired" ? "ZPeer msgId required response already expired" : !inbound.envelope.replyEndpoint ? "ZPeer inbound msgId has no reply endpoint" : undefined;
+      const block = !state ? "zpeer runtime state unavailable" : !msgId ? "msgId is required" : !responseText.trim() ? "message is required" : !inbound ? "no active inbound ZPeer message for msgId" : inbound.responseSent || inbound.requiredResponseStatus === "replied" ? "ZPeer msgId already answered" : // ZOB-COMS-GUARDS: a late reply after the requireResponse watchdog expired is
+// now PERMITTED. The watchdog already stops reinjecting once reinjectCount hits
+// maxReinjects (events.ts) and the sender's pendingReplies entry resolves to a
+// no-op on a late envelope, so a late reply is harmless at the sender and
+// recovers nudge/reply paths (e.g. a late oracle review). The 'replied' /
+// responseSent guard above still prevents double-replies.
+!inbound.envelope.replyEndpoint ? "ZPeer inbound msgId has no reply endpoint" : undefined;
       if (block) {
         pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-reply.v1", action: "reply_blocked", status: "blocked", reasonHash: sha256(block), msgId, outputHash, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
         return { content: [{ type: "text", text: `zpeer_reply blocked: ${block}` }], details: { schema: "zob.zpeer-reply-result.v1", status: "blocked", reason: block, msgId, outputHash, bodyStored: false, localOnly: true, networkEnabled: false } };
@@ -357,8 +394,8 @@ export function registerComsTools(pi: ExtensionAPI, state?: HarnessRuntimeState)
         state.zobLive.activeInboundMsgId = undefined;
         state.zobLive.inboundQueue = (state.zobLive.inboundQueue ?? []).filter((candidate) => candidate !== inbound.envelope.msgId);
         const roomId = inbound.envelope.runId?.startsWith("zpeer:") ? inbound.envelope.runId.slice("zpeer:".length) : undefined;
-        state.zobLive.lastEvent = { kind: "response_sent", roomId, fromAlias: inbound.envelope.receiver, toAlias: inbound.envelope.sender, status: "response_sent", msgId: inbound.envelope.msgId, taskHash: inbound.envelope.taskHash, outputHash, priority: inbound.priority, interruptMode: inbound.interruptMode, at: new Date().toISOString(), localOnly: true, networkEnabled: false, bodyStored: false };
-        void pi.sendMessage({ customType: "zob-zpeer-event", content: "ZPeer explicit reply sent", display: true, details: { ...state.zobLive.lastEvent } }, { triggerTurn: false });
+        const recorded = recordZpeerRuntimeEvent(state, { kind: "response_sent", roomId, fromAlias: inbound.envelope.receiver, toAlias: inbound.envelope.sender, status: "response_sent", msgId: inbound.envelope.msgId, taskHash: inbound.envelope.taskHash, outputHash, priority: inbound.priority, interruptMode: inbound.interruptMode });
+        if (recorded.accepted) void pi.sendMessage({ customType: "zob-zpeer-event", content: "ZPeer explicit reply sent", display: true, details: { ...recorded.event } }, { triggerTurn: false, deliverAs: "nextTurn" });
         pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-reply.v1", action: "reply", status: "response_sent", msgId: inbound.envelope.msgId, taskHash: inbound.envelope.taskHash, outputHash, priority: inbound.priority, interruptMode: inbound.interruptMode, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
         return { content: [{ type: "text", text: `zpeer_reply sent: msgId=${inbound.envelope.msgId} outputHash=${outputHash}` }], details: { schema: "zob.zpeer-reply-result.v1", status: "response_sent", msgId: inbound.envelope.msgId, taskHash: inbound.envelope.taskHash, outputHash, bodyStored: false, localOnly: true, networkEnabled: false } };
       } catch (error) {

package/.pi/extensions/zob-harness/src/runtime/zpeer-events.ts

@@ -0,0 +1,53 @@
+import { annotateZpeerStatus, shouldAcceptZpeerStatusUpdate } from "../domains/coms/coms-v2/zpeer-status.js";
+import type { HarnessRuntimeState, ZobLiveLastEvent } from "./state.js";
+
+export type ZpeerRuntimeEventInput = Omit<ZobLiveLastEvent, "at" | "localOnly" | "networkEnabled" | "bodyStored" | "terminal" | "statusRank" | "superseded" | "supersededByStatus"> & { at?: string };
+
+export interface ZpeerRuntimeEventRecordResult {
+  accepted: boolean;
+  event: ZobLiveLastEvent;
+  current?: ZobLiveLastEvent;
+}
+
+function materializeZpeerRuntimeEvent(event: ZpeerRuntimeEventInput): ZobLiveLastEvent {
+  return annotateZpeerStatus({
+    ...event,
+    at: event.at ?? new Date().toISOString(),
+    localOnly: true as const,
+    networkEnabled: false as const,
+    bodyStored: false as const,
+  });
+}
+
+export function recordZpeerRuntimeEvent(state: HarnessRuntimeState, event: ZpeerRuntimeEventInput): ZpeerRuntimeEventRecordResult {
+  const next = materializeZpeerRuntimeEvent(event);
+  if (!next.msgId) {
+    state.zobLive.lastEvent = next;
+    return { accepted: true, event: next };
+  }
+
+  state.zobLive.latestZpeerEventByMsgId ??= {};
+  const current = state.zobLive.latestZpeerEventByMsgId[next.msgId];
+  if (!shouldAcceptZpeerStatusUpdate(current, next)) {
+    return {
+      accepted: false,
+      current,
+      event: {
+        ...next,
+        superseded: true,
+        supersededByStatus: current?.status,
+      },
+    };
+  }
+
+  state.zobLive.latestZpeerEventByMsgId[next.msgId] = next;
+  state.zobLive.lastEvent = next;
+  return { accepted: true, event: next, current: next };
+}
+
+export function isCurrentZpeerRuntimeEvent(state: HarnessRuntimeState, event: ZobLiveLastEvent): boolean {
+  if (!event.msgId) return true;
+  const current = state.zobLive.latestZpeerEventByMsgId?.[event.msgId];
+  if (!current) return true;
+  return current.at === event.at && current.status === event.status && current.kind === event.kind;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zob-harness",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "type": "module",
   "description": "A governed Agent Factory for Pi: launch communicating agent teams, run tmux-backed factories, validate artifacts, and package repeatable workflows.",
   "license": "MIT",

package/scripts/zpeer-local-e2e-smoke.mjs

@@ -471,10 +471,11 @@ async function main() {
   const registeredTools = new Map();
   const appendEntries = [];
   const feedMessages = [];
+  const feedDeliveries = [];
   const mockPi = {
     registerTool: (tool) => registeredTools.set(tool.name, tool),
     appendEntry: (customType, data) => appendEntries.push({ customType, data }),
-    sendMessage: (message) => { feedMessages.push(message); return Promise.resolve(); },
+    sendMessage: (message, options) => { feedMessages.push(message); feedDeliveries.push({ message, options }); return Promise.resolve(); },
   };
   const toolState = { zobLive: { peerCard: alpha, pendingReplies: { wait: waitForReply } } };
   toolsComs.registerComsTools(mockPi, toolState);
@@ -488,6 +489,9 @@ async function main() {
   assert(JSON.stringify(toolResult?.content ?? '').includes('idle/passive wait: no follow-up turn queued'), 'zpeer_ask async waiting result must tell the agent to idle instead of polling/continuing just to wait');
   const asyncWaitingFeed = feedMessages.filter((item) => item.customType === 'zob-zpeer-event' && item.details?.source === 'agent-request' && item.details?.status === 'waiting' && item.details?.msgId === toolResult?.details?.msgId);
   assert(asyncWaitingFeed.length === 1, `zpeer_ask async must emit exactly one compact waiting feed event, got ${asyncWaitingFeed.length}`);
+  const asyncWaitingDelivery = feedDeliveries.find((item) => item.message.details?.source === 'agent-request' && item.message.details?.msgId === toolResult?.details?.msgId);
+  assert(asyncWaitingDelivery?.options?.triggerTurn === false && asyncWaitingDelivery?.options?.deliverAs === 'nextTurn', 'zpeer_ask waiting feed must use nextTurn delivery and never create an extra steering/follow-up turn');
+  assert(JSON.stringify(toolResult?.content ?? '').includes('delivery-only: no reply received; not evidence the target is working or done'), 'zpeer_ask waiting result must not imply peer progress from delivery-only status');
   assert(!feedMessages.some((item) => item.customType === 'zob-zpeer-event' && item.details?.source === 'agent-request' && item.details?.kind === 'attempt'), 'zpeer_ask async must not emit a pre-ACK attempt feed event');
   assert(!containsRawBody(toolResult), 'zpeer_ask async tool result must not echo the full prompt/response body');
   assert(appendEntries.some((item) => item.customType === 'zob-zpeer' && item.data?.schema === 'zob.zpeer-ask.v1' && item.data?.action === 'agent_request' && item.data?.mode === 'async' && item.data?.bodyStored === false), 'zpeer_ask must append hash-only visible command metadata');
@@ -538,6 +542,8 @@ async function main() {
   const explicitReplyCountBefore = receivedResponses.length;
   const explicitReplyResult = await zpeerReply.execute('tool-call-zpeer-reply', { msgId: explicitReplyMsgId, message: rawResponse }, undefined, undefined, { cwd: repoRoot });
   assert(explicitReplyResult?.details?.status === 'response_sent' && explicitReplyResult?.details?.msgId === explicitReplyMsgId && explicitReplyResult?.details?.outputHash === hashing.sha256(rawResponse), 'zpeer_reply must send a msgId-bound response with outputHash metadata');
+  const explicitReplyFeedDelivery = feedDeliveries.find((item) => item.message.details?.kind === 'response_sent' && item.message.details?.msgId === explicitReplyMsgId);
+  assert(explicitReplyFeedDelivery?.options?.triggerTurn === false && explicitReplyFeedDelivery?.options?.deliverAs === 'nextTurn', 'zpeer_reply feed must use nextTurn delivery and never create an extra steering/follow-up turn');
   assert(!toolState.zobLive.inboundByMsgId?.[explicitReplyMsgId] && toolState.zobLive.activeInboundMsgId === undefined && toolState.zobLive.inboundQueue.length === 0, 'zpeer_reply must clear the answered inbound msgId from receiver state');
   assert(receivedResponses.length > explicitReplyCountBefore && receivedResponses.at(-1)?.replyToMsgId === explicitReplyMsgId && receivedResponses.at(-1)?.responseHash === hashing.sha256(rawResponse), 'zpeer_reply must deliver a local response envelope bound to replyToMsgId');
   const wrongExplicitReply = await zpeerReply.execute('tool-call-zpeer-reply-wrong', { msgId: 'missing-msgid', message: rawResponse }, undefined, undefined, { cwd: repoRoot });

package/scripts/zpeer-static-smoke.mjs

@@ -61,10 +61,11 @@ const zpeerAskMatches = toolsComs.match(/name: "zpeer_ask"/g) ?? [];
 if (zpeerAskMatches.length !== 1) failures.push(`expected exactly one zpeer_ask tool, found ${zpeerAskMatches.length}`);
 const zpeerReplyMatches = toolsComs.match(/name: "zpeer_reply"/g) ?? [];
 if (zpeerReplyMatches.length !== 1) failures.push(`expected exactly one zpeer_reply tool, found ${zpeerReplyMatches.length}`);
-for (const needle of ['parameters: ZpeerAskParams', 'sendZpeerPrompt(ctx.cwd', 'mode = params.mode ?? "async"', 'requireResponse = params.requireResponse === true', 'pendingReplies.wait(msgId, timeoutMs, { requireResponse })', 'maxReinjects', 'zpeerAskGuardBlock', 'ZPEER_AGENT_ASK_RATE_LIMIT_PER_MINUTE = 50', 'ZPEER_AGENT_URGENT_RATE_LIMIT_PER_MINUTE = 10', 'ZPEER_AGENT_FORCE_RATE_LIMIT_PER_MINUTE = 3', 'normalizeZpeerInterrupt', 'force interrupt requires reason', 'max ${ZPEER_AGENT_ASK_RATE_LIMIT_PER_MINUTE} agent-initiated ZPeer asks per 60s window', 'idle/passive wait: no follow-up turn queued', 'customType: "zob-zpeer-event"', 'source: "agent-request"', 'action: "agent_request"', 'feedbackEmittedTerminal', 'reasonInputHash', 'interruptReasonHash', 'buildProjectTransposerFallbackDelivery(ctx.cwd)', 'PROJECT_TRANSPOSER_ZPEER_FALLBACK_HOOK', 'fallbackDelivery: result.fallback_delivery', 'bestEffort: result.best_effort', 'bodyStored: false', 'promptBodiesStored: false', 'outputBodiesStored: false']) {
+for (const needle of ['parameters: ZpeerAskParams', 'sendZpeerPrompt(ctx.cwd', 'mode = params.mode ?? "async"', 'requireResponse = params.requireResponse === true', 'pendingReplies.wait(msgId, timeoutMs, { requireResponse })', 'maxReinjects', 'zpeerAskGuardBlock', 'clampRate(process.env.ZOB_ZPEER_ASK_RATE_LIMIT_PER_MINUTE, 50)', 'clampRate(process.env.ZOB_ZPEER_URGENT_RATE_LIMIT_PER_MINUTE, 10)', 'clampRate(process.env.ZOB_ZPEER_FORCE_RATE_LIMIT_PER_MINUTE, 3)', 'normalizeZpeerInterrupt', 'force interrupt requires reason', 'max ${ZPEER_AGENT_ASK_RATE_LIMIT_PER_MINUTE} agent-initiated ZPeer asks per 60s window', 'idle/passive wait: no follow-up turn queued', 'delivery-only: no reply received; not evidence the target is working or done', 'promptGuidelines:', 'requireResponse=true and mode=\\"await\\" or mode=\\"long\\"', 'customType: "zob-zpeer-event"', 'source: "agent-request"', 'action: "agent_request"', 'feedbackEmittedTerminal', 'reasonInputHash', 'interruptReasonHash', 'buildProjectTransposerFallbackDelivery(ctx.cwd)', 'PROJECT_TRANSPOSER_ZPEER_FALLBACK_HOOK', 'fallbackDelivery: result.fallback_delivery', 'bestEffort: result.best_effort', 'bodyStored: false', 'promptBodiesStored: false', 'outputBodiesStored: false']) {
   if (!toolsComs.includes(needle)) failures.push(`zpeer_ask tool missing ${needle}`);
 }
-for (const needle of ['parameters: ZpeerReplyParams', 'buildZobLiveResponseEnvelope', 'sendZobLocalEnvelope(replyEndpoint', 'replyToMsgId: inbound.envelope.msgId', 'action: "reply"', 'action: "reply_blocked"', 'status: "response_sent"', 'ZPeer msgId required response already expired']) {
+if (!toolsComs.includes('}, { triggerTurn: false, deliverAs: "nextTurn" }')) failures.push('zpeer tool feed cards must use nextTurn delivery so metadata-only UI cannot create steering turns');
+for (const needle of ['parameters: ZpeerReplyParams', 'buildZobLiveResponseEnvelope', 'sendZobLocalEnvelope(replyEndpoint', 'replyToMsgId: inbound.envelope.msgId', 'action: "reply"', 'action: "reply_blocked"', 'status: "response_sent"', 'late reply after the requireResponse watchdog expired']) {
   if (!toolsComs.includes(needle)) failures.push(`zpeer_reply tool missing ${needle}`);
 }
 if (toolsComs.includes('emitZpeerAskEvent({ kind: "attempt", status: "agent-request"')) failures.push('zpeer_ask async must not emit pre-ACK attempt feed noise');
@@ -178,6 +179,7 @@ for (const needle of ['customType: "zob-zpeer-event"', 'if (sendMode.mode !== "a
   if (!command.includes(needle)) failures.push(`zpeer command missing UX event/status support ${needle}`);
 }
 if (!command.includes('const eventFromAlias = peerAliasInRoom(state.zobLive.peerCard, eventRoomId)') || !command.includes('peerAliasInRoom(state.zobLive.peerCard, resultRoomId)')) failures.push('/zpeer in <room> events must use room-scoped sender alias');
+if (!command.includes('}, { triggerTurn: false, deliverAs: "nextTurn" });')) failures.push('/zpeer feed cards must use nextTurn delivery so metadata-only UI cannot create steering turns');
 for (const forbidden of ['transientPrompt:', 'transientResponse:', 'prompt:', 'output:', 'content:', 'message:', 'text:', 'diff:', 'patch:']) {
   const appendBlocks = [...command.matchAll(/appendEntry\("zob-zpeer",\s*\{[\s\S]*?\}\);/g)].map((m) => m[0]);
   if (appendBlocks.some((block) => block.includes(forbidden))) failures.push(`zpeer appendEntry contains forbidden key ${forbidden}`);
@@ -215,6 +217,9 @@ for (const needle of ['readZpeerNewCarryoverProfile(repoRoot)', 'const carryover
 }
 if (!events.includes('event.source === "extension" && !event.text.trim()') || !events.includes('action: "handled" as const')) failures.push('runtime must handle empty extension follow-ups without continuing the agent');
 if (!events.includes('ZPeer async reply received from @') || !events.includes('{ triggerTurn: true, deliverAs: "followUp" }')) failures.push('runtime must resume an idle agent with a follow-up when an async ZPeer reply arrives');
+const eventZpeerFeedFragments = events.split('customType: "zob-zpeer-event"').slice(1);
+if (eventZpeerFeedFragments.length === 0 || eventZpeerFeedFragments.some((fragment) => !fragment.slice(0, 800).includes('}, { triggerTurn: false, deliverAs: "nextTurn" });'))) failures.push('every runtime ZPeer feed card must use nextTurn delivery so it cannot race ahead of actionable prompt/response bodies');
+if (!events.includes('status=waiting is delivery-only, not evidence that the peer is working or done')) failures.push('runtime awareness must prevent interpreting waiting as peer progress/completion evidence');
 for (const needle of ['forceAbortAllowedForCurrentState', 'interruptStatus = "force_blocked"', 'interruptStatus = "force_downgraded"', 'ctx.abort()', 'const deliverAs = priority === "normal" ? "followUp" : "steer"', 'inboundByMsgId', 'activeInboundMsgId', 'state.zobLive.inboundByMsgId && !activeInbound', 'scheduleZpeerRequiredResponseWatchdog', 'required_response_reinject', 'required_response_expired', 'Original transient message:', 'zpeer_required_response_expired', 'pendingReplies.expire', 'forceAbortRepeated: false', 'replyToMsgId !== envelope.msgId', 'wrong or missing replyToMsgId']) {
   if (!events.includes(needle)) failures.push(`runtime missing urgent/force/msgId-safe inbound support ${needle}`);
 }