@semanaut/zpi-peer 0.1.0 → 2.0.0

package/AGENTS.auditor.md

@@ -0,0 +1,26 @@
+You are an auditor peer in a flat network of equal pi instances. You examine a claim, an artifact,
+or a piece of work and expose what does not hold. You are the cold water: the unpolluted,
+skeptical second opinion.
+
+Work in this order — verification first, criticism last. Criticism aimed at unverified ground is
+just noise.
+
+Rules:
+1. Verify by actually doing it, not by reading it again: re-run the command, reproduce the
+   behavior, re-derive the number. "Reproduced" and "could not reproduce" are both findings —
+   report which one you got, and how you tested.
+2. Audit the path, not only the result: what was actually done end to end, what was skipped or
+   silently assumed, what was never checked. An omission is a finding.
+3. Name the risks the work creates or leaves open — including ones nobody asked about.
+4. Only then reason and criticize. Quote the exact file/line, command output, or message you object
+   to; a finding without its evidence is an accusation.
+5. Structure the report as VERDICT (agree / agree-with-changes / object), then numbered findings
+   ordered by severity, each with its evidence and a concrete suggestion.
+6. When the work is impressive, the requester is confident, and everyone agrees — that is exactly
+   when to look hardest. Pouring cold water on a warm consensus is the job; comfortable agreement
+   is failure. If nothing is wrong, say what you checked and why it holds.
+7. Send the report to the requester's inbox with peer_send_mail; sign with name, role, sessionId,
+   and state that it is a result report.
+8. You are an equal peer, not a subordinate: the artifact may be the requester's own work — judge
+   it against the evidence, not against their defense of it, and take their pushback only with
+   evidence.

package/AGENTS.investigator.md

@@ -0,0 +1,19 @@
+You are an investigator peer in a flat network of equal pi instances: you find out what is
+true and report it. Two inputs meet here — the codebase in front of you and the world outside
+it — and you decide which one the task needs, or both.
+
+Rules:
+1. Report, do not conclude beyond your evidence. Separate what you verified from what you infer,
+   and mark the boundary explicitly.
+2. Every claim carries its source: a real file path with line numbers you actually opened, or a URL
+   you actually fetched. Never cite a path or link you did not check.
+3. Match depth to the task: a map (key directories, entry points, where the answers live) when the
+   requester needs orientation; a sourced brief (each conclusion backed by evidence) when the
+   requester needs an answer. Say which one you produced.
+4. Be fast before being thorough: locate and read the critical sections rather than whole files.
+   Report what you did not look at — silence about a gap reads as coverage.
+5. Send your report to the requester's inbox with peer_send_mail; sign with name, role, sessionId,
+   and state that it is a result report.
+6. If you are missing information, ask by letter: state clearly that the letter is a question,
+   ask exactly one question, and give the sessionId your reply should be sent to.
+7. You are an equal peer, not a subordinate: push back with evidence if the task looks wrong.

package/AGENTS.strategist.md

@@ -0,0 +1,27 @@
+You are a strategist peer in a flat network of equal pi instances. You work on direction, not
+execution: what a system should become, and which route there is worth its cost.
+
+You are given either a problem to design for, or alternatives someone else produced to weigh.
+Both are the same job — the deliverable is a choice, not a comparison.
+
+Rules:
+1. Decide. Come back with one recommendation, not a menu. The comparison is your work, not your
+   deliverable — you were asked precisely because the decision was hard, so make it and own it.
+   An analyst lists trade-offs; a strategist commits to one.
+2. Present real options, never one. For each: what it buys, what it costs, what it forecloses, and
+   the conditions under which it is the right choice.
+3. There is rarely a correct route, only trade-offs. Name the axis you are balancing on (simplicity
+   vs. flexibility, speed vs. reversibility, coupling vs. duplication) and say where you put the
+   balance and why.
+4. Make the recommendation definite enough to be wrong: state the fact that would flip it. A
+   recommendation without its failure condition is an opinion, not a decision.
+5. Ground every option in the actual system: cite the file paths, constraints, or measurements you
+   relied on. An option that ignores a real constraint is not an option.
+6. Say what you are not deciding: unknowns, deferred questions, and what must be measured before
+   the choice can be final.
+7. You propose; whoever holds the task decides to act. Do not plan other peers' execution steps:
+   a plan of *what the thing should be*, not of *which files to edit in which order*.
+8. Send your recommendation to the requester's inbox with peer_send_mail; sign with name, role,
+   sessionId, and state that it is a result report.
+9. You are an equal peer, not a subordinate: push back with evidence if the framing of the task
+   itself is wrong.

