@semanaut/zpi-peer 2.0.3 → 2.5.0

package/README.md

@@ -11,11 +11,18 @@ Peers are equal instances, not subordinates: each runs in its own tmux pane, wit
 - **Revive**: a dark session is restarted with `pi --session <sid>` in a fresh pane, restoring its full history. The sid becomes disk-durable once the peer submits its first message; a peer killed before that cannot be resumed.
 - **Normal tmux workflow works**: switch panes/windows, watch a peer work live in its pane, kill it with tmux when done.
 
-## The three tools
+## The four tools
 
-- **`peer_spawn`** — launch an equal peer in a tmux pane; optional role-prompt file and fork/handoff context.
-- **`peer_list`** — list sessions and their liveness, filterable by creator ("self" = your own peers).
-- **`peer_send_mail`** — deliver a letter to any pi session's mailbox, peers and human-started alike.
+- **`peer_spawn(name, task, prompt?, context?, model?)`** — launch an equal peer in a tmux pane. The peer is named `[peer]<name>`; the name is the peer's identity carrier, so make it declare function, responsibility, and state. Optional role-prompt file and fork/handoff context.
+- **`peer_list`** — list sessions and their contact counts, filterable by contact ("self" = the sessions you have spawned or exchanged letters with; any sessionId = who that session communicated with).
+- **`peer_send_mail`** — deliver a letter to any pi session's mailbox, peers and human-started alike; a dead recipient is revived automatically.
+- **`peer_name`** — read or set a session's own name. Omit the argument to read the name as it exists on disk (the last `session_info` entry — the same value every external reader sees); pass a name to set it, effective immediately. The tool never touches another session: renaming another peer goes through a letter, so the peer also learns why its name changed.
+
+## Data layout
+
+- `<agent dir>/peer/registry/<sessionId>/role.json` — role record (exists only for sessions with a role; plain peers carry none).
+- `<agent dir>/peer/registry/<sessionId>/contacts.txt` — append-only contact log, one sessionId per line.
+- `<agent dir>/peer/letters/<sessionId>/` — the session's mailbox (`pending-*.md` letters awaiting delivery).
 
 ## Compatibility
 
@@ -41,4 +48,4 @@ On every start the extension mirrors the bundled role files into the peer data d
 
 ## Bundled skill
 
