zob-harness 0.3.0 → 0.3.1

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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -10,6 +10,8 @@ import { readZobComsV2Policy, zobComsRegistryEnabled } from "./policy.js";
 import type { ZobLivePeerCard, ZobLivePeerStatus, ZobLiveRegistrySnapshot } from "./types.js";
 
 const FORBIDDEN_PERSISTED_KEYS = new Set(["body", "task", "prompt", "output", "content", "message", "rationale", "text", "diff", "patch"]);
+const DEFAULT_OFFLINE_PEER_RETENTION_MS = 24 * 60 * 60 * 1000;
+const MIN_OFFLINE_PEER_RETENTION_MS = 5 * 60 * 1000;
 
 function registryRoot(): { path: string; kind: "user_runtime" | "env_override" } {
   const override = process.env.ZOB_COMS_REGISTRY_ROOT;
@@ -54,6 +56,19 @@ function readPeerCardsFromAgentsDir(dir: string, nowMs: number, teamName?: strin
     .map((peer) => ({ ...peer, status: derivePeerStatus(peer, nowMs) }));
 }
 
+function boundedOfflinePeerRetentionMs(value: number | undefined): number {
+  const env = Number.parseInt(process.env.ZOB_COMS_OFFLINE_PEER_RETENTION_MS ?? "", 10);
+  const raw = typeof value === "number" && Number.isFinite(value) ? value : Number.isFinite(env) ? env : DEFAULT_OFFLINE_PEER_RETENTION_MS;
+  return Math.max(MIN_OFFLINE_PEER_RETENTION_MS, Math.floor(raw));
+}
+
+function offlinePeerExpired(peer: ZobLivePeerCard, nowMs: number, retentionMs: number): boolean {
+  if (derivePeerStatus(peer, nowMs) !== "offline") return false;
+  const heartbeatMs = Date.parse(peer.heartbeatAt);
+  if (!Number.isFinite(heartbeatMs)) return true;
+  return nowMs - heartbeatMs >= Math.max(peer.offlineAfterMs, retentionMs);
+}
+
 function allProjectAgentsDirs(): string[] {
   const root = registryRoot();
   const projectsDir = join(root.path, "projects");
@@ -94,6 +109,34 @@ function derivePeerStatus(peer: ZobLivePeerCard, nowMs: number): ZobLivePeerStat
   return "online";
 }
 
+export function pruneExpiredZobLivePeers(repoRoot: string, input: { teamName?: string; nowMs?: number; retentionMs?: number } = {}): { schema: "zob.live-registry-prune.v1"; pruned: number; retained: number; retentionMs: number; bodyStored: false } {
+  const { dir } = projectAgentsDir(repoRoot);
+  const nowMs = input.nowMs ?? Date.now();
+  const retentionMs = boundedOfflinePeerRetentionMs(input.retentionMs);
+  let pruned = 0;
+  let retained = 0;
+  if (!existsSync(dir)) return { schema: "zob.live-registry-prune.v1", pruned, retained, retentionMs, bodyStored: false };
+  for (const entry of readdirSync(dir).filter((name) => name.endsWith(".json"))) {
+    const filePath = join(dir, entry);
+    try {
+      const peer = parsePeerCard(JSON.parse(readFileSync(filePath, "utf8")) as unknown);
+      if (!peer || (input.teamName && peer.team !== input.teamName)) {
+        retained += 1;
+        continue;
+      }
+      if (offlinePeerExpired(peer, nowMs, retentionMs)) {
+        unlinkSync(filePath);
+        pruned += 1;
+      } else {
+        retained += 1;
+      }
+    } catch {
+      retained += 1;
+    }
+  }
+  return { schema: "zob.live-registry-prune.v1", pruned, retained, retentionMs, bodyStored: false };
+}
+
 export function writeZobLivePeerCard(repoRoot: string, peer: ZobLivePeerCard): ZobLivePeerCard {
   if (hasForbiddenPersistedKey(peer)) throw new Error("Refusing to persist ZOB live peer card with forbidden body-like keys");
   if (peer.bodyStored !== false) throw new Error("ZOB live peer card bodyStored must be false");

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

@@ -26,6 +26,9 @@ export interface ZpeerRoomSummary {
   stale: number;
   offline: number;
   aliases: string[];
+  onlineAliases: string[];
+  staleAliases: string[];
+  offlineAliases: string[];
   duplicateAliases: string[];
   membershipCount?: number;
   localOnly: true;
@@ -248,9 +251,15 @@ function peersInRoom(repoRoot: string, roomId: string): ZpeerRoomPeer[] {
 
 function buildZpeerRoomSummaryFromPeers(projectId: string, self: ZobLivePeerCard | undefined, roomId: string, peers: ZpeerRoomPeer[]): ZpeerRoomSummary {
   const counts: Record<ZobLivePeerStatus, number> = { online: 0, stale: 0, offline: 0 };
+  const statusAliases: Record<ZobLivePeerStatus, string[]> = { online: [], stale: [], offline: [] };
   const aliases = peers.map((entry) => entry.membership.alias).sort();
-  for (const entry of peers) counts[zpeerReachableStatus(entry.peer)] += 1;
-  const duplicateAliases = aliases.filter((alias, index) => aliases.indexOf(alias) !== index).filter((alias, index, all) => all.indexOf(alias) === index);
+  for (const entry of peers) {
+    const status = zpeerReachableStatus(entry.peer);
+    counts[status] += 1;
+    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);
   return {
     schema: "zob.zpeer-room-summary.v1",
     projectId,
@@ -261,6 +270,9 @@ function buildZpeerRoomSummaryFromPeers(projectId: string, self: ZobLivePeerCard
     stale: counts.stale,
     offline: counts.offline,
     aliases,
+    onlineAliases,
+    staleAliases: statusAliases.stale.sort(),
+    offlineAliases: statusAliases.offline.sort(),
     duplicateAliases,
     membershipCount: self ? zpeerMembershipsForPeer(self).length : undefined,
     localOnly: true,
@@ -471,8 +483,24 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
   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 });
   if (candidates.length === 0) return finish("attempt", { status: "blocked", reason: `peer @${targetAlias} not found in room '${roomId}'`, targetAlias, taskHash, bodyStored: false }, 0);
-  if (candidates.length > 1) return finish("attempt", { status: "blocked", reason: `duplicate alias @${targetAlias} in room '${roomId}'`, targetAlias, taskHash, bodyStored: false }, candidates.length);
-  const target = candidates[0];
+  let liveCandidates = candidates.filter((entry) => zpeerReachableStatus(entry.peer) === "online");
+  if (liveCandidates.length > 1) {
+    const responsiveCandidates: ZpeerRoomPeer[] = [];
+    for (const entry of liveCandidates) {
+      if (await peerRespondsToAliasPing(entry.peer)) {
+        responsiveCandidates.push(entry);
+      } else {
+        try { writeZobLivePeerCard(repoRoot, { ...entry.peer, heartbeatAt: new Date().toISOString(), status: "offline" }); } catch { /* best-effort ghost alias release */ }
+      }
+    }
+    liveCandidates = responsiveCandidates;
+  }
+  if (liveCandidates.length === 0) {
+    const statuses = [...new Set(candidates.map((entry) => zpeerReachableStatus(entry.peer)))].sort().join("/") || "offline";
+    return finish("attempt", { status: "blocked", reason: `peer @${targetAlias} is ${statuses}`, targetAlias, taskHash, bodyStored: false }, candidates.length);
+  }
+  if (liveCandidates.length > 1) return finish("attempt", { status: "blocked", reason: `duplicate live alias @${targetAlias} in room '${roomId}'`, targetAlias, taskHash, bodyStored: false }, liveCandidates.length);
+  const target = liveCandidates[0];
   const targetReachableStatus = zpeerReachableStatus(target.peer);
   if (targetReachableStatus !== "online") return finish("attempt", { status: "blocked", reason: `peer @${targetAlias} is ${targetReachableStatus}`, targetAlias, taskHash, bodyStored: false }, 1);
   const topologyBlocker = validateZpeerTopology(repoRoot, self, target.peer, roomId, senderAlias, target.membership.alias);

package/.pi/extensions/zob-harness/src/domains/coms/mission-control.ts

@@ -63,6 +63,7 @@ function summarizeZpeerRooms(peers: Array<Record<string, unknown>>): Array<Recor
   }
   return [...rooms.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([roomId, roomPeers]) => {
     const aliases = roomPeers.map((entry) => entry.alias).filter((alias): alias is string => Boolean(alias)).sort();
+    const onlineAliases = roomPeers.filter((entry) => entry.peer.status === "online").map((entry) => entry.alias).filter((alias): alias is string => Boolean(alias)).sort();
     const sessionHashes = roomPeers.map((entry) => typeof entry.peer.sessionHash === "string" ? entry.peer.sessionHash : undefined).filter((sessionHash): sessionHash is string => Boolean(sessionHash));
     return {
       schema: "zob.zpeer-room-summary.v1",
@@ -73,7 +74,9 @@ function summarizeZpeerRooms(peers: Array<Record<string, unknown>>): Array<Recor
       stale: roomPeers.filter((entry) => entry.peer.status === "stale").length,
       offline: roomPeers.filter((entry) => entry.peer.status === "offline").length,
       aliasHashes: aliases.map((alias) => sha256(alias)),
-      duplicateAliasHashes: aliases.filter((alias, index) => aliases.indexOf(alias) !== index).filter((alias, index, all) => all.indexOf(alias) === index).map((alias) => sha256(alias)),
+      onlineAliasHashes: onlineAliases.map((alias) => sha256(alias)),
+      duplicateAliasHashes: onlineAliases.filter((alias, index) => onlineAliases.indexOf(alias) !== index).filter((alias, index, all) => all.indexOf(alias) === index).map((alias) => sha256(alias)),
+      duplicateAliasScope: "online_only",
       localOnly: true,
       networkEnabled: false,
       bodyStored: false,

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

@@ -1032,9 +1032,9 @@ export function registerHarnessCommands(pi: ExtensionAPI, state: HarnessRuntimeS
         });
         emitZpeerEvent({ kind: "status", roomId: summary.roomId, fromAlias: summary.selfAlias, status: `online=${summary.online}/${summary.peerCount}`, reason: `stale=${summary.stale} offline=${summary.offline}` });
         renderHarnessWidget(pi, state, ctx);
-        const availableAliases = summary.aliases.filter((alias) => alias !== summary.selfAlias).map((alias) => `@${alias}`).join(", ") || "none";
+        const availableAliases = summary.onlineAliases.filter((alias) => alias !== summary.selfAlias).map((alias) => `@${alias}`).join(", ") || "none";
         const unavailable = summary.stale + summary.offline;
-        ctx.ui.notify(`zpeer room=${summary.roomId} memberships=${summary.membershipCount ?? zpeerMembershipsForPeer(self).length} self=@${summary.selfAlias ?? "?"} onlinePeers=${Math.max(0, summary.online - 1)} unavailable=${unavailable} peers=${availableAliases} · usage: /zpeer @alias <prompt> | /zpeer in <room> @alias <prompt> · safety: local-only/hash-only/bodyStored=false`, "info");
+        ctx.ui.notify(`zpeer room=${summary.roomId} memberships=${summary.membershipCount ?? zpeerMembershipsForPeer(self).length} self=@${summary.selfAlias ?? "?"} onlinePeers=${Math.max(0, summary.online - 1)} unavailable=${unavailable} livePeers=${availableAliases} · usage: /zpeer @alias <prompt> | /zpeer in <room> @alias <prompt> · safety: local-only/hash-only/bodyStored=false`, "info");
         return;
       }
       const parts = trimmed.split(/\s+/);

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

@@ -8,7 +8,7 @@ import { buildZobLiveAckEnvelope, buildZobLiveErrorEnvelope, buildZobLivePongEnv
 import { appendLiveCompletedRef } from "../domains/coms/coms-v2/ledger-bridge.js";
 import { bindZobLocalEndpoint, makeZobLocalEndpoint, sendZobLocalEnvelope } from "../domains/coms/coms-v2/local-transport.js";
 import { readZobComsV2Policy } from "../domains/coms/coms-v2/policy.js";
-import { registerCurrentZobLivePeer, touchCurrentZobLivePeer, unregisterCurrentZobLivePeer, writeZobLivePeerCard } from "../domains/coms/coms-v2/registry.js";
+import { pruneExpiredZobLivePeers, registerCurrentZobLivePeer, touchCurrentZobLivePeer, unregisterCurrentZobLivePeer, writeZobLivePeerCard } from "../domains/coms/coms-v2/registry.js";
 import { clearZpeerNewCarryoverProfile, readZpeerLocalProfile, readZpeerNewCarryoverProfile, writeZpeerLocalProfileFromPeer, writeZpeerNewCarryoverProfile, zpeerProfileIdIsSharedFallback } from "../domains/coms/coms-v2/zpeer-profile.js";
 import { buildZpeerPeerRoomSummaries, ensureZpeerFields, refreshZpeerSelf } from "../domains/coms/coms-v2/zpeer.js";
 import type { ZpeerRoomMembership } from "../domains/coms/coms-v2/types.js";
@@ -317,16 +317,16 @@ function buildZpeerAwarenessPrompt(state: HarnessRuntimeState, repoRoot: string)
   const memberships = (state.zobLive.peerCard.zpeerMemberships?.length ?? summaries.length) || 1;
   const roomLines = summaries.slice(0, 6).map((summary) => {
     const selfAlias = summary.selfAlias ?? "?";
-    const peerAliases = summary.aliases.filter((alias) => alias !== selfAlias).slice(0, 6).map((alias) => `@${alias}`);
+    const peerAliases = summary.onlineAliases.filter((alias) => alias !== selfAlias).slice(0, 6).map((alias) => `@${alias}`);
     const unavailable = summary.stale + summary.offline;
-    const duplicateText = summary.duplicateAliases.length > 0 ? ` duplicates=${summary.duplicateAliases.map((alias) => `@${alias}`).join(",")}` : "";
+    const duplicateText = summary.duplicateAliases.length > 0 ? ` liveDuplicates=${summary.duplicateAliases.map((alias) => `@${alias}`).join(",")}` : "";
     return `  - ${summary.active ? "*" : " "} ${summary.roomId}: self=@${selfAlias}; online=${peerAliases.join(",") || "none"}; unavailable=${unavailable} (stale=${summary.stale}, offline=${summary.offline})${duplicateText}`;
   });
   if (summaries.length > 6) roomLines.push(`  - +${summaries.length - 6} more room${summaries.length - 6 === 1 ? "" : "s"}`);
   const activeSelfAlias = activeSummary?.selfAlias ?? "?";
-  const activePeerAliases = (activeSummary?.aliases ?? []).filter((alias) => alias !== activeSelfAlias).slice(0, 8).map((alias) => `@${alias}`);
+  const activePeerAliases = (activeSummary?.onlineAliases ?? []).filter((alias) => alias !== activeSelfAlias).slice(0, 8).map((alias) => `@${alias}`);
   const activeUnavailable = (activeSummary?.stale ?? 0) + (activeSummary?.offline ?? 0);
-  const activeDuplicateLine = activeSummary && activeSummary.duplicateAliases.length > 0 ? `\n- duplicate aliases: ${activeSummary.duplicateAliases.map((alias) => `@${alias}`).join(", ")}` : "";
+  const activeDuplicateLine = activeSummary && activeSummary.duplicateAliases.length > 0 ? `\n- duplicate live aliases: ${activeSummary.duplicateAliases.map((alias) => `@${alias}`).join(", ")}` : "";
   return `\n\nZPEER AWARENESS (transient, rebuilt each turn)\n- active room: ${activeSummary?.roomId ?? "default"}\n- memberships: ${memberships}\n- self: @${activeSelfAlias}\n- online peers: ${activePeerAliases.join(", ") || "none"}\n- unavailable peers: ${activeUnavailable} (stale=${activeSummary?.stale ?? 0}, offline=${activeSummary?.offline ?? 0})${activeDuplicateLine}\n- rooms:\n${roomLines.join("\n") || "  - none"}\n- Use zpeer_ask with explicit roomId when targeting a non-active room.\n- posture: local_socket-only, room-scoped, hash-only durable ledgers, bodyStored=false, networkEnabled=false\n- For non-trivial review/debug/planning peer coordination, agents may use zpeer_ask with mode=\"async\" so the request is visible, governed, and non-blocking; /zpeer remains the interactive command path.\n- Passive wait rule: if the only remaining action is waiting for ZPeer/coms replies, stop the turn and remain idle; do not poll, call tools, or continue just to wait.\n- Use ZPeer only when useful or user-requested; avoid spam, duplicate asks, and reply loops; do not use it for hidden free chat or to bypass topology/safety gates.\n- Raw ZPeer bodies are transient; durable records must remain hash-only/bodyStored=false.\n- last ZPeer event: ${formatZpeerLastEvent(state.zobLive.lastEvent)}`;
 }
 
@@ -389,6 +389,7 @@ function handleSameAgentModeIntent(pi: ExtensionAPI, state: HarnessRuntimeState,
 async function startOrRefreshZobLiveRuntime(pi: ExtensionAPI, state: HarnessRuntimeState, ctx: ExtensionContext): Promise<void> {
   const repoRoot = ctx.cwd;
   const profileId = zpeerRuntimeProfileId(ctx);
+  try { pruneExpiredZobLivePeers(repoRoot); } catch { /* best-effort ghost peer cleanup; live runtime must remain available */ }
   const policy = readZobComsV2Policy(repoRoot);
   if (policy.mode === "off" || policy.mode === "required_network") {
     safelyUpdateZobLivePeer(repoRoot, state.zobLive.peerCard ? "touch" : "register");

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

@@ -353,8 +353,8 @@ export function renderHarnessWidget(pi: ExtensionAPI, state: HarnessRuntimeState
           const marker = summary.active ? "*" : " ";
           const selfAlias = `@${summary.selfAlias ?? "?"}`;
           const peerState = `${summary.online}/${summary.peerCount}${summary.stale > 0 ? ` s${summary.stale}` : ""}${summary.offline > 0 ? ` off${summary.offline}` : ""}`;
-          const peerAliases = summary.aliases.filter((alias) => alias !== summary.selfAlias).slice(0, 2).map((alias) => `@${alias}`);
-          const aliasOverflow = Math.max(0, summary.aliases.length - (summary.selfAlias && summary.aliases.includes(summary.selfAlias) ? 1 : 0) - peerAliases.length);
+          const peerAliases = summary.onlineAliases.filter((alias) => alias !== summary.selfAlias).slice(0, 2).map((alias) => `@${alias}`);
+          const aliasOverflow = Math.max(0, summary.onlineAliases.length - (summary.selfAlias && summary.onlineAliases.includes(summary.selfAlias) ? 1 : 0) - peerAliases.length);
           const aliasText = peerAliases.length > 0 ? `${peerAliases.join(" ")}${aliasOverflow > 0 ? ` +${aliasOverflow}` : ""}` : "no peers";
           return theme.fg("muted", truncateToWidth(`${marker} ${summary.roomId} ${selfAlias} ${peerState} ${aliasText}`, 52, "…"));
         });

package/.pi/skills/zob-agentic-spec-team/SKILL.md

@@ -8,15 +8,18 @@ description: Use when launching, running, reviewing, or extending the Agentic Sp
 
 Use this skill to run a reusable ZOB-native spec production workflow. It ingests a mission plus explicit source paths, coordinates a run-scoped ZTeam, asks the human only through `spec-chief`, and produces a detailed, testable, traceable implementation spec.
 
-V1 packaging is composite and deliberately **not** a runtime extension:
+V1 packaging is composite and deliberately **not** a runtime extension. It is a specialized Agent Factory pattern:
 
 ```text
 Skill = rules and operating contract
 Factory = repeatable checkpoints, sentinels, validators
 ZTeam/ZAgents = run-scoped human-facing team
 CLI = scriptable entrypoint and tmux automation
+Coms = parent-visible async asks, blockers, evidence refs, and oracle/no-ship routing
 ```
 
+Use the generic `examples/agent-factory-tmux-comms/` pattern for a smaller teaching version of the same shape.
+
 ## Entry points
 
 ```bash

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

@@ -30,6 +30,17 @@ ZOB coms live transport may be transient, but ZOB audit must stay metadata-only.
 - No silent fallback from required live delivery to append-only success.
 - No token/secret logging.
 
+## Tmux Agent Factory safety
+
+For tmux-backed ZAgent teams:
+
+- Tmux is a local launch/observation surface, not the durable source of truth.
+- Startup kickoff files are allowed when they stay bounded and avoid secrets/raw private dumps; post-start pane paste is not reliable proof of delivery.
+- Pane capture may be useful for live diagnosis, but do not persist captured prompt/output bodies into ledgers, reports, Mission Control, or skills.
+- Supervisors/watchdogs must be bounded and local-only; they may detect stale windows or nudge a specific owed-response agent only with hash/body-free durable records.
+- Team communication must remain parent-visible. Prefer one `control` room with lanes/tags/artifact sections unless a bounded owner-approved route exists.
+- Completion still requires artifacts, validation evidence, and oracle/no-ship review when applicable; an active tmux session or chat reply is not completion evidence.
+
 ## Goal Room and owner-pool safety
 
 For parallel owner micro-worker pools:
@@ -48,6 +59,8 @@ No-ship if:
 - live send succeeds while receiver is absent/stale/offline;
 - await treats timeout/stale/offline as success;
 - hidden worker-to-worker free chat works outside a typed parent-visible Goal Room;
+- tmux pane paste/capture is treated as reliable durable communication or completion evidence;
+- a supervisor/watchdog nudges indefinitely, starts broad work, or stores raw pane bodies;
 - a non-owner writes owned paths instead of sending an owner request;
 - a worker applies or merges directly into the main workspace;
 - network starts without explicit auth/locality policy;

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

@@ -35,6 +35,17 @@ Use this skill when:
 - Do not bypass topology guards.
 - Do not enable network transport without explicit auth/locality policy.
 
+## Tmux/ZAgent communication pattern
+
+For tmux-backed Agent Factory teams:
+
+- Treat each tmux window as a local Pi/ZAgent session with its own identity and room membership.
+- Use tmux only to start, attach, inspect status, or close the local session; do not use pane paste as the primary communication transport.
+- Prefer startup files (`pi @chief-kickoff.md`, `pi @worker-kickoff.md`) for initial instructions so Pi receives one bounded message block.
+- Use async ZPeer/Goal Room-style asks for normal coordination; do not block in polling loops after sending a non-blocking ask.
+- Keep messages short and actionable with `CONTEXT`, `ASK`, `EVIDENCE`, `URGENCY`, and `BLOCKER` fields.
+- When a reply affects scope, ownership, merge readiness, oracle status, or completion, mirror only body-free metadata/artifact refs into durable records.
+
 ## Expected pattern
 
 ```text

package/.pi/skills/zob-factory/SKILL.md

@@ -17,6 +17,19 @@ Use when the task is repeated, batchable, or should become a reusable system rat
 5. Pilot: 10 items max with bounded concurrency.
 6. Batch: only after pilot sentinel and oracle gate.
 
+## Agent Factory shape
+
+Some factories produce not only code or reports, but a supervised team workflow. Treat these as **Agent Factories**. A safe Agent Factory defines:
+
+- ZAgent roles, prompts, default modes, and allowed authority;
+- ZTeam topology, aliases, rooms, entry agent, and `parentVisible` communication policy;
+- optional manual tmux launcher with start/attach/status/close only;
+- startup kickoff templates or rendered kickoff files passed as `pi @kickoff.md`;
+- run artifacts such as `run-manifest.json`, workgraph/status/iteration logs, readiness or kickoff-dispatch records;
+- validation and oracle/no-ship gates before completion claims.
+
+Do not treat launching a tmux team as factory success. Success comes from evidence artifacts, validators, and oracle review.
+
 ## Required artifacts
 
 - `manifest.json`
@@ -26,3 +39,11 @@ Use when the task is repeated, batchable, or should become a reusable system rat
 - `validation.json`
 - phase sentinel (`SMOKE_PASSED.sentinel`, `PILOT_PASSED.sentinel`, or `BATCH_PASSED.sentinel`)
 - `DONE.sentinel` only after validation passes
+
+For Agent Factories, also prefer:
+
+- team manifest or generated run-scoped team manifest
+- kickoff templates or rendered startup kickoff files
+- `autonomous-workgraph.md` / `autonomous-status.md` / `iteration-log.md`
+- `kickoff-dispatch.json` or equivalent body-free startup proof
+- communication protocol and no-ship policy

package/.pi/skills/zob-harness/SKILL.md

@@ -9,12 +9,26 @@ description: Use when working inside the ZOB Pi harness, designing agentic workf
 Use this skill for any task involving:
 - Pi extensions, prompt templates, skills, or agent definitions.
 - Multi-agent delegation workflows.
+- Agent Factory design: ZAgents, ZTeams, tmux launchers, kickoff files, visible coms, workgraphs, and oracle gates.
 - Safety gates and damage-control policy.
 - Software-factory design from repeated manual workflows.
 - Runtime tool/command routing via `.pi/capabilities/zob-public-runtime-capabilities.json`.
 
 For routing behavior, load `zob-tool-router` before non-trivial or tool-ambiguous work. For compaction/recovery behavior, load `zob-compaction-policy` before changing compaction hooks or resuming from a compacted long-running goal. For domain behavior, load the domain skill named by the registry instead of inlining details here: `zob-goal-todo-tree`, `zob-coms-v2-live`, `zob-coms-safety`, `zob-mission-control-coms`, `zob-autonomous-runtime`, `zob-factory`, `zob-sandbox`, `zob-oracle`, or `zob-spec` as applicable.
 
+## Agent Factory posture
+
+Treat ZOB as a governed Agent Factory when the owner wants persistent local agent roles rather than one transient assistant. An Agent Factory may include:
+
+- ZAgent role definitions and prompts;
+- ZTeam topology, rooms, aliases, entry agent, and communication policy;
+- optional tmux launchers for manual local startup/attach/status/close;
+- startup kickoff files passed as `pi @kickoff.md`, not post-start pane paste as the primary transport;
+- run artifacts such as `run-manifest.json`, workgraph/status/iteration logs, validation reports, and `kickoff-dispatch.json`;
+- oracle/no-ship gates before completion claims.
+
+Communication is a core deliverable. Prefer one parent-visible control room by default; use lanes/tags/artifact sections instead of hidden worker rooms unless the owner explicitly approves a bounded route. The generic teaching example lives in `examples/agent-factory-tmux-comms/`.
+
 ## Operating model
 
 1. Classify the task as one of: `explore`, `plan`, `implement`, `oracle`, `factory`, `orchestrator`.

package/.pi/skills/zob-zagent-creator/SKILL.md

@@ -40,10 +40,18 @@ Generated definitions must stay project-local and are not harness-global:
 
 Never write generated ZAgent, ZTeam, prompt, or tmux launcher artifacts outside those directories unless the owner explicitly provides a different project-local allowed path.
 
+## Documentation examples vs active project teams
+
+When creating documentation-only Agent Factory examples, write them under an explicit example path such as `examples/agent-factory-tmux-comms/` and mark them as inert/example-only. Do not place example manifests under `.pi/zagents/` or `.pi/zteams/` unless the owner is asking to create an active project-local team.
+
+Example files may illustrate a team manifest, manual tmux launcher, and kickoff templates, but they must state that real activation requires owner review and adaptation into `.pi/zagents/`, `.pi/zagents/prompts/`, and `.pi/zteams/`.
+
 ## Optional tmux launcher mode
 
 When the owner starts or qualifies the natural-language request with `tmux`, generate a project-local tmux launcher script alongside the generated ZTeam manifests. This is a convenience artifact only: the assistant must write the script and report manual commands, but must not run tmux, start Pi sessions, attach to tmux, or close tmux sessions automatically.
 
+For Agent Factory launchers, prefer startup kickoff files (`pi @chief-kickoff.md`, `pi @worker-kickoff.md`) over post-start tmux pane paste. Tmux is a local launch/observation wrapper; communication and durable evidence still belong to ZPeer/Goal Room-style visible coordination and run artifacts.
+
 Accepted owner request patterns include:
 
 - `/skill:zob-zagent-creator tmux ...`
@@ -292,6 +300,7 @@ ZAgent manifest mode shape:
 - When the ask mentions model choice or cost/quality tradeoffs, read the model catalog/routing files and record a justified per-ZAgent `model` plus metadata instead of guessing.
 - Keep definitions minimal, auditable, and project-local.
 - When generating tmux launchers, treat multi-team requests as bundles, deduplicate shared agents by `zagentId`, and document included teams, unique agents, and bridge/shared agents.
+- For Agent Factory teams, include or reference the communication policy: `parentVisible: true`, `hiddenPeerChat: false`, `bodyStored: false`, `networkEnabled: false`, and owner/oracle gates for completion.
 - Preserve existing runtime code and safety policy unless the owner explicitly asks for a separate implementation task.
 - Ask for clarification when authority, launch conditions, write permissions, or external access are ambiguous.
 
@@ -303,6 +312,7 @@ ZAgent manifest mode shape:
 - Do not create manifests, prompts, or tmux launchers outside `.pi/zagents/`, `.pi/zagents/prompts/`, or `.pi/zteams/`.
 - Do not grant broad filesystem, network, browser, secret, commit, push, or destructive-command authority by default.
 - Do not generate tmux launchers that duplicate shared ZAgents per team, use `killall`, broad process kills, install daemons, access credentials, or perform global cleanup.
+- Do not present a tmux launcher or kickoff template as proof that agents launched, communicated, validated, or completed work.
 - Do not enable live/global model routing or store provider credentials/API keys while selecting ZAgent models.
 - Do not choose `vanilla` as a default mode unless the owner explicitly requested vanilla/base Pi/direct unrestricted behavior.
 - Do not treat ZAgent creation as delivery success for live communication or mission execution.

package/.pi/zagents/agent-factory-pacman-chief.json

@@ -0,0 +1,22 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "agent-factory-pacman-chief",
+  "team": "agent-factory-pacman-multiplayer",
+  "role": "orchestrator",
+  "alias": "pacman_chief",
+  "description": "Owner-facing chief for the generative Pac-Man multiplayer Agent Factory demo; coordinates workers, workgraph, communication, and final synthesis.",
+  "promptRef": ".pi/zagents/prompts/agent-factory-pacman-chief.md",
+  "defaultMode": "orchestrator",
+  "defaultRoom": "pacman-factory",
+  "activeRoom": "pacman-factory",
+  "rooms": [{ "id": "pacman-factory", "alias": "pacman_chief", "role": "lead", "active": true }],
+  "allowedTools": ["read", "bash", "write", "edit", "zpeer_ask"],
+  "allowedPaths": ["examples/agent-factory-pacman-multiplayer/", "reports/agent-factory-pacman-runs/", ".pi/zteams/agent-factory-pacman-multiplayer.json", ".pi/zteams/agent-factory-pacman-multiplayer.tmux.sh", ".pi/zteams/agent-factory-pacman-multiplayer-runtime.mjs", ".pi/zteams/templates/agent-factory-pacman-*.template.md"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/agent-sessions/", ".pi/coms/"],
+  "approvalGates": { "externalAccess": "human", "externalWrite": "human+oracle", "commitOrPush": "human" },
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["pacman-factory"], "parentVisible": true, "hiddenPeerChat": false, "bodyStored": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false,
+  "metadata": { "modeSelection": { "reason": "Chief coordinates the autonomous team and workgraph.", "authorityNote": "defaultMode sets initial posture only and does not expand permissions." } }
+}

package/.pi/zagents/agent-factory-pacman-engine-builder.json

@@ -0,0 +1,21 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "agent-factory-pacman-engine-builder",
+  "team": "agent-factory-pacman-multiplayer",
+  "role": "engine-builder",
+  "alias": "engine_builder",
+  "description": "Generates the deterministic TypeScript Pac-Man game engine, movement/collision/scoring logic, and tests under the run project directory.",
+  "promptRef": ".pi/zagents/prompts/agent-factory-pacman-engine-builder.md",
+  "defaultMode": "implement",
+  "defaultRoom": "pacman-factory",
+  "activeRoom": "pacman-factory",
+  "rooms": [{ "id": "pacman-factory", "alias": "engine_builder", "role": "engine", "active": true }],
+  "allowedTools": ["read", "bash", "write", "edit", "zpeer_ask"],
+  "allowedPaths": ["examples/agent-factory-pacman-multiplayer/", "reports/agent-factory-pacman-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/agent-sessions/", ".pi/coms/"],
+  "approvalGates": { "externalAccess": "human", "externalWrite": "human+oracle", "commitOrPush": "human" },
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["pacman-factory"], "parentVisible": true, "hiddenPeerChat": false, "bodyStored": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/agent-factory-pacman-frontend-builder.json

@@ -0,0 +1,21 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "agent-factory-pacman-frontend-builder",
+  "team": "agent-factory-pacman-multiplayer",
+  "role": "frontend-builder",
+  "alias": "frontend_builder",
+  "description": "Generates the browser game UI, rendering, local multiplayer controls, HUD, and launcher under the run project directory.",
+  "promptRef": ".pi/zagents/prompts/agent-factory-pacman-frontend-builder.md",
+  "defaultMode": "implement",
+  "defaultRoom": "pacman-factory",
+  "activeRoom": "pacman-factory",
+  "rooms": [{ "id": "pacman-factory", "alias": "frontend_builder", "role": "frontend", "active": true }],
+  "allowedTools": ["read", "bash", "write", "edit", "zpeer_ask"],
+  "allowedPaths": ["examples/agent-factory-pacman-multiplayer/", "reports/agent-factory-pacman-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/agent-sessions/", ".pi/coms/"],
+  "approvalGates": { "externalAccess": "human", "externalWrite": "human+oracle", "commitOrPush": "human" },
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["pacman-factory"], "parentVisible": true, "hiddenPeerChat": false, "bodyStored": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/agent-factory-pacman-game-architect.json

@@ -0,0 +1,21 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "agent-factory-pacman-game-architect",
+  "team": "agent-factory-pacman-multiplayer",
+  "role": "game-architect",
+  "alias": "game_architect",
+  "description": "Designs the generated Pac-Man game architecture, engine/UI boundaries, state contracts, validation ladder, and implementation order.",
+  "promptRef": ".pi/zagents/prompts/agent-factory-pacman-game-architect.md",
+  "defaultMode": "plan",
+  "defaultRoom": "pacman-factory",
+  "activeRoom": "pacman-factory",
+  "rooms": [{ "id": "pacman-factory", "alias": "game_architect", "role": "architecture", "active": true }],
+  "allowedTools": ["read", "bash", "write", "edit", "zpeer_ask"],
+  "allowedPaths": ["examples/agent-factory-pacman-multiplayer/", "reports/agent-factory-pacman-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/agent-sessions/", ".pi/coms/"],
+  "approvalGates": { "externalAccess": "human", "externalWrite": "human+oracle", "commitOrPush": "human" },
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["pacman-factory"], "parentVisible": true, "hiddenPeerChat": false, "bodyStored": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/agent-factory-pacman-game-designer.json

@@ -0,0 +1,21 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "agent-factory-pacman-game-designer",
+  "team": "agent-factory-pacman-multiplayer",
+  "role": "game-designer",
+  "alias": "game_designer",
+  "description": "Defines Pac-Man multiplayer gameplay rules, controls, scoring, round flow, and playability acceptance criteria.",
+  "promptRef": ".pi/zagents/prompts/agent-factory-pacman-game-designer.md",
+  "defaultMode": "plan",
+  "defaultRoom": "pacman-factory",
+  "activeRoom": "pacman-factory",
+  "rooms": [{ "id": "pacman-factory", "alias": "game_designer", "role": "game_design", "active": true }],
+  "allowedTools": ["read", "bash", "write", "edit", "zpeer_ask"],
+  "allowedPaths": ["examples/agent-factory-pacman-multiplayer/", "reports/agent-factory-pacman-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/agent-sessions/", ".pi/coms/"],
+  "approvalGates": { "externalAccess": "human", "externalWrite": "human+oracle", "commitOrPush": "human" },
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["pacman-factory"], "parentVisible": true, "hiddenPeerChat": false, "bodyStored": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/agent-factory-pacman-qa-oracle.json

@@ -0,0 +1,21 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "agent-factory-pacman-qa-oracle",
+  "team": "agent-factory-pacman-multiplayer",
+  "role": "qa-oracle",
+  "alias": "qa_oracle",
+  "description": "Skeptically validates generated Pac-Man multiplayer project playability, tests, structure, safety, and no-ship posture.",
+  "promptRef": ".pi/zagents/prompts/agent-factory-pacman-qa-oracle.md",
+  "defaultMode": "oracle",
+  "defaultRoom": "pacman-factory",
+  "activeRoom": "pacman-factory",
+  "rooms": [{ "id": "pacman-factory", "alias": "qa_oracle", "role": "oracle", "active": true }],
+  "allowedTools": ["read", "bash", "zpeer_ask"],
+  "allowedPaths": ["examples/agent-factory-pacman-multiplayer/", "reports/agent-factory-pacman-runs/", ".pi/zagents/agent-factory-pacman-*.json", ".pi/zteams/agent-factory-pacman-multiplayer.json", ".pi/zteams/agent-factory-pacman-multiplayer-runtime.mjs", ".pi/zteams/agent-factory-pacman-multiplayer.tmux.sh"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/agent-sessions/", ".pi/coms/"],
+  "approvalGates": { "externalAccess": "human", "externalWrite": "human+oracle", "commitOrPush": "human" },
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["pacman-factory"], "parentVisible": true, "hiddenPeerChat": false, "bodyStored": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/prompts/agent-factory-pacman-chief.md

@@ -0,0 +1,53 @@
+# Agent Factory Pac-Man Chief
+
+You are `agent-factory-pacman-chief`, alias `pacman_chief`, the owner-facing coordinator for the Pac-Man multiplayer generative demo.
+
+## Mission
+
+Coordinate a local ZTeam that **generates** a playable Pac-Man-inspired multiplayer browser game under the run target:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/project/
+```
+
+Do not build the game inside `examples/agent-factory-pacman-multiplayer/`; that folder is only the source brief.
+
+## Required communication posture
+
+Use only the parent-visible `pacman-factory` room. Communicate proactively. Do not wait silently.
+
+Message shape:
+
+```text
+CONTEXT:
+ASK:
+EVIDENCE:
+URGENCY:
+BLOCKER:
+```
+
+You must dispatch and track:
+
+- gameplay questions to `@game_designer`;
+- architecture decisions to `@game_architect`;
+- engine/state/collision tasks to `@engine_builder`;
+- rendering/input/HUD tasks to `@frontend_builder`;
+- playability/no-ship/validation review to `@qa_oracle`.
+
+## First turn
+
+1. Read the kickoff file, mission, output contract, and run manifest.
+2. Confirm `READY` in `pacman-factory`.
+3. Update the run workgraph/status/iteration log.
+4. Ask `@game_designer` for rules, controls, scoring, and acceptance criteria.
+5. Ask `@game_architect` for engine/UI/state architecture and validation ladder.
+6. Ask builders to wait for gameplay + architecture handoff before creating broad module boundaries.
+7. Ask `@qa_oracle` for validation/no-ship criteria.
+
+## Must not
+
+- Do not commit/push/tag.
+- Do not read secrets.
+- Do not launch hidden rooms.
+- Do not write generated game code outside the run `project/` directory.
+- Do not claim completion without validation evidence and oracle review.

package/.pi/zagents/prompts/agent-factory-pacman-engine-builder.md

@@ -0,0 +1,41 @@
+# Agent Factory Pac-Man Engine Builder
+
+You are `agent-factory-pacman-engine-builder`, alias `engine_builder`.
+
+## Mission
+
+Generate the deterministic TypeScript game engine for Pac-Man multiplayer under the run project directory:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/project/
+```
+
+## Deliverables
+
+- Game state/types.
+- Maze/grid movement and wall collision.
+- Pellet/score handling.
+- Player/ghost/obstacle collision rules.
+- Round end/restart logic.
+- Engine tests.
+
+## Proactive communication
+
+Ask `@game_architect` when the state model or contracts are unclear. Ask `@game_designer` when scoring/rules are unclear. Ask `@frontend_builder` before changing UI-facing state shapes. Ask `@qa_oracle` when validation coverage is ready or blocked.
+
+Use:
+
+```text
+CONTEXT:
+ASK:
+EVIDENCE:
+URGENCY:
+BLOCKER:
+```
+
+## Must not
+
+- Do not read secrets or raw session/coms bodies.
+- Do not add external service requirements.
+- Do not write generated game code outside the run `project/` directory.
+- Do not claim completion without tests or explicit blocker evidence.