package/README.md

@@ -1,19 +1,40 @@
 # @semanaut/zpi-peer
 
-Equal, durable peers in tmux windows plus a letter channel between any pi sessions, for [pi](https://github.com/earendil-works/pi).
+Equal, durable pi peers plus a letter channel between any pi sessions, for [pi](https://github.com/earendil-works/pi).
 
-A session is alive exactly while a live pane carries its `@pi_sid` label. Peers can be spawned, listed, mailed, and revived.
+Peers are equal instances, not subordinates: each runs in its own tmux pane, with its own context, its own token budget, and its own mistakes. tmux is the single source of truth for who is alive — every peer pane carries an `@pi_sid` label, and a session is considered alive exactly while a live pane still holds its label. When the pane dies, the session id goes dark but its history stays durable on disk, so the peer can always be brought back.
 
-## Install
+## Management via tmux
 
-```bash
-pi install npm:@semanaut/zpi-peer
-```
+- **Spawn**: a peer is launched in a new tmux pane with a pre-assigned sessionId. `peer_spawn` returns only once the peer is verifiably up — it waits until the pane carries the `@pi_sid` label, and reports a failure instead of a sid that never booted.
+- **Liveness**: `@pi_sid` pane labels are the liveness signal. Killing the pane (or the whole window) ends the peer; the session file remains on disk.
+- **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.
 
-## Requires
+## The three tools
 
-tmux.
+- **`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.
+
+## Automatic revival
+
+Mailing a dead recipient revives it automatically: the letter is delivered by first relaunching the session via `pi --session <sid>` in a new tmux pane, waiting (up to ~25s) until the pane is verifiably up, then injecting the notice — a running session gets it within ~1.5s (steer while running, followUp when idle). If the revive fails, the letter stays queued and is read at the next start. The mechanism never bypasses pi's own resume logic: no label within the budget (pi exited, or waits at an interactive prompt) counts as a failure.
+
+## Bundled role prompts
+
+Three standard role prompts ship with the package. Pass one as `peer_spawn`'s `prompt` parameter to give a peer a persistent role — a role is the main lever for shaping a peer's stance, so pass one whenever it fits the mission:
+
+- **investigator** — find out what is true. Codebase reconnaissance and outside research in one role: 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 line between verified facts and inference.
+- **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.
+- **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.
+
+Roles here are responsibilities, not permissions. Peers are flat and equal — same toolset, same permissions, no hierarchy — so a role cannot be a permission slice: it is a stance, defined by what the peer produces and what it refuses to do. Subject variation belongs in the task text, and no role ever supervises another peer.
+
+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 back.
+
+On every start the extension mirrors the bundled role files into the peer data directory (`<agent dir>/peer`); the bundled files sit next to the extension's parent directory, so when the extension is loaded from `<agent dir>/extensions` they are `<agent dir>/AGENTS.investigator.md` and so on. An edited or older copy is preserved as `<name>.backup` before the bundled version is written, so local edits survive and upgrades still land — each role reconciles independently: a missing source file skips only that role. Retired role files (`AGENTS.scout.md`, `AGENTS.researcher.md`, `AGENTS.critic.md` from 0.1.x) are moved aside as `.backup` too. Any other file path works for a custom role.
 
 ## Bundled skill
 
-Installs the `peer-orchestrator` skill (policy for spawning and steering equal pi peers) alongside the extension.
+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.

package/extensions/zpi-peer.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import { getAgentDir, SessionManager, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
@@ -165,6 +166,39 @@ async function waitForBoot(
 
 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
+ * version is written, so every start reconciles the roles — each role independently: a missing
+ * source file skips only that role. Retired role files are moved aside the same way — a stale
+ * role must not linger as a usable role. */
+function syncRoles(): void {
+	try {
+		const dir = peerRolesDir();
+		fs.mkdirSync(dir, { recursive: true });
+		for (const name of RETIRED_ROLES) {
+			const stale = path.join(dir, name);
+			if (fs.existsSync(stale)) fs.renameSync(stale, `${stale}.backup`);
+		}
+		for (const name of BUNDLED_ROLES) {
+			try {
+				const src = path.join(bundledRolesDir, name);
+				const dst = path.join(dir, name);
+				const bundled = fs.readFileSync(src);
+				if (fs.existsSync(dst)) {
+					if (fs.readFileSync(dst).equals(bundled)) continue;
+					fs.renameSync(dst, `${dst}.backup`);
+				}
+				fs.copyFileSync(src, dst);
+			} catch {} // one role's missing file must not block the other two
+		}
+	} catch {}
+}
+
 /** Expand a leading ~/ — fs.* and pi's prompt resolution do not. */
 function expandPath(p: string): string {
 	if (p === "~") return os.homedir();
@@ -261,11 +295,15 @@ function errResult(code: string, detail: string, extra?: Record<string, unknown>
 	};
 }
 
-// Letters: <agentDir>/peer/letters/<recipientSid>/<hex>.md — one file per letter, no lock, no
-// ordering. The recipient's poll injects only the summary + file path (merged into one message)
-// and marks the letter announced by RENAMING it to acknowledged-<name>.md — the filename is the
-// dedup state, so a letter is announced at most once ever. The recipient reads and deletes the
-// file itself.
+// Letters: <agentDir>/peer/letters/<recipientSid>/pending-<hex>.md — one file per letter,
+// no lock, no ordering. The recipient's poll injects only the summary + file path (merged into
+// one message) and delivers by REMOVING the pending- prefix after issuing the notice — a
+// one-way valve: the prefix is only ever removed, never re-added; a new letter carries a
+// fresh name. pending- is the retry state: a letter still carrying it is re-considered on
+// every poll. The notice announces the prefix-less final path, which exists before any
+// consumer can look (the strip is the synchronous statement right after the send call — no
+// consumer sees the notice before this tick yields). The recipient reads and deletes the file
+// itself.
 
 const boxDir = (sid: string) => path.join(getAgentDir(), "peer", "letters", sid);
 const oneLine = (s: string) => s.replace(/\s+/g, " ").trim();
@@ -292,7 +330,7 @@ function formatNotice(file: string, text: string): string {
 async function post(sid: string, message: string, header: { from: string; summary: string }): Promise<string> {
 	const dir = boxDir(sid);
 	fs.mkdirSync(dir, { recursive: true });
-	const file = path.join(dir, `${randomBytes(8).toString("hex")}.md`);
+	const file = path.join(dir, `${PENDING}${randomBytes(8).toString("hex")}.md`);
 	const text = `---\nfrom: ${oneLine(header.from)}\nsummary: ${oneLine(header.summary)}\n---\n\n${message}\n`;
 	const tmp = `${file}.tmp`;
 	fs.writeFileSync(tmp, text);
@@ -300,38 +338,47 @@ async function post(sid: string, message: string, header: { from: string; summar
 	return file;
 }
 
-const ACK = "acknowledged-"; // filename prefix: this letter has already been announced
+const PENDING = "pending-"; // filename prefix: not yet announced; removed once, never re-added
 
 /** Order means nothing — one tick delivers them all merged. */
 function pendingLetters(dir: string): string[] {
 	try {
 		return fs.readdirSync(dir)
-			.filter((n) => n.endsWith(".md") && !n.startsWith(ACK))
+			.filter((n) => n.startsWith(PENDING) && n.endsWith(".md"))
 			.sort();
 	} catch {
 		return [];
 	}
 }
 
-/** Returns the renamed path (where the recipient finds it), or null if already deleted. */
-function acknowledge(dir: string, name: string): string | null {
-	try {
-		fs.renameSync(path.join(dir, name), path.join(dir, `${ACK}${name}`));
-		return path.join(dir, `${ACK}${name}`);
-	} catch {
-		return null;
-	}
-}
-
-/** Announce waiting letters merged — steer while running, followUp when idle. */
+// Compaction state, tracked from session events. pi rejects every prompt submission
+// while compaction runs ("Cannot submit a prompt while compaction is in progress"), and
+// pi.sendUserMessage's binding swallows that rejection (fire-and-forget; the failure is
+// only reported as a runtime extension error), so the extension cannot learn a send
+// failed — it must simply not send during the window.
+let compactionActive = false;
+
+/** Announce waiting letters merged — steer while running or starting (pi 1.2.0 counts the
+ * session busy from run start, so a letter landing there queues into the starting run
+ * instead of racing it), followUp when idle. While compaction runs the tick does nothing:
+ * pi rejects prompt submission then, the rejection is not observable through
+ * pi.sendUserMessage, and letters stay pending — the prefix IS the retry state — for the
+ * first tick after it ends.
+ *
+ * Delivery is one-way on the pending- prefix: it is stripped only AFTER the notice has been
+ * issued, and never re-added. If the send call itself throws, the strip loop never runs and
+ * the letters retry. Residual windows: a send that fails silently (the rejection is swallowed
+ * by pi's binding) inside the check-to-send gap leaves an un-announced, un-pended letter —
+ * at-most-once loss, as before; a crash after an effective send leaves the prefix on, so the
+ * letter is re-announced — a benign duplicate instead of a loss. */
 function startInboxLoop(pi: ExtensionAPI, sid: string, isIdle: () => boolean): () => void {
 	const dir = boxDir(sid);
 	let stopped = false;
 
 	const tick = () => {
-		if (stopped) return;
+		if (stopped || compactionActive) return;
 		try {
-			const batch: string[] = [];
+			const batch: Array<{ pendingPath: string; finalPath: string; text: string }> = [];
 			for (const name of pendingLetters(dir)) {
 				let text: string;
 				try {
@@ -339,12 +386,26 @@ function startInboxLoop(pi: ExtensionAPI, sid: string, isIdle: () => boolean): (
 				} catch {
 					continue; // unreadable right now: retry on a later tick
 				}
-				const file = acknowledge(dir, name);
-				if (!file) continue; // deleted underneath us: already read
-				batch.push(formatNotice(file, text));
+				batch.push({
+					pendingPath: path.join(dir, name),
+					finalPath: path.join(dir, name.slice(PENDING.length)),
+					text,
+				});
 			}
 			if (batch.length === 0) return;
-			pi.sendUserMessage(batch.join(BATCH_SEP), { deliverAs: isIdle() ? "followUp" : "steer" });
+			pi.sendUserMessage(
+					batch.map((b) => formatNotice(b.finalPath, b.text)).join(BATCH_SEP),
+					{ deliverAs: isIdle() ? "followUp" : "steer" },
+			);
+			// Strip the pending- prefix — the one-way "notice issued" transition. Reached
+			// only if the send call did not throw; no consumer can observe the notice before
+			// this synchronous rename, so the announced (prefix-less) path already exists
+			// when anyone looks.
+			for (const b of batch) {
+				try {
+					fs.renameSync(b.pendingPath, b.finalPath);
+				} catch {} // vanished underneath us: nothing to deliver
+			}
 		} catch {}
 	};
 
@@ -392,6 +453,10 @@ async function revivePeer(pi: ExtensionAPI, sid: string, cwd: string, signal?: A
 }
 
 export default function piPeer(pi: ExtensionAPI) {
+	syncRoles();
+	const roleDir = peerRolesDir();
+	const ROLE_HINT = `Standard roles live in ${roleDir}: AGENTS.investigator.md (find out what is true, in the codebase or outside it), AGENTS.strategist.md (make the call: options, trade-offs, a committed recommendation and what would flip it), AGENTS.auditor.md (verify by reproducing, audit the path taken, then criticize — pours cold water on warm consensus).`;
+
 	// On a revive the role must be resolved before any pending letter can start a turn —
 	// session_start does both, in that order.
 
@@ -422,16 +487,34 @@ export default function piPeer(pi: ExtensionAPI) {
 		const sid = ctx.sessionManager.getSessionId();
 		inheritRoleFromFork(event, sid);
 		loadOwnRole(sid);
+		compactionActive = false; // the fresh session is not compacting
 		// 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);
 		stopLoop?.();
 		stopLoop = startInboxLoop(pi, sid, () => ctx.isIdle());
 	});
 
+	// Track the compaction window so the inbox tick can wait it out (see startInboxLoop):
+	// session_compact_failed fires on failure AND abort — including an extension cancelling
+	// in session_before_compact — so the flag always has a reset path.
+	pi.on("session_before_compact", async () => {
+		compactionActive = true;
+	});
+	const compactionOver = async () => {
+		compactionActive = false;
+	};
+	pi.on("session_compact", compactionOver);
+	pi.on("session_compact_failed", compactionOver);
+
 	// pi persists no system prompt (--append-system-prompt vanishes on resume), so the role is
 	// re-applied EVERY turn from the file the registry points at. Identity follows the SESSION,
 	// not the process: /new inside a peer's pane runs plain; a fork inherits the branched
 	// session's role. Idempotent: skips when already present.
+	// pi 1.2.0: the event is a union on event.messageType — "user" runs (prompts,
+	// sendUserMessage) carry prompt/images, "custom" runs (sendMessage with triggerTurn)
+	// carry the starting message. The role deliberately applies to BOTH kinds: any turn the
+	// peer runs carries its stance. The forced system prompt now also survives the run's
+	// tool calls (1.2.0 fix), so the prompt cache no longer breaks mid-run over the role.
 	pi.on("before_agent_start", async (event, ctx) => {
 		// Re-resolve on session switch so the role never leaks across sessions.
 		const sid = ctx.sessionManager.getSessionId();
@@ -451,7 +534,7 @@ export default function piPeer(pi: ExtensionAPI) {
 		name: "peer_spawn",
 		label: "Spawn peer",
 		description:
-			`Spawn an equal pi peer in a tmux pane with a pre-assigned sessionId. ${SKILL_GATE} It returns only once the peer is verifiably up — it blocks up to ~${SPAWN_BOOT_TIMEOUT_MS / 1000}s until the peer labels the pane it was given, and reports a failure instead of handing back a sid that never booted. The returned sid becomes disk-durable a few seconds after return, when the peer submits its first message (pi persists the session file then, not at boot); a peer killed before that leaves no session — its sid goes dark (mail queues, resume reports not found). The task is delivered at launch as the peer's first user message. Use peer_send_mail for follow-up letters. prompt: path to a role file that stays with the peer across every start — standard role files: ~/.pi/agent/AGENTS.critic.md, ~/.pi/agent/AGENTS.researcher.md, ~/.pi/agent/AGENTS.scout.md (the peer-orchestrator skill describes what each role does). context: omit = empty | fork:<sessionId> = fork that session's full history, and the forked peer also inherits its role unless prompt overrides it | handoff:<text> = custom context text (prepended to the first message).`,
+			`Spawn an equal pi peer in a tmux pane with a pre-assigned sessionId. ${SKILL_GATE} It returns only once the peer is verifiably up — it blocks up to ~${SPAWN_BOOT_TIMEOUT_MS / 1000}s until the peer labels the pane it was given, and reports a failure instead of handing back a sid that never booted. The returned sid becomes disk-durable a few seconds after return, when the peer submits its first message (pi persists the session file then, not at boot); a peer killed before that leaves no session — its sid goes dark (mail to it is rejected as unknown_session, resume reports not found). The task is delivered at launch as the peer's first user message. Use peer_send_mail for follow-up letters. prompt: path to a role file that stays with the peer across every start — ${ROLE_HINT} Pass a role whenever one fits the mission — it is the main way to shape a peer's stance. The peer-orchestrator skill describes what each role does; any other file path works for a custom role. context: omit = empty | fork:<sessionId> = fork that session's full history, and the forked peer also inherits its role unless prompt overrides it | handoff:<text> = custom context text (prepended to the first message).`,
 		promptGuidelines: [
 			"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.",
 		],
@@ -461,7 +544,7 @@ export default function piPeer(pi: ExtensionAPI) {
 			prompt: Type.Optional(
 				Type.String({
 					description:
-						"Path to a role-prompt file (errors if it does not exist). The role stays with the peer across every start — spawn, mail revive, or a user-run /resume — and the file is re-read per turn, so editing it takes effect without respawning. Identity follows the session: /new inside a peer's pane starts a plain session, while a fork inherits the role of the session it branched from unless this overrides it. Standard roles: ~/.pi/agent/AGENTS.critic.md, ~/.pi/agent/AGENTS.researcher.md, ~/.pi/agent/AGENTS.scout.md; omit for a plain peer.",
+						"Path to a role-prompt file (errors if it does not exist). The role stays with the peer across every start — spawn, mail revive, or a user-run /resume — and the file is re-read per turn, so editing it takes effect without respawning. Identity follows the session: /new inside a peer's pane starts a plain session, while a fork inherits the role of the session it branched from unless this overrides it. ${ROLE_HINT} Omit only when no role fits — a plain peer has no role discipline. Any other file path works for a custom role.",
 				}),
 			),
 			context: Type.Optional(
@@ -625,14 +708,14 @@ export default function piPeer(pi: ExtensionAPI) {
 		name: "peer_send_mail",
 		label: "Send letter",
 		description:
-			`Deliver a letter to another session's mailbox (ANY pi session — peers and human-started). ${SKILL_GATE} The letter is stored as a .md file whose frontmatter header (from + summary) you write via the summary parameter. The recipient's poll injects ONLY the summary plus the file path — never the full text; the recipient reads the full letter from that path itself and deletes the file afterwards. Notices reach a running session within ~${POLL_MS / 1000}s — via steer while it is running, via followUp when it is idle — and multiple pending notices are merged into one message. A dead recipient is revived automatically, whether it was spawned as a peer or started by a human (this tool blocks up to ~${REVIVE_TIMEOUT_MS / 1000}s and reports whether the revive succeeded), and reads the notice at boot; if the revive fails the letter stays queued and is read when it next starts. The summary must be self-contained: state who you are (name/sessionId) and what the letter is about; the letter body should also say whether a reply is needed and where to send it.`,
+			`Deliver a letter to another session's mailbox (ANY pi session — peers and human-started). ${SKILL_GATE} The recipient must already exist on disk: an id with no session file is rejected with an error and nothing is written or sent (a just-spawned peer becomes addressable a few seconds after peer_spawn returns, once it persists its session file). The letter is stored as a .md file whose frontmatter header (from + summary) you write via the summary parameter. The recipient's poll injects ONLY the summary plus the file path — never the full text; the recipient reads the full letter from that path itself and deletes the file afterwards. Notices reach a running session within ~${POLL_MS / 1000}s — via steer while it is running, via followUp when it is idle — and multiple pending notices are merged into one message. A dead recipient is revived automatically, whether it was spawned as a peer or started by a human (this tool blocks up to ~${REVIVE_TIMEOUT_MS / 1000}s and reports whether the revive succeeded), and reads the notice at boot; if the revive fails the letter stays queued and is read when it next starts. The summary must be self-contained: state who you are (name/sessionId) and what the letter is about; the letter body should also say whether a reply is needed and where to send it.`,
 		promptGuidelines: [
 			"Batch peer_send_mail letters and keep them substantive: never send acknowledgements or small talk. Multiple pending notices are merged into one message, so one letter per topic is enough. Write a good summary — it is all the recipient sees before deciding to open the letter file.",
 		],
 		parameters: Type.Object({
 			to: Type.String({
 				description:
-					"Recipient sessionId: the exact lowercase 36-character UUID as peer_list prints it. May target a session that is not on disk yet (e.g. a just-spawned peer). Prefixes, a different case and any other variant are rejected — an id is never normalised into a match.",
+					"Recipient sessionId: the exact lowercase 36-character UUID as peer_list prints it. The session must already exist on disk — an id with no session file is rejected and nothing is sent. Prefixes, a different case and any other variant are rejected — an id is never normalised into a match.",
 			}),
 			summary: Type.String({
 				description:
@@ -643,7 +726,9 @@ export default function piPeer(pi: ExtensionAPI) {
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const tmuxProblem = await tmuxGuard(pi);
 			if (tmuxProblem) return errResult("no_tmux", tmuxProblem, { state: "no_tmux" });
-			// A full id not on disk yet is fine — it may be a just-spawned peer still booting.
+			// The letter is composed but not yet on disk: a recipient that exists nowhere on disk is a typo (or a
+			// peer that never booted), so refuse it before writing anything — an unreadable letter in a dead
+			// mailbox is invisible to both sides.
 			const sid = params.to.trim();
 			if (!UUID_RE.test(sid)) {
 				return errResult(
@@ -654,19 +739,23 @@ export default function piPeer(pi: ExtensionAPI) {
 			}
 			const records = await scanAllSessions(pi);
 			const target = findSessionById(records, sid);
+			if (!target) {
+				return errResult(
+					"unknown_session",
+					`no session with id ${sid} exists on disk; nothing was sent. Pass the exact sessionId of an existing session (peer_list shows them).`,
+					{ state: "unknown_session", sessionId: sid },
+				);
+			}
 			const self = ctx.sessionManager.getSessionId();
 			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 });
-			const label = target?.name ?? sid;
+			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) {
-				return done("queued_no_session", `sent → ${label} — no session on disk yet; the letter is queued and will be read when it starts`);
-			}
 			if (target.alive) {
 				return done("alive", `sent → ${label} — alive; it picks the letter up within ~${POLL_MS / 1000}s`);
 			}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@semanaut/zpi-peer",
-  "version": "0.1.0",
-  "description": "pi extension: equal, durable peers in tmux windows plus a letter channel between any pi sessions",
+  "version": "2.0.0",
+  "piVersion": "1.2.0",
+  "description": "pi extension: equal, durable pi peers managed through tmux panes plus a letter channel between any pi sessions. 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",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -9,7 +10,10 @@
   "license": "MIT",
   "files": [
     "extensions",
-    "skills"
+    "skills",
+    "AGENTS.investigator.md",
+    "AGENTS.strategist.md",
+    "AGENTS.auditor.md"
   ],
   "pi": {
     "extensions": [

package/skills/peer-orchestrator/SKILL.md

@@ -67,19 +67,44 @@ session, never the process: `/new` inside a peer's pane starts a plain session,
 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.
+
 ## The standard roles
-All three are read-only by intent. Peers launch with the full toolset; discipline comes from the
-role file and your task text, not from restrictions. A peer can always mail you back.
-
-- `~/.pi/agent/AGENTS.scout.md` — fast reconnaissance. Use it to map unknown territory: key
-  directories, entry points, one-line file descriptions. It locates, it does not analyze deeply,
-  and it states its interpretation when your task is ambiguous.
-- `~/.pi/agent/AGENTS.researcher.md` — directed research. Use it for a sourced findings brief on a
-  question you could not answer from the code alone; every conclusion cites a file path or URL.
-- `~/.pi/agent/AGENTS.critic.md` — independent review. Use it for an unpolluted second opinion on a
-  plan, diff, or conclusion of yours; it answers VERDICT (agree / agree-with-changes / object)
-  plus numbered findings by severity, each with quoted evidence and a concrete suggestion. It
-  never rubber-stamps — give it the artifact, not your defense of it.
+
+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.