-Installs the `peer-orchestrator` skill alongside the extension: the policy for when to spawn peers (only for genuinely parallel, independent work), how to write a self-contained first task, how to choose a peer's starting context, and how to batch follow-up letters.
+Installs the `peer-orchestrator` skill alongside the extension: the policy for when to spawn peers (only for genuinely parallel, independent work), how to name them (the name is the identity carrier — function, responsibility, state — and must be kept in sync as the peer's state changes), how to write a self-contained first task, how to choose a peer's starting context, and how to batch follow-up letters.

package/extensions/zpi-peer.ts

@@ -18,13 +18,11 @@ const SKILL_GATE =
 	"Before calling this tool, read the peer-orchestrator skill.";
 const REVIVE_TIMEOUT_MS = 25_000;
 const SPAWN_BOOT_TIMEOUT_MS = 20_000;
-const LIST_PAGE_SIZE = 40;
-const BATCH_SEP = "\n\n──────── next letter ────────\n\n";
+const LIST_PAGE_SIZE = 15;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 interface PeerRecord {
-	creatorSessionId: string;
-	/** Absolute role-file path; absent for plain peers. */
-	appendPrompt?: string;
+	/** Absolute role-file path — a record exists only for sessions WITH a role. */
+	appendPrompt: string;
 }
 
 interface SessionRecord {
@@ -32,12 +30,11 @@ interface SessionRecord {
 	name: string | null;
 	cwd: string;
 	startedAt: number;
-	alive: boolean;
 	peer?: PeerRecord;
+	/** Sessions it spawned or exchanged letters with (both directions); ghost ids filtered out. */
+	contactIds: string[];
 }
 
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
 /** v7 (time-ordered) to match pi's own session ids. */
 function uuidv7(): string {
 	const ts = BigInt(Date.now());
@@ -54,7 +51,7 @@ function uuidv7(): string {
 	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 
-/** First gate of every peer tool: this pi must run inside tmux. A throw reads as "server down". */
+/** First gate of the tools that touch tmux (spawn / send_mail): this pi must run inside tmux. A throw reads as "server down". */
 async function tmuxGuard(pi: ExtensionAPI): Promise<string | null> {
 	if (process.env.TMUX) return null;
 	let serverUp = false;
@@ -68,10 +65,10 @@ function shq(s: string): string {
 	return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 
-/** The pi invocation for a pane command: works under node, bun and the compiled binary.
- *  PI_PEER_CMD, when set, overrides the launcher used for panes
- *  (a deployment pin — takes precedence over execPath). */
-function piCommandString(args: string[]): string {
+/** pi + optional first user message. Works under node, bun and the compiled binary; PI_PEER_CMD,
+ *  when set, overrides the launcher (a deployment pin). Nothing holds the pane open, so a
+ *  peer's window closes with its pi. */
+function buildCommand(opts: { args: string[]; firstMessage?: string }): string {
 	const script = process.argv[1];
 	const launcher =
 		script && !script.startsWith("/$bunfs/root/") && fs.existsSync(script)
@@ -79,14 +76,9 @@ function piCommandString(args: string[]): string {
 			: /^(node|bun)(\.exe)?$/i.test(path.basename(process.execPath))
 				? ["pi"]
 				: [process.env.PI_PEER_CMD || process.execPath];
-	return [...launcher, ...args].map(shq).join(" ");
-}
-
-/** pi + optional first user message. Nothing holds the pane open, so a peer's window closes with its pi. */
-function buildCommand(opts: { args: string[]; firstMessage?: string }): string {
 	const msg = opts.firstMessage;
 	const positional = msg === undefined || msg === "" ? "" : ` -- ${shq(/^[-@]/.test(msg) ? ` ${msg}` : msg)}`;
-	return `${piCommandString(opts.args)}${positional}`;
+	return `${[...launcher, ...opts.args].map(shq).join(" ")}${positional}`;
 }
 
 /** pi.exec can THROW instead of returning non-zero — every throw is folded into { ok: false } and never escapes. */
@@ -113,8 +105,7 @@ async function killPane(pi: ExtensionAPI, pane: string): Promise<void> {
 	} catch {}
 }
 
-// Every TUI pi labels its own pane with its sessionId; the pane dies with its pi, so the label
-// needs no TTL. print/json/rpc runs must not steal their pane's label.
+// A pane's @pi_sid is written by the TUI pi that owns it and dies with it — no TTL needed.
 
 /** pane_id -> @pi_sid of every live pane. THROWS when tmux is unreachable — never silently "nothing is alive". */
 async function paneLabels(pi: ExtensionAPI): Promise<Map<string, string>> {
@@ -131,15 +122,6 @@ async function paneLabels(pi: ExtensionAPI): Promise<Map<string, string>> {
 	return out;
 }
 
-/** Best effort — without the label this session reads as dead. */
-async function labelPane(pi: ExtensionAPI, sid: string): Promise<void> {
-	const pane = process.env.TMUX_PANE;
-	if (!pane) return;
-	try {
-		await pi.exec("tmux", ["set-option", "-p", "-t", pane, "@pi_sid", sid], {});
-	} catch {}
-}
-
 /** True only once the peer labels its pane (its session_start writes it — proof of boot). A gone pane means pi exited: fail at once. */
 async function waitForBoot(
 	pi: ExtensionAPI,
@@ -159,7 +141,7 @@ async function waitForBoot(
 		const label = labels.get(pane);
 		if (label === sid) return true;
 		if (label === undefined) return false;
-		await sleep(500);
+		await new Promise((r) => setTimeout(r, 500));
 	}
 	return false;
 }
@@ -169,7 +151,6 @@ const registryDir = () => path.join(getAgentDir(), "peer", "registry");
 const peerRolesDir = () => path.join(getAgentDir(), "peer");
 const BUNDLED_ROLES = ["AGENTS.investigator.md", "AGENTS.strategist.md", "AGENTS.auditor.md"];
 const RETIRED_ROLES = ["AGENTS.scout.md", "AGENTS.researcher.md", "AGENTS.critic.md"];
-const bundledRolesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 /** Mirror the bundled role files (which sit next to the extension's parent directory) directly
  * into <agentDir>/peer. An edited or older copy is kept as `<name>.backup` before the bundled
@@ -186,7 +167,7 @@ function syncRoles(): void {
 		}
 		for (const name of BUNDLED_ROLES) {
 			try {
-				const src = path.join(bundledRolesDir, name);
+				const src = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", name);
 				const dst = path.join(dir, name);
 				const bundled = fs.readFileSync(src);
 				if (fs.existsSync(dst)) {
@@ -206,18 +187,20 @@ function expandPath(p: string): string {
 	return p;
 }
 
-// Peer identity lives ONLY here, never in session files — a fork cannot pollute it by
-// file copying, and no scan can miss it. The spawner writes before launching, newest-wins.
+// Peer role identity lives ONLY here, never in session files — a fork cannot pollute it by
+// file copying, and no scan can miss it. A record exists only for sessions WITH a role;
+// plain peers carry no role.json at all.
+const sessionDir = (sid: string) => path.join(registryDir(), sid);
+const roleFile = (sid: string) => path.join(sessionDir(sid), "role.json");
+
 function writePeerRecord(sid: string, rec: PeerRecord): void {
-	fs.mkdirSync(registryDir(), { recursive: true });
-	const norm: PeerRecord = rec.appendPrompt ? { ...rec, appendPrompt: expandPath(rec.appendPrompt) } : rec;
-	const file = path.join(registryDir(), `${sid}.json`);
-	const tmp = `${file}.tmp`;
-	fs.writeFileSync(tmp, JSON.stringify(norm));
-	fs.renameSync(tmp, file); // tmp+rename: readers never see a half-written record
+	fs.mkdirSync(sessionDir(sid), { recursive: true });
+	const tmp = `${roleFile(sid)}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify({ appendPrompt: expandPath(rec.appendPrompt) }));
+	fs.renameSync(tmp, roleFile(sid)); // tmp+rename: readers never see a half-written record
 }
 
-// Records are write-once, so this cache (negatives included) never goes stale.
+// Role records are write-once (the role path never changes), so this cache (negatives included) never goes stale.
 const recordCache = new Map<string, PeerRecord | null>();
 
 function readPeerRecord(sid: string): PeerRecord | null {
@@ -225,41 +208,53 @@ function readPeerRecord(sid: string): PeerRecord | null {
 	if (hit !== undefined) return hit;
 	let rec: PeerRecord | null = null;
 	try {
-		const raw = JSON.parse(fs.readFileSync(path.join(registryDir(), `${sid}.json`), "utf-8"));
-		if (raw && typeof raw.creatorSessionId === "string") rec = raw as PeerRecord;
+		const raw = JSON.parse(fs.readFileSync(roleFile(sid), "utf-8"));
+		if (raw && typeof raw.appendPrompt === "string") rec = { appendPrompt: raw.appendPrompt };
 	} catch {}
 	recordCache.set(sid, rec);
 	return rec;
 }
 
-function deletePeerRecord(sid: string): void {
+const contactsFile = (sid: string) => path.join(sessionDir(sid), "contacts.txt");
+
+/** Append-only contact log: one sessionId per line, both directions written by whoever acts
+ *  (spawn or letter). A single short O_APPEND write is atomic under the kernel's inode lock, so
+ *  concurrent writers never overwrite each other — there is no read-modify-write to race. A
+ *  crash mid-write leaves at most a partial line, which readContacts drops via the UUID check;
+ *  duplicates are harmless because reads dedupe. */
+function addContact(a: string, b: string): void {
 	try {
-		fs.unlinkSync(path.join(registryDir(), `${sid}.json`));
-	} catch {}
-	recordCache.delete(sid);
+		fs.mkdirSync(sessionDir(a), { recursive: true });
+		fs.mkdirSync(sessionDir(b), { recursive: true });
+		fs.appendFileSync(contactsFile(a), `${b}\n`);
+		fs.appendFileSync(contactsFile(b), `${a}\n`);
+	} catch {} // best effort: a lost line only narrows a future peer_list filter
 }
 
-function listPeerRecords(): Map<string, PeerRecord> {
-	const out = new Map<string, PeerRecord>();
-	let names: string[];
+function readContacts(sid: string): string[] {
+	let raw: string;
 	try {
-		names = fs.readdirSync(registryDir());
+		raw = fs.readFileSync(contactsFile(sid), "utf-8");
 	} catch {
-		return out;
-	}
-	for (const n of names) {
-		if (!n.endsWith(".json")) continue;
-		const sid = n.slice(0, -".json".length);
-		const rec = readPeerRecord(sid);
-		if (rec) out.set(sid, rec);
+		return [];
 	}
-	return out;
+	return [...new Set(raw.split("\n").filter((l) => UUID_RE.test(l)))];
 }
 
-/** Sessions on disk joined with the registry. Uses pi's listAll(): its parser lets the LAST session_info win, naming a fork after itself, not its parent. */
+// Removes the whole session folder: spawn-failure paths call this before any contact exists,
+// so the folder holds at most role.json — a sid that never booted never lingers.
+function deletePeerRecord(sid: string): void {
+	try {
+		fs.rmSync(sessionDir(sid), { recursive: true, force: true });
+	} catch {}
+	recordCache.delete(sid);
+}
+
+/** Sessions on disk joined with the registry — a pure disk read, no tmux. pi's listAll() parser
+ *  lets the LAST session_info win, naming a fork after itself, not its parent. Liveness is
+ *  deliberately absent: a pane-level fact, queried per sid only where it matters (send_mail). */
 async function scanAllSessions(pi: ExtensionAPI): Promise<SessionRecord[]> {
 	const infos = await SessionManager.listAll();
-	const alive = new Set((await paneLabels(pi)).values());
 	const records: SessionRecord[] = infos.map((info) => {
 		const started = info.created.getTime();
 		return {
@@ -267,13 +262,14 @@ async function scanAllSessions(pi: ExtensionAPI): Promise<SessionRecord[]> {
 			name: info.name ?? null,
 			cwd: info.cwd,
 			startedAt: Number.isNaN(started) ? info.modified.getTime() : started,
-			alive: alive.has(info.id),
+			contactIds: [],
 		};
 	});
-	const peers = listPeerRecords();
+	const known = new Set(records.map((r) => r.sessionId));
 	for (const r of records) {
-		const rec = peers.get(r.sessionId);
+		const rec = readPeerRecord(r.sessionId);
 		if (rec) r.peer = rec;
+		r.contactIds = readContacts(r.sessionId).filter((id) => known.has(id));
 	}
 	records.sort((a, b) => b.startedAt - a.startedAt);
 	return records;
@@ -283,7 +279,40 @@ async function scanAllSessions(pi: ExtensionAPI): Promise<SessionRecord[]> {
 function findSessionById(records: SessionRecord[], sessionId: string): SessionRecord | undefined {
 	return records.find((r) => r.sessionId === sessionId);
 }
-const fmtTime = (ms: number) => new Date(ms).toISOString().replace("T", " ").slice(0, 16);
+
+/** This session's file, located the way the tools tell models to: the <timestamp>_<sid>.jsonl file somewhere under <agentDir>/sessions/. */
+function findSessionFile(sid: string): string | null {
+	const root = path.join(getAgentDir(), "sessions");
+	try {
+		for (const dir of fs.readdirSync(root, { withFileTypes: true })) {
+			if (!dir.isDirectory()) continue;
+			for (const f of fs.readdirSync(path.join(root, dir.name))) {
+				if (f.endsWith(`_${sid}.jsonl`)) return path.join(root, dir.name, f);
+			}
+		}
+	} catch {}
+	return null;
+}
+
+/** The name as every external reader sees it: the LAST session_info entry of the session file.
+ *  The file is the single source of truth — pi's in-memory copy is deliberately never consulted. */
+function readNameFromFile(sid: string): { name: string | null; file: string | null } {
+	const file = findSessionFile(sid);
+	if (!file) return { name: null, file: null };
+	let name: string | null = null;
+	try {
+		for (const line of fs.readFileSync(file, "utf-8").split("\n")) {
+			if (!line) continue;
+			try {
+				const entry = JSON.parse(line);
+				if (entry?.type === "session_info") name = typeof entry.name === "string" ? entry.name : null;
+			} catch {} // a torn trailing line is not a rename; the only writer of the file is pi itself
+		}
+	} catch {
+		return { name: null, file };
+	}
+	return { name, file };
+}
 
 /** Uniform failed-tool result: "<code>: <detail>" text plus structured { code, message, …extra }. */
 function errResult(code: string, detail: string, extra?: Record<string, unknown>) {
@@ -308,20 +337,14 @@ function errResult(code: string, detail: string, extra?: Record<string, unknown>
 const boxDir = (sid: string) => path.join(getAgentDir(), "peer", "letters", sid);
 const oneLine = (s: string) => s.replace(/\s+/g, " ").trim();
 
-/** Parse a letter's frontmatter header (from + summary), as written by post(). */
-function parseLetterHeader(text: string): { from: string | null; summary: string | null } {
-	const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
-	if (!m) return { from: null, summary: null };
-	const pick = (key: string) => new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(m[1])?.[1]?.trim() || null;
-	return { from: pick("from"), summary: pick("summary") };
-}
-
 function formatNotice(file: string, text: string): string {
-	const { from, summary } = parseLetterHeader(text);
+	// frontmatter (from + summary) as written by post()
+	const header = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
+	const pick = (key: string) => new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(header)?.[1]?.trim() || null;
 	return [
 		`New letter received.`,
-		`From: ${from ?? "unknown sender"}`,
-		`Summary: ${summary ?? "(no summary header)"}`,
+		`From: ${pick("from") ?? "unknown sender"}`,
+		`Summary: ${pick("summary") ?? "(no summary header)"}`,
 		`Full letter file: "${file}" — read it yourself with the read tool, delete the letter file (rm) after reading so letters won't pile up.`,
 	].join("\n");
 }
@@ -394,7 +417,7 @@ function startInboxLoop(pi: ExtensionAPI, sid: string, isIdle: () => boolean): (
 			}
 			if (batch.length === 0) return;
 			pi.sendUserMessage(
-					batch.map((b) => formatNotice(b.finalPath, b.text)).join(BATCH_SEP),
+					batch.map((b) => formatNotice(b.finalPath, b.text)).join("\n\n──────── next letter ────────\n\n"),
 					{ deliverAs: isIdle() ? "followUp" : "steer" },
 			);
 			// Strip the pending- prefix — the one-way "notice issued" transition. Reached
@@ -468,16 +491,15 @@ export default function piPeer(pi: ExtensionAPI) {
 		appendPromptPath = readPeerRecord(sid)?.appendPrompt ?? null;
 	};
 
-	// A fork keeps the branched session's role; an existing record is never copied over —
-	// the spawner's own write (copy, then override) is newer and wins.
+	// A fork keeps the branched session's role; an existing record (the spawner's write) is never overwritten.
 	const inheritRoleFromFork = (event: { reason?: string; previousSessionFile?: string }, ownSid: string) => {
 		if (event.reason !== "fork" || !event.previousSessionFile) return;
 		const file = path.basename(event.previousSessionFile);
 		const srcSid = file.endsWith(".jsonl") ? file.slice(0, -".jsonl".length).split("_").pop() : undefined;
-		if (!srcSid || fs.existsSync(path.join(registryDir(), `${ownSid}.json`))) return;
+		if (!srcSid || fs.existsSync(roleFile(ownSid))) return;
 		const src = readPeerRecord(srcSid);
-		if (!src?.appendPrompt) return;
-		writePeerRecord(ownSid, { ...src });
+		if (!src) return;
+		writePeerRecord(ownSid, { appendPrompt: src.appendPrompt }); // role only — contacts are never inherited
 		recordCache.delete(ownSid); // a lookup may already have cached "no record" for this sid
 	};
 
@@ -487,9 +509,14 @@ export default function piPeer(pi: ExtensionAPI) {
 		const sid = ctx.sessionManager.getSessionId();
 		inheritRoleFromFork(event, sid);
 		loadOwnRole(sid);
-		compactionActive = false; // the fresh session is not compacting
+		compactionActive = false;
 		// Only a TUI owns a pane: a nested print/json pi inherits $TMUX_PANE and would steal it.
-		if (ctx.mode === "tui") await labelPane(pi, sid);
+		// Best effort — without the label this session reads as dead.
+		if (ctx.mode === "tui" && process.env.TMUX_PANE) {
+			try {
+				await pi.exec("tmux", ["set-option", "-p", "-t", process.env.TMUX_PANE, "@pi_sid", sid], {});
+			} catch {}
+		}
 		stopLoop?.();
 		stopLoop = startInboxLoop(pi, sid, () => ctx.isIdle());
 	});
@@ -539,7 +566,7 @@ export default function piPeer(pi: ExtensionAPI) {
 			"Use peer_spawn only when the user asked for parallel/independent work or a task clearly warrants a separate context; every letter sent via peer_send_mail costs the recipient one LLM turn.",
 		],
 		parameters: Type.Object({
-			topic: Type.String({ description: "Session topic; the peer is named '[peer]<topic>'" }),
+			name: Type.String({ description: "Session name seed; the peer is named '[peer]<name>'" }),
 			task: Type.String({ description: "Self-contained first message; delivered at launch as the peer's first user message" }),
 			prompt: Type.Optional(
 				Type.String({
@@ -563,11 +590,11 @@ export default function piPeer(pi: ExtensionAPI) {
 
 			// Pre-assigned id: --session-id creates exactly this session; the wait after launch only confirms it.
 			const sid = uuidv7();
-			const name = `[peer]${params.topic}`.slice(0, 60);
+			const name = `[peer]${params.name}`;
 
 			let mode = "empty";
 			let forkSid: string | undefined;
-			let inherited: PeerRecord | undefined;
+			let inheritedRole: string | undefined;
 			let payload: string | undefined;
 			const ctxArg = (params.context ?? "").trim();
 			if (ctxArg) {
@@ -581,7 +608,7 @@ export default function piPeer(pi: ExtensionAPI) {
 					if (!source) return fail("unknown_session", `fork: no session with id ${src} (try peer_list)`);
 					mode = "fork";
 					forkSid = src;
-					inherited = source.peer; // the forked session's registry fields, overridden below
+					inheritedRole = source.peer?.appendPrompt;
 				} else if (kind === "handoff") {
 					mode = "handoff";
 					payload = rest;
@@ -590,17 +617,13 @@ export default function piPeer(pi: ExtensionAPI) {
 				}
 			}
 
-			let appendPrompt: string | undefined;
+			let role: string | undefined;
 			if (params.prompt) {
-				appendPrompt = expandPath(params.prompt);
-				if (!fs.existsSync(appendPrompt)) return fail("prompt_file_missing", `prompt file not found: ${params.prompt}`);
+				role = expandPath(params.prompt);
+				if (!fs.existsSync(role)) return fail("prompt_file_missing", `prompt file not found: ${params.prompt}`);
 			}
-			// Newest-wins: a fork copies the source record, this spawn's fields override it.
-			writePeerRecord(sid, {
-				...(inherited ?? {}),
-				creatorSessionId: ctx.sessionManager.getSessionId(),
-				...(appendPrompt ? { appendPrompt } : {}),
-			});
+			if (!role) role = inheritedRole;
+			if (role) writePeerRecord(sid, { appendPrompt: role });
 
 			// No --append-system-prompt: the role hook re-applies the role file every turn.
 			const piArgs: string[] = ["--session-id", sid, "--name", name];
@@ -628,7 +651,6 @@ export default function piPeer(pi: ExtensionAPI) {
 				return fail("boot_failed", launched.message);
 			}
 
-			// No sid is reported until the peer labels its pane.
 			if (!(await waitForBoot(pi, sid, launched.pane, signal))) {
 				const why = signal?.aborted
 					? "spawn cancelled while waiting for the peer to start"
@@ -637,6 +659,7 @@ export default function piPeer(pi: ExtensionAPI) {
 				await killPane(pi, launched.pane);
 				return fail("boot_failed", `${why} — pane=${launched.pane} (closed)`);
 			}
+			addContact(ctx.sessionManager.getSessionId(), sid); // a spawn counts as contact
 			const message = `peer launched: ${name} | sessionId=${sid} | context=${mode} | pane=${launched.pane} — the peer is up and the task was delivered as its first message; use peer_send_mail for follow-up letters`;
 			return {
 				content: [{ type: "text" as const, text: message }],
@@ -649,33 +672,33 @@ export default function piPeer(pi: ExtensionAPI) {
 		name: "peer_list",
 		label: "List sessions",
 		description:
-			"List pi sessions, alive or exited. " + SKILL_GATE + " The first line summarises the total count and the current page (40 sessions per page, newest first; pass page for older ones). Then one line per session: name | creator (`created by sessionId: <id>` for a spawned peer, `created by user manually` for a human-started one) | alive | not alive | absolute cwd | YYYY-MM-DD HH:MM | sessionId. parent:'self' filters to peers spawned by this session. To read a session's transcript, resolve its file by sessionId: `find <agentDir>/sessions -name '*_<sessionId>.jsonl'`.",
+			"List pi sessions. " + SKILL_GATE + " The first line summarises the total count and the current page (15 sessions per page, newest first; pass page for older ones). Then one line per session: name | contacts (how many sessions it has spawned or exchanged letters with, either direction) | absolute cwd | YYYY-MM-DD HH:MM | sessionId. contact filters to the sessions that have communicated with one session — pass \"self\" or any exact lowercase 36-character sessionId; a spawn and an exchanged letter both count. To read a session's transcript, resolve its file by sessionId: `find <agentDir>/sessions -name '*_<sessionId>.jsonl'`.",
 		parameters: Type.Object({
-			parent: Type.Optional(
-				Type.String({ description: 'Creator sessionId (exact lowercase 36-character UUID), or "self" for this session; peers only' }),
+			contact: Type.Optional(
+				Type.String({
+					description:
+						'Filter to sessions that have communicated with one session: "self" for this session, or the exact lowercase 36-character UUID of any session. A spawn or an exchanged letter counts, in either direction.',
+				}),
 			),
-			alive: Type.Optional(Type.Boolean({ description: "true = only alive, false = only not alive" })),
 			page: Type.Optional(
 				Type.Number({ description: `1-based page number, ${LIST_PAGE_SIZE} sessions per page (default: 1)` }),
 			),
 		}),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const tmuxProblem = await tmuxGuard(pi);
-			if (tmuxProblem) return errResult("no_tmux", tmuxProblem, { total: 0 });
 			const self = ctx.sessionManager.getSessionId();
 			let recs = await scanAllSessions(pi);
-			if (params.parent) {
-				const creator = params.parent === "self" ? self : params.parent.trim();
-				if (!UUID_RE.test(creator)) {
+			if (params.contact) {
+				const target = params.contact === "self" ? self : params.contact.trim();
+				if (!UUID_RE.test(target)) {
 					return errResult(
-						"bad_parent",
-						`"${params.parent}" is not a sessionId. Pass "self" or the exact lowercase 36-character UUID as peer_list prints it.`,
+						"bad_contact",
+						`"${params.contact}" is not a sessionId. Pass "self" or the exact lowercase 36-character UUID as peer_list prints it.`,
 						{ total: 0 },
 					);
 				}
-				recs = recs.filter((r) => r.peer?.creatorSessionId === creator);
+				const ids = new Set(readContacts(target));
+				recs = recs.filter((r) => ids.has(r.sessionId));
 			}
-			if (params.alive !== undefined) recs = recs.filter((r) => r.alive === params.alive);
 
 			const total = recs.length;
 			const totalPages = Math.max(1, Math.ceil(total / LIST_PAGE_SIZE));
@@ -689,8 +712,8 @@ export default function piPeer(pi: ExtensionAPI) {
 			}
 			const start = (page - 1) * LIST_PAGE_SIZE;
 			const lines = recs.slice(start, start + LIST_PAGE_SIZE).map((r) => {
-				const by = r.peer ? `created by sessionId: ${r.peer.creatorSessionId}` : "created by user manually";
-				return `${r.name ?? "—"} | ${by} | ${r.alive ? "alive" : "not alive"} | ${r.cwd} | ${fmtTime(r.startedAt)} | ${r.sessionId}`;
+				const time = new Date(r.startedAt).toISOString().replace("T", " ").slice(0, 16);
+				return `${r.name ?? "—"} | contacts: ${r.contactIds.length || "none"} | ${r.cwd} | ${time} | ${r.sessionId}`;
 			});
 			const shown = lines.length;
 			const header = `total: ${total} matching session${total === 1 ? "" : "s"} | page ${page}/${totalPages}${shown > 0 ? ` | showing ${start + 1}-${start + shown}` : ""}`;
@@ -750,13 +773,16 @@ export default function piPeer(pi: ExtensionAPI) {
 			const selfName = findSessionById(records, self)?.name;
 			const from = selfName ? `${selfName} (sessionId: ${self})` : `sessionId: ${self}`;
 			const letterFile = await post(sid, params.message, { from, summary: params.summary });
+			addContact(self, sid); // an exchanged letter counts as contact
 			const label = target.name ?? sid;
 			const done = (state: string, text: string) => ({
 				content: [{ type: "text" as const, text: `${text} | letter file: ${letterFile}` }],
 				details: { recipient: label, sessionId: sid, state, letterFile },
 			});
 
-			if (target.alive) {
+			// paneLabels throws if tmux died mid-call (we are behind tmuxGuard) — an honest error
+			// beats a false "not alive" that would push a live peer down the revive path.
+			if ([...(await paneLabels(pi)).values()].includes(sid)) {
 				return done("alive", `sent → ${label} — alive; it picks the letter up within ~${POLL_MS / 1000}s`);
 			}
 			// Empty recorded cwd (old sessions) falls back to the sender's.
@@ -769,4 +795,49 @@ export default function piPeer(pi: ExtensionAPI) {
 					);
 		},
 	});
+
+	// Self-only by design: a rename of ANOTHER session is a request, not a write — it goes through a
+	// letter (peer_send_mail), so the recipient also learns WHY its name changed. The read path is
+	// the file tail on purpose: it is the same value every external reader (peer_list) sees.
+	pi.registerTool({
+		name: "peer_name",
+		label: "Read or set own session name",
+		description:
+			"Read or set THIS session's name — a peer's identity carrier: it declares what this session does, what it is responsible for, and its current state; peer_list shows it first, and it is often the only thing a reader sees before deciding to mail, fork, or skip. " + SKILL_GATE + " Omit name to read the current name exactly as it exists on disk — the last session_info entry of this session's file, the same value every external reader sees; a session with no name entry reads as unnamed. Pass name to set it — effective immediately for this process and on disk. This tool never touches another session: to change another session's name (dead or alive — peer_send_mail revives a dead recipient), send a letter stating the reason and the new name; the recipient renames itself.",
+		promptGuidelines: [
+			"A name change is almost always a state change: update your own name with peer_name in the same run that changes your state (retirement, redirection, reassignment) — never rename another session, ask it by letter.",
+		],
+		parameters: Type.Object({
+			name: Type.Optional(
+				Type.String({
+					description: "New name for this session — function, responsibility, and state. Omit to read the current name.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const sid = ctx.sessionManager.getSessionId();
+			if (params.name === undefined) {
+				const { name, file } = readNameFromFile(sid);
+				const text = name
+					? `this session's name: ${name}`
+					: file
+						? "this session has no name on disk yet — set one with peer_name (function, responsibility, state)."
+						: "this session's file is not on disk yet (pi persists it with this session's first submitted message); a name set now takes effect in this process and lands on disk with the file.";
+				return { content: [{ type: "text" as const, text }], details: { name, sessionId: sid, file } };
+			}
+			const name = params.name.trim();
+			if (!name) {
+				return errResult(
+					"bad_name",
+					"a name cannot be empty or whitespace-only — pass a non-empty name, or omit it to read the current name.",
+				);
+			}
+			pi.setSessionName(name);
+			const message = `session renamed: ${name} — effective immediately for this process and on disk; peer_list and every file reader see it from now on`;
+			return {
+				content: [{ type: "text" as const, text: message }],
+				details: { name, sessionId: sid, message },
+			};
+		},
+	});
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@semanaut/zpi-peer",
-  "version": "2.0.3",
+  "version": "2.5.0",
   "piVersion": "1.3.0",
-  "description": "pi extension: equal, durable pi peers managed through tmux panes plus a letter channel between any pi sessions. tmux runs on Unix-like systems (Linux, macOS, BSD; Windows via WSL/Cygwin); native Windows is not supported. Tools: peer_spawn (launch a peer in a tmux pane), peer_list (list peers, alive or exited), peer_send_mail (deliver a letter, reviving dead recipients). Ships investigator / strategist / auditor role prompts; developed against the pi version given by the piVersion field",
+  "description": "pi extension: equal, durable pi peers managed through tmux panes plus a letter channel between any pi sessions. tmux runs on Unix-like systems (Linux, macOS, BSD; Windows via WSL/Cygwin); native Windows is not supported. Tools: peer_spawn (launch a peer in a tmux pane), peer_list (list sessions with their contact counts), peer_send_mail (deliver a letter, reviving dead recipients), peer_name (read or set a session's name — the peer's identity carrier). Ships investigator / strategist / auditor role prompts; developed against the pi version given by the piVersion field",
   "type": "module",
   "keywords": [
     "pi-package"

package/skills/peer-orchestrator/SKILL.md

@@ -1,115 +1,63 @@
 ---
 name: peer-orchestrator
-description: Policy for creating and steering equal pi peers. Load when considering peer_spawn — deciding to run directions in parallel, choosing a peer's starting context, or writing its first task.
+description: Policy for creating and steering equal pi peers. Load when considering peer_spawn, peer_list, peer_send_mail, or peer_name — deciding to run directions in parallel, choosing a peer's starting context, writing its first task, or reading/changing a session's name.
 ---
 
 # Peer Orchestrator
 
 ## Mental model
-Peers are equal instances, not subordinates: you have no control over them, only a launch and a
-messaging channel. Each peer has its own context, its own token budget, its own mistakes.
-Work directly by default; spawn a peer only when the user asked for parallel/independent work,
-or a task clearly warrants a separate context. Never spawn for a single lookup or a file read.
+Peers are equal instances, not subordinates: you have no control over them, only a launch and a messaging channel. Each peer has its own context, its own token budget, its own mistakes.
+Work directly by default; spawn a peer only when the user asked for parallel/independent work, or a task clearly warrants a separate context. Never spawn for a single lookup or a file read.
 
-## The three tools
+## The four tools
 
-### `peer_spawn(topic, task, prompt?, context?, model?)`
-Creates a peer in its own tmux pane and returns its sessionId immediately — no handshake. The peer
-is named `[peer]<topic>`, receives `task` as its first message, and starts working as soon as it
-boots. Use `peer_send_mail` for everything after that.
+### `peer_spawn(name, task, prompt?, context?, model?)`
+Creates a peer in its own tmux pane and returns its sessionId immediately — no handshake. You name it at spawn — the peer is named `[peer]<name>` — it receives `task` as its first message, and starts working as soon as it boots. Use `peer_send_mail` for everything after that.
 
 ### `peer_send_mail(to, summary, message)`
-Delivers a letter to any session's mailbox as a .md file with a frontmatter header (from + summary).
-The recipient's poll injects only the summary plus the file path — never the full text; the recipient
-reads the full letter itself and deletes the file afterwards. Notices reach a running session within
-~1.5s — via steer while it is running, via followUp when it is idle — and pending notices merge into one
-message. A dead recipient is revived automatically — the call may block up to ~20s and tells you
-whether the revive succeeded; on failure the letter stays queued and is read whenever that session
-next runs.
-The summary is all the recipient sees up front: state who you are (name/sessionId) and what the
-letter is about. The letter body must be self-contained: state whether a reply is needed and where
-to send it. Batch related matters into one letter — every letter costs the recipient a turn.
-
-### `peer_list(parent?, alive?, page?)`
-Lists sessions with their creator, liveness, cwd, and sessionId — newest first, 40 per page; the
-first line summarises the total count and the current page (pass `page` for older ones). Run it
-before spawning: reusing or forking an existing peer beats recreating one. Use `parent: "self"` to
-see only your own peers.
+Delivers a letter to any session's mailbox as a .md file with a frontmatter header (from + summary). The recipient's poll injects only the summary plus the file path; the recipient reads the full letter itself and deletes the file afterwards.
+The summary is all the recipient sees up front: state who you are (name/sessionId) and what the letter is about. The letter body must be self-contained: state whether a reply is needed and where to send it. Batch related matters into one letter.
+Notices reach a running session within seconds and pending notices merge into one message. A dead recipient is revived automatically — the call may block up to ~25s and tells you whether the revive succeeded; on failure the letter stays queued and is read whenever that session next runs.
+
+### `peer_list(contact?, page?)`
+Lists sessions with their contact count, cwd, and sessionId — newest first, 15 per page; the first line summarises the total count and the current page (pass `page` for older ones).
+Use `contact: "self"` to see the sessions you have spawned or exchanged letters with (either direction counts); pass any other sessionId to inspect who that session has communicated with.
+Run it before spawning: reusing or forking an existing peer beats recreating one — a session's whole history is on disk whether it is running or not, so mail it instead of spawning a duplicate.
+
+### `peer_name(name?)`
+Reads or sets THIS session's name. Omit `name` to read: the value returned is the name as it exists on disk; a session with no name entry reads as unnamed. Pass `name` to set: effective immediately.
+Name is shown in `peer_list` as the first field and is the only thing a reader sees before deciding to mail, so the name should declare and stay consistent with exact function, responsibility, and state.
+Your name is your own responsibility. Whenever your state changes — retirement, a new direction, a changed task — update your name with `peer_name` in the same run, so that other peers are not misled.
 
 ## Writing a spawn
 
-### `topic`
-The peer's name is `[peer]<topic>` (capped at 60 chars). Name the peer after its task or
-responsibility in detail — a reader should understand what the peer does from the topic alone,
-without opening its task. Use a semantic, mission-descriptive name, not a vague handle: e.g.
-`investigate-auth-latency-and-analyze-causes`, `分析8月英伟达股价波动情况以判断未来走势` — not `task1`,
-`helper`, or a bare `refactor-auth`.
+### `name`
+The peer's name is `[peer]<name>`. The name is the peer's identity carrier — see `peer_name`. A compliant name declares function, responsibility, and state, separated by `|`: e.g. `investigate-auth-latency-and-root-causes | owns the auth-latency diagnosis report for the main session | active, one-shot mission`, `宏观与全球央行跟踪 | 负责 economy 日报的宏观板块 | 活跃,每日例行`, `英伟达股价走势分析 | 已交付一次性走势判断报告 | 已退役 2026-10-19` — not `task1`, `helper`, a bare `refactor-auth`, or a function-only name like `investigate-auth-latency-and-analyze-causes` (no responsibility, no state).
 
 ### `task`
-The task is the peer's entire brief — it has no other context. State: the goal, the boundaries,
-the expected output format, and where to send the result (your own sessionId; the peer learns it
-from what you write). Make it self-contained: the peer must be able to finish without asking back.
+The task is the peer's entire brief — it has no other context. State: the goal, the boundaries, the expected output format, and where to send the result (your own sessionId; the peer learns it from what you write). Make it self-contained: the peer must be able to finish without asking back.
 
 ### `context`
 - omit — empty context; cheapest; the default for a self-contained task.
-- `fork:<sessionId>` — inherit that session's full history, and the forked peer also inherits its
-  role (unless you pass a different `prompt`, or the source has no role — then nothing is inherited);
-  only when the peer truly needs everything you know (expensive).
-- `handoff:<text>` — you write exactly what the peer needs; best token/value ratio for a large
-  context. To pass on your own context, write the handoff yourself — do NOT reuse your /compact
-  summary: it is a self-continuation artifact and is stale by everything that happened after it.
+- `fork:<sessionId>` — inherit that session's full history, and the forked peer also inherits its role (unless you pass a different `prompt`, or the source has no role — then nothing is inherited); only when the peer truly needs everything you know (expensive).
+- `handoff:<text>` — you write exactly what the peer needs; best token/value ratio for a large context. To pass on your own context, write the handoff yourself — do NOT reuse your /compact summary: it is a self-continuation artifact and is stale by everything that happened after it.
 
 ### `prompt` (role)
-Pass the path to a role file — no need to read it first; `peer_spawn` only checks it exists. The
-role stays with that session across every start (fresh spawn, revive after a letter, or a manual
-`/resume`), and editing the role file takes effect without respawning. Identity follows the
-session, never the process: `/new` inside a peer's pane starts a plain session, while a fork
-inherits the role of the session it branched from (unless you pass `prompt`) — spawn a proper
-peer when a new one is needed.
-
-**Pass a role whenever one fits the mission.** It is the main lever you have for shaping a peer's
-stance, and it costs one path string. Leave it empty only when no standard role fits and the task
-text alone can carry the discipline you need — a plain peer has no role discipline at all.
-
-## What a role is here
-
-Peers are flat and equal: same toolset, same permissions, no hierarchy. A role therefore cannot be
-a permission slice — it is a **responsibility and a stance**, expressed as what the peer produces
-and what it refuses to do. Two consequences:
-
-- A role must change the output contract or the discipline, not the subject matter. "Review the
-  frontend" is a task; "verify, audit, then criticize" is a role. Subject variation belongs in `task`.
-- A role never implies rank. No role is an overseer of another, and a role file must not tell a
-  peer to direct, schedule, or supervise other peers. Every peer can spawn and mail every other.
-
-Peers launch with the full toolset: whatever discipline a role shows comes from its stance and its
-task text, never from restrictions. A peer can always mail you back.
+Path to a role file. Its text is appended to the peer's system prompt on every turn — it survives every restart (spawn, revive, manual resume), and editing the file takes effect without respawning. Pass one whenever it fits the mission; omitted, the peer runs with no discipline beyond its task.
 
 ## The standard roles
 
-Pass the path of the role file you want to `peer_spawn`'s prompt parameter; the exact paths are
-given in the peer_spawn tool description. For a custom role, pass the path of any other role file.
-
-- **investigator** — find out what is true. Merges codebase reconnaissance with outside research:
-  a map of where things are, or a sourced brief on what the evidence says. It cites every path and
-  URL it actually checked, and marks the boundary between what it verified and what it infers. Use
-  it whenever you need facts you do not have.
-- **strategist** — make the call. Given a problem, or given alternatives someone else produced, it
-  weighs them and commits: real options with what each buys and costs, the axis being balanced, one
-  recommendation definite enough to be wrong, and the fact that would flip it. Decisive, not
-  analytic — it decides, then says what would change its mind. It proposes; it does not plan
-  execution steps or direct other peers. Use it before committing to an approach.
-- **auditor** — expose what does not hold, and dare to say so. It verifies by actually doing:
-  re-runs, reproduces, re-derives — then audits the path actually taken (including what was
-  skipped), names the risks, and only then criticizes: VERDICT (agree / agree-with-changes /
-  object) plus numbered findings by severity, each with evidence and a concrete suggestion. It
-  pours cold water on warm consensus and never rubber-stamps — give it the artifact, not your
-  defense of it.
+A role is a stance, not a rank and not permissions. It changes how the peer works — what it produces and what it refuses — never what it works on: "review the frontend" is a task, "verify, audit, then criticize" is a role. It never grants control over other peers: every peer stays equal.
+Pass the path of the role file you want to `peer_spawn`'s prompt parameter; the exact paths are given in the peer_spawn tool description. For a custom role, pass the path of any other role file.
+
+- **investigator** — find out what is true. Merges codebase reconnaissance with outside research: a map of where things are, or a sourced brief on what the evidence says. It cites every path and URL it actually checked, and marks the boundary between what it verified and what it infers. Use it whenever you need facts you do not have.
+- **strategist** — make the call. Given a problem, or given alternatives someone else produced, it weighs them and commits: real options with what each buys and costs, the axis being balanced, one recommendation definite enough to be wrong, and the fact that would flip it. Decisive, not analytic — it decides, then says what would change its mind. It proposes; it does not plan execution steps or direct other peers. Use it before committing to an approach.
+- **auditor** — expose what does not hold, and dare to say so. It verifies by actually doing: re-runs, reproduces, re-derives — then audits the path actually taken (including what was skipped), names the risks, and only then criticizes: VERDICT (agree / agree-with-changes / object) plus numbered findings by severity, each with evidence and a concrete suggestion. It pours cold water on warm consensus and never rubber-stamps — give it the artifact, not your defense of it.
 
 ## Conventions
 - One direction per peer; a peer with two missions does neither well.
 - Tell the peer where to reply (your sessionId) in the task itself.
 - Waiting for a peer's report does not require you to stay active: an incoming letter is injected into your context and starts a new conversation turn by itself, even after your output has ended. Finish your reply and stop; holding the turn open (timed pauses, re-checks, sleep) only burns time and tokens.
 - No acknowledgements or small talk by letter; write only when there is substance.
-- A peer that goes quiet is not stuck — letters merge while it is busy; wait for its report before
-  nudging, and nudge with new information, not with "status?".
+- Keep the name truthful: a name that has drifted from the peer's real state is a bug — update it with `peer_name` in the same run that changes the state.
+- A peer that goes quiet is not stuck — letters merge while it is busy; wait for its report before nudging, and nudge with new information, not with "status?".