zob-harness 0.7.1 → 0.8.0

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

@@ -1626,7 +1626,7 @@
         "AGENTS.md",
         ".pi/skills/zob-zagent-creator/SKILL.md"
       ],
-      "noShipNotes": "Project-local ZTeam bundle UX for .pi/zteams/ only. ZTeam members are full-session Pi/ZPeer identities tied to live coordination, not delegate subagents; launch-plan is plan/metadata only and must not spawn processes. Persisted command metadata must remain hash/body-free."
+      "noShipNotes": "Project-local ZTeam bundle UX for .pi/zteams/ only. ZTeam members are full-session Pi/ZPeer identities tied to live coordination, not delegate subagents; launch-plan is plan/metadata only and must not spawn processes; reset sends Pi /new to existing scoped tmux agent windows without close/start. Persisted command metadata must remain hash/body-free."
     },
     {
       "name": "rules_status",

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

@@ -5,13 +5,16 @@ import { dirname, join } from "node:path";
 import { loadTeamDefinition, validateTeamDefinition } from "../../topology/teams.js";
 import { isRecord } from "../../../core/utils/records.js";
 import { safeFileStem } from "../../../core/utils/paths.js";
+import { sha256 } from "../../../core/utils/hashing.js";
 import { buildCurrentZobLivePeerCard, buildZobComsProjectId } from "./identity.js";
+import { pingZobLocalEndpoint } from "./local-transport.js";
 import { readZobComsV2Policy, zobComsRegistryEnabled } from "./policy.js";
-import type { ZobLivePeerCard, ZobLivePeerStatus, ZobLiveRegistrySnapshot } from "./types.js";
+import type { ZobLivePeerCard, ZobLivePeerStatus, ZobLiveRegistrySnapshot, ZobLiveTeamAgentLease } 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;
+const MIN_LEASE_TTL_MS = 30_000;
 
 function registryRoot(): { path: string; kind: "user_runtime" | "env_override" } {
   const override = process.env.ZOB_COMS_REGISTRY_ROOT;
@@ -31,6 +34,12 @@ function projectAgentsDir(repoRoot: string): { dir: string; projectId: string; k
   return { dir: join(root.path, "projects", projectId, "agents"), projectId, kind: root.kind };
 }
 
+function projectLeasesDir(repoRoot: string): { dir: string; projectId: string; kind: "user_runtime" | "env_override" } {
+  const root = registryRoot();
+  const projectId = buildZobComsProjectId(repoRoot);
+  return { dir: join(root.path, "projects", projectId, "leases"), projectId, kind: root.kind };
+}
+
 function peerPath(repoRoot: string, peer: Pick<ZobLivePeerCard, "roleId" | "sessionHash">): string {
   const { dir } = projectAgentsDir(repoRoot);
   return join(dir, `${safeFileStem(`${peer.roleId}-${peer.sessionHash.slice(0, 12)}`)}.json`);
@@ -40,6 +49,22 @@ function peerPathForProjectId(projectId: string, peer: Pick<ZobLivePeerCard, "ro
   return join(registryRoot().path, "projects", safeFileStem(projectId), "agents", `${safeFileStem(`${peer.roleId}-${peer.sessionHash.slice(0, 12)}`)}.json`);
 }
 
+function stableLeaseStem(input: Pick<ZobLivePeerCard, "team" | "roleId"> | Pick<ZobLiveTeamAgentLease, "teamId" | "agentId">): string {
+  const teamId = "team" in input ? input.team : input.teamId;
+  const agentId = "roleId" in input ? input.roleId : input.agentId;
+  return safeFileStem(`${teamId}-${agentId}`);
+}
+
+function leasePath(repoRoot: string, peer: Pick<ZobLivePeerCard, "team" | "roleId">): string {
+  const { dir } = projectLeasesDir(repoRoot);
+  return join(dir, `${stableLeaseStem(peer)}.json`);
+}
+
+function leasePathForTeamAgent(repoRoot: string, teamId: string, agentId: string): string {
+  const { dir } = projectLeasesDir(repoRoot);
+  return join(dir, `${safeFileStem(`${teamId}-${agentId}`)}.json`);
+}
+
 function readPeerCardsFromAgentsDir(dir: string, nowMs: number, teamName?: string): ZobLivePeerCard[] {
   if (!existsSync(dir)) return [];
   return readdirSync(dir)
@@ -56,6 +81,22 @@ function readPeerCardsFromAgentsDir(dir: string, nowMs: number, teamName?: strin
     .map((peer) => ({ ...peer, status: derivePeerStatus(peer, nowMs) }));
 }
 
+function readLeasesFromDir(dir: string, nowMs: number, teamName?: string): ZobLivePeerCard[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((entry) => entry.endsWith(".json"))
+    .map((entry) => {
+      try {
+        return parseTeamAgentLease(JSON.parse(readFileSync(join(dir, entry), "utf8")) as unknown);
+      } catch {
+        return undefined;
+      }
+    })
+    .filter((lease): lease is ZobLiveTeamAgentLease => Boolean(lease))
+    .filter((lease) => !teamName || lease.teamId === teamName)
+    .map((lease) => leaseToPeerCard(lease, 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;
@@ -69,6 +110,12 @@ function offlinePeerExpired(peer: ZobLivePeerCard, nowMs: number, retentionMs: n
   return nowMs - heartbeatMs >= Math.max(peer.offlineAfterMs, retentionMs);
 }
 
+function leaseExpired(lease: ZobLiveTeamAgentLease, nowMs: number, retentionMs = 0): boolean {
+  const expiresMs = Date.parse(lease.expiresAt);
+  if (!Number.isFinite(expiresMs)) return true;
+  return nowMs >= expiresMs + Math.max(0, retentionMs);
+}
+
 function allProjectAgentsDirs(): string[] {
   const root = registryRoot();
   const projectsDir = join(root.path, "projects");
@@ -78,6 +125,15 @@ function allProjectAgentsDirs(): string[] {
     .map((entry) => join(projectsDir, entry.name, "agents"));
 }
 
+function allProjectLeasesDirs(): string[] {
+  const root = registryRoot();
+  const projectsDir = join(root.path, "projects");
+  if (!existsSync(projectsDir)) return [];
+  return readdirSync(projectsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(projectsDir, entry.name, "leases"));
+}
+
 function buildSnapshot(projectId: string, kind: "user_runtime" | "env_override", peers: ZobLivePeerCard[], teamName?: string): ZobLiveRegistrySnapshot {
   const counts: Record<ZobLivePeerStatus, number> = { online: 0, stale: 0, offline: 0 };
   for (const peer of peers) counts[peer.status] += 1;
@@ -100,6 +156,15 @@ function parsePeerCard(value: unknown): ZobLivePeerCard | undefined {
   return value as unknown as ZobLivePeerCard;
 }
 
+function parseTeamAgentLease(value: unknown): ZobLiveTeamAgentLease | undefined {
+  if (!isRecord(value) || value.schema !== "zob.live-team-agent-lease.v1") return undefined;
+  if (hasForbiddenPersistedKey(value) || value.bodyStored !== false || value.localOnly !== true || value.networkEnabled !== false) return undefined;
+  if (value.stableLease !== true || value.exclusiveBy !== "teamId+agentId") return undefined;
+  if (typeof value.teamId !== "string" || typeof value.agentId !== "string" || typeof value.sessionHash !== "string") return undefined;
+  if (typeof value.leaseOwnerId !== "string" || typeof value.endpoint !== "string" || typeof value.endpointHash !== "string") return undefined;
+  return value as unknown as ZobLiveTeamAgentLease;
+}
+
 function derivePeerStatus(peer: ZobLivePeerCard, nowMs: number): ZobLivePeerStatus {
   if (peer.status === "offline") return "offline";
   const heartbeatMs = Date.parse(peer.heartbeatAt);
@@ -109,32 +174,206 @@ function derivePeerStatus(peer: ZobLivePeerCard, nowMs: number): ZobLivePeerStat
   return "online";
 }
 
+function deriveLeaseStatus(lease: ZobLiveTeamAgentLease, nowMs: number): ZobLivePeerStatus {
+  if (lease.status === "offline" || leaseExpired(lease, nowMs)) return "offline";
+  const heartbeatMs = Date.parse(lease.heartbeatAt);
+  if (!Number.isFinite(heartbeatMs)) return "stale";
+  if (nowMs - heartbeatMs >= lease.offlineAfterMs) return "offline";
+  if (nowMs - heartbeatMs >= lease.staleAfterMs) return "stale";
+  return "online";
+}
+
+function leaseOwnerId(peer: Pick<ZobLivePeerCard, "team" | "roleId" | "sessionHash" | "endpointHash">): string {
+  return `${peer.team}:${peer.roleId}:${peer.sessionHash}:${peer.endpointHash}`;
+}
+
+function sameLeaseOwner(lease: ZobLiveTeamAgentLease, peer: Pick<ZobLivePeerCard, "team" | "roleId" | "sessionHash" | "endpointHash">): boolean {
+  return lease.teamId === peer.team
+    && lease.agentId === peer.roleId
+    && lease.sessionHash === peer.sessionHash
+    && lease.endpointHash === peer.endpointHash
+    && lease.leaseOwnerId === leaseOwnerId(peer);
+}
+
+function leaseExpiresAt(peer: Pick<ZobLivePeerCard, "offlineAfterMs" | "staleAfterMs">, nowMs: number): string {
+  const ttlMs = Math.max(MIN_LEASE_TTL_MS, Math.floor(Math.max(peer.offlineAfterMs, peer.staleAfterMs * 2)));
+  return new Date(nowMs + ttlMs).toISOString();
+}
+
+function buildTeamAgentLease(repoRoot: string, peer: ZobLivePeerCard, input: { nowMs?: number } = {}): ZobLiveTeamAgentLease {
+  const nowMs = input.nowMs ?? Date.now();
+  const now = new Date(nowMs).toISOString();
+  const projectId = buildZobComsProjectId(repoRoot);
+  const ownerId = leaseOwnerId(peer);
+  return {
+    schema: "zob.live-team-agent-lease.v1",
+    projectId,
+    teamId: peer.team,
+    agentId: peer.roleId,
+    roleId: peer.roleId,
+    roleType: peer.roleType,
+    leadId: peer.leadId,
+    agent: peer.agent,
+    sessionId: peer.sessionId,
+    sessionHash: peer.sessionHash,
+    leaseOwnerId: ownerId,
+    leaseOwnerHash: sha256(ownerId),
+    transport: peer.transport,
+    endpoint: peer.endpoint,
+    endpointHash: peer.endpointHash,
+    cwdHash: peer.cwdHash,
+    pid: peer.pid,
+    startedAt: peer.startedAt,
+    heartbeatAt: now,
+    leasedAt: now,
+    renewedAt: now,
+    expiresAt: leaseExpiresAt(peer, nowMs),
+    contextUsedPct: peer.contextUsedPct,
+    queueDepth: peer.queueDepth,
+    status: peer.status === "offline" ? "offline" : "online",
+    zpeerRoomId: peer.zpeerRoomId,
+    zpeerAlias: peer.zpeerAlias,
+    zpeerActiveRoomId: peer.zpeerActiveRoomId,
+    zpeerMemberships: peer.zpeerMemberships,
+    zpeerLocalOnly: peer.zpeerLocalOnly,
+    staleAfterMs: peer.staleAfterMs,
+    offlineAfterMs: peer.offlineAfterMs,
+    stableLease: true,
+    exclusiveBy: "teamId+agentId",
+    localOnly: true,
+    networkEnabled: false,
+    bodyStored: false,
+  };
+}
+
+function renewTeamAgentLease(repoRoot: string, existing: ZobLiveTeamAgentLease | undefined, peer: ZobLivePeerCard, input: { nowMs?: number } = {}): ZobLiveTeamAgentLease {
+  const nowMs = input.nowMs ?? Date.now();
+  const now = new Date(nowMs).toISOString();
+  const next = buildTeamAgentLease(repoRoot, peer, { nowMs });
+  return existing && sameLeaseOwner(existing, peer)
+    ? { ...next, leasedAt: existing.leasedAt, renewedAt: now }
+    : next;
+}
+
+function leaseToPeerCard(lease: ZobLiveTeamAgentLease, nowMs: number): ZobLivePeerCard {
+  return {
+    schema: "zob.live-peer-card.v1",
+    projectId: lease.projectId,
+    team: lease.teamId,
+    roleId: lease.roleId,
+    roleType: lease.roleType,
+    leadId: lease.leadId,
+    agent: lease.agent,
+    sessionId: lease.sessionId,
+    sessionHash: lease.sessionHash,
+    transport: lease.transport,
+    endpoint: lease.endpoint,
+    endpointHash: lease.endpointHash,
+    cwdHash: lease.cwdHash,
+    pid: lease.pid,
+    startedAt: lease.startedAt,
+    heartbeatAt: lease.heartbeatAt,
+    contextUsedPct: lease.contextUsedPct,
+    queueDepth: lease.queueDepth,
+    status: deriveLeaseStatus(lease, nowMs),
+    zpeerRoomId: lease.zpeerRoomId,
+    zpeerAlias: lease.zpeerAlias,
+    zpeerActiveRoomId: lease.zpeerActiveRoomId,
+    zpeerMemberships: lease.zpeerMemberships,
+    zpeerLocalOnly: lease.zpeerLocalOnly,
+    staleAfterMs: lease.staleAfterMs,
+    offlineAfterMs: lease.offlineAfterMs,
+    bodyStored: false,
+  };
+}
+
+function readLeaseAtPath(filePath: string): ZobLiveTeamAgentLease | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    return parseTeamAgentLease(JSON.parse(readFileSync(filePath, "utf8")) as unknown);
+  } catch {
+    return undefined;
+  }
+}
+
+function writeLeaseAtPath(filePath: string, lease: ZobLiveTeamAgentLease): ZobLiveTeamAgentLease {
+  if (hasForbiddenPersistedKey(lease)) throw new Error("Refusing to persist ZOB live team-agent lease with forbidden body-like keys");
+  if (lease.bodyStored !== false || lease.localOnly !== true || lease.networkEnabled !== false) throw new Error("ZOB live team-agent lease must be localOnly=true networkEnabled=false bodyStored=false");
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(lease, null, 2)}\n`, "utf8");
+  return lease;
+}
+
+function leaseHasLocalSocketEndpoint(lease: ZobLiveTeamAgentLease): boolean {
+  return lease.transport === "local_socket"
+    && Boolean(lease.endpoint)
+    && !lease.endpoint.startsWith("pending-")
+    && lease.endpoint !== "observe-only"
+    && existsSync(lease.endpoint);
+}
+
+async function leaseRespondsToPing(lease: ZobLiveTeamAgentLease): Promise<boolean> {
+  if (!leaseHasLocalSocketEndpoint(lease)) return false;
+  try {
+    const response = await pingZobLocalEndpoint(lease.endpoint, `zteam-agent-lease-ping:${lease.teamId}:${lease.agentId}:${Date.now()}`);
+    return response.type === "pong" || response.type === "ack";
+  } catch {
+    return false;
+  }
+}
+
 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 {
+  if (existsSync(dir)) {
+    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;
       }
-    } catch {
+    }
+  }
+  const leasePrune = pruneExpiredZobLiveTeamAgentLeases(repoRoot, input);
+  return { schema: "zob.live-registry-prune.v1", pruned: pruned + leasePrune.pruned, retained: retained + leasePrune.retained, retentionMs, bodyStored: false };
+}
+
+export function pruneExpiredZobLiveTeamAgentLeases(repoRoot: string, input: { teamName?: string; nowMs?: number; retentionMs?: number } = {}): { schema: "zob.live-team-agent-lease-prune.v1"; pruned: number; retained: number; retentionMs: number; bodyStored: false } {
+  const { dir } = projectLeasesDir(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-team-agent-lease-prune.v1", pruned, retained, retentionMs, bodyStored: false };
+  for (const entry of readdirSync(dir).filter((name) => name.endsWith(".json"))) {
+    const filePath = join(dir, entry);
+    const lease = readLeaseAtPath(filePath);
+    if (!lease || (input.teamName && lease.teamId !== input.teamName)) {
+      retained += 1;
+      continue;
+    }
+    if (leaseExpired(lease, nowMs, retentionMs)) {
+      unlinkSync(filePath);
+      pruned += 1;
+    } else {
       retained += 1;
     }
   }
-  return { schema: "zob.live-registry-prune.v1", pruned, retained, retentionMs, bodyStored: false };
+  return { schema: "zob.live-team-agent-lease-prune.v1", pruned, retained, retentionMs, bodyStored: false };
 }
 
 export function writeZobLivePeerCard(repoRoot: string, peer: ZobLivePeerCard): ZobLivePeerCard {
@@ -142,7 +381,7 @@ export function writeZobLivePeerCard(repoRoot: string, peer: ZobLivePeerCard): Z
   if (peer.bodyStored !== false) throw new Error("ZOB live peer card bodyStored must be false");
   const { dir } = projectAgentsDir(repoRoot);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(peerPath(repoRoot, peer), `${JSON.stringify(peer, null, 2)}\n`, "utf8");
+  writeFileSync(peerPath(repoRoot, peer), `${JSON.stringify({ ...peer, projectId: buildZobComsProjectId(repoRoot) }, null, 2)}\n`, "utf8");
   return peer;
 }
 
@@ -155,18 +394,112 @@ export function writeZobLivePeerCardToProjectId(peer: ZobLivePeerCard): ZobLiveP
   return peer;
 }
 
+export function writeZobLiveTeamAgentLease(repoRoot: string, peer: ZobLivePeerCard, input: { reason?: string; nowMs?: number } = {}): ZobLiveTeamAgentLease {
+  const filePath = leasePath(repoRoot, peer);
+  const existing = readLeaseAtPath(filePath);
+  const nowMs = input.nowMs ?? Date.now();
+  if (existing && !sameLeaseOwner(existing, peer) && !leaseExpired(existing, nowMs)) return existing;
+  const ownedExisting = existing && sameLeaseOwner(existing, peer) ? existing : undefined;
+  return writeLeaseAtPath(filePath, renewTeamAgentLease(repoRoot, ownedExisting, peer, { nowMs }));
+}
+
+export async function claimZobLiveTeamAgentLease(repoRoot: string, peer: ZobLivePeerCard, input: { reason?: string; nowMs?: number } = {}): Promise<
+  | { ok: true; status: "acquired" | "renewed" | "reclaimed"; lease: ZobLiveTeamAgentLease; previousOwnerHash?: string; pingChecked: boolean; bodyStored: false }
+  | { ok: false; status: "blocked_live_owner"; lease: ZobLiveTeamAgentLease; ownerHash: string; reason: string; pingChecked: true; bodyStored: false }
+> {
+  const filePath = leasePath(repoRoot, peer);
+  const existing = readLeaseAtPath(filePath);
+  const nowMs = input.nowMs ?? Date.now();
+  if (!existing) {
+    const lease = writeLeaseAtPath(filePath, buildTeamAgentLease(repoRoot, peer, { nowMs }));
+    return { ok: true, status: "acquired", lease, pingChecked: false, bodyStored: false };
+  }
+  if (sameLeaseOwner(existing, peer)) {
+    const lease = writeLeaseAtPath(filePath, renewTeamAgentLease(repoRoot, existing, peer, { nowMs }));
+    return { ok: true, status: "renewed", lease, pingChecked: false, bodyStored: false };
+  }
+  const responsive = await leaseRespondsToPing(existing);
+  if (responsive) {
+    return {
+      ok: false,
+      status: "blocked_live_owner",
+      lease: existing,
+      ownerHash: existing.leaseOwnerHash,
+      reason: `stable team-agent lease for ${existing.teamId}/${existing.agentId} is held by a responsive live endpoint`,
+      pingChecked: true,
+      bodyStored: false,
+    };
+  }
+  const lease = writeLeaseAtPath(filePath, buildTeamAgentLease(repoRoot, peer, { nowMs }));
+  return { ok: true, status: "reclaimed", lease, previousOwnerHash: existing.leaseOwnerHash, pingChecked: true, bodyStored: false };
+}
+
+export function releaseZobLiveTeamAgentLease(repoRoot: string, peer: ZobLivePeerCard, input: { reason?: string } = {}): { schema: "zob.live-team-agent-lease-release.v1"; released: boolean; reason: "released" | "not_found" | "owner_mismatch"; teamId: string; agentId: string; leaseOwnerHash?: string; bodyStored: false } {
+  void input;
+  const filePath = leasePath(repoRoot, peer);
+  const existing = readLeaseAtPath(filePath);
+  if (!existing) return { schema: "zob.live-team-agent-lease-release.v1", released: false, reason: "not_found", teamId: peer.team, agentId: peer.roleId, bodyStored: false };
+  if (!sameLeaseOwner(existing, peer)) return { schema: "zob.live-team-agent-lease-release.v1", released: false, reason: "owner_mismatch", teamId: peer.team, agentId: peer.roleId, leaseOwnerHash: existing.leaseOwnerHash, bodyStored: false };
+  unlinkSync(filePath);
+  return { schema: "zob.live-team-agent-lease-release.v1", released: true, reason: "released", teamId: peer.team, agentId: peer.roleId, leaseOwnerHash: existing.leaseOwnerHash, bodyStored: false };
+}
+
+export function ownsZobLiveTeamAgentLease(repoRoot: string, peer: ZobLivePeerCard): { schema: "zob.live-team-agent-lease-ownership.v1"; owned: boolean; reason: "owned" | "not_found" | "owner_mismatch" | "expired"; teamId: string; agentId: string; leaseOwnerHash?: string; bodyStored: false } {
+  const filePath = leasePath(repoRoot, peer);
+  const existing = readLeaseAtPath(filePath);
+  if (!existing) return { schema: "zob.live-team-agent-lease-ownership.v1", owned: false, reason: "not_found", teamId: peer.team, agentId: peer.roleId, bodyStored: false };
+  if (leaseExpired(existing, Date.now())) return { schema: "zob.live-team-agent-lease-ownership.v1", owned: false, reason: "expired", teamId: peer.team, agentId: peer.roleId, leaseOwnerHash: existing.leaseOwnerHash, bodyStored: false };
+  if (!sameLeaseOwner(existing, peer)) return { schema: "zob.live-team-agent-lease-ownership.v1", owned: false, reason: "owner_mismatch", teamId: peer.team, agentId: peer.roleId, leaseOwnerHash: existing.leaseOwnerHash, bodyStored: false };
+  return { schema: "zob.live-team-agent-lease-ownership.v1", owned: true, reason: "owned", teamId: peer.team, agentId: peer.roleId, leaseOwnerHash: existing.leaseOwnerHash, bodyStored: false };
+}
+
+export async function retireInactiveZobLiveTeamAgentLeases(repoRoot: string, input: { teamName: string; agentIds: string[]; nowMs?: number }): Promise<{ schema: "zob.live-team-agent-lease-retire.v1"; teamName: string; checked: number; retired: number; retainedLive: number; missing: number; errorHashes: string[]; bodyStored: false }> {
+  const errors: string[] = [];
+  let checked = 0;
+  let retired = 0;
+  let retainedLive = 0;
+  let missing = 0;
+  const uniqueAgentIds = [...new Set(input.agentIds.filter((agentId) => agentId.trim().length > 0))];
+  for (const agentId of uniqueAgentIds) {
+    const filePath = leasePathForTeamAgent(repoRoot, input.teamName, agentId);
+    const lease = readLeaseAtPath(filePath);
+    if (!lease) {
+      missing += 1;
+      continue;
+    }
+    checked += 1;
+    try {
+      const live = await leaseRespondsToPing(lease);
+      if (live) {
+        retainedLive += 1;
+      } else {
+        unlinkSync(filePath);
+        retired += 1;
+      }
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return { schema: "zob.live-team-agent-lease-retire.v1", teamName: input.teamName, checked, retired, retainedLive, missing, errorHashes: errors.map((error) => sha256(error)), bodyStored: false };
+}
+
 export function registerCurrentZobLivePeer(repoRoot: string, teamName = "zob-core"): ZobLivePeerCard | undefined {
   const policy = readZobComsV2Policy(repoRoot);
   if (!zobComsRegistryEnabled(policy)) return undefined;
   const team = loadTeamDefinition(repoRoot, teamName);
   const errors = [...team.errors, ...validateTeamDefinition(repoRoot, team.definition)];
   if (errors.length > 0 || !team.definition) throw new Error(`Cannot register ZOB live peer: ${errors.join("; ")}`);
-  return writeZobLivePeerCard(repoRoot, buildCurrentZobLivePeerCard(repoRoot, team.definition, policy));
+  const peer = writeZobLivePeerCard(repoRoot, buildCurrentZobLivePeerCard(repoRoot, team.definition, policy));
+  writeZobLiveTeamAgentLease(repoRoot, peer, { reason: "register_current" });
+  return peer;
 }
 
 export function touchCurrentZobLivePeer(repoRoot: string, teamName = "zob-core"): ZobLivePeerCard | undefined {
   const peer = registerCurrentZobLivePeer(repoRoot, teamName);
-  return peer ? writeZobLivePeerCard(repoRoot, { ...peer, heartbeatAt: new Date().toISOString(), status: "online" }) : undefined;
+  if (!peer) return undefined;
+  const touched = writeZobLivePeerCard(repoRoot, { ...peer, heartbeatAt: new Date().toISOString(), status: "online" });
+  writeZobLiveTeamAgentLease(repoRoot, touched, { reason: "touch_current" });
+  return touched;
 }
 
 export function unregisterCurrentZobLivePeer(repoRoot: string, teamName = "zob-core"): ZobLivePeerCard | undefined {
@@ -174,17 +507,25 @@ export function unregisterCurrentZobLivePeer(repoRoot: string, teamName = "zob-c
   const team = loadTeamDefinition(repoRoot, teamName);
   if (!team.definition || !zobComsRegistryEnabled(policy)) return undefined;
   const peer = buildCurrentZobLivePeerCard(repoRoot, team.definition, policy);
+  releaseZobLiveTeamAgentLease(repoRoot, peer, { reason: "unregister_current" });
   return writeZobLivePeerCard(repoRoot, { ...peer, heartbeatAt: new Date().toISOString(), status: "offline" });
 }
 
 export function readZobLiveRegistrySnapshot(repoRoot: string, teamName?: string): ZobLiveRegistrySnapshot {
-  const { dir, projectId, kind } = projectAgentsDir(repoRoot);
-  return buildSnapshot(projectId, kind, readPeerCardsFromAgentsDir(dir, Date.now(), teamName), teamName);
+  const { dir, projectId, kind } = projectLeasesDir(repoRoot);
+  const nowMs = Date.now();
+  if (existsSync(dir)) return buildSnapshot(projectId, kind, readLeasesFromDir(dir, nowMs, teamName), teamName);
+  const agents = projectAgentsDir(repoRoot);
+  return buildSnapshot(agents.projectId, agents.kind, readPeerCardsFromAgentsDir(agents.dir, nowMs, teamName), teamName);
 }
 
 export function readZobLiveRegistryAllProjectsSnapshot(repoRoot: string, teamName?: string): ZobLiveRegistrySnapshot {
   const { projectId, kind } = projectAgentsDir(repoRoot);
   const nowMs = Date.now();
-  const peers = allProjectAgentsDirs().flatMap((dir) => readPeerCardsFromAgentsDir(dir, nowMs, teamName));
+  const leaseDirs = allProjectLeasesDirs();
+  const hasLeaseDomain = leaseDirs.some((dir) => existsSync(dir));
+  const peers = hasLeaseDomain
+    ? leaseDirs.flatMap((dir) => readLeasesFromDir(dir, nowMs, teamName))
+    : allProjectAgentsDirs().flatMap((dir) => readPeerCardsFromAgentsDir(dir, nowMs, teamName));
   return buildSnapshot(projectId, kind, peers, teamName);
 }

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

@@ -114,6 +114,46 @@ export interface ZobLivePeerCard {
   bodyStored: false;
 }
 
+export interface ZobLiveTeamAgentLease {
+  schema: "zob.live-team-agent-lease.v1";
+  projectId: string;
+  teamId: string;
+  agentId: string;
+  roleId: string;
+  roleType: ZobLiveRoleType;
+  leadId?: string;
+  agent: string;
+  sessionId: string;
+  sessionHash: string;
+  leaseOwnerId: string;
+  leaseOwnerHash: string;
+  transport: ZobLiveTransportKind;
+  endpoint: string;
+  endpointHash: string;
+  cwdHash: string;
+  pid?: number;
+  startedAt: string;
+  heartbeatAt: string;
+  leasedAt: string;
+  renewedAt: string;
+  expiresAt: string;
+  contextUsedPct: number;
+  queueDepth: number;
+  status: ZobLivePeerStatus;
+  zpeerRoomId?: string;
+  zpeerAlias?: string;
+  zpeerActiveRoomId?: string;
+  zpeerMemberships?: ZpeerRoomMembership[];
+  zpeerLocalOnly?: true;
+  staleAfterMs: number;
+  offlineAfterMs: number;
+  stableLease: true;
+  exclusiveBy: "teamId+agentId";
+  localOnly: true;
+  networkEnabled: false;
+  bodyStored: false;
+}
+
 export interface ZobLiveRegistrySnapshot {
   schema: "zob.live-registry-snapshot.v1";
   projectId: string;

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

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { buildZobComsProjectId } from "./identity.js";
 import { buildZobLiveEnvelope } from "./envelope.js";
 import { sendZobLocalEnvelope } from "./local-transport.js";
-import { readZobLiveRegistryAllProjectsSnapshot, writeZobLivePeerCard, writeZobLivePeerCardToProjectId } from "./registry.js";
+import { ownsZobLiveTeamAgentLease, readZobLiveRegistryAllProjectsSnapshot, writeZobLivePeerCard, writeZobLivePeerCardToProjectId, writeZobLiveTeamAgentLease } from "./registry.js";
 import type { ZobLivePeerCard, ZobLivePeerStatus, ZpeerRoomMembership, ZpeerRoomMembershipRole } from "./types.js";
 import { validateZobComsEdge } from "../../topology/coms.js";
 import { loadTeamDefinition, validateTeamDefinition } from "../../topology/teams.js";
@@ -233,7 +233,9 @@ export function ensureZpeerFields(repoRoot: string, peer: ZobLivePeerCard, roomI
 export function refreshZpeerSelf(repoRoot: string, peer: ZobLivePeerCard, roomId?: string, alias?: string, restoredMemberships?: ZpeerRoomMembership[]): ZobLivePeerCard {
   const ensured = ensureZpeerFields(repoRoot, peer, roomId, alias, restoredMemberships);
   if (!hasLocalSocketEndpointEvidence(ensured)) return ensured;
-  return writeZobLivePeerCard(repoRoot, { ...ensured, heartbeatAt: new Date().toISOString(), status: "online" });
+  const refreshed = writeZobLivePeerCard(repoRoot, { ...ensured, heartbeatAt: new Date().toISOString(), status: "online" });
+  writeZobLiveTeamAgentLease(repoRoot, refreshed, { reason: "zpeer_refresh" });
+  return refreshed;
 }
 
 type ZobLiveRegistrySnapshotValue = ReturnType<typeof readZobLiveRegistryAllProjectsSnapshot>;
@@ -477,6 +479,8 @@ export async function sendZpeerPrompt(repoRoot: string, self: ZobLivePeerCard, t
   };
 
   if (!selfMembership) return finish("attempt", { status: "blocked", reason: `current peer is not a member of room '${roomId}'`, targetAlias: targetAlias ?? undefined, taskHash, bodyStored: false });
+  const leaseOwnership = ownsZobLiveTeamAgentLease(repoRoot, self);
+  if (!leaseOwnership.owned) return finish("attempt", { status: "blocked", reason: `current peer does not own stable team-agent lease (${leaseOwnership.reason})`, targetAlias: targetAlias ?? undefined, taskHash, bodyStored: false });
   if (selfMembership.role === "observer") return finish("attempt", { status: "blocked", reason: `current peer is observer-only in room '${roomId}'`, targetAlias: targetAlias ?? undefined, taskHash, 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 });