zob-harness 0.14.0 → 0.15.0

package/.pi/capabilities/zob-public-runtime-capabilities.json

@@ -719,7 +719,27 @@
       "docRefs": [
         ".pi/extensions/zob-harness/src/AGENTS.md"
       ],
-      "noShipNotes": "Agent-initiated visible ZPeer ask; local_socket only, room-scoped with optional explicit roomId, mode defaults async, normal/urgent/force are rate/loop guarded, force requires a hashed reason and role/topology guards, raw bodies transient and durable records hash-only."
+      "noShipNotes": "Agent-initiated visible ZPeer ask; local_socket only, room-scoped with optional explicit roomId, mode defaults async, opt-in requireResponse tracks msgId-correlated replies with bounded timeout/reinjection metadata, normal/urgent/force are rate/loop guarded, force requires a hashed reason and role/topology guards, raw bodies transient and durable records hash-only."
+    },
+    {
+      "name": "zpeer_reply",
+      "family": "coms-v2-live",
+      "modes": [
+        "explore",
+        "plan",
+        "implement",
+        "oracle",
+        "factory",
+        "orchestrator"
+      ],
+      "skillRefs": [
+        ".pi/skills/zob-coms-v2-live/SKILL.md",
+        ".pi/skills/zob-coms-safety/SKILL.md"
+      ],
+      "docRefs": [
+        ".pi/extensions/zob-harness/src/AGENTS.md"
+      ],
+      "noShipNotes": "Explicit msgId-bound ZPeer reply path for active inbound messages; local_socket only, requires exact active msgId, wrong/expired/already-answered msgIds are blocked, raw reply body is transient and durable metadata stores outputHash/status only."
     },
     {
       "name": "zob_goal_room_send",
@@ -1671,7 +1691,7 @@
         "AGENTS.md",
         ".pi/extensions/zob-harness/src/AGENTS.md"
       ],
