@semanaut/zpi-peer 2.1.0 → 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_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.
+- **`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

@@ -189,13 +189,15 @@ function expandPath(p: string): string {
 
 // 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 .json at all. Legacy records with creatorSessionId are ignored on read.
+// 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 file = path.join(registryDir(), `${sid}.json`);
-	const tmp = `${file}.tmp`;
+	fs.mkdirSync(sessionDir(sid), { recursive: true });
+	const tmp = `${roleFile(sid)}.tmp`;
 	fs.writeFileSync(tmp, JSON.stringify({ appendPrompt: expandPath(rec.appendPrompt) }));
-	fs.renameSync(tmp, file); // tmp+rename: readers never see a half-written record
+	fs.renameSync(tmp, roleFile(sid)); // tmp+rename: readers never see a half-written record
 }
 
 // Role records are write-once (the role path never changes), so this cache (negatives included) never goes stale.
@@ -206,14 +208,14 @@ 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"));
+		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;
 }
 
-const contactsFile = (sid: string) => path.join(registryDir(), `${sid}.contacts`);
+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
@@ -222,7 +224,8 @@ const contactsFile = (sid: string) => path.join(registryDir(), `${sid}.contacts`
  *  duplicates are harmless because reads dedupe. */
 function addContact(a: string, b: string): void {
 	try {
-		fs.mkdirSync(registryDir(), { recursive: true });
+		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
@@ -238,9 +241,11 @@ function readContacts(sid: string): string[] {
 	return [...new Set(raw.split("\n").filter((l) => UUID_RE.test(l)))];
 }
 
+// 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.unlinkSync(path.join(registryDir(), `${sid}.json`));
+		fs.rmSync(sessionDir(sid), { recursive: true, force: true });
 	} catch {}
 	recordCache.delete(sid);
 }
@@ -275,6 +280,40 @@ function findSessionById(records: SessionRecord[], sessionId: string): SessionRe
 	return records.find((r) => r.sessionId === sessionId);
 }
 
+/** 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>) {
 	const message = `${code}: ${detail}`;
@@ -457,7 +496,7 @@ export default function piPeer(pi: ExtensionAPI) {
 		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) return;
 		writePeerRecord(ownSid, { appendPrompt: src.appendPrompt }); // role only — contacts are never inherited
@@ -527,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({
@@ -551,7 +590,7 @@ 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;
@@ -756,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.1.0",
+  "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 sessions with their contact counts), 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,117 +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 ~25s 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.
+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). 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. 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.
+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?".