zob-harness 0.14.0 → 0.15.1

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/registry.ts

@@ -246,6 +246,7 @@ function buildTeamAgentLease(repoRoot: string, peer: ZobLivePeerCard, input: { n
     contextUsedPct: peer.contextUsedPct,
     queueDepth: peer.queueDepth,
     status: peer.status === "offline" ? "offline" : "online",
+    socketVerifiedAt: peer.socketVerifiedAt,
     zpeerRoomId: peer.zpeerRoomId,
     zpeerAlias: peer.zpeerAlias,
     zpeerActiveRoomId: peer.zpeerActiveRoomId,
@@ -291,6 +292,7 @@ function leaseToPeerCard(lease: ZobLiveTeamAgentLease, nowMs: number): ZobLivePe
     contextUsedPct: lease.contextUsedPct,
     queueDepth: lease.queueDepth,
     status: deriveLeaseStatus(lease, nowMs),
+    socketVerifiedAt: lease.socketVerifiedAt,
     zpeerRoomId: lease.zpeerRoomId,
     zpeerAlias: lease.zpeerAlias,
     zpeerActiveRoomId: lease.zpeerActiveRoomId,
@@ -578,8 +580,9 @@ export async function sweepZobLivePeerHealth(repoRoot: string, input: { teamName
       }
     }
     if (responds) {
+      const livePeer = { ...peer, heartbeatAt: nowIso, status: "online", socketVerifiedAt: nowIso } as ZobLivePeerCard;
+      applySweepPeerUpdate(repoRoot, livePeer, nowMs);
       if (peer.status !== "online") {
-        applySweepPeerUpdate(repoRoot, { ...peer, heartbeatAt: nowIso, status: "online", socketVerifiedAt: nowIso } as ZobLivePeerCard, nowMs);
         revived += 1;
       } else {
         retainedLive += 1;

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/types.ts

@@ -104,6 +104,7 @@ export interface ZobLivePeerCard {
   contextUsedPct: number;
   queueDepth: number;
   status: ZobLivePeerStatus;
+  socketVerifiedAt?: string;
   zpeerRoomId?: string;
   zpeerAlias?: string;
   zpeerActiveRoomId?: string;
@@ -141,6 +142,7 @@ export interface ZobLiveTeamAgentLease {
   contextUsedPct: number;
   queueDepth: number;
   status: ZobLivePeerStatus;
+  socketVerifiedAt?: string;
   zpeerRoomId?: string;
   zpeerAlias?: string;
   zpeerActiveRoomId?: string;

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;
@@ -69,20 +75,36 @@ export interface ZpeerSendFeedback {
   result: ZpeerSendResult;
 }
 
+export type ZpeerFallbackDelivery = (input: {
+  targetAlias: string;
+  senderAlias: string;
+  roomId: string;
+  taskHash?: string;
+  prompt: string;
+  priority: ZpeerInterruptPriority;
+  interruptMode: ZpeerInterruptMode;
+  requireResponse: boolean;
+  responseTimeoutMs?: number;
+  maxReinjects?: number;
+}) => Promise<{ delivered: boolean; target?: string; reason?: string }>;
+
 export interface ZpeerSendOptions {
   mode?: ZpeerSendMode;
   roomId?: string;
   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
   // the target agent's pane). This keeps coms-v2 IO-free; the app supplies the tmux
   // delivery. A fallback delivery is NOT verified delivery: outputHash stays absent,
   // confirmation_ref stays null, and bodyStored stays false (coms-safety: append-only /
-  // best-effort is not delivery success).
-  fallbackDelivery?: (input: { targetAlias: string; roomId: string; taskHash?: string; prompt: string }) => Promise<{ delivered: boolean; target?: string; reason?: string }>;
+  // best-effort is not delivery success). Force/abort is never eligible for fallback.
+  fallbackDelivery?: ZpeerFallbackDelivery;
 }
 
 interface ZpeerRoomPeer {
@@ -100,6 +122,37 @@ export function safeZpeerAlias(value: string | undefined): string | undefined {
   return trimmed;
 }
 
+export function zpeerAliasLookupKey(value: string | undefined): string | undefined {
+  const alias = safeZpeerAlias(value);
+  return alias ? alias.replaceAll("-", "_") : undefined;
+}
+
+export function zpeerAliasesEquivalent(left: string | undefined, right: string | undefined): boolean {
+  const leftKey = zpeerAliasLookupKey(left);
+  const rightKey = zpeerAliasLookupKey(right);
+  return Boolean(leftKey && rightKey && leftKey === rightKey);
+}
+
+export function zpeerAliasIncluded(aliases: readonly string[] | undefined, alias: string | undefined): boolean {
+  const key = zpeerAliasLookupKey(alias);
+  return Boolean(key && aliases?.some((candidate) => zpeerAliasLookupKey(candidate) === key));
+}
+
+export function duplicateZpeerAliasLookupKeys(aliases: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (const alias of aliases) {
+    const key = zpeerAliasLookupKey(alias);
+    if (!key) continue;
+    if (seen.has(key)) duplicates.add(alias);
+    else seen.add(key);
+  }
+  return aliases.filter((alias) => {
+    const key = zpeerAliasLookupKey(alias);
+    return Boolean(key && duplicates.has(alias)) || Boolean(key && aliases.filter((candidate) => zpeerAliasLookupKey(candidate) === key).length > 1);
+  }).filter((alias, index, all) => all.indexOf(alias) === index).sort();
+}
+
 export function safeZpeerRoomId(value: string | undefined): string | undefined {
   const trimmed = value?.trim();
   if (!trimmed || !ROOM_PATTERN.test(trimmed)) return undefined;
@@ -189,8 +242,12 @@ function withZpeerMembershipState(repoRoot: string, peer: ZobLivePeerCard, membe
   });
 }
 
+function zpeerStrictSocketEvidenceRequired(): boolean {
+  return /^(1|true|yes|on|strict)$/i.test(process.env.ZOB_ZPEER_REQUIRE_VERIFIED_SOCKET ?? "");
+}
+
 function zpeerReachableStatus(peer: ZobLivePeerCard): ZobLivePeerStatus {
-  if (peer.status === "online" && hasLocalSocketEndpointEvidence(peer)) return "online";
+  if (peer.status === "online" && hasLocalSocketEndpointEvidence(peer, { requireVerified: zpeerStrictSocketEvidenceRequired() })) return "online";
   if (peer.status === "stale") return "stale";
   return "offline";
 }
@@ -212,9 +269,34 @@ async function peerRespondsToAliasPing(peer: ZobLivePeerCard): Promise<boolean>
   }
 }
 
+async function probeAndReviveZpeerCandidate(repoRoot: string, entry: ZpeerRoomPeer): Promise<ZpeerRoomPeer | undefined> {
+  if (!hasLocalSocketEndpointEvidence(entry.peer)) return undefined;
+  const nowIso = new Date().toISOString();
+  try {
+    const response = await sendZobLocalEnvelope(entry.peer.endpoint, {
+      schema: "zob.live-envelope.v1",
+      type: "ping",
+      msgId: `zpeer-candidate-probe:${entry.peer.roleId}:${Date.now()}`,
+      hops: 0,
+      timestamp: nowIso,
+      bodyStored: false,
+    }, { timeoutMs: 1_000 });
+    if (response.type !== "pong" && response.type !== "ack") return undefined;
+    const revived = { ...entry.peer, heartbeatAt: nowIso, status: "online", socketVerifiedAt: nowIso } as ZobLivePeerCard;
+    if (revived.zpeerAdhoc === true || revived.projectId !== buildZobComsProjectId(repoRoot)) {
+      writeZobLivePeerCardToProjectId(revived);
+    } else {
+      writeZobLiveTeamAgentLease(repoRoot, revived, { reason: "zpeer_candidate_probe" });
+    }
+    return { ...entry, peer: revived };
+  } catch {
+    return undefined;
+  }
+}
+
 async function activeAliasCollision(repoRoot: string, self: ZobLivePeerCard, roomId: string, alias: string): Promise<ZpeerRoomPeer | undefined> {
   for (const entry of peersInRoom(repoRoot, roomId)) {
-    if (entry.peer.sessionHash === self.sessionHash || entry.membership.alias !== alias) continue;
+    if (entry.peer.sessionHash === self.sessionHash || !zpeerAliasesEquivalent(entry.membership.alias, alias)) continue;
     if (await peerRespondsToAliasPing(entry.peer)) return entry;
     if (zpeerReachableStatus(entry.peer) === "online") {
       try { writeZobLivePeerCard(repoRoot, { ...entry.peer, heartbeatAt: new Date().toISOString(), status: "offline" }); } catch { /* best-effort stale alias release */ }
@@ -281,7 +363,7 @@ function buildZpeerRoomSummaryFromPeers(projectId: string, self: ZobLivePeerCard
     statusAliases[status].push(entry.membership.alias);
   }
   const onlineAliases = statusAliases.online.sort();
-  const duplicateAliases = onlineAliases.filter((alias, index) => onlineAliases.indexOf(alias) !== index).filter((alias, index, all) => all.indexOf(alias) === index);
+  const duplicateAliases = duplicateZpeerAliasLookupKeys(onlineAliases);
   return {
     schema: "zob.zpeer-room-summary.v1",
     projectId,
@@ -425,6 +507,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 +532,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 +589,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 +611,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 });
@@ -530,8 +633,8 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
   if (priority === "force" && !ZPEER_FORCE_ALLOWED_SENDER_ROLE_TYPES.has(self.roleType)) return finish("attempt", { status: "blocked", reason: `force interrupt not allowed from role type ${self.roleType}`, targetAlias: targetAlias ?? undefined, taskHash, interruptStatus: "force_blocked", bodyStored: false });
   if (!targetAlias) return finish("attempt", { status: "blocked", reason: "invalid target alias", bodyStored: false });
   if (!transientPrompt.trim()) return finish("attempt", { status: "blocked", reason: "empty peer prompt", targetAlias, bodyStored: false });
-  const candidates = peersInRoom(repoRoot, roomId).filter((entry) => entry.membership.alias === targetAlias && entry.peer.sessionHash !== self.sessionHash);
-  if (targetAlias === senderAlias) return finish("attempt", { status: "blocked", reason: "cannot send to self", targetAlias, taskHash, bodyStored: false });
+  const candidates = peersInRoom(repoRoot, roomId).filter((entry) => zpeerAliasesEquivalent(entry.membership.alias, targetAlias) && entry.peer.sessionHash !== self.sessionHash);
+  if (zpeerAliasesEquivalent(targetAlias, senderAlias)) return finish("attempt", { status: "blocked", reason: "cannot send to self", targetAlias, taskHash, bodyStored: false });
   if (candidates.length === 0) return finish("attempt", { status: "blocked", reason: `peer @${targetAlias} not found in room '${roomId}'`, targetAlias, taskHash, bodyStored: false }, 0);
   let liveCandidates = candidates.filter((entry) => zpeerReachableStatus(entry.peer) === "online");
   if (liveCandidates.length > 1) {
@@ -545,6 +648,14 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
     }
     liveCandidates = responsiveCandidates;
   }
+  if (liveCandidates.length === 0) {
+    const probedCandidates: ZpeerRoomPeer[] = [];
+    for (const entry of candidates) {
+      const revived = await probeAndReviveZpeerCandidate(repoRoot, entry);
+      if (revived) probedCandidates.push(revived);
+    }
+    liveCandidates = probedCandidates;
+  }
   if (liveCandidates.length === 0) {
     const statuses = [...new Set(candidates.map((entry) => zpeerReachableStatus(entry.peer)))].sort().join("/") || "offline";
     // WS-ZH4: last-resort fallback delivery. When local-socket transport is blocked
@@ -552,14 +663,15 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
     // pane), deliver the prompt best-effort. This is NOT verified delivery:
     // outputHash/confirmation_ref stay absent and bodyStored stays false; the receiver,
     // if it answers at all, answers via its own local_socket later (that ledgered reply
-    // is what WS-Q5 counts). If no fallback is supplied or it fails/declines, fall
-    // through to the standard blocked result unchanged.
-    if (options.fallbackDelivery && targetAlias && priority === "normal") {
+    // is what WS-Q5 counts). Urgent/steer is eligible when the caller explicitly wires
+    // a safe fallback hook; force/abort is never eligible. If no fallback is supplied or
+    // it fails/declines, fall through to the standard blocked result unchanged.
+    if (options.fallbackDelivery && targetAlias && priority !== "force") {
       try {
-        const fallback = await options.fallbackDelivery({ targetAlias, roomId, taskHash, prompt: transientPrompt });
+        const fallback = await options.fallbackDelivery({ targetAlias, senderAlias, roomId, taskHash, prompt: transientPrompt, priority, interruptMode, requireResponse, responseTimeoutMs: requireResponse ? responseTimeoutMs : undefined, maxReinjects: requireResponse ? maxReinjects : undefined });
         if (fallback.delivered) {
           const fallbackMsgId = `zpeer-fallback:${self.sessionHash.slice(0, 8)}:${Date.now()}`;
-          return finish("attempt", { status: "delivered", reason: `tmux_sendkeys_fallback: peer @${targetAlias} socket ${statuses}; best-effort delivery to ${fallback.target ?? targetAlias} (not verified)`, msgId: fallbackMsgId, targetAlias, taskHash, deliveryMethod: "tmux_sendkeys", fallback_delivery: true, best_effort: true, bodyStored: false }, candidates.length);
+          return finish("attempt", { status: "delivered", reason: `tmux_sendkeys_fallback: peer @${targetAlias} socket ${statuses}; best-effort delivery to ${fallback.target ?? targetAlias} (not verified)`, msgId: fallbackMsgId, targetAlias, taskHash, deliveryStatus: "blocked", deliveryMethod: "tmux_sendkeys", fallback_delivery: true, best_effort: true, responseReceived: requireResponse ? false : undefined, bodyStored: false }, candidates.length);
         }
       } catch {
         // best-effort fallback failed; fall through to the standard blocked result.
@@ -578,7 +690,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 +707,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 +718,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/domains/coms/zagents.ts

@@ -3,7 +3,7 @@ import { basename, join, relative, resolve } from "node:path";
 
 import type { ModeName } from "../../core/types/core.js";
 import { MODE_TOOLS } from "../../core/constants.js";
-import { safeZpeerAlias, safeZpeerRoomId } from "./coms-v2/zpeer.js";
+import { safeZpeerAlias, safeZpeerRoomId, zpeerAliasIncluded, zpeerAliasesEquivalent } from "./coms-v2/zpeer.js";
 import { parseJsonFile } from "../../core/utils/json.js";
 import { isSafeArtifactName } from "../../core/utils/paths.js";
 import { isRecord } from "../../core/utils/records.js";
@@ -438,7 +438,7 @@ function communicationPolicyNarrowingErrors(base: ZAgentCommunicationPolicy | un
     for (const room of overlay.allowedRooms ?? []) if (!base.allowedRooms.includes(room)) errors.push(`${label}.allowedRooms must be a subset of the base policy: ${room}`);
   }
   if (base?.allowedAliases) {
-    for (const alias of overlay.allowedAliases ?? []) if (!base.allowedAliases.includes(alias)) errors.push(`${label}.allowedAliases must be a subset of the base policy: ${alias}`);
+    for (const alias of overlay.allowedAliases ?? []) if (!zpeerAliasIncluded(base.allowedAliases, alias)) errors.push(`${label}.allowedAliases must be a subset of the base policy: ${alias}`);
   }
   return errors;
 }
@@ -865,7 +865,7 @@ function policyAllowsZpeerContact(policy: ZAgentCommunicationPolicy | undefined,
   if (!policy) return true;
   if (policy.zpeerContact === false || policy.allowZpeerContact === false) return false;
   if (roomId && policy.allowedRooms && !policy.allowedRooms.includes(roomId)) return false;
-  if (alias && policy.allowedAliases && !policy.allowedAliases.includes(alias)) return false;
+  if (alias && policy.allowedAliases && !zpeerAliasIncluded(policy.allowedAliases, alias)) return false;
   if (policy.requireActiveRoom && !roomId) return false;
   return true;
 }
@@ -876,7 +876,7 @@ export function zteamAllowsZpeerContact(team: ZTeamManifest, zagentId: string, r
     ...(team.members ?? []),
     ...(team.agents ?? []),
   ];
-  const member = members.find((candidate) => zteamMemberAgentId(candidate) === zagentId || candidate.alias === alias);
+  const member = members.find((candidate) => zteamMemberAgentId(candidate) === zagentId || zpeerAliasesEquivalent(candidate.alias, alias));
   if (!member) return false;
   if (!policyAllowsZpeerContact(member.communicationPolicy, roomId, alias ?? member.alias)) return false;
   const rooms = zteamMemberRooms(member, team.defaultRoom);