-      "noShipNotes": "Local-only multi-room-scoped peer UX with active-room compatibility; transient prompt/response over local_socket, persisted command/mission metadata is hash/body-free."
+      "noShipNotes": "Local-only multi-room-scoped peer UX with active-room compatibility; supports /zpeer reply <msgId> <response> and --require-response; transient prompt/response over local_socket, persisted command/mission metadata is hash/body-free."
     },
     {
       "name": "zagent",

package/.pi/extensions/zob-harness/src/core/constants.ts

@@ -46,7 +46,7 @@ export const SUPERVISED_READONLY_CHILD_TOOLS = ["read", "grep", "find", "ls"] as
 export const READ_ONLY_CHAIN_TOOLS = ["read", "grep", "find", "ls"] as const;
 export const BLOCKED_CHAIN_TOOLS = ["bash", "edit", "write", "delegate_agent", "delegate_task", "orchestrate_run", "factory_run", "factory_quarantine_review", "factory_quarantine_activate", "factory_quarantine_verify_activation", "chain_run"] as const;
 
-export const ZOB_COMS_TOOLS = ["zob_coms_send", "zob_coms_ack", "zob_coms_status", "zob_coms_reply", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask"] as const;
+export const ZOB_COMS_TOOLS = ["zob_coms_send", "zob_coms_ack", "zob_coms_status", "zob_coms_reply", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zpeer_reply"] as const;
 export const ZOB_GOAL_ROOM_TOOLS = ["zob_goal_room_send", "zob_goal_room_list"] as const;
 export const ZOB_GOVERNED_REQUEST_TOOLS = ["zob_governed_request_extract"] as const;
 export const ZOB_WORKSPACE_CLAIM_TOOLS = ["zob_workspace_claim", "zob_workspace_release", "zob_workspace_claims_list"] as const;
@@ -70,10 +70,10 @@ export const ZOB_AUTONOMOUS_READ_TOOLS = ["zob_autonomous_validate_run", "zob_au
 export const ZOB_AUTONOMOUS_FACTORY_TOOLS = ["zob_autonomous_dry_run", "zob_autonomous_readonly_smoke"] as const;
 
 export const MODE_TOOLS: Record<ModeName, string[]> = {
-  explore: ["read", "grep", "find", "ls", "bash", "delegate_agent", "delegate_task", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zob_goal_room_list", "zob_workspace_claims_list", "zob_worker_pool_status", "zob_merge_queue_list", ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS],
+  explore: ["read", "grep", "find", "ls", "bash", "delegate_agent", "delegate_task", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zpeer_reply", "zob_goal_room_list", "zob_workspace_claims_list", "zob_worker_pool_status", "zob_merge_queue_list", ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS],
   plan: ["read", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
   implement: ["read", "bash", "edit", "write", "grep", "find", "ls", "delegate_agent", "delegate_task", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
-  oracle: ["read", "grep", "find", "ls", "bash", "delegate_agent", "delegate_task", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zob_goal_room_list", "zob_workspace_claims_list", "zob_worker_pool_status", "zob_merge_queue_list", ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS],
+  oracle: ["read", "grep", "find", "ls", "bash", "delegate_agent", "delegate_task", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zpeer_reply", "zob_goal_room_list", "zob_workspace_claims_list", "zob_worker_pool_status", "zob_merge_queue_list", ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS],
   orchestrator: ["read", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS],
   factory: ["read", "bash", "edit", "write", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "factory_run", "factory_quarantine_review", "factory_quarantine_activate", "factory_quarantine_verify_activation", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_AUTONOMOUS_FACTORY_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
   // Vanilla is handled specially by applyMode: all currently available Pi tools are enabled.

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

@@ -28,6 +28,13 @@ export interface ZobLiveEnvelope {
   artifactHashes?: string[];
   replyEndpoint?: string;
   replyEndpointHash?: string;
+  requireResponse?: boolean;
+  responseTimeoutMs?: number;
+  responseRequiredBy?: string;
+  maxReinjects?: number;
+  reinjectCount?: number;
+  replyToMsgId?: string;
+  responseHash?: string;
   transientPrompt?: string;
   transientResponse?: string;
   priority?: ZpeerInterruptPriority;
@@ -76,6 +83,10 @@ export function buildZobLiveAckEnvelope(request: ZobLiveEnvelope, interruptStatu
     interruptMode: request.interruptMode,
     interruptReasonHash: request.interruptReasonHash,
     interruptStatus: interruptStatus ?? request.interruptStatus,
+    requireResponse: request.requireResponse,
+    responseTimeoutMs: request.responseTimeoutMs,
+    responseRequiredBy: request.responseRequiredBy,
+    maxReinjects: request.maxReinjects,
   });
 }
 
@@ -122,6 +133,18 @@ export function validateZobLiveEnvelope(value: unknown): string[] {
   if (value.interruptMode !== undefined && (typeof value.interruptMode !== "string" || !ZPEER_INTERRUPT_MODES.has(value.interruptMode))) errors.push("ZOB live envelope interruptMode is invalid");
   if (value.interruptReasonHash !== undefined && (typeof value.interruptReasonHash !== "string" || !/^[a-f0-9]{64}$/i.test(value.interruptReasonHash))) errors.push("ZOB live envelope interruptReasonHash must be sha256 hex when provided");
   if (value.interruptStatus !== undefined && (typeof value.interruptStatus !== "string" || !ZPEER_INTERRUPT_STATUSES.has(value.interruptStatus))) errors.push("ZOB live envelope interruptStatus is invalid");
+  if (value.requireResponse !== undefined && typeof value.requireResponse !== "boolean") errors.push("ZOB live envelope requireResponse must be boolean when provided");
+  if (value.responseTimeoutMs !== undefined && (typeof value.responseTimeoutMs !== "number" || !Number.isFinite(value.responseTimeoutMs) || value.responseTimeoutMs < 25 || value.responseTimeoutMs > 30 * 60 * 1000)) errors.push("ZOB live envelope responseTimeoutMs must be 25..1800000 when provided");
+  if (value.responseRequiredBy !== undefined && (typeof value.responseRequiredBy !== "string" || !Number.isFinite(Date.parse(value.responseRequiredBy)))) errors.push("ZOB live envelope responseRequiredBy must be an ISO timestamp when provided");
+  if (value.maxReinjects !== undefined && (typeof value.maxReinjects !== "number" || !Number.isInteger(value.maxReinjects) || value.maxReinjects < 0 || value.maxReinjects > 3)) errors.push("ZOB live envelope maxReinjects must be 0..3 when provided");
+  if (value.reinjectCount !== undefined && (typeof value.reinjectCount !== "number" || !Number.isInteger(value.reinjectCount) || value.reinjectCount < 0 || value.reinjectCount > 3)) errors.push("ZOB live envelope reinjectCount must be 0..3 when provided");
+  if (value.replyToMsgId !== undefined && (typeof value.replyToMsgId !== "string" || value.replyToMsgId.trim().length === 0)) errors.push("ZOB live envelope replyToMsgId must be non-empty when provided");
+  if (value.responseHash !== undefined && (typeof value.responseHash !== "string" || !/^[a-f0-9]{64}$/i.test(value.responseHash))) errors.push("ZOB live envelope responseHash must be sha256 hex when provided");
+  if (value.type === "prompt" && value.requireResponse === true) {
+    if (typeof value.replyEndpoint !== "string" || value.replyEndpoint.length === 0) errors.push("ZOB live required-response prompt requires replyEndpoint");
+    if (typeof value.responseRequiredBy !== "string") errors.push("ZOB live required-response prompt requires responseRequiredBy");
+  }
+  if (value.type === "response" && value.replyToMsgId !== value.msgId) errors.push("ZOB live response replyToMsgId must match msgId");
   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");

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

@@ -2,7 +2,7 @@ import type { ZobLiveEnvelope } from "./envelope.js";
 
 export interface ZobPendingReplyResult {
   msgId: string;
-  status: "completed" | "error" | "timeout";
+  status: "completed" | "error" | "timeout" | "required_response_expired";
   envelope?: ZobLiveEnvelope;
   errorHash?: string;
 }
@@ -10,6 +10,7 @@ export interface ZobPendingReplyResult {
 interface PendingReply {
   msgId: string;
   createdAt: number;
+  requireResponse: boolean;
   resolve: (result: ZobPendingReplyResult) => void;
   timer: ReturnType<typeof setTimeout>;
 }
@@ -17,11 +18,16 @@ interface PendingReply {
 export class ZobPendingReplies {
   private readonly pending = new Map<string, PendingReply>();
   private readonly completed = new Map<string, ZobPendingReplyResult>();
+  private readonly expired = new Set<string>();
 
-  wait(msgId: string, timeoutMs: number): Promise<ZobPendingReplyResult> {
+  wait(msgId: string, timeoutMs: number, options: { requireResponse?: boolean } = {}): Promise<ZobPendingReplyResult> {
     const completed = this.completed.get(msgId);
     if (completed) {
       this.completed.delete(msgId);
+      if (options.requireResponse === true && completed.status === "completed" && completed.envelope?.replyToMsgId !== msgId) {
+        this.expired.add(msgId);
+        return Promise.resolve({ msgId, status: "required_response_expired" });
+      }
       return Promise.resolve(completed);
     }
     const boundedTimeout = Math.max(25, Math.min(30 * 60 * 1000, Math.floor(timeoutMs)));
@@ -29,22 +35,27 @@ export class ZobPendingReplies {
     return new Promise<ZobPendingReplyResult>((resolve) => {
       const timer = setTimeout(() => {
         this.pending.delete(msgId);
-        resolve({ msgId, status: "timeout" });
+        if (options.requireResponse === true) this.expired.add(msgId);
+        resolve({ msgId, status: options.requireResponse === true ? "required_response_expired" : "timeout" });
       }, boundedTimeout);
       timer.unref?.();
-      this.pending.set(msgId, { msgId, createdAt: Date.now(), resolve, timer });
+      this.pending.set(msgId, { msgId, createdAt: Date.now(), requireResponse: options.requireResponse === true, resolve, timer });
     });
   }
 
   complete(msgId: string, envelope: ZobLiveEnvelope): boolean {
-    const result: ZobPendingReplyResult = { msgId, status: "completed", envelope };
+    if (this.expired.has(msgId)) return false;
     const item = this.pending.get(msgId);
+    if (item?.requireResponse && envelope.replyToMsgId !== msgId) return false;
+    if (envelope.replyToMsgId !== undefined && envelope.replyToMsgId !== msgId) return false;
+    const result: ZobPendingReplyResult = { msgId, status: "completed", envelope };
     if (!item) {
       this.completed.set(msgId, result);
       return false;
     }
     clearTimeout(item.timer);
     this.pending.delete(msgId);
+    this.expired.delete(msgId);
     item.resolve(result);
     return true;
   }
@@ -58,11 +69,27 @@ export class ZobPendingReplies {
     }
     clearTimeout(item.timer);
     this.pending.delete(msgId);
+    this.expired.delete(msgId);
+    item.resolve(result);
+    return true;
+  }
+
+  expire(msgId: string, errorHash?: string): boolean {
+    const result: ZobPendingReplyResult = { msgId, status: "required_response_expired", errorHash };
+    this.expired.add(msgId);
+    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 {
+    this.expired.delete(msgId);
     const item = this.pending.get(msgId);
     if (!item) return false;
     clearTimeout(item.timer);
@@ -75,6 +102,7 @@ export class ZobPendingReplies {
     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 })),
+      ...[...this.expired.values()].map((msgId) => ({ msgId, status: "required_response_expired", bodyStored: false })),
     ];
   }
 }

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

@@ -45,6 +45,8 @@ export function buildZobLiveResponseEnvelope(request: ZobLiveEnvelope, transient
     outputHash: capture.outputHash,
     artifactRefs: capture.artifactRefs,
     artifactHashes: capture.artifactHashes,
+    replyToMsgId: request.msgId,
+    responseHash: capture.outputHash,
     transientResponse,
   });
 }

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

@@ -43,7 +43,7 @@ export interface ZpeerPeerRoomSummary extends ZpeerRoomSummary {
 }
 
 export type ZpeerSendMode = "await" | "async" | "long";
-export type ZpeerSendStatus = "delivered" | "waiting" | "reply" | "completed" | "blocked" | "error" | "timeout" | "expired";
+export type ZpeerSendStatus = "delivered" | "waiting" | "reply" | "completed" | "blocked" | "error" | "timeout" | "expired" | "required_response_expired";
 
 export interface ZpeerSendResult {
   status: ZpeerSendStatus;
@@ -58,6 +58,12 @@ export interface ZpeerSendResult {
   interruptMode?: ZpeerInterruptMode;
   interruptStatus?: ZpeerInterruptStatus;
   interruptReasonHash?: string;
+  requireResponse?: boolean;
+  responseRequiredBy?: string;
+  responseTimeoutMs?: number;
+  maxReinjects?: number;
+  responseReceived?: boolean;
+  deliveryStatus?: "delivered" | "blocked" | "stale" | "offline" | "transport_error";
   deliveryMethod?: "local_socket" | "tmux_sendkeys";
   fallback_delivery?: boolean;
   best_effort?: boolean;
@@ -75,6 +81,9 @@ export interface ZpeerSendOptions {
   priority?: ZpeerInterruptPriority;
   interruptMode?: ZpeerInterruptMode;
   interruptReasonHash?: string;
+  requireResponse?: boolean;
+  responseTimeoutMs?: number;
+  maxReinjects?: number;
   onFeedback?: (feedback: ZpeerSendFeedback) => void;
   // WS-ZH4: optional best-effort fallback delivery seam. When local-socket delivery is
   // blocked (0 live candidates), the app may inject a fallback (e.g. tmux send-keys to
@@ -425,6 +434,12 @@ function appendZpeerPeerRecords(repoRoot: string, record: {
   interruptMode?: ZpeerInterruptMode;
   interruptStatus?: ZpeerInterruptStatus;
   interruptReasonHash?: string;
+  requireResponse?: boolean;
+  responseRequiredBy?: string;
+  responseTimeoutMs?: number;
+  maxReinjects?: number;
+  responseReceived?: boolean;
+  deliveryStatus?: "delivered" | "blocked" | "stale" | "offline" | "transport_error";
   deliveryMethod?: "local_socket" | "tmux_sendkeys";
   fallbackDelivery?: boolean;
 }): void {
@@ -444,6 +459,12 @@ function appendZpeerPeerRecords(repoRoot: string, record: {
     interruptMode: record.interruptMode,
     interruptStatus: record.interruptStatus,
     interruptReasonHash: record.interruptReasonHash,
+    requireResponse: record.requireResponse,
+    responseRequiredBy: record.responseRequiredBy,
+    responseTimeoutMs: record.responseTimeoutMs,
+    maxReinjects: record.maxReinjects,
+    responseReceived: record.responseReceived,
+    deliveryStatus: record.deliveryStatus,
     deliveryMethod: record.deliveryMethod,
     fallbackDelivery: record.fallbackDelivery,
     localOnly: true,
@@ -495,6 +516,9 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
   const interruptMode = options.interruptMode ?? (priority === "force" ? "abort" : priority === "urgent" ? "steer" : "none");
   const interruptReasonHash = options.interruptReasonHash;
   const interruptRequested = priority !== "normal" || interruptMode !== "none";
+  const requireResponse = options.requireResponse === true;
+  const responseTimeoutMs = Math.max(1_000, Math.min(30 * 60 * 1000, Math.floor(options.responseTimeoutMs ?? (mode === "long" ? 30 * 60 * 1000 : 10 * 60 * 1000))));
+  const maxReinjects = Math.max(0, Math.min(3, Math.floor(options.maxReinjects ?? 1)));
   const emitFeedback = (kind: ZpeerSendFeedback["kind"], result: ZpeerSendResult): void => {
     options.onFeedback?.({ kind, result });
   };
@@ -514,10 +538,16 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
       interruptMode: result.interruptMode ?? interruptMode,
       interruptStatus: result.interruptStatus,
       interruptReasonHash: result.interruptReasonHash ?? interruptReasonHash,
+      requireResponse: result.requireResponse,
+      responseRequiredBy: result.responseRequiredBy,
+      responseTimeoutMs: result.responseTimeoutMs,
+      maxReinjects: result.maxReinjects,
+      responseReceived: result.responseReceived,
+      deliveryStatus: result.deliveryStatus,
       deliveryMethod: result.deliveryMethod,
       fallbackDelivery: result.fallback_delivery,
     });
-    return { roomId, priority, interruptMode, interruptReasonHash, ...result };
+    return { 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 });
@@ -578,7 +608,8 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
   if (self.transport !== "local_socket" || !self.endpoint || self.endpoint.startsWith("pending-") || self.endpoint === "observe-only") return finish("attempt", { status: "blocked", reason: "current session has no local_socket reply endpoint", targetAlias, taskHash, bodyStored: false }, 1);
 
   const msgId = `zpeer:${self.sessionHash.slice(0, 8)}:${target.peer.sessionHash.slice(0, 8)}:${Date.now()}`;
-  finish("attempt", { status: "delivered", msgId, targetAlias, taskHash, bodyStored: false }, 1);
+  const responseRequiredBy = requireResponse ? new Date(Date.now() + responseTimeoutMs).toISOString() : undefined;
+  finish("attempt", { status: "delivered", msgId, targetAlias, taskHash, requireResponse: requireResponse || undefined, responseRequiredBy, responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined, maxReinjects: requireResponse ? maxReinjects : undefined, deliveryStatus: "delivered", responseReceived: requireResponse ? false : undefined, bodyStored: false }, 1);
   const liveEnvelope = buildZobLiveEnvelope({
     type: "prompt",
     msgId,
@@ -594,6 +625,10 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
     interruptRequested,
     interruptMode,
     interruptReasonHash,
+    requireResponse: requireResponse || undefined,
+    responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined,
+    responseRequiredBy,
+    maxReinjects: requireResponse ? maxReinjects : undefined,
   });
   try {
     const ack = await sendZobLocalEnvelope(target.peer.endpoint, liveEnvelope, { timeoutMs: 5_000 });
@@ -601,27 +636,32 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
     const ackInterruptStatus = ack.interruptStatus;
     appendZpeerPeerRecords(repoRoot, { event: "ack", status: "delivered", roomId, msgId, senderAlias, targetAlias, taskHash, priority, interruptMode, interruptStatus: ackInterruptStatus, interruptReasonHash, peerCount: 1 });
     if (ackInterruptStatus === "force_blocked") return finish("terminal", { status: "blocked", reason: "force interrupt blocked by receiver policy", msgId, targetAlias, taskHash, interruptStatus: ackInterruptStatus, bodyStored: false }, 1);
-    if (mode === "async") {
-      const waiting = finish("terminal", { status: "waiting", reason: "delivered locally; awaiting async reply", msgId, targetAlias, taskHash, interruptStatus: ackInterruptStatus, bodyStored: false }, 1);
+    if (mode === "async" && !requireResponse) {
+      const waiting = finish("terminal", { status: "waiting", reason: "delivered locally; awaiting async reply", msgId, targetAlias, taskHash, interruptStatus: ackInterruptStatus, deliveryStatus: "delivered", bodyStored: false }, 1);
       emitFeedback("waiting", waiting);
       return waiting;
     }
-    emitFeedback("delivered", { status: "delivered", roomId, msgId, targetAlias, taskHash, priority, interruptMode, interruptStatus: ackInterruptStatus, interruptReasonHash, bodyStored: false });
-    emitFeedback("waiting", { status: "waiting", roomId, reason: mode === "long" ? "waiting for long peer reply" : "waiting for peer reply", msgId, targetAlias, taskHash, priority, interruptMode, interruptStatus: ackInterruptStatus, interruptReasonHash, bodyStored: false });
+    emitFeedback("delivered", { status: "delivered", roomId, msgId, targetAlias, taskHash, priority, interruptMode, interruptStatus: ackInterruptStatus, interruptReasonHash, requireResponse: requireResponse || undefined, responseRequiredBy, responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined, maxReinjects: requireResponse ? maxReinjects : undefined, deliveryStatus: "delivered", responseReceived: requireResponse ? false : undefined, bodyStored: false });
+    emitFeedback("waiting", { status: "waiting", roomId, reason: requireResponse ? "waiting for required peer response" : mode === "long" ? "waiting for long peer reply" : "waiting for peer reply", msgId, targetAlias, taskHash, priority, interruptMode, interruptStatus: ackInterruptStatus, interruptReasonHash, requireResponse: requireResponse || undefined, responseRequiredBy, responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined, maxReinjects: requireResponse ? maxReinjects : undefined, deliveryStatus: "delivered", responseReceived: requireResponse ? false : undefined, bodyStored: false });
     const reply = await awaitReply(msgId);
     const replyEnvelope = reply["envelope"];
     if (reply.status === "completed") {
       const transientResponse = replyEnvelope?.transientResponse;
-      const result = finish("terminal", { status: "reply", msgId, targetAlias, taskHash, outputHash: replyEnvelope?.outputHash ?? (transientResponse ? sha256(transientResponse) : undefined), transientResponse, interruptStatus: ackInterruptStatus, bodyStored: false }, 1);
+      const result = finish("terminal", { status: "reply", msgId, targetAlias, taskHash, outputHash: replyEnvelope?.outputHash ?? (transientResponse ? sha256(transientResponse) : undefined), transientResponse, interruptStatus: ackInterruptStatus, requireResponse: requireResponse || undefined, responseRequiredBy, responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined, maxReinjects: requireResponse ? maxReinjects : undefined, deliveryStatus: "delivered", responseReceived: requireResponse ? true : undefined, bodyStored: false }, 1);
       emitFeedback("reply", result);
       return result;
     }
+    if (reply.status === "required_response_expired") {
+      const result = finish("terminal", { status: "required_response_expired", reason: "required peer response expired", msgId, targetAlias, taskHash, interruptStatus: ackInterruptStatus, requireResponse: true, responseRequiredBy, responseTimeoutMs, maxReinjects, deliveryStatus: "delivered", responseReceived: false, bodyStored: false }, 1);
+      emitFeedback("expired", result);
+      return result;
+    }
     if (reply.status === "timeout") {
-      const result = finish("terminal", { status: "timeout", reason: "await response timed out", msgId, targetAlias, taskHash, interruptStatus: ackInterruptStatus, bodyStored: false }, 1);
+      const result = finish("terminal", { status: "timeout", reason: "await response timed out", msgId, targetAlias, taskHash, interruptStatus: ackInterruptStatus, deliveryStatus: "delivered", bodyStored: false }, 1);
       emitFeedback(mode === "long" ? "expired" : "timeout", result);
       return result;
     }
-    const result = finish("terminal", { status: "error", reason: replyEnvelope?.errorHash ?? "peer response error", msgId, targetAlias, taskHash, interruptStatus: ackInterruptStatus, bodyStored: false }, 1);
+    const result = finish("terminal", { status: "error", reason: replyEnvelope?.errorHash ?? "peer response error", msgId, targetAlias, taskHash, interruptStatus: ackInterruptStatus, requireResponse: requireResponse || undefined, responseRequiredBy, responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined, maxReinjects: requireResponse ? maxReinjects : undefined, deliveryStatus: "delivered", responseReceived: requireResponse ? false : undefined, bodyStored: false }, 1);
     emitFeedback("error", result);
     return result;
   } catch (error) {

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

@@ -10,6 +10,8 @@ import { sha256 } from "../../core/utils/hashing.js";
 import { writeZpeerLocalProfileFromPeer } from "../../domains/coms/coms-v2/zpeer-profile.js";
 import { buildZpeerRoomSummary, changeZpeerAlias, changeZpeerRoom, clearZpeerRoom, joinZpeerRoom, leaveZpeerRoom, peerAliasInRoom, refreshZpeerSelf, safeZpeerAlias, safeZpeerRoomId, sendZpeerPrompt, useZpeerRoom, zpeerMembershipsForPeer, type ZpeerSendMode } from "../../domains/coms/coms-v2/zpeer.js";
 import type { ZpeerInterruptMode, ZpeerInterruptPriority, ZpeerInterruptStatus } from "../../domains/coms/coms-v2/envelope.js";
+import { sendZobLocalEnvelope } from "../../domains/coms/coms-v2/local-transport.js";
+import { buildZobLiveResponseEnvelope } from "../../domains/coms/coms-v2/response-capture.js";
 import { readZobLiveRegistryAllProjectsSnapshot } from "../../domains/coms/coms-v2/registry.js";
 import { loadActiveZagentScopedMode } from "../events.js";
 import { resolveRuleProfile } from "../../domains/governance/rules.js";
@@ -1412,7 +1414,7 @@ export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeSta
   });
 
   pi.registerCommand("zpeer", {
-    description: "Room-scoped local peer sessions: /zpeer, /zpeer name <alias>, /zpeer room <roomId>, /zpeer @alias <prompt>, /zpeer urgent @alias <prompt>, /zpeer force @alias --reason <reason> <prompt>",
+    description: "Room-scoped local peer sessions: /zpeer, /zpeer name <alias>, /zpeer room <roomId>, /zpeer @alias <prompt>, /zpeer reply <msgId> <response>, /zpeer --require-response @alias <prompt>, /zpeer urgent @alias <prompt>, /zpeer force @alias --reason <reason> <prompt>",
     handler: async (args, ctx) => {
       if (!state.zobLive.peerCard) {
         ctx.ui.notify("/zpeer unavailable: current session has not registered a local peer endpoint yet", "warning");
@@ -1539,9 +1541,50 @@ export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeSta
         ctx.ui.notify(`zpeer left ${parts[1]}; active=${result.peer.zpeerRoomId}`, "info");
         return;
       }
-      const sendModeFromParts = (inputParts: string[]): { mode: ZpeerSendMode; priority: ZpeerInterruptPriority; interruptMode: ZpeerInterruptMode; interruptReasonHash?: string; reasonHash?: string; aliasToken?: string; bodyParts: string[]; error?: string } => {
+      if (verb === "reply") {
+        const msgId = parts[1]?.trim();
+        const responseText = parts.slice(2).join(" ").trim();
+        const outputHash = responseText ? sha256(responseText) : undefined;
+        const inbound = msgId ? state.zobLive.inboundByMsgId?.[msgId] : undefined;
+        const block = !msgId ? "msgId is required" : !responseText ? "response text 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;
+        if (block) {
+          pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-command.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() });
+          ctx.ui.notify(`/zpeer reply blocked: ${block}`, "warning");
+          return;
+        }
+        if (!inbound || !inbound.envelope.replyEndpoint) {
+          ctx.ui.notify("/zpeer reply blocked: invalid reply state", "warning");
+          return;
+        }
+        const replyEndpoint = inbound.envelope.replyEndpoint;
+        try {
+          const responseEnvelope = { ...buildZobLiveResponseEnvelope(inbound.envelope, responseText, inbound.envelope.artifactRefs, inbound.envelope.artifactHashes), replyToMsgId: inbound.envelope.msgId, responseHash: outputHash };
+          const ack = await sendZobLocalEnvelope(replyEndpoint, responseEnvelope, { timeoutMs: 5_000 });
+          if (ack.type !== "ack") throw new Error(`expected ack, got ${ack.type}`);
+          if (inbound.watchdogTimer) clearTimeout(inbound.watchdogTimer);
+          inbound.responseSent = true;
+          inbound.requiredResponseStatus = "replied";
+          if (state.zobLive.inboundByMsgId) delete state.zobLive.inboundByMsgId[inbound.envelope.msgId];
+          if (state.zobLive.inbound?.envelope.msgId === inbound.envelope.msgId) state.zobLive.inbound = { ...state.zobLive.inbound, responseSent: true };
+          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;
+          emitZpeerEvent({ 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 });
+          pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-command.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() });
+          renderHarnessWidget(pi, state, ctx);
+          ctx.ui.notify(`zpeer reply sent msgId=${inbound.envelope.msgId} outputHash=${outputHash}`, "info");
+        } catch (error) {
+          const reason = error instanceof Error ? error.message : String(error);
+          pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-command.v1", action: "reply_error", status: "error", reasonHash: sha256(reason), msgId, outputHash, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
+          ctx.ui.notify(`/zpeer reply error: ${reason}`, "warning");
+        }
+        return;
+      }
+      const sendModeFromParts = (inputParts: string[]): { mode: ZpeerSendMode; priority: ZpeerInterruptPriority; interruptMode: ZpeerInterruptMode; interruptReasonHash?: string; reasonHash?: string; requireResponse?: boolean; maxReinjects?: number; aliasToken?: string; bodyParts: string[]; error?: string } => {
         let mode: ZpeerSendMode = inputParts.includes("--async") ? "async" : inputParts.includes("--long") ? "long" : "await";
         let priority: ZpeerInterruptPriority = "normal";
+        let requireResponse = false;
+        let maxReinjects = 1;
         let aliasToken: string | undefined;
         let reason: string | undefined;
         const bodyParts: string[] = [];
@@ -1574,6 +1617,23 @@ export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeSta
             priority = "force";
             continue;
           }
+          if (lower === "--require-response") {
+            requireResponse = true;
+            continue;
+          }
+          if (lower === "--max-reinjects") {
+            const parsed = Number(inputParts[index + 1]);
+            if (!Number.isFinite(parsed)) return { mode, priority, interruptMode: "none", aliasToken, bodyParts, error: "--max-reinjects requires a number" };
+            maxReinjects = Math.max(0, Math.min(3, Math.floor(parsed)));
+            index += 1;
+            continue;
+          }
+          if (lower.startsWith("--max-reinjects=")) {
+            const parsed = Number(part.slice("--max-reinjects=".length));
+            if (!Number.isFinite(parsed)) return { mode, priority, interruptMode: "none", aliasToken, bodyParts, error: "--max-reinjects requires a number" };
+            maxReinjects = Math.max(0, Math.min(3, Math.floor(parsed)));
+            continue;
+          }
           if (lower === "--reason") {
             reason = inputParts[index + 1];
             index += 1;
@@ -1591,7 +1651,7 @@ export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeSta
         }
         const interruptMode: ZpeerInterruptMode = priority === "force" ? "abort" : priority === "urgent" ? "steer" : "none";
         if (priority === "force" && !reason?.trim()) return { mode, priority, interruptMode, aliasToken, bodyParts, error: "--reason is required for force" };
-        return { mode, priority, interruptMode, interruptReasonHash: reason?.trim() ? sha256(reason) : undefined, reasonHash: reason?.trim() ? sha256(reason) : undefined, aliasToken, bodyParts };
+        return { mode, priority, interruptMode, interruptReasonHash: reason?.trim() ? sha256(reason) : undefined, reasonHash: reason?.trim() ? sha256(reason) : undefined, requireResponse, maxReinjects, aliasToken, bodyParts };
       };
       const explicitRoomId = verb === "in" ? parts[1] : undefined;
       const sendParts = explicitRoomId ? parts.slice(2) : parts;
@@ -1611,19 +1671,22 @@ export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeSta
         }
         if (sendMode.mode !== "async") emitZpeerEvent({ kind: "attempt", roomId: eventRoomId, fromAlias: eventFromAlias, toAlias: targetAlias, status: "attempt", taskHash: transientPrompt.trim() ? sha256(transientPrompt) : undefined, priority: sendMode.priority, interruptMode: sendMode.interruptMode });
         let feedbackEmittedTerminal = false;
-        const result = await sendZpeerPrompt(ctx.cwd, state.zobLive.peerCard, targetAlias, transientPrompt, (msgId) => state.zobLive.pendingReplies.wait(msgId, replyTimeoutMs), {
+        const result = await sendZpeerPrompt(ctx.cwd, state.zobLive.peerCard, targetAlias, transientPrompt, (msgId) => state.zobLive.pendingReplies.wait(msgId, replyTimeoutMs, { requireResponse: sendMode.requireResponse === true }), {
           mode: sendMode.mode,
           roomId: explicitRoomId,
           priority: sendMode.priority,
           interruptMode: sendMode.interruptMode,
           interruptReasonHash: sendMode.interruptReasonHash,
+          requireResponse: sendMode.requireResponse === true,
+          responseTimeoutMs: replyTimeoutMs,
+          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";
+            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";
             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 });
           },
         });
-        const terminalKind = result.status === "reply" || result.status === "completed" ? "reply" : result.status === "blocked" ? "blocked" : result.status === "timeout" ? "timeout" : result.status === "expired" ? "expired" : result.status === "error" ? "error" : result.status === "waiting" ? "waiting" : "delivered";
+        const terminalKind = result.status === "reply" || result.status === "completed" ? "reply" : result.status === "blocked" ? "blocked" : result.status === "timeout" ? "timeout" : result.status === "expired" ? "expired" : result.status === "required_response_expired" ? "required_response_expired" : result.status === "error" ? "error" : result.status === "waiting" ? "waiting" : "delivered";
         if (!feedbackEmittedTerminal) {
           const resultRoomId = result.roomId ?? eventRoomId;
           emitZpeerEvent({ kind: terminalKind, roomId: resultRoomId, fromAlias: peerAliasInRoom(state.zobLive.peerCard, resultRoomId) ?? eventFromAlias, toAlias: result.targetAlias ?? targetAlias, status: result.status, reason: result.reason, msgId: result.msgId, taskHash: result.taskHash, outputHash: result.outputHash, priority: result.priority ?? sendMode.priority, interruptMode: result.interruptMode ?? sendMode.interruptMode, interruptStatus: result.interruptStatus });
@@ -1643,6 +1706,12 @@ export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeSta
           interruptStatus: result.interruptStatus,
           interruptReasonHash: result.interruptReasonHash ?? sendMode.interruptReasonHash,
           reasonInputHash: sendMode.reasonHash,
+          requireResponse: sendMode.requireResponse === true || undefined,
+          responseRequiredBy: result.responseRequiredBy,
+          responseTimeoutMs: result.responseTimeoutMs,
+          maxReinjects: result.maxReinjects,
+          responseReceived: result.responseReceived,
+          deliveryStatus: result.deliveryStatus,
           localOnly: true,
           networkEnabled: false,
           bodyStored: false,
@@ -1667,7 +1736,7 @@ export function registerZliveCommands(pi: ExtensionAPI, state: HarnessRuntimeSta
         }
         return;
       }
-      ctx.ui.notify("Usage: /zpeer | /zpeer rooms | /zpeer clear <roomId> | /zpeer join <roomId> [as <alias>] | /zpeer use <roomId> | /zpeer leave <roomId> | /zpeer @alias <prompt> | /zpeer urgent @alias <prompt> | /zpeer force @alias --reason <reason> <prompt> | /zpeer in <roomId> urgent|force @alias <prompt>", "warning");
+      ctx.ui.notify("Usage: /zpeer | /zpeer rooms | /zpeer clear <roomId> | /zpeer join <roomId> [as <alias>] | /zpeer use <roomId> | /zpeer leave <roomId> | /zpeer reply <msgId> <response> | /zpeer @alias <prompt> | /zpeer --require-response @alias <prompt> | /zpeer urgent @alias <prompt> | /zpeer force @alias --reason <reason> <prompt> | /zpeer in <roomId> urgent|force @alias <prompt>", "warning");
     },
   });
 }

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

@@ -92,7 +92,8 @@ function recordZpeerInbound(state: HarnessRuntimeState, envelope: ZobLiveEnvelop
   ensureZpeerInboundState(state);
   const priority = zpeerEnvelopePriority(envelope);
   const interruptMode = zpeerEnvelopeInterruptMode(envelope, priority);
-  const inbound: ZobInboundZpeerMessage = { envelope, receivedAt: new Date().toISOString(), responseSent: false, priority, interruptMode, repoRoot };
+  const requireResponse = envelope.requireResponse === true;
+  const inbound: ZobInboundZpeerMessage = { envelope, receivedAt: new Date().toISOString(), responseSent: false, priority, interruptMode, repoRoot, requireResponse, responseRequiredBy: envelope.responseRequiredBy, responseTimeoutMs: envelope.responseTimeoutMs, reinjectCount: 0, maxReinjects: envelope.maxReinjects ?? 1, requiredResponseStatus: requireResponse ? "owed" : undefined };
   state.zobLive.inboundByMsgId![envelope.msgId] = inbound;
   if (!state.zobLive.inboundQueue!.includes(envelope.msgId)) state.zobLive.inboundQueue!.push(envelope.msgId);
   state.zobLive.inbound = { envelope, receivedAt: inbound.receivedAt, responseSent: false, repoRoot };
@@ -122,14 +123,80 @@ function activeZpeerInboundForResponse(state: HarnessRuntimeState): ZobInboundZp
   return undefined;
 }
 
+function clearZpeerInboundWatchdog(inbound: ZobInboundZpeerMessage | undefined): void {
+  if (inbound?.watchdogTimer) clearTimeout(inbound.watchdogTimer);
+  if (inbound) inbound.watchdogTimer = undefined;
+}
+
 function finishZpeerInboundResponse(state: HarnessRuntimeState, msgId: string, responseSent: boolean): void {
   const inbound = state.zobLive.inboundByMsgId?.[msgId];
-  if (inbound) inbound.responseSent = responseSent;
+  clearZpeerInboundWatchdog(inbound);
+  if (inbound) {
+    inbound.responseSent = responseSent;
+    if (inbound.requireResponse && responseSent) inbound.requiredResponseStatus = "replied";
+  }
   if (state.zobLive.inbound?.envelope.msgId === msgId) state.zobLive.inbound = { ...state.zobLive.inbound, responseSent };
   state.zobLive.activeInboundMsgId = undefined;
   state.zobLive.inboundQueue = (state.zobLive.inboundQueue ?? []).filter((candidate) => candidate !== msgId);
 }
 
+function boundedRequiredResponseTimeoutMs(envelope: ZobLiveEnvelope): number {
+  return Math.max(1_000, Math.min(30 * 60 * 1000, Math.floor(envelope.responseTimeoutMs ?? 10 * 60 * 1000)));
+}
+
+function scheduleZpeerRequiredResponseWatchdog(pi: ExtensionAPI, state: HarnessRuntimeState, inbound: ZobInboundZpeerMessage): void {
+  if (inbound.requireResponse !== true || inbound.responseSent) return;
+  clearZpeerInboundWatchdog(inbound);
+  const timeoutMs = boundedRequiredResponseTimeoutMs(inbound.envelope);
+  const maxReinjects = Math.max(0, Math.min(3, Math.floor(inbound.maxReinjects ?? 1)));
+  const deadlineMs = inbound.responseRequiredBy ? Date.parse(inbound.responseRequiredBy) : Date.now() + timeoutMs;
+  const remainingMs = Number.isFinite(deadlineMs) ? Math.max(25, deadlineMs - Date.now()) : timeoutMs;
+  const reminderSliceMs = Math.max(25, Math.floor(timeoutMs / Math.max(1, maxReinjects + 1)));
+  const dueMs = Math.min(remainingMs, reminderSliceMs);
+  const timer = setTimeout(() => {
+    const current = state.zobLive.inboundByMsgId?.[inbound.envelope.msgId];
+    if (!current || current.responseSent || current.requiredResponseStatus === "replied" || current.requiredResponseStatus === "cancelled") return;
+    const reinjectCount = current.reinjectCount ?? 0;
+    const roomId = current.envelope.runId?.startsWith("zpeer:") ? current.envelope.runId.slice("zpeer:".length) : undefined;
+    if (reinjectCount < maxReinjects) {
+      current.reinjectCount = reinjectCount + 1;
+      current.requiredResponseStatus = "reinjecting";
+      setZpeerLastEvent(state, { kind: "required_response_reinject", roomId, fromAlias: current.envelope.sender, toAlias: current.envelope.receiver, status: "required_response_reinject", msgId: current.envelope.msgId, taskHash: current.envelope.taskHash, priority: current.priority, interruptMode: current.priority === "normal" ? "none" : "steer", interruptStatus: current.envelope.interruptStatus });
+      pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-required-response-watchdog.v1", action: "reinject", status: "required_response_reinject", msgId: current.envelope.msgId, roomIdHash: roomId ? sha256(roomId) : undefined, senderAliasHash: current.envelope.sender ? sha256(current.envelope.sender) : undefined, receiverAliasHash: current.envelope.receiver ? sha256(current.envelope.receiver) : undefined, taskHash: current.envelope.taskHash, reinjectCount: current.reinjectCount, maxReinjects, priority: current.priority, interruptMode: current.priority === "normal" ? "none" : "steer", forceAbortRepeated: false, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
+      void pi.sendMessage({
+        customType: "zob-coms-inbound",
+        content: [
+          "ZPEER_RESPONSE_REQUIRED.v1",
+          "",
+          "You have an unanswered ZPeer message waiting. Process it now or state the blocker.",
+          `msgId: ${current.envelope.msgId}`,
+          `from: @${current.envelope.sender ?? "?"}`,
+          roomId ? `room: ${roomId}` : undefined,
+          `reinject: ${current.reinjectCount}/${maxReinjects}`,
+          `priority: ${current.priority}`,
+          "reply binding: active; your assistant response to this turn will be sent back for this msgId.",
+          "",
+          "Original transient message:",
+          current.envelope.transientPrompt ?? "",
+        ].filter((line): line is string => line !== undefined).join("\n"),
+        display: false,
+        details: { kind: "zpeer-required-response-reminder", msgId: current.envelope.msgId, runId: current.envelope.runId, sender: current.envelope.sender, receiver: current.envelope.receiver, taskHash: current.envelope.taskHash, requireResponse: true, reinjectCount: current.reinjectCount, maxReinjects, priority: current.priority, interruptMode: current.priority === "normal" ? "none" : "steer", forceAbortRepeated: false, bodyStored: false, localOnly: true, networkEnabled: false },
+      }, { triggerTurn: true, deliverAs: current.priority === "normal" ? "followUp" : "steer" });
+      scheduleZpeerRequiredResponseWatchdog(pi, state, current);
+      return;
+    }
+    current.requiredResponseStatus = "expired";
+    setZpeerLastEvent(state, { kind: "required_response_expired", roomId, fromAlias: current.envelope.sender, toAlias: current.envelope.receiver, status: "required_response_expired", msgId: current.envelope.msgId, taskHash: current.envelope.taskHash, priority: current.priority, interruptMode: current.interruptMode });
+    pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-required-response-watchdog.v1", action: "expire", status: "required_response_expired", msgId: current.envelope.msgId, roomIdHash: roomId ? sha256(roomId) : undefined, senderAliasHash: current.envelope.sender ? sha256(current.envelope.sender) : undefined, receiverAliasHash: current.envelope.receiver ? sha256(current.envelope.receiver) : undefined, taskHash: current.envelope.taskHash, reinjectCount: current.reinjectCount ?? 0, maxReinjects, responseRequiredBy: current.responseRequiredBy, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
+    if (current.envelope.replyEndpoint) {
+      void sendZobLocalEnvelope(current.envelope.replyEndpoint, buildZobLiveErrorEnvelope(current.envelope, "required ZPeer response expired", "zpeer_required_response_expired"), { timeoutMs: 5_000 }).catch(() => undefined);
+    }
+    finishZpeerInboundResponse(state, current.envelope.msgId, false);
+  }, dueMs);
+  timer.unref?.();
+  inbound.watchdogTimer = timer;
+}
+
 function forceAbortAllowedForCurrentState(ctx: ExtensionContext): boolean {
   return typeof ctx.abort === "function" && !ctx.isIdle();
 }
@@ -170,6 +237,7 @@ function handleInboundZpeerPrompt(pi: ExtensionAPI, state: HarnessRuntimeState,
   pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-inbound-interrupt.v1", status: interruptStatus ?? "prompt_received", priority, interruptMode, interruptStatus, msgId: envelope.msgId, roomIdHash: roomId ? sha256(roomId) : undefined, senderAliasHash: envelope.sender ? sha256(envelope.sender) : undefined, receiverAliasHash: envelope.receiver ? sha256(envelope.receiver) : undefined, taskHash: envelope.taskHash, interruptReasonHash: envelope.interruptReasonHash, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
   if (interruptStatus === "force_blocked") return interruptStatus;
   const inbound = recordZpeerInbound(state, envelope, repoRoot);
+  scheduleZpeerRequiredResponseWatchdog(pi, state, inbound);
   const deliverAs = priority === "normal" ? "followUp" : "steer";
   void pi.sendMessage({
     customType: "zob-zpeer-event",
@@ -181,7 +249,7 @@ function handleInboundZpeerPrompt(pi: ExtensionAPI, state: HarnessRuntimeState,
     customType: "zob-coms-inbound",
     content: envelope.transientPrompt ?? "",
     display: false,
-    details: { kind: "zob-coms-inbound", msgId: envelope.msgId, runId: envelope.runId, sender: envelope.sender, receiver: envelope.receiver, taskHash: envelope.taskHash, priority: inbound.priority, interruptMode: inbound.interruptMode, interruptStatus, bodyStored: false, localOnly: true, networkEnabled: false },
+    details: { kind: "zob-coms-inbound", msgId: envelope.msgId, runId: envelope.runId, sender: envelope.sender, receiver: envelope.receiver, taskHash: envelope.taskHash, priority: inbound.priority, interruptMode: inbound.interruptMode, interruptStatus, requireResponse: inbound.requireResponse || undefined, responseRequiredBy: inbound.responseRequiredBy, maxReinjects: inbound.maxReinjects, bodyStored: false, localOnly: true, networkEnabled: false },
   }, { triggerTurn: true, deliverAs });
   return interruptStatus;
 }
@@ -699,7 +767,29 @@ async function startOrRefreshZobLiveRuntime(pi: ExtensionAPI, state: HarnessRunt
     const endpoint = makeZobLocalEndpoint(basePeer.sessionId);
     const server = await bindZobLocalEndpoint(endpoint, async (envelope) => {
       if (envelope.type === "ping") return buildZobLivePongEnvelope(envelope);
+      if (envelope.type === "error") {
+        if (envelope.errorCode === "zpeer_required_response_expired") state.zobLive.pendingReplies.expire(envelope.msgId, envelope.errorHash);
+        else state.zobLive.pendingReplies.fail(envelope.msgId, envelope.errorHash ?? sha256(envelope.errorCode ?? "zpeer_error"));
+        clearPassivePeerWaitForResponse(state, { ...envelope, type: "response" });
+        setZpeerLastEvent(state, {
+          kind: envelope.errorCode === "zpeer_required_response_expired" ? "required_response_expired" : "error",
+          roomId: envelope.runId?.startsWith("zpeer:") ? envelope.runId.slice("zpeer:".length) : undefined,
+          fromAlias: envelope.sender,
+          toAlias: envelope.receiver,
+          status: envelope.errorCode === "zpeer_required_response_expired" ? "required_response_expired" : "error",
+          msgId: envelope.msgId,
+          taskHash: envelope.taskHash,
+        });
+        void pi.sendMessage({
+          customType: "zob-zpeer-event",
+          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 });
+        return buildZobLiveAckEnvelope(envelope);
+      }
       if (envelope.type === "response") {
+        if (envelope.replyToMsgId !== envelope.msgId) return buildZobLiveErrorEnvelope(envelope, "wrong or missing replyToMsgId for ZPeer response", "wrong_msgId");
         const completedActiveWait = state.zobLive.pendingReplies.complete(envelope.msgId, envelope);
         clearPassivePeerWaitForResponse(state, envelope);
         setZpeerLastEvent(state, {
@@ -970,6 +1060,7 @@ 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;
   if (state.zobLive.inboundByMsgId && !activeInbound) return;
   const responseText = latestAssistantText(event);
   if (!responseText.trim()) return;
@@ -994,7 +1085,7 @@ async function sendInboundZobLiveResponse(pi: ExtensionAPI, state: HarnessRuntim
   }
   const artifactRefs = responseCapture ? [...(inbound.envelope.artifactRefs ?? []), responseCapture.artifactRef] : inbound.envelope.artifactRefs;
   const artifactHashes = responseCapture ? [...(inbound.envelope.artifactHashes ?? []), responseCapture.artifactHash] : inbound.envelope.artifactHashes;
-  const responseEnvelope = buildZobLiveResponseEnvelope(inbound.envelope, responseText, artifactRefs, artifactHashes);
+  const responseEnvelope = { ...buildZobLiveResponseEnvelope(inbound.envelope, responseText, artifactRefs, artifactHashes), replyToMsgId: inbound.envelope.msgId, responseHash: sha256(responseText) };
   await sendZobLocalEnvelope(inbound.envelope.replyEndpoint, responseEnvelope, { timeoutMs: 5_000 });
   finishZpeerInboundResponse(state, inbound.envelope.msgId, true);
   setZpeerLastEvent(state, {
@@ -1027,7 +1118,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" ? "warning" : "muted";
+    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 line = [
       theme.fg("accent", "◆ ZPeer"),
       theme.fg("muted", kind),

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

@@ -359,7 +359,14 @@ const ZpeerAskParams = Type.Object({
   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. Ignored by async mode; capped 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." })),
+  maxReinjects: Type.Optional(Type.Number({ description: "Bounded receiver reminder budget for requireResponse. Default 1, capped 0..3." })),
+});
+
+const ZpeerReplyParams = Type.Object({
+  msgId: Type.String({ description: "ZPeer inbound msgId being answered. Must match an active unanswered inbound message." }),
+  message: Type.String({ description: "Transient reply body. Sent over local socket only; durable records store outputHash/metadata, not the raw message." }),
 });
 
 const ZobComsReadinessParams = Type.Object({
@@ -754,6 +761,7 @@ export {
   ZobComsSendParams,
   ZobComsStatusParams,
   ZpeerAskParams,
+  ZpeerReplyParams,
   ZcommitRunParams,
   ZteamHotAddParams,
   ZteamRemoveParams,

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

@@ -37,7 +37,7 @@ export interface DelegationMouseRuntimeState {
 }
 
 export interface ZobLiveLastEvent {
-  kind: "status" | "attempt" | "delivered" | "waiting" | "reply" | "sent" | "completed" | "blocked" | "error" | "timeout" | "expired" | "inbound" | "response_sent" | "heartbeat" | "urgent_delivered" | "force_accepted" | "force_downgraded" | "force_blocked";
+  kind: "status" | "attempt" | "delivered" | "waiting" | "reply" | "sent" | "completed" | "blocked" | "error" | "timeout" | "expired" | "required_response_expired" | "required_response_reinject" | "inbound" | "response_sent" | "heartbeat" | "urgent_delivered" | "force_accepted" | "force_downgraded" | "force_blocked";
   roomId?: string;
   fromAlias?: string;
   toAlias?: string;
@@ -80,6 +80,13 @@ export interface ZobInboundZpeerMessage {
   priority: ZpeerInterruptPriority;
   interruptMode: ZpeerInterruptMode;
   repoRoot: string;
+  requireResponse?: boolean;
+  responseRequiredBy?: string;
+  responseTimeoutMs?: number;
+  reinjectCount?: number;
+  maxReinjects?: number;
+  requiredResponseStatus?: "owed" | "reinjecting" | "replied" | "expired" | "cancelled";
+  watchdogTimer?: ReturnType<typeof setTimeout>;
 }
 
 export interface ZobLiveRuntimeState {

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

@@ -4,6 +4,7 @@ import { readZobLiveRegistrySnapshot } from "../domains/coms/coms-v2/registry.js
 import { peerAliasInRoom, refreshZpeerSelf, safeZpeerAlias, safeZpeerRoomId, sendZpeerPrompt, type ZpeerSendMode, type ZpeerSendResult } from "../domains/coms/coms-v2/zpeer.js";
 import { buildZobLiveEnvelope, type ZpeerInterruptMode, type ZpeerInterruptPriority, type ZpeerInterruptStatus } from "../domains/coms/coms-v2/envelope.js";
 import { sendZobLocalEnvelope } from "../domains/coms/coms-v2/local-transport.js";
+import { buildZobLiveResponseEnvelope } from "../domains/coms/coms-v2/response-capture.js";
 import { appendLiveDeliveredStatus, appendLiveErrorStatus, appendLiveSendRequestedRef } from "../domains/coms/coms-v2/ledger-bridge.js";
 import { writeZobComsRedactedCapture } from "../domains/coms/coms-v2/transcript-capture.js";
 import type { TeamDefinition } from "../types.js";
@@ -17,6 +18,7 @@ import {
   ZobComsSendParams,
   ZobComsStatusParams,
   ZpeerAskParams,
+  ZpeerReplyParams,
 } from "./schemas.js";
 import {
   ackZobComsMessage,
@@ -69,6 +71,13 @@ type ZpeerAskToolParams = {
   force?: boolean;
   interruptMode?: ZpeerInterruptMode;
   timeoutMs?: number;
+  requireResponse?: boolean;
+  maxReinjects?: number;
+};
+
+type ZpeerReplyToolParams = {
+  msgId: string;
+  message: string;
 };
 
 function boundedZpeerAskTimeoutMs(mode: ZpeerSendMode, raw: number | undefined): number {
@@ -107,8 +116,8 @@ function zpeerAskGuardBlock(state: HarnessRuntimeState, params: ZpeerAskToolPara
   return undefined;
 }
 
-function zpeerTerminalKind(status: ZpeerSendResult["status"]): "delivered" | "waiting" | "reply" | "blocked" | "error" | "timeout" | "expired" {
-  return status === "reply" || status === "completed" ? "reply" : status === "blocked" ? "blocked" : status === "timeout" ? "timeout" : status === "expired" ? "expired" : status === "error" ? "error" : status === "waiting" ? "waiting" : "delivered";
+function zpeerTerminalKind(status: ZpeerSendResult["status"]): "delivered" | "waiting" | "reply" | "blocked" | "error" | "timeout" | "expired" | "required_response_expired" {
+  return status === "reply" || status === "completed" ? "reply" : status === "blocked" ? "blocked" : status === "timeout" ? "timeout" : status === "expired" ? "expired" : status === "required_response_expired" ? "required_response_expired" : status === "error" ? "error" : status === "waiting" ? "waiting" : "delivered";
 }
 
 function updatePassivePeerWaitState(state: HarnessRuntimeState, result: ZpeerSendResult, fallback: { roomId: string; targetAlias: string }): void {
@@ -245,21 +254,26 @@ export function registerComsTools(pi: ExtensionAPI, state?: HarnessRuntimeState)
         return { content: [{ type: "text", text: `zpeer_ask blocked: ${guardReason}` }], details: result };
       }
       const timeoutMs = boundedZpeerAskTimeoutMs(mode, params.timeoutMs);
+      const requireResponse = params.requireResponse === true;
+      const maxReinjects = Math.max(0, Math.min(3, Math.floor(params.maxReinjects ?? 1)));
       let feedbackEmittedTerminal = false;
-      const result = await sendZpeerPrompt(ctx.cwd, self, targetAlias, params.message, (msgId) => state.zobLive.pendingReplies.wait(msgId, timeoutMs), {
+      const result = await sendZpeerPrompt(ctx.cwd, self, targetAlias, params.message, (msgId) => state.zobLive.pendingReplies.wait(msgId, timeoutMs, { requireResponse }), {
         mode,
         roomId: params.roomId,
         priority: interrupt.priority,
         interruptMode: interrupt.interruptMode,
         interruptReasonHash: interrupt.interruptReasonHash,
+        requireResponse,
+        responseTimeoutMs: timeoutMs,
+        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";
+          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";
           emitZpeerAskEvent({ kind: feedback.kind, roomId: feedback.result.roomId, status: feedback.result.status, reason: feedback.result.reason, msgId: feedback.result.msgId, taskHash: feedback.result.taskHash, outputHash: feedback.result.outputHash, interruptStatus: feedback.result.interruptStatus });
         },
       });
       if (!feedbackEmittedTerminal) emitZpeerAskEvent({ kind: zpeerTerminalKind(result.status), roomId: result.roomId, status: result.status, reason: result.reason, msgId: result.msgId, taskHash: result.taskHash, outputHash: result.outputHash, interruptStatus: result.interruptStatus });
       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, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
+      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, 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 transientReplyText = (result.status === "reply" || result.status === "completed") && result.transientResponse
@@ -270,6 +284,48 @@ export function registerComsTools(pi: ExtensionAPI, state?: HarnessRuntimeState)
     },
   });
 
+  pi.registerTool({
+    name: "zpeer_reply",
+    label: "ZPeer Reply",
+    description: "Reply to an active inbound ZPeer message by msgId. Raw reply bodies are transient local-socket payloads only; durable metadata stores hashes/status only.",
+    promptSnippet: "Use zpeer_reply({ msgId, message }) when a ZPeer inbound requires an explicit msgId-bound answer after inspection; never reply to a different msgId.",
+    parameters: ZpeerReplyParams,
+    async execute(_toolCallId, params: ZpeerReplyToolParams, _signal, _onUpdate, ctx) {
+      const msgId = params.msgId?.trim();
+      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;
+      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 } };
+      }
+      if (!state || !inbound || !inbound.envelope.replyEndpoint) return { content: [{ type: "text", text: "zpeer_reply blocked: invalid reply state" }], details: { schema: "zob.zpeer-reply-result.v1", status: "blocked", reason: "invalid_reply_state", msgId, outputHash, bodyStored: false, localOnly: true, networkEnabled: false } };
+      const replyEndpoint = inbound.envelope.replyEndpoint;
+      try {
+        const responseEnvelope = { ...buildZobLiveResponseEnvelope(inbound.envelope, responseText, inbound.envelope.artifactRefs, inbound.envelope.artifactHashes), replyToMsgId: inbound.envelope.msgId, responseHash: outputHash };
+        const ack = await sendZobLocalEnvelope(replyEndpoint, responseEnvelope, { timeoutMs: 5_000 });
+        if (ack.type !== "ack") throw new Error(`expected ack, got ${ack.type}`);
+        if (inbound.watchdogTimer) clearTimeout(inbound.watchdogTimer);
+        inbound.responseSent = true;
+        inbound.requiredResponseStatus = "replied";
+        if (state.zobLive.inboundByMsgId) delete state.zobLive.inboundByMsgId[inbound.envelope.msgId];
+        if (state.zobLive.inbound?.envelope.msgId === inbound.envelope.msgId) state.zobLive.inbound = { ...state.zobLive.inbound, responseSent: true };
+        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 });
+        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) {
+        const reason = error instanceof Error ? error.message : String(error);
+        pi.appendEntry("zob-zpeer", { schema: "zob.zpeer-reply.v1", action: "reply_error", status: "error", reasonHash: sha256(reason), msgId, outputHash, localOnly: true, networkEnabled: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, generatedAt: new Date().toISOString() });
+        return { content: [{ type: "text", text: `zpeer_reply error: ${reason}` }], details: { schema: "zob.zpeer-reply-result.v1", status: "error", reasonHash: sha256(reason), msgId, outputHash, bodyStored: false, localOnly: true, networkEnabled: false } };
+      }
+    },
+  });
+
   pi.registerTool({
     name: "zob_coms_send",
     label: "ZOB Coms Send",

package/.pi/prompts/implement.md

@@ -13,7 +13,7 @@ Rules:
 - In a parallel owner pool, edit only your owned/write paths; read-across sibling refs for context/evidence only. If you need another owner's path, send a typed owner request and wait for parent/owner decision.
 - If running without harness tools/extensions, do not call Goal Room/ZPeer directly; emit a hash/body-free `OWNER_CHANGE_REQUEST.v1` final-output block (`requested_by`, `owner_worker`, `requested_paths`, `body_hash`, `change_hash`, `reason_hash`, optional `validation_plan_hash`, safe refs, `FINAL_MARKER: OWNER_CHANGE_REQUEST_END`) for the parent to extract with `zob_governed_request_extract`.
 - Goal Room is canonical for owner requests, decisions, blockers, and evidence; ZPeer is transient clarification only and cannot replace parent-owned arbitration.
-- If using ZPeer urgent/force, load `.pi/skills/zob-coms-v2-live/SKILL.md` and `.pi/skills/zob-coms-safety/SKILL.md`; `urgent` is steer-only, `force` requires an explicit transient reason and hash-only metadata, and ACK/interrupt status is not completion evidence.
+- If using ZPeer urgent/force/requireResponse, load `.pi/skills/zob-coms-v2-live/SKILL.md` and `.pi/skills/zob-coms-safety/SKILL.md`; `urgent` is steer-only, `force` requires an explicit transient reason and hash-only metadata, `requireResponse` needs exact msgId correlation or terminal expiration, explicit replies must use `zpeer_reply`/`/zpeer reply <msgId>`, and ACK/interrupt/reinjection status is not completion evidence.
 - No secrets. No destructive commands. No commits unless explicitly requested or governed autocommit is explicitly policy-authorized for this slice.
 - If commit/push work is authorized, load `.pi/skills/zob-commit/SKILL.md` and `.pi/git-policy.json`, then use only governed `/zcommit` commands or the agent-executable `zob_zcommit_run` tool when the user explicitly asks the agent to commit/push; no aliases and no direct git commit/push/tag/force-push/bulk-stage commands.
 - Verify with narrowest relevant checks first.

package/.pi/prompts/orchestrator.md

@@ -36,7 +36,7 @@ Orchestrator loop:
    - Keep `allowed_paths` repo-relative only; never pass external absolute/home paths to children. Use repo-local `reports/...` snapshots or `context_ref` artifacts for external context. Keep `forbidden_paths` deny-only.
    - Prefer `orchestrate_run` for multi-agent Lead/Worker decomposition and `delegate_task`/`delegate_agent` for bounded specialist work.
    - Use Goal Room as canonical for pool owner requests/decisions, blockers, and evidence. Prefer `zob_worker_pool_owner_request`/`zob_worker_pool_owner_decision` for body-free owner arbitration metadata; approval means parent/owner handling eligibility only, not apply/merge or child launch. For `--no-extensions` children, accept a final-output `OWNER_CHANGE_REQUEST.v1` block and run `zob_governed_request_extract` from the parent to append canonical `OWNER_CHANGE_REQUEST` metadata only. ZPeer is optional transient local clarification only; do not treat ZPeer/free chat as delivery, decision, merge evidence, or completion evidence.
-   - For live ZPeer steering, choose the lowest sufficient priority: `normal` for ordinary async asks, `urgent` for steer-only priority injection, and `force` only for explicit parent/user-approved controlled interruption with a transient reason; durable records must remain hash-only and ACK/interrupt status is not read/digestion proof.
+   - For live ZPeer steering, choose the lowest sufficient priority: `normal` for ordinary async asks, opt-in `requireResponse`/`--require-response` only when a bounded msgId-correlated answer is required, use `zpeer_reply`/`/zpeer reply <msgId>` only for exact active inbound answers, `urgent` for steer-only priority injection, and `force` only for explicit parent/user-approved controlled interruption with a transient reason; durable records must remain hash-only and ACK/interrupt/reinjection status is not read/digestion proof.
 5. Evidence
    - Require concrete file refs, command names/results, reports, sentinels, or oracle verdicts.
    - Attach evidence to TODOs; planned orchestration is not completed implementation.

package/.pi/skills/zob-coms-safety/SKILL.md

@@ -18,7 +18,7 @@ ZOB coms live transport may be transient, but ZOB audit must stay metadata-only.
 - Allow Shared Goal Room messages only when they are parent-visible, typed, metadata/hash-only, and not hidden worker-to-worker free chat.
 - For Goal TODO handoff, treat ZPeer as transient live delivery/clarification only and Goal Room hash-only metadata as canonical for TODO refs, receiver refs, custom-message hashes, result hashes, blockers, and evidence refs.
 - For ZPeer priorities, preserve `normal`/`urgent`/`force` semantics: `urgent` is steer-only and must not abort; `force` requires an explicit transient reason, stores only `reasonHash`/`interruptReasonHash`, and remains blocked unless topology, room, role, rate, lease, and local-socket guards pass.
-- Treat ZPeer ACK/interrupt status as delivery/control metadata only, not as read/digestion proof or TODO completion evidence.
+- Treat ZPeer ACK/interrupt/reinjection status as delivery/control metadata only, not as read/digestion proof or TODO completion evidence; opt-in required responses must expire terminally unless an exact msgId-correlated reply arrives. Use `zpeer_reply` or `/zpeer reply <msgId> <response>` only when the `msgId` is active inbound; wrong, expired, or already-answered msgIds must block.
 - Treat governed requests (`DELEGATION_REQUEST.v1`, `ORACLE_REQUEST.v1`, `CONTEXT_REQUEST.v1`, `OWNER_CHANGE_REQUEST.v1`) as proposals only: parent/governor decides; extraction must not dispatch, mutate TODO state, apply owner changes, or store raw bodies.
 - Treat stale/offline as blockers, not completion evidence.
 - Keep Mission Control commands proposal-only and parent-owned.

package/.pi/skills/zob-coms-v2-live/SKILL.md

@@ -18,7 +18,7 @@ Use this skill when:
 - Treat `zob_coms_send` as live-first when policy mode is `required_local` or `required_network`.
 - Include `transientBody` only for live transport delivery; it must never be stored in `.pi/coms`.
 - Use `taskHash`, `outputHash`, and `artifactRefs` for durable evidence.
-- For ZPeer direct asks, use governed `zpeer_ask` or `/zpeer`; supported priorities are `normal`, `urgent`, and `force`.
+- For ZPeer direct asks, use governed `zpeer_ask` or `/zpeer`; supported priorities are `normal`, `urgent`, and `force`; use opt-in `requireResponse`/`--require-response` only when a real msgId-correlated answer is needed, and use `zpeer_reply` or `/zpeer reply <msgId> <response>` only for the exact active inbound `msgId`.
 - Use `urgent` only for priority steer delivery without aborting the receiver.
 - Use `force` only for explicit controlled interrupts: provide a transient reason, persist only its hash, require topology/room/role/rate/local-socket guards, and expect `force_accepted`, `force_downgraded`, or `force_blocked` metadata.
 - Treat missing ACK, stale peer, offline peer, timeout, or transport error as blocker evidence.
@@ -27,7 +27,7 @@ Use this skill when:
 - For children launched without harness extensions, owner-change coordination is via final-output `OWNER_CHANGE_REQUEST.v1` blocks extracted by the parent, not direct child Goal Room/ZPeer writes.
 - When a live answer changes ownership, scope, conflict, or merge readiness, mirror only typed hash/body-free metadata to Goal Room.
 - Let the runtime capture normal inbound responses when handling live prompts.
-- Prefer `zob_coms_get` / `zob_coms_await` with the `msgId` returned by your own send.
+- Prefer `zob_coms_get` / `zob_coms_await` with the `msgId` returned by your own send; required-response success must come from exact msgId/replyToMsgId correlation, not ACK/reinjection/delivery metadata.
 
 ## MUST NOT
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zob-harness",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "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

@@ -102,6 +102,7 @@ async function main() {
   const toolsComs = await import(`${compiledSrc}/runtime/tools-coms.js`);
   const localTransport = await import(`${compiledComsV2}/local-transport.js`);
   const envelope = await import(`${compiledComsV2}/envelope.js`);
+  const pendingModule = await import(`${compiledComsV2}/pending-replies.js`);
   const hashing = await import(`${compiledSrc}/core/utils/hashing.js`);
 
   process.env.ZOB_ZPEER_PROFILE_ID = 'profile-alpha';
@@ -217,6 +218,10 @@ async function main() {
   }));
 
   servers.push(await localTransport.bindZobLocalEndpoint(betaEndpoint, async (incoming) => {
+    if (incoming.type === 'response') {
+      receivedResponses.push(incoming);
+      return envelope.buildZobLiveAckEnvelope(incoming);
+    }
     receivedPrompts.push(incoming);
     if (incoming.type === 'prompt' && incoming.replyEndpoint) {
       setTimeout(() => {
@@ -229,6 +234,8 @@ async function main() {
           team: incoming.team,
           taskHash: incoming.taskHash,
           outputHash: hashing.sha256(rawResponse),
+          replyToMsgId: incoming.msgId,
+          responseHash: hashing.sha256(rawResponse),
           transientResponse: rawResponse,
         });
         localTransport.sendZobLocalEnvelope(incoming.replyEndpoint, response, { timeoutMs: 5_000 }).catch((error) => {
@@ -357,6 +364,30 @@ async function main() {
   assert(ghostDuplicateSummary.onlineAliases.filter((alias) => alias === 'beta').length === 1, 'only the live beta lease alias should be listed as online');
   assert(!ghostDuplicateSummary.duplicateAliases.includes('beta'), 'card-only alias ghosts must not be reported as live duplicate aliases');
 
+  const requiredPromptCountBefore = receivedPrompts.length;
+  const requiredReplyResult = await zpeer.sendZpeerPrompt(repoRoot, alpha, 'beta', rawPrompt, waitForReply, { requireResponse: true, responseTimeoutMs: 1_000, maxReinjects: 1 });
+  assert(requiredReplyResult.status === 'reply' && requiredReplyResult.requireResponse === true && requiredReplyResult.responseReceived === true && requiredReplyResult.deliveryStatus === 'delivered', `requireResponse send expected correlated reply, got ${requiredReplyResult.status}`);
+  const requiredPromptEnvelope = receivedPrompts.at(-1);
+  assert(receivedPrompts.length === requiredPromptCountBefore + 1 && requiredPromptEnvelope.requireResponse === true && requiredPromptEnvelope.responseRequiredBy && requiredPromptEnvelope.maxReinjects === 1, 'requireResponse prompt envelope must carry bounded required-response metadata');
+  const requiredExpired = await zpeer.sendZpeerPrompt(repoRoot, adhocOne, 'adhoctwo', rawPrompt, (msgId) => new pendingModule.ZobPendingReplies().wait(msgId, 75, { requireResponse: true }), { mode: 'async', requireResponse: true, responseTimeoutMs: 75, maxReinjects: 1 });
+  assert(requiredExpired.status === 'required_response_expired' && requiredExpired.responseReceived === false && requiredExpired.deliveryStatus === 'delivered', `requireResponse no-reply send expected required_response_expired, got ${requiredExpired.status}`);
+  const wrongMsgPending = new pendingModule.ZobPendingReplies();
+  const wrongWait = wrongMsgPending.wait('right-msg', 75, { requireResponse: true });
+  const wrongAccepted = wrongMsgPending.complete('right-msg', envelope.buildZobLiveEnvelope({ type: 'response', msgId: 'right-msg', replyToMsgId: 'wrong-msg', transientResponse: rawResponse }));
+  const wrongResult = await wrongWait;
+  assert(wrongAccepted === false && wrongResult.status === 'required_response_expired', 'wrong replyToMsgId must not satisfy a required-response wait');
+  const missingMsgPending = new pendingModule.ZobPendingReplies();
+  const missingWait = missingMsgPending.wait('missing-reply-to-msg', 75, { requireResponse: true });
+  const missingAccepted = missingMsgPending.complete('missing-reply-to-msg', envelope.buildZobLiveEnvelope({ type: 'response', msgId: 'missing-reply-to-msg', transientResponse: rawResponse }));
+  const missingResult = await missingWait;
+  assert(missingAccepted === false && missingResult.status === 'required_response_expired', 'missing replyToMsgId must not satisfy a required-response wait');
+  const missingValidation = envelope.validateZobLiveEnvelope(envelope.buildZobLiveEnvelope({ type: 'response', msgId: 'missing-validation-msg', transientResponse: rawResponse }));
+  assert(missingValidation.some((error) => error.includes('replyToMsgId')), 'response envelope validation must reject missing replyToMsgId');
+  const latePending = new pendingModule.ZobPendingReplies();
+  const lateResult = await latePending.wait('late-msg', 75, { requireResponse: true });
+  const lateAccepted = latePending.complete('late-msg', envelope.buildZobLiveEnvelope({ type: 'response', msgId: 'late-msg', replyToMsgId: 'late-msg', transientResponse: rawResponse }));
+  assert(lateResult.status === 'required_response_expired' && lateAccepted === false, 'late response after required-response expiration must not retroactively satisfy the wait');
+
   const directPromptCountBefore = receivedPrompts.length;
   const directResponseCountBefore = receivedResponses.length;
   assert(alpha.team !== beta.team, 'same-room non-worker allowance fixture must cover cross-team peers');
@@ -387,6 +418,8 @@ async function main() {
   const forceWithoutReason = await zpeer.sendZpeerPrompt(repoRoot, alpha, 'beta', rawPrompt, waitForReply, { mode: 'async', priority: 'force', interruptMode: 'abort' });
   assert(forceWithoutReason.status === 'blocked' && forceWithoutReason.interruptStatus === 'force_blocked' && String(forceWithoutReason.reason).includes('reason hash'), 'force without reason hash must be blocked before delivery');
   const forceReasonHash = hashing.sha256('no-ship smoke reason');
+  const forceRequiredExpired = await zpeer.sendZpeerPrompt(repoRoot, adhocOne, 'adhoctwo', rawPrompt, (msgId) => new pendingModule.ZobPendingReplies().wait(msgId, 75, { requireResponse: true }), { mode: 'async', priority: 'force', interruptMode: 'abort', interruptReasonHash: forceReasonHash, requireResponse: true, responseTimeoutMs: 75, maxReinjects: 1 });
+  assert(forceRequiredExpired.status === 'blocked' || forceRequiredExpired.status === 'required_response_expired', 'force + requireResponse must either respect force guards or expire; reinjection must not be counted as success');
   const forcePromptCountBefore = receivedPrompts.length;
   const forceResult = await zpeer.sendZpeerPrompt(repoRoot, alpha, 'beta', rawPrompt, waitForReply, { mode: 'async', priority: 'force', interruptMode: 'abort', interruptReasonHash: forceReasonHash });
   assert(forceResult.status === 'waiting' && forceResult.priority === 'force' && forceResult.interruptMode === 'abort' && forceResult.interruptStatus === 'force_accepted' && forceResult.interruptReasonHash === forceReasonHash, `force send expected waiting/force_accepted, got ${forceResult.status}/${forceResult.interruptStatus}`);
@@ -430,8 +463,49 @@ async function main() {
   assert(forceToolBlocked?.details?.status === 'blocked' && forceToolBlocked?.details?.interruptStatus === 'force_blocked' && String(forceToolBlocked?.details?.reason).includes('reason'), 'zpeer_ask force without reason must be blocked');
   const forceToolResult = await zpeerAsk.execute('tool-call-zpeer-ask-force', { targetAlias: 'beta', message: 'force tool smoke prompt', force: true, reason: 'force smoke reason' }, undefined, undefined, { cwd: repoRoot });
   assert(forceToolResult?.details?.status === 'waiting' && forceToolResult?.details?.priority === 'force' && forceToolResult?.details?.interruptMode === 'abort' && forceToolResult?.details?.interruptStatus === 'force_accepted' && forceToolResult?.details?.interruptReasonHash === hashing.sha256('force smoke reason'), 'zpeer_ask force must require reason and deliver abort metadata');
-
-  const duplicateGuard = await zpeerAsk.execute('tool-call-zpeer-ask-dup', { targetAlias: 'beta', message: 'force tool smoke prompt' }, undefined, undefined, { cwd: repoRoot });
+  const requireToolResult = await zpeerAsk.execute('tool-call-zpeer-ask-require-response', { targetAlias: 'beta', message: 'required response tool smoke prompt', requireResponse: true, timeoutMs: 1000 }, undefined, undefined, { cwd: repoRoot });
+  assert(requireToolResult?.details?.status === 'reply' && requireToolResult?.details?.requireResponse === true && requireToolResult?.details?.responseReceived === true, 'zpeer_ask requireResponse must wait for a msgId-correlated reply instead of returning delivery-only waiting');
+
+  const zpeerReply = registeredTools.get('zpeer_reply');
+  assert(zpeerReply, 'zpeer_reply tool must be registered by registerComsTools');
+  assert(zpeerReply.parameters, 'zpeer_reply tool must expose a schema');
+  const explicitReplyMsgId = 'explicit-reply-msg';
+  toolState.zobLive.inboundByMsgId = {
+    [explicitReplyMsgId]: {
+      envelope: envelope.buildZobLiveEnvelope({
+        type: 'prompt',
+        msgId: explicitReplyMsgId,
+        runId: 'zpeer:default',
+        sender: 'beta',
+        receiver: 'alpha',
+        taskHash: hashing.sha256(rawPrompt),
+        transientPrompt: rawPrompt,
+        replyEndpoint: betaEndpoint,
+        replyEndpointHash: hashing.sha256(betaEndpoint),
+        requireResponse: true,
+      }),
+      receivedAt: new Date().toISOString(),
+      responseSent: false,
+      priority: 'normal',
+      interruptMode: 'none',
+      repoRoot,
+      requireResponse: true,
+      requiredResponseStatus: 'owed',
+    },
+  };
+  toolState.zobLive.inboundQueue = [explicitReplyMsgId];
+  toolState.zobLive.activeInboundMsgId = explicitReplyMsgId;
+  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');
+  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 });
+  assert(wrongExplicitReply?.details?.status === 'blocked' && String(wrongExplicitReply?.details?.reason).includes('no active inbound'), 'zpeer_reply must block wrong or non-active msgId replies');
+  assert(!containsRawBody(explicitReplyResult) && !containsRawBody(wrongExplicitReply), 'zpeer_reply tool results must not echo raw response body');
+  assert(appendEntries.some((item) => item.customType === 'zob-zpeer' && item.data?.schema === 'zob.zpeer-reply.v1' && item.data?.action === 'reply' && item.data?.bodyStored === false), 'zpeer_reply must append hash-only reply metadata');
+
+  const duplicateGuard = await zpeerAsk.execute('tool-call-zpeer-ask-dup', { targetAlias: 'beta', message: 'required response tool smoke prompt' }, undefined, undefined, { cwd: repoRoot });
   assert(duplicateGuard?.details?.status === 'blocked' && String(duplicateGuard?.details?.reason).includes('duplicate'), 'zpeer_ask must block duplicate target/message loop attempts');
   const selfGuard = await zpeerAsk.execute('tool-call-zpeer-ask-self', { targetAlias: 'alpha', message: 'different smoke prompt' }, undefined, undefined, { cwd: repoRoot });
   assert(selfGuard?.details?.status === 'blocked' && String(selfGuard?.details?.reason).includes('self'), 'zpeer_ask must block self-target attempts');
@@ -478,6 +552,7 @@ async function main() {
   }
   assert(messages.some((record) => record.event === 'ack' && record.status === 'delivered' && record.taskHash === hashing.sha256(rawPrompt)), 'peer ledger must include delivered ack hash record');
   assert(messages.some((record) => record.event === 'terminal' && record.status === 'reply' && record.outputHash === hashing.sha256(rawResponse)), 'peer ledger must include reply outputHash record');
+  assert(messages.some((record) => record.event === 'terminal' && record.status === 'required_response_expired' && record.requireResponse === true && record.responseReceived === false), 'peer ledger must include required-response expiration metadata');
   assert(messages.some((record) => record.event === 'terminal' && record.status === 'waiting' && record.taskHash === hashing.sha256(rawPrompt)), 'peer ledger must include async waiting hash record');
   assert(messages.some((record) => record.event === 'attempt' && record.status === 'blocked' && record.reasonHash), 'peer ledger must include hash-only blocked room-isolation record');
   assert(messages.some((record) => record.event === 'ack' && record.priority === 'urgent' && record.interruptMode === 'steer' && record.interruptStatus === 'urgent_delivered'), 'peer ledger must include urgent delivered interrupt metadata');

package/scripts/zpeer-static-smoke.mjs

@@ -31,6 +31,9 @@ function readSurface(file) {
 
 const files = [
   '.pi/extensions/zob-harness/src/domains/coms/coms-v2/zpeer.ts',
+  '.pi/extensions/zob-harness/src/domains/coms/coms-v2/envelope.ts',
+  '.pi/extensions/zob-harness/src/domains/coms/coms-v2/pending-replies.ts',
+  '.pi/extensions/zob-harness/src/domains/coms/coms-v2/response-capture.ts',
   '.pi/extensions/zob-harness/src/domains/coms/coms-v2/registry.ts',
   '.pi/extensions/zob-harness/src/domains/coms/coms-v2/zpeer-profile.ts',
   '.pi/extensions/zob-harness/src/domains/coms/coms-v2/transcript-capture.ts',
@@ -54,26 +57,32 @@ if (commandMatches.length !== 1) failures.push(`expected exactly one zpeer comma
 const toolsComs = contents['.pi/extensions/zob-harness/src/runtime/tools-coms.ts'];
 const zpeerAskMatches = toolsComs.match(/name: "zpeer_ask"/g) ?? [];
 if (zpeerAskMatches.length !== 1) failures.push(`expected exactly one zpeer_ask tool, found ${zpeerAskMatches.length}`);
-for (const needle of ['parameters: ZpeerAskParams', 'sendZpeerPrompt(ctx.cwd', 'mode = params.mode ?? "async"', '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', 'bodyStored: false', 'promptBodiesStored: false', 'outputBodiesStored: false']) {
+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', '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(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');
 if (!toolsComs.includes('peerAliasInRoom(self, requestedRoomId)') || !toolsComs.includes('peerAliasInRoom(self, eventRoomId)')) failures.push('zpeer_ask feed events must use room-scoped sender alias for explicit roomId');
 const schemas = contents['.pi/extensions/zob-harness/src/runtime/schemas.ts'];
-for (const needle of ['const ZpeerAskParams', 'targetAlias', 'message', 'roomId', 'Default async', '["async", "await", "long"]', 'timeoutMs', 'ZpeerAskParams']) {
-  if (!schemas.includes(needle)) failures.push(`zpeer_ask schema missing ${needle}`);
+for (const needle of ['const ZpeerAskParams', 'targetAlias', 'message', 'roomId', 'Default async', '["async", "await", "long"]', 'timeoutMs', 'requireResponse', 'maxReinjects', 'ZpeerAskParams', 'const ZpeerReplyParams', 'msgId', 'ZpeerReplyParams']) {
+  if (!schemas.includes(needle)) failures.push(`zpeer schemas missing ${needle}`);
 }
 const registry = contents['.pi/capabilities/zob-public-runtime-capabilities.json'];
-if (!registry.includes('"name": "zpeer_ask"') || !registry.includes('rate/loop guarded')) failures.push('capability registry missing zpeer_ask visibility/safety notes');
+if (!registry.includes('"name": "zpeer_ask"') || !registry.includes('rate/loop guarded') || !registry.includes('requireResponse tracks msgId-correlated replies')) failures.push('capability registry missing zpeer_ask visibility/safety notes');
+if (!registry.includes('"name": "zpeer_reply"') || !registry.includes('wrong/expired/already-answered msgIds are blocked')) failures.push('capability registry missing zpeer_reply visibility/safety notes');
 const constants = contents['.pi/extensions/zob-harness/src/core/constants.ts'];
 const zpeerComsAllowlistBlock = constants.match(/export const ZOB_COMS_TOOLS = \[[^\n]*\] as const;/)?.[0] ?? '';
-if (!zpeerComsAllowlistBlock.includes('"zpeer_ask"')) failures.push('ZOB_COMS_TOOLS missing zpeer_ask active allowlist entry');
+if (!zpeerComsAllowlistBlock.includes('"zpeer_ask"') || !zpeerComsAllowlistBlock.includes('"zpeer_reply"')) failures.push('ZOB_COMS_TOOLS missing zpeer_ask/zpeer_reply active allowlist entry');
 const modeBlocks = Object.fromEntries([...constants.matchAll(/\n  (explore|plan|implement|oracle|orchestrator|factory): \[[^\n]*\],/g)].map((match) => [match[1], match[0]]));
 for (const mode of ['plan', 'implement', 'orchestrator', 'factory']) {
   if (!modeBlocks[mode]?.includes('...ZOB_COMS_TOOLS')) failures.push(`MODE_TOOLS.${mode} must expose zpeer_ask through ZOB_COMS_TOOLS`);
 }
 for (const mode of ['explore', 'oracle']) {
-  if (!modeBlocks[mode]?.includes('"zpeer_ask"')) failures.push(`MODE_TOOLS.${mode} missing zpeer_ask explicit active allowlist entry`);
+  if (!modeBlocks[mode]?.includes('"zpeer_ask"') || !modeBlocks[mode]?.includes('"zpeer_reply"')) failures.push(`MODE_TOOLS.${mode} missing zpeer_ask/zpeer_reply explicit active allowlist entry`);
 }
 for (const forbidden of ['transientPrompt:', 'transientResponse:', 'prompt:', 'output:', 'content: params.message', 'message: params.message', 'text: params.message', 'diff:', 'patch:']) {
   const appendBlocks = [...toolsComs.matchAll(/appendEntry\("zob-zpeer",\s*\{[\s\S]*?\}\);/g)].map((m) => m[0]);
@@ -81,15 +90,27 @@ for (const forbidden of ['transientPrompt:', 'transientResponse:', 'prompt:', 'o
 }
 
 const zpeer = contents['.pi/extensions/zob-harness/src/domains/coms/coms-v2/zpeer.ts'];
+const envelope = contents['.pi/extensions/zob-harness/src/domains/coms/coms-v2/envelope.ts'];
+const pendingReplies = contents['.pi/extensions/zob-harness/src/domains/coms/coms-v2/pending-replies.ts'];
+const responseCapture = contents['.pi/extensions/zob-harness/src/domains/coms/coms-v2/response-capture.ts'];
 const liveRegistry = contents['.pi/extensions/zob-harness/src/domains/coms/coms-v2/registry.ts'];
 const zpeerProfile = contents['.pi/extensions/zob-harness/src/domains/coms/coms-v2/zpeer-profile.ts'];
-for (const needle of ['networkEnabled: false', 'localOnly: true', 'bodyStored: false', 'sendZobLocalEnvelope', 'taskHash', 'outputHash', 'ZpeerSendMode', 'status: "waiting"', 'status: "reply"', 'zpeerMembershipsForPeer', 'joinZpeerRoom', 'leaveZpeerRoom', 'useZpeerRoom', 'clearZpeerRoom', 'preservedSelf: true', 'roomId?: string', 'buildZpeerPeerRoomSummaries', 'active: membership.roomId === activeRoomId', 'peerRespondsToAliasPing', 'activeAliasCollision', 'zpeer-alias-ping', 'zpeerAdhoc']) {
+for (const needle of ['networkEnabled: false', 'localOnly: true', 'bodyStored: false', 'sendZobLocalEnvelope', 'taskHash', 'outputHash', 'ZpeerSendMode', 'status: "waiting"', 'status: "reply"', 'required_response_expired', 'requireResponse', 'responseRequiredBy', 'responseReceived', 'deliveryStatus', 'zpeerMembershipsForPeer', 'joinZpeerRoom', 'leaveZpeerRoom', 'useZpeerRoom', 'clearZpeerRoom', 'preservedSelf: true', 'roomId?: string', 'buildZpeerPeerRoomSummaries', 'active: membership.roomId === activeRoomId', 'peerRespondsToAliasPing', 'activeAliasCollision', 'zpeer-alias-ping', 'zpeerAdhoc']) {
   if (!zpeer.includes(needle)) failures.push(`zpeer missing ${needle}`);
 }
 for (const needle of ['peer-messages.jsonl', 'peer-status.jsonl', 'appendZpeerPeerRecords', 'reasonHash', 'priority', 'interruptMode', 'interruptStatus', 'interruptReasonHash', 'bodyStored: false']) {
   if (!zpeer.includes(needle)) failures.push(`zpeer hash-only peer ledger support missing ${needle}`);
 }
 if (/required_network|pi-vs-claude-code|sse/.test(zpeer)) failures.push('zpeer must not enable network/SSE transport');
+for (const needle of ['value.type === "response" && value.replyToMsgId !== value.msgId', 'ZOB live response replyToMsgId must match msgId']) {
+  if (!envelope.includes(needle)) failures.push(`envelope missing strict response replyToMsgId validation ${needle}`);
+}
+for (const needle of ['requireResponse: options.requireResponse === true', 'item?.requireResponse && envelope.replyToMsgId !== msgId', 'completed.envelope?.replyToMsgId !== msgId']) {
+  if (!pendingReplies.includes(needle)) failures.push(`pending replies missing strict required-response correlation ${needle}`);
+}
+for (const needle of ['replyToMsgId: request.msgId', 'responseHash: capture.outputHash']) {
+  if (!responseCapture.includes(needle)) failures.push(`response capture missing msgId-safe response envelope field ${needle}`);
+}
 const roomFirstTopologyIndex = zpeer.indexOf('if (selfInRequestedRoom && targetInRequestedRoom && !bothPeersAreWorkers) return undefined;');
 const hardTeamMismatchIndex = zpeer.indexOf('zpeer topology blocked: peers are in different teams');
 if (roomFirstTopologyIndex === -1) failures.push('zpeer topology must allow same-room non-worker peers before team/ZTeam policy');
@@ -138,7 +159,7 @@ for (const forbidden of ['transientPrompt:', 'transientResponse:', 'prompt:', 'r
 }
 if (!command.includes('zpeerCommandProfileId(ctx)') || !command.includes('writeZpeerLocalProfileFromPeer(ctx.cwd, result.peer, zpeerProfileId)')) failures.push('zpeer command must save profile under the current Pi session profile after successful name/room changes');
 if (!command.includes('customType: "zob-zpeer-response"') || !command.includes('result.transientResponse')) failures.push('zpeer command missing transient response display support');
-for (const needle of ['customType: "zob-zpeer-event"', 'if (sendMode.mode !== "async") emitZpeerEvent({ kind: "attempt"', 'feedbackEmittedTerminal', 'send_async', 'replyTimeoutMs', 'idle/passive wait; no follow-up turn queued', 'safety: local-only/hash-only/bodyStored=false', 'verb === "clear"', 'action: "clear"', 'verb === "join"', 'verb === "use"', 'verb === "leave"', 'verb === "rooms"', 'verb === "in"', 'tokenizeZpeerArgs', 'priorityToken', '--reason is required for force', 'interruptReasonHash', 'reasonInputHash', 'interrupt=${result.interruptStatus}', '/zpeer urgent @alias <prompt>', '/zpeer force @alias --reason <reason> <prompt>']) {
+for (const needle of ['customType: "zob-zpeer-event"', 'if (sendMode.mode !== "async") emitZpeerEvent({ kind: "attempt"', 'feedbackEmittedTerminal', 'send_async', 'replyTimeoutMs', '--require-response', 'requireResponse', 'maxReinjects', 'idle/passive wait; no follow-up turn queued', 'safety: local-only/hash-only/bodyStored=false', 'verb === "clear"', 'action: "clear"', 'verb === "join"', 'verb === "use"', 'verb === "leave"', 'verb === "reply"', 'action: "reply"', 'action: "reply_blocked"', 'buildZobLiveResponseEnvelope', 'sendZobLocalEnvelope(replyEndpoint', 'replyToMsgId: inbound.envelope.msgId', '/zpeer reply <msgId> <response>', 'verb === "rooms"', 'verb === "in"', 'tokenizeZpeerArgs', 'priorityToken', '--reason is required for force', 'interruptReasonHash', 'reasonInputHash', 'interrupt=${result.interruptStatus}', '/zpeer urgent @alias <prompt>', '/zpeer force @alias --reason <reason> <prompt>']) {
   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');
@@ -177,7 +198,7 @@ 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');
-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']) {
+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}`);
 }
 for (const needle of ['ZPEER AWARENESS (transient, rebuilt each turn)', 'buildZpeerPeerRoomSummaries(repoRoot, state.zobLive.peerCard)', '- rooms:', 'explicit roomId', 'zpeer_ask with mode=\\"async\\"', 'Passive wait rule', 'stop the turn and remain idle', 'avoid spam', 'Raw ZPeer bodies are transient', 'registerMessageRenderer("zob-zpeer-event"', 'scheduleZpeerHeartbeat', 'clearZpeerHeartbeatTimer', 'refreshZpeerSelf(repoRoot', 'kind: "response_sent"', 'kind: "inbound"', 'zpeerStableTeamAgentLeaseRequired', 'withZpeerLeaseMode', 'leaseStatus = "unavailable"', 'runtime_adhoc']) {