@trim21/personal-pi-extensions 0.0.208 → 0.0.209

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.208",
+  "version": "0.0.209",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/lib/cli-args.ts

@@ -0,0 +1,116 @@
+/**
+ * Minimal command-line argument parsing for `/command` handlers.
+ *
+ * The pi command API passes handlers a raw string (current versions) or a
+ * token array (newer ones); this helper accepts either and yields
+ * positionals plus flags, so handlers never care about the input shape.
+ *
+ * A raw string is split with shell-like rules first: whitespace separates
+ * tokens, single quotes preserve everything literally, double quotes allow
+ * `\"` / `\\` escapes, and a backslash outside quotes escapes the next
+ * character. Unlike bash, empty tokens are dropped and an unterminated
+ * quote raises a SyntaxError.
+ *
+ * Flags (only long form, `--name`):
+ *   --name value    flag "name" = "value" (value may not start with `--`)
+ *   --name=value    same
+ *   --flag          boolean flag = true
+ *   --              everything after is a positional
+ */
+
+export interface ParsedArgs {
+  /** Non-flag arguments, in order. */
+  positionals: string[];
+  /** `--name value` / `--name=value` → string; `--flag` → true. */
+  flags: Record<string, string | boolean>;
+}
+
+/** Does this token look like a long flag (`--x`, but not the bare `--`)? */
+function isFlagToken(token: string): boolean {
+  return token.startsWith("--") && token !== "--";
+}
+
+/** Shell-like tokenizer for a raw command line. Empty tokens are dropped. */
+export function shlexSplit(raw: string): string[] {
+  const tokens: string[] = [];
+  let cur = "";
+  let quote: "'" | '"' | undefined;
+  let i = 0;
+  while (i < raw.length) {
+    const c = raw[i];
+    if (quote) {
+      if (c === quote) {
+        quote = undefined;
+      } else if (c === "\\" && quote === '"' && (raw[i + 1] === '"' || raw[i + 1] === "\\")) {
+        cur += raw[i + 1];
+        i++;
+      } else {
+        cur += c;
+      }
+      i++;
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      quote = c;
+      i++;
+      continue;
+    }
+    if (c === "\\") {
+      if (i + 1 < raw.length) cur += raw[i + 1];
+      i += 2;
+      continue;
+    }
+    if (/\s/.test(c)) {
+      if (cur) {
+        tokens.push(cur);
+        cur = "";
+      }
+      i++;
+      continue;
+    }
+    cur += c;
+    i++;
+  }
+  if (quote !== undefined) {
+    throw new SyntaxError(`unterminated quote in command arguments: ${raw}`);
+  }
+  if (cur) tokens.push(cur);
+  return tokens;
+}
+
+export function parseArgs(input: string | string[]): ParsedArgs {
+  const tokens = Array.isArray(input) ? input : shlexSplit(input);
+  const positionals: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  let positionalOnly = false;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (positionalOnly) {
+      positionals.push(token);
+      continue;
+    }
+    if (token === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    const m = /^--([a-zA-Z0-9][a-zA-Z0-9-]*)(?:=(.*))?$/.exec(token);
+    if (!m) {
+      positionals.push(token);
+      continue;
+    }
+    const name = m[1];
+    if (m[2] !== undefined) {
+      flags[name] = m[2];
+      continue;
+    }
+    // `--name value` form: consume the next token unless it is itself a flag.
+    const next = tokens[i + 1];
+    if (next !== undefined && !isFlagToken(next)) {
+      flags[name] = next;
+      i++;
+    } else {
+      flags[name] = true;
+    }
+  }
+  return { positionals, flags };
+}

package/src/talk/core.ts

@@ -3,13 +3,13 @@
  * storage backend, and yields deliveries and notifications to an adapter
  * through events. Pi-free — the pi adapter (index.ts) owns the pi API surface.
  *
- * Visibility model: groups are the only visibility boundary. A session in a
- * group sees only its co-members; a session in no group sees only itself.
+ * Visibility model: groups are the only visibility boundary. An agent in a
+ * group sees only its co-members; an agent in no group sees only itself.
  * Membership is read live from storage on every operation, so joining or
- * leaving a group takes effect immediately for every session.
+ * leaving a group takes effect immediately for every agent.
  *
  * Delivery model: a letter is removed from the inbox only AFTER the adapter
- * reports it was handed to the session (`events.deliver` returns true). A
+ * reports it was handed to the agent (`events.deliver` returns true). A
  * letter whose delivery fails stays in the inbox and is retried on the next
  * poll — so a swallowed sendMessage error no longer destroys the letter.
  */
@@ -17,7 +17,7 @@
 import { age, formatListing, refusalUnknown, shortAddr } from "./format.js";
 import {
   deleteGroup,
-  groupForSession,
+  groupForAgent,
   isValidGroupName,
   listGroups,
   newGroupId,
@@ -45,12 +45,12 @@ import {
 } from "./mailbox.js";
 import { inboundAccepts, OutboundPolicy } from "./policy.js";
 import {
+  type AgentRecord,
   listRecords,
   type Presence,
   presenceOf,
   readRecord,
   readStartTime,
-  type SessionRecord,
   sweep,
   writeRecord,
 } from "./registry.js";
@@ -58,7 +58,7 @@ import type { TalkStorage } from "./storage.js";
 
 type AskOutcome =
   { replied: true; body: string; from: string } | { replied: false; reason: string };
-type TargetResult = { ok: true; record: SessionRecord } | { ok: false; error: string };
+type TargetResult = { ok: true; record: AgentRecord } | { ok: false; error: string };
 type SendResult = { ok: true; letter: Letter; verdict: string } | { ok: false; error: string };
 
 export interface TalkCoreEvents {
@@ -84,14 +84,14 @@ const SWEEP_INTERVAL_MS = 30 * 60 * 1000;
  * Mutual-ask arbitration: true when the peer asked first. The `ts` fields of
  * the two ask letters are fixed values inside the letters, so both sides
  * compare the same pair and reach symmetric conclusions. On a same-ms
- * collision, `cwd + sessionId` breaks the tie deterministically.
+ * collision, `cwd + agentId` breaks the tie deterministically.
  */
 export function peerAskedFirst(
-  peer: { ts: number; cwd: string; sessionId: string },
-  self: { ts: number; cwd: string; sessionId: string },
+  peer: { ts: number; cwd: string; agentId: string },
+  self: { ts: number; cwd: string; agentId: string },
 ): boolean {
-  const peerKey = `${peer.cwd}\u0000${peer.sessionId}`;
-  const selfKey = `${self.cwd}\u0000${self.sessionId}`;
+  const peerKey = `${peer.cwd}\u0000${peer.agentId}`;
+  const selfKey = `${self.cwd}\u0000${self.agentId}`;
   return peer.ts < self.ts || (peer.ts === self.ts && peerKey < selfKey);
 }
 
@@ -100,7 +100,7 @@ export class TalkCore {
   private readonly events: TalkCoreEvents;
   private readonly now: () => number;
 
-  private self: SessionRecord | undefined;
+  private self: AgentRecord | undefined;
   private readonly policy = new OutboundPolicy();
   private readonly askWaiters = new Map<string, (outcome: AskOutcome) => void>();
   private readonly watched = new Map<string, Presence>();
@@ -124,7 +124,7 @@ export class TalkCore {
     return this.self?.addr;
   }
 
-  private requireSelf(): SessionRecord {
+  private requireSelf(): AgentRecord {
     const self = this.self;
     if (!self) throw new Error("Talk core is not started");
     return self;
@@ -132,7 +132,7 @@ export class TalkCore {
 
   // ── Lifecycle ──────────────────────────────────────────────────────────
 
-  async start(self: SessionRecord): Promise<void> {
+  async start(self: AgentRecord): Promise<void> {
     await this.storage.init();
     // Record the process start time so presence can rule out pid reuse later.
     const pidStart = readStartTime(self.pid);
@@ -141,7 +141,7 @@ export class TalkCore {
     try {
       await sweep(this.storage, this.now());
     } catch {
-      // sweep failure never breaks the session
+      // sweep failure never breaks the agent
     }
     this.startInboxPoll();
     // Reclaim dead records periodically, not just at startup.
@@ -150,7 +150,7 @@ export class TalkCore {
     }, SWEEP_INTERVAL_MS);
     this.sweeper.unref();
     // Drain mail queued while offline — deferred: delivering during
-    // session_start races the session's own first turn.
+    // session_start races the agent's own first turn.
     const initial = setTimeout(() => {
       void this.checkInbox();
     }, INITIAL_DRAIN_DELAY_MS);
@@ -183,18 +183,18 @@ export class TalkCore {
     void this.writeSelf({ status: "idle" });
   }
 
-  setSessionName(name: string): void {
+  setAgentName(name: string): void {
     void this.writeSelf({ name });
   }
 
-  private async writeSelf(patch: Partial<SessionRecord>): Promise<void> {
+  private async writeSelf(patch: Partial<AgentRecord>): Promise<void> {
     if (!this.self) return;
-    // A dead session pins lastSeenAt to 0 so no later event re-freshens it.
+    // A dead agent pins lastSeenAt to 0 so no later event re-freshens it.
     this.self = { ...this.self, ...patch, lastSeenAt: this.dead ? 0 : this.now() };
     try {
       await writeRecord(this.storage, this.self);
     } catch {
-      // registration failures never break the session
+      // registration failures never break the agent
     }
   }
 
@@ -297,32 +297,32 @@ export class TalkCore {
   // ── Outbound ───────────────────────────────────────────────────────────
 
   /**
-   * Session ids of the caller's group members, or null when the caller is in
+   * Agent ids of the caller's group members, or null when the caller is in
    * no group. Visibility is read live from storage on every operation, so a
-   * group change takes effect immediately for every session.
+   * group change takes effect immediately for every agent.
    */
   private async myGroupMemberIds(): Promise<Set<string> | null> {
     const self = this.requireSelf();
-    const group = await groupForSession(this.storage, self.sessionId);
+    const group = await groupForAgent(this.storage, self.agentId);
     return group ? new Set(group.members) : null;
   }
 
   /**
-   * Resolve a target by its exact session id (uuid). Only co-members of the
-   * caller's group are reachable; a session in no group sees no peers at all.
+   * Resolve a target by its exact agent id (uuid). Only co-members of the
+   * caller's group are reachable; an agent in no group sees no peers at all.
    */
   private async resolveTarget(to: string): Promise<TargetResult> {
     const self = this.requireSelf();
     const records = await listRecords(this.storage);
     const memberIds = await this.myGroupMemberIds();
-    const others = records.filter((r) => r.addr !== self.addr && memberIds?.has(r.sessionId));
-    const target = others.find((r) => r.sessionId === to);
+    const others = records.filter((r) => r.addr !== self.addr && memberIds?.has(r.agentId));
+    const target = others.find((r) => r.agentId === to);
     if (!target) return { ok: false, error: refusalUnknown(to) };
     return { ok: true, record: target };
   }
 
   private async sendLetter(
-    target: SessionRecord,
+    target: AgentRecord,
     kind: LetterKind,
     body: string,
     replyTo?: string,
@@ -337,7 +337,7 @@ export class TalkCore {
     if (!verdict.ok) return { ok: false, error: verdict.reason };
     const letter: Letter = {
       id: newMessageId(),
-      from: { addr: self.addr, name: self.name, cwd: self.cwd, sessionId: self.sessionId },
+      from: { addr: self.addr, name: self.name, cwd: self.cwd, agentId: self.agentId },
       kind,
       body,
       ts: this.now(),
@@ -351,9 +351,7 @@ export class TalkCore {
         ok: true,
         letter,
         verdict:
-          receipt === "delivered"
-            ? "delivered"
-            : "queued (waits on disk until the session resumes)",
+          receipt === "delivered" ? "delivered" : "queued (waits on disk until the agent resumes)",
       };
     }
     return {
@@ -407,7 +405,7 @@ export class TalkCore {
    * - the later ask yields: its waiter is settled with a "peer asked first"
    *   reason, and the peer's ask is delivered so this side answers it first.
    *
-   * On a same-millisecond ts collision, session dir + session id (carried in
+   * On a same-millisecond ts collision, agent dir + agent id (carried in
    * `letter.from`) breaks the tie deterministically — both sides compute the
    * same comparison and reach symmetric conclusions.
    */
@@ -418,8 +416,8 @@ export class TalkCore {
     const waiter = this.askWaiters.get(myAsk.askId);
     if (!waiter) return;
     const peerFirst = peerAskedFirst(
-      { ts: letter.ts, cwd: letter.from.cwd, sessionId: letter.from.sessionId },
-      { ts: myAsk.ts, cwd: self.cwd, sessionId: self.sessionId },
+      { ts: letter.ts, cwd: letter.from.cwd, agentId: letter.from.agentId },
+      { ts: myAsk.ts, cwd: self.cwd, agentId: self.agentId },
     );
     if (!peerFirst) return; // we asked first; keep waiting — the peer will yield
     this.askWaiters.delete(myAsk.askId);
@@ -433,10 +431,10 @@ export class TalkCore {
   // ── Tool actions ───────────────────────────────────────────────────────
 
   /**
-   * JSON listing of visible sessions, including self (marked `self: true`).
-   * Grouped sessions see only their co-members; a session in no group sees
+   * JSON listing of visible agents, including self (marked `self: true`).
+   * Grouped agents see only their co-members; an agent in no group sees
    * only itself. Every visible record is listed, live or offline; presence
-   * decides the per-session status.
+   * decides the per-agent status.
    */
   async list(): Promise<string> {
     const self = this.requireSelf();
@@ -444,7 +442,7 @@ export class TalkCore {
     const memberIds = await this.myGroupMemberIds();
     const records = all.filter((r) => {
       if (r.addr === self.addr) return !this.dead;
-      return memberIds?.has(r.sessionId) ?? false;
+      return memberIds?.has(r.agentId) ?? false;
     });
     return formatListing(records, self.addr, presenceOf);
   }
@@ -457,30 +455,30 @@ export class TalkCore {
     const filtered = records.filter((r) => {
       if (r.cwd !== cwd) return false;
       if (r.addr === self.addr) return !this.dead;
-      return memberIds?.has(r.sessionId) ?? false;
+      return memberIds?.has(r.agentId) ?? false;
     });
     return formatListing(filtered, self.addr, presenceOf);
   }
 
   /** Visible peer records (excluding self), e.g. for command completions. */
-  async listPeers(): Promise<SessionRecord[]> {
+  async listPeers(): Promise<AgentRecord[]> {
     const self = this.requireSelf();
     const records = await listRecords(this.storage);
     const memberIds = await this.myGroupMemberIds();
-    return records.filter((r) => r.addr !== self.addr && (memberIds?.has(r.sessionId) ?? false));
+    return records.filter((r) => r.addr !== self.addr && (memberIds?.has(r.agentId) ?? false));
   }
 
   /**
-   * Mark a session as dead: set its offline flag and pin lastSeenAt to 0 so
+   * Mark an agent as dead: set its offline flag and pin lastSeenAt to 0 so
    * the next sweep reaps it (empty mailbox). Without a target, marks this
-   * session — later writeSelf calls no longer refresh lastSeenAt, and the
+   * agent — later writeSelf calls no longer refresh lastSeenAt, and the
    * record stays offline for peers.
    */
   async markDead(target?: string): Promise<string> {
     if (!target) {
       this.dead = true;
       await this.writeSelf({ offline: true });
-      return "Marked this session as dead.";
+      return "Marked this agent as dead.";
     }
     const resolved = await this.resolveTarget(target);
     if (!resolved.ok) return resolved.error;
@@ -494,7 +492,7 @@ export class TalkCore {
     for (const peer of peers) {
       await writeRecord(this.storage, { ...peer, lastSeenAt: 0, offline: true });
     }
-    return `Marked ${peers.length} session(s) as dead.`;
+    return `Marked ${peers.length} agent(s) as dead.`;
   }
 
   // ── Groups ─────────────────────────────────────────────────────────────
@@ -502,9 +500,9 @@ export class TalkCore {
   /** Remove the caller from its current group, deleting the group when it empties. */
   private async leaveCurrentGroup(): Promise<boolean> {
     const self = this.requireSelf();
-    const group = await groupForSession(this.storage, self.sessionId);
+    const group = await groupForAgent(this.storage, self.agentId);
     if (!group) return false;
-    const others = group.members.filter((m) => m !== self.sessionId);
+    const others = group.members.filter((m) => m !== self.agentId);
     if (others.length === 0) {
       await deleteGroup(this.storage, group.id);
     } else {
@@ -517,36 +515,42 @@ export class TalkCore {
    * Join or create a group and join it. With no name a fresh uuid is
    * generated; with a name, the group is joined when it exists and created
    * otherwise. Leaving any current group first keeps the single-group
-   * invariant.
+   * invariant. When `agentName` is given, the agent's display name (what
+   * peers see in talk-list-agents) is set to it — also when the agent is
+   * already in the group, so re-joining can rename.
    */
-  async groupJoin(groupName?: string): Promise<string> {
+  async groupJoin(groupName?: string, agentName?: string): Promise<string> {
     const self = this.requireSelf();
     const name =
       groupName === undefined || groupName.trim() === "" ? newGroupId() : groupName.trim();
     if (!isValidGroupName(name)) {
       return `Invalid group name '${name}'. Allowed: letters, digits, '-' and '_' (max 64 chars).`;
     }
+    if (agentName !== undefined) {
+      await this.writeSelf({ name: agentName });
+    }
+    const nameNote = agentName === undefined ? "" : ` You are visible as "${agentName}".`;
     const existing = await readGroup(this.storage, name);
-    if (existing?.members.includes(self.sessionId)) {
-      return `Already in group ${name} (${existing.members.length} member(s)).`;
+    if (existing?.members.includes(self.agentId)) {
+      return `Already in group ${name} (${existing.members.length} member(s)).${nameNote}`;
     }
     await this.leaveCurrentGroup();
     if (existing) {
       await writeGroup(this.storage, {
         ...existing,
-        members: [...existing.members, self.sessionId],
+        members: [...existing.members, self.agentId],
         updatedAt: this.now(),
       });
-      return `Joined group ${name} (${existing.members.length + 1} member(s)). You now see only co-members.`;
+      return `Joined group ${name} (${existing.members.length + 1} member(s)). You now see only co-members.${nameNote}`;
     }
     const now = this.now();
     await writeGroup(this.storage, {
       id: name,
-      members: [self.sessionId],
+      members: [self.agentId],
       createdAt: now,
       updatedAt: now,
     });
-    return `Created group ${name}. Other sessions join it with /talk-group-join ${name}.`;
+    return `Created group ${name}.${nameNote} Other agents join it with /talk-group-join ${name}.`;
   }
 
   /** Join the most recently created group; no-op when already in it. */
@@ -560,9 +564,9 @@ export class TalkCore {
   /** Leave the current group; an emptied group is deleted. */
   async groupLeave(): Promise<string> {
     const self = this.requireSelf();
-    const group = await groupForSession(this.storage, self.sessionId);
+    const group = await groupForAgent(this.storage, self.agentId);
     if (!group) return "Not in any group.";
-    const others = group.members.filter((m) => m !== self.sessionId);
+    const others = group.members.filter((m) => m !== self.agentId);
     if (others.length === 0) {
       await deleteGroup(this.storage, group.id);
       return `Left group ${group.id} (deleted — it was empty).`;
@@ -581,7 +585,7 @@ export class TalkCore {
     return `Deleted group ${name} (${group.members.length} member(s)).`;
   }
 
-  /** Delete every group; all sessions become ungrouped. */
+  /** Delete every group; all agents become ungrouped. */
   async groupClear(): Promise<string> {
     const groups = await listGroups(this.storage);
     for (const group of groups) await deleteGroup(this.storage, group.id);
@@ -597,17 +601,15 @@ export class TalkCore {
     const groups = await listGroups(this.storage);
     if (groups.length === 0) return "No groups.";
     const records = await listRecords(this.storage);
-    const label = (sessionId: string): string => {
-      const rec = records.find((r) => r.sessionId === sessionId);
-      const id = sessionId.length > 8 ? `${sessionId.slice(0, 8)}…` : sessionId;
-      return rec ? `${rec.name} (${id})` : `unknown session (${id})`;
+    const label = (agentId: string): string => {
+      const rec = records.find((r) => r.agentId === agentId);
+      const id = agentId.length > 8 ? `${agentId.slice(0, 8)}…` : agentId;
+      return rec ? `${rec.name} (${id})` : `unknown agent (${id})`;
     };
     const lines = groups
       .toSorted((a, b) => b.createdAt - a.createdAt)
       .map((g) => {
-        const members = g.members.map((m) =>
-          m === self.sessionId ? `${label(m)} ← you` : label(m),
-        );
+        const members = g.members.map((m) => (m === self.agentId ? `${label(m)} ← you` : label(m)));
         return `- ${g.id} (created ${age(g.createdAt)}): ${members.join(", ")}`;
       });
     return `Groups (${groups.length}):\n${lines.join("\n")}`;
@@ -617,7 +619,7 @@ export class TalkCore {
     if (!to) return 'send requires "to".';
     if (!body) return 'send requires "message".';
     if (to === "*" || to === "cwd") {
-      return "send requires a single session id; broadcasting is disabled.";
+      return "send requires a single agent id; broadcasting is disabled.";
     }
     const resolved = await this.resolveTarget(to);
     if (!resolved.ok) return resolved.error;
@@ -683,10 +685,10 @@ export class TalkCore {
   }
 
   /** Build a minimal record from a letter's sender when the peer record is gone. */
-  private recordFromLetter(letter: Letter): SessionRecord {
+  private recordFromLetter(letter: Letter): AgentRecord {
     return {
       addr: letter.from.addr,
-      sessionId: letter.from.sessionId,
+      agentId: letter.from.agentId,
       name: letter.from.name,
       cwd: letter.from.cwd,
       pid: 0,

package/src/talk/format.ts

@@ -4,10 +4,9 @@
  */
 
 import type { Letter } from "./mailbox.js";
-import type { Presence, SessionRecord } from "./registry.js";
+import type { AgentRecord, Presence } from "./registry.js";
 
-export const BOUNDARY_PREAMBLE =
-  "This came from another pi session (a peer agent), not from the user.";
+export const BOUNDARY_PREAMBLE = "This came from another pi agent, not from the user.";
 
 export function shortAddr(addr: string): string {
   return addr.slice(0, 6);
@@ -21,20 +20,20 @@ export function age(ts: number, now: number = Date.now()): string {
   return `${Math.round(m / 60)}h ago`;
 }
 
-/** Delivery text injected into the receiving session's LLM context. */
+/** Delivery text injected into the receiving agent's LLM context. */
 export function formatDelivery(letter: Letter, now: number = Date.now()): string {
   const from = letter.from;
-  const header = `From pi session ${from.sessionId} (${from.cwd}) — "${from.name}"`;
+  const header = `From pi agent ${from.agentId} (${from.cwd}) — "${from.name}"`;
   const meta = `_id ${letter.id} · ${letter.kind} · sent ${age(letter.ts, now)}_`;
   const hint =
     letter.kind === "ask" ? `\n\nReply with the talk-reply tool, replyTo: "${letter.id}"` : "";
   return `${BOUNDARY_PREAMBLE}\n\n${header}:\n\n${letter.body}\n\n${meta}${hint}`;
 }
 
-/** One session as the model sees it in a listing. `id` is the stable pi
- * session uuid; `name` is the display name when one was set; `self` marks
- * the calling session itself. */
-export interface SessionListItem {
+/** One agent as the model sees it in a listing. `id` is the stable pi
+ * agent uuid; `name` is the display name when one was set; `self` marks
+ * the calling agent itself. */
+export interface AgentListItem {
   status: string;
   work_dir: string;
   id: string;
@@ -42,17 +41,17 @@ export interface SessionListItem {
   self?: boolean;
 }
 
-/** Machine-readable JSON listing of sessions (what the model sees). */
+/** Machine-readable JSON listing of agents (what the model sees). */
 export function formatListing(
-  records: SessionRecord[],
+  records: AgentRecord[],
   selfAddr: string,
-  presence: (r: SessionRecord) => Presence,
+  presence: (r: AgentRecord) => Presence,
 ): string {
   if (records.length === 0) return "[]";
-  const items: SessionListItem[] = records.map((r) => {
+  const items: AgentListItem[] = records.map((r) => {
     const p = presence(r);
     const status = p === "live" ? r.status : "offline";
-    const item: SessionListItem = { status, work_dir: r.cwd, id: r.sessionId, name: r.name };
+    const item: AgentListItem = { status, work_dir: r.cwd, id: r.agentId, name: r.name };
     if (r.addr === selfAddr) item.self = true;
     return item;
   });
@@ -60,5 +59,5 @@ export function formatListing(
 }
 
 export function refusalUnknown(to: string): string {
-  return `Unknown session id '${to}'. Get session ids with talk-list-sessions.`;
+  return `Unknown agent id '${to}'. Get agent ids with talk-list-agents.`;
 }

package/src/talk/group.ts

@@ -1,14 +1,14 @@
 /**
- * Session groups for the talk mailbox: an explicit, uuid-addressed set of
- * sessions that see only each other. Core layer — depends only on
+ * Agent groups for the talk mailbox: an explicit, uuid-addressed set of
+ * agents that see only each other. Core layer — depends only on
  * TalkStorage, never on pi.
  *
  * Rules:
- * - A session belongs to at most one group (single-group invariant).
- * - Groups are public: any session can join any group by its uuid, and a
+ * - An agent belongs to at most one group (single-group invariant).
+ * - Groups are public: any agent can join any group by its uuid, and a
  *   member can leave freely. There is no owner.
- * - Visibility is fully group-driven: a grouped session sees only its
- *   co-members; a session in no group sees only itself.
+ * - Visibility is fully group-driven: a grouped agent sees only its
+ *   co-members; an agent in no group sees only itself.
  * - A group that empties is deleted; a one-member group is a normal state
  *   (a creator waiting for peers to join).
  */
@@ -22,7 +22,7 @@ import type { TalkStorage } from "./storage.js";
 
 export const GroupSchema = Type.Object({
   id: Type.String(),
-  /** pi session uuids of the members. */
+  /** pi agent uuids of the members. */
   members: Type.Array(Type.String()),
   createdAt: Type.Number(),
   updatedAt: Type.Number(),
@@ -79,16 +79,13 @@ export async function deleteGroup(storage: TalkStorage, id: string): Promise<boo
 }
 
 /**
- * The group a session currently belongs to. Under the single-group invariant
- * this is at most one; corrupted data that lists the session in several
+ * The group an agent currently belongs to. Under the single-group invariant
+ * this is at most one; corrupted data that lists the agent in several
  * groups resolves to the first match.
  */
-export async function groupForSession(
-  storage: TalkStorage,
-  sessionId: string,
-): Promise<Group | null> {
+export async function groupForAgent(storage: TalkStorage, agentId: string): Promise<Group | null> {
   for (const group of await listGroups(storage)) {
-    if (group.members.includes(sessionId)) return group;
+    if (group.members.includes(agentId)) return group;
   }
   return null;
 }

package/src/talk/index.ts

@@ -18,11 +18,12 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
+import { parseArgs } from "../lib/cli-args.js";
 import { resolveHomePath } from "../lib/path.js";
 import { TalkCore } from "./core.js";
 import { formatDelivery } from "./format.js";
 import type { Letter } from "./mailbox.js";
-import { deriveAddr, type SessionRecord } from "./registry.js";
+import { type AgentRecord, deriveAddr } from "./registry.js";
 import { SqliteTalkStorage } from "./storage.js";
 
 const DELIVERY_TYPE = "talk:delivery";
@@ -108,14 +109,16 @@ export default function talk(pi: ExtensionAPI) {
   const dbPath = configured
     ? resolveHomePath(configured, getAgentDir())
     : path.join(getAgentDir(), "talk.db");
-  // "queue": deliver on the session's next natural turn without waking it;
-  // "steer": interrupt mid-run / wake an idle session immediately.
+  // "queue": deliver on the agent's next natural turn without waking it;
+  // "steer": interrupt mid-run / wake an idle agent immediately.
   const deliverMode: "steer" | "queue" = settings.deliver ?? "queue";
   const storage = new SqliteTalkStorage(dbPath);
 
-  let self: SessionRecord | undefined;
+  let self: AgentRecord | undefined;
+  /** Display name explicitly set via `--name`; kept across session_info_changed. */
+  let explicitName: string | undefined;
 
-  function deliverToSession(letter: Letter): boolean {
+  function deliverToAgent(letter: Letter): boolean {
     const details: DeliveryDetails = {
       id: letter.id,
       kind: letter.kind,
@@ -142,7 +145,7 @@ export default function talk(pi: ExtensionAPI) {
   const core = new TalkCore({
     storage,
     events: {
-      deliver: deliverToSession,
+      deliver: deliverToAgent,
       notify(content) {
         // Presence transitions are informational — queue for the next turn
         // rather than steering into a busy agent.
@@ -162,13 +165,13 @@ export default function talk(pi: ExtensionAPI) {
   // ── Lifecycle ──────────────────────────────────────────────────────────
 
   pi.on("session_start", (_event, ctx: ExtensionContext) => {
-    const sessionId = ctx.sessionManager.getSessionId();
+    const agentId = ctx.sessionManager.getSessionId();
     const cwd = ctx.sessionManager.getCwd() ?? ctx.cwd;
     const now = Date.now();
     self = {
-      addr: deriveAddr(cwd, sessionId),
-      sessionId,
-      name: pi.getSessionName() ?? "Unnamed session",
+      addr: deriveAddr(cwd, agentId),
+      agentId,
+      name: pi.getSessionName() ?? "Unnamed agent",
       cwd,
       pid: process.pid,
       startedAt: now,
@@ -182,15 +185,17 @@ export default function talk(pi: ExtensionAPI) {
   pi.on("agent_end", () => core.setIdle());
   pi.on("agent_settled", () => core.setIdle());
   pi.on("before_agent_start", (event) => {
-    // One-line nudge: before coordinating with other pi sessions, read the
+    // One-line nudge: before coordinating with other pi agents, read the
     // shipped workflow skill. Skipped when the skill file is absent.
     if (!fs.existsSync(SKILL_PATH)) return;
     return {
-      systemPrompt: `${event.systemPrompt}\n\nBefore multi-session collaboration, read ${SKILL_PATH} to understand the talk workflow.`,
+      systemPrompt: `${event.systemPrompt}\n\nBefore multi-agent collaboration, read ${SKILL_PATH} to understand the talk workflow.`,
     };
   });
   pi.on("session_info_changed", () => {
-    if (self) core.setSessionName(pi.getSessionName() ?? self.name);
+    // A name set explicitly via `--name` wins over pi's session title;
+    // otherwise follow pi's session name.
+    if (self) core.setAgentName(explicitName ?? pi.getSessionName() ?? self.name);
   });
   pi.on("session_shutdown", () => {
     void core.stop();
@@ -199,12 +204,12 @@ export default function talk(pi: ExtensionAPI) {
   // ── Tools ──────────────────────────────────────────────────────────────
 
   pi.registerTool({
-    name: "talk-list-sessions",
-    label: "List Talk Sessions",
-    description: "List visible pi sessions (id, status, work_dir, name).",
-    promptSnippet: "List other pi sessions on this machine",
+    name: "talk-list-agents",
+    label: "List Talk Agents",
+    description: "List visible pi agents (id, status, work_dir, name).",
+    promptSnippet: "List other pi agents on this machine",
     parameters: Type.Object({
-      cwd: Type.Optional(Type.String({ description: "Only list sessions in this directory" })),
+      cwd: Type.Optional(Type.String({ description: "Only list agents in this directory" })),
     }),
     async execute(_toolCallId, params) {
       const initError = requireInit();
@@ -217,10 +222,10 @@ export default function talk(pi: ExtensionAPI) {
     name: "talk-ask",
     label: "Ask Talk",
     description:
-      "Ask another pi session a question and block until it replies (or times out). Before asking, it checks whether that session already sent you something; if so, you are told to read and reply first instead of asking.",
-    promptSnippet: "Ask another pi session a question and wait for the reply",
+      "Ask another pi agent a question and block until it replies (or times out). Before asking, it checks whether that agent already sent you something; if so, you are told to read and reply first instead of asking.",
+    promptSnippet: "Ask another pi agent a question and wait for the reply",
     parameters: Type.Object({
-      to: Type.String({ description: "Target session (name/address/@alias)" }),
+      to: Type.String({ description: "Target agent (name/address/@alias)" }),
       message: Type.String({ description: "The question" }),
       timeoutMs: Type.Optional(
         Type.Number({ description: `Wait cap in ms; default ${ASK_TIMEOUT_MS}` }),
@@ -244,10 +249,10 @@ export default function talk(pi: ExtensionAPI) {
     name: "talk-send",
     label: "Send Talk Message",
     description:
-      "Send a plain-text message to a single pi session. Plain text only, ≤32KB — send a summary and a path, never file contents.",
-    promptSnippet: "Send a message to another pi session",
+      "Send a plain-text message to a single pi agent. Plain text only, ≤32KB — send a summary and a path, never file contents.",
+    promptSnippet: "Send a message to another pi agent",
     parameters: Type.Object({
-      to: Type.String({ description: "Target session id (from talk-list-sessions)" }),
+      to: Type.String({ description: "Target agent id (from talk-list-agents)" }),
       message: Type.String({ description: "Message body" }),
     }),
     async execute(_toolCallId, params) {
@@ -277,7 +282,7 @@ export default function talk(pi: ExtensionAPI) {
   // ── /talk commands ────────────────────────────────────────────────────
 
   pi.registerCommand("talk", {
-    description: "List registered pi sessions",
+    description: "List registered pi agents",
     async handler() {
       const text = requireInit() ?? (await core.list());
       pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
@@ -286,7 +291,7 @@ export default function talk(pi: ExtensionAPI) {
 
   pi.registerCommand("talk-dead", {
     description:
-      "Mark a talk session as dead (shown offline, swept soon): no arg = this session, <sessionId> = that session, --all = every other visible session",
+      "Mark a talk agent as dead (shown offline, swept soon): no arg = this agent, <agentId> = that agent, --all = every other visible agent",
     async handler(args) {
       const initError = requireInit();
       const trimmed = args.trim();
@@ -303,17 +308,21 @@ export default function talk(pi: ExtensionAPI) {
 
   pi.registerCommand("talk-group-join", {
     description:
-      "Join or create a private session group (members see only each other; a session in no group sees only itself). No arg = new group with a generated uuid; <name> = join that group, or create it when it does not exist",
+      "Join or create a private agent group (members see only each other; an agent in no group sees only itself). No arg = new group with a generated uuid; <name> = join that group, or create it when it does not exist; --name <alias> additionally sets this agent's display name (e.g. --name frontend)",
     async handler(args) {
       const initError = requireInit();
-      const token = args.trim();
-      const text = initError ?? (await core.groupJoin(token || undefined));
+      const parsed = parseArgs(args);
+      const groupName = parsed.positionals[0];
+      const flag = parsed.flags.name;
+      const agentName = typeof flag === "string" && flag.trim() !== "" ? flag.trim() : undefined;
+      if (agentName !== undefined) explicitName = agentName;
+      const text = initError ?? (await core.groupJoin(groupName || undefined, agentName));
       pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
     },
   });
 
   pi.registerCommand("talk-group-join-last", {
-    description: "Join the most recently created session group (no-op when already in it).",
+    description: "Join the most recently created agent group (no-op when already in it).",
     async handler() {
       const initError = requireInit();
       const text = initError ?? (await core.groupJoinLast());
@@ -322,7 +331,7 @@ export default function talk(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("talk-group-leave", {
-    description: "Leave the current session group (an emptied group is deleted).",
+    description: "Leave the current agent group (an emptied group is deleted).",
     async handler() {
       const initError = requireInit();
       const text = initError ?? (await core.groupLeave());
@@ -331,7 +340,7 @@ export default function talk(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("talk-group-list", {
-    description: "List all session groups and their members, newest first.",
+    description: "List all agent groups and their members, newest first.",
     async handler() {
       const initError = requireInit();
       const text = initError ?? (await core.groupList());
@@ -341,7 +350,7 @@ export default function talk(pi: ExtensionAPI) {
 
   pi.registerCommand("talk-group-del", {
     description:
-      "Delete a session group by name; its members become ungrouped (see only themselves).",
+      "Delete an agent group by name; its members become ungrouped (see only themselves).",
     async handler(args) {
       const initError = requireInit();
       const name = args.trim();
@@ -352,7 +361,7 @@ export default function talk(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("talk-group-clear", {
-    description: "Delete every session group; all sessions become ungrouped.",
+    description: "Delete every agent group; all agents become ungrouped.",
     async handler() {
       const initError = requireInit();
       const text = initError ?? (await core.groupClear());

package/src/talk/mailbox.ts

@@ -6,7 +6,7 @@
  * - A reader never sees half a letter: writes are atomic (single SQL upsert).
  * - Consumption is decoupled from delivery: `listInbox` only reads; the
  *   caller removes a letter with `removeLetter` AFTER it has been handed to
- *   the session. A letter that could not be delivered stays in the inbox and
+ *   the agent. A letter that could not be delivered stays in the inbox and
  *   is retried on the next poll.
  * - Every value read from storage is validated with a TypeBox schema.
  * - Every deposit and delivery appends one append-only audit line. The log
@@ -27,7 +27,7 @@ export const LetterSchema = Type.Object({
     addr: Type.String(),
     name: Type.String(),
     cwd: Type.String(),
-    sessionId: Type.String(),
+    agentId: Type.String(),
   }),
   kind: Type.Union([
     Type.Literal("message"),
@@ -42,6 +42,25 @@ export const LetterSchema = Type.Object({
 export type Letter = Static<typeof LetterSchema>;
 export type LetterKind = Letter["kind"];
 
+/**
+ * Migrate letters written before the session→agent rename, which carried the
+ * sender's pi session id as `from.sessionId`. Current letters pass through
+ * unchanged; anything else returns null.
+ */
+export function normalizeLetter(value: unknown): Letter | null {
+  if (Value.Check(LetterSchema, value)) return value;
+  const record = value as { from?: unknown } | null;
+  const from = record?.from;
+  if (typeof from !== "object" || from === null) return null;
+  const fromRecord = from as Record<string, unknown>;
+  if (typeof fromRecord.sessionId !== "string") return null;
+  const migrated = {
+    ...(value as object),
+    from: { ...fromRecord, agentId: fromRecord.sessionId },
+  };
+  return Value.Check(LetterSchema, migrated) ? migrated : null;
+}
+
 export const OutAskSchema = Type.Object({
   askId: Type.String(),
   toAddr: Type.String(),
@@ -133,7 +152,8 @@ export async function listInbox(storage: TalkStorage, addr: string): Promise<Inb
   const out: InboxItem[] = [];
   for (const fileName of await storage.listKeys(inboxNs(addr))) {
     const raw = await storage.readJson(inboxNs(addr), fileName);
-    if (isValidLetter(raw)) out.push({ fileName, letter: raw });
+    const letter = normalizeLetter(raw);
+    if (letter && isValidLetter(letter)) out.push({ fileName, letter });
     // corrupt letters are skipped; the caller may remove them separately
   }
   return out; // keys are already sorted by listKeys
@@ -161,7 +181,7 @@ const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
  * Consumption receipt: after depositing to a LIVE target, wait briefly for
  * the exact letter to vanish from the target's inbox. Under the
  * deliver-then-remove semantics, disappearance means the receiver actually
- * handed the letter to its session, not merely drained it.
+ * handed the letter to its agent, not merely drained it.
  */
 export async function awaitReceipt(
   storage: TalkStorage,
@@ -218,7 +238,7 @@ export async function readIncomingAsk(
   askId: string,
 ): Promise<Letter | null> {
   const raw = await storage.readJson(asksNs(addr), askKey(askId));
-  return Value.Check(LetterSchema, raw) ? raw : null;
+  return normalizeLetter(raw);
 }
 
 export async function readOutgoingAsk(
@@ -242,7 +262,8 @@ export async function pendingAsks(storage: TalkStorage, addr: string): Promise<L
   for (const key of await storage.listKeys(asksNs(addr))) {
     if (key.startsWith("out-")) continue;
     const raw = await storage.readJson(asksNs(addr), key);
-    if (Value.Check(LetterSchema, raw)) out.push(raw);
+    const letter = normalizeLetter(raw);
+    if (letter) out.push(letter);
   }
   return out;
 }

package/src/talk/policy.ts

@@ -57,7 +57,7 @@ export class OutboundPolicy {
     if (this.sentAt.length >= RATE_LIMIT_MAX) {
       return {
         ok: false,
-        reason: `Rate limited: ${RATE_LIMIT_MAX} messages per ${RATE_LIMIT_WINDOW_MS / 1000}s per session.`,
+        reason: `Rate limited: ${RATE_LIMIT_MAX} messages per ${RATE_LIMIT_WINDOW_MS / 1000}s per agent.`,
       };
     }
     return { ok: true };

package/src/talk/registry.ts

@@ -1,12 +1,12 @@
 /**
- * Session registry for the talk mailbox: who is around, where, and whether
+ * Agent registry for the talk mailbox: who is around, where, and whether
  * they are reachable. Core layer — depends only on TalkStorage, never on pi.
  *
  * Design:
  * - An address belongs to a conversation, not a process: hash of cwd + pi
- *   session id, so a resumed session (`pi -c`) answers to the same address and
- *   two sessions on one directory never share an inbox.
- * - A record outlives the process that wrote it — that's what makes a session
+ *   agent id, so a resumed agent (`pi -c`) answers to the same address and
+ *   two agents on one directory never share an inbox.
+ * - A record outlives the process that wrote it — that's what makes an agent
  *   addressable while it's down (mail waits on disk).
  * - Presence is the offline flag plus the pid and its start time: a record
  *   whose process is alive (pid + matching start time, ruling out pid reuse)
@@ -26,7 +26,32 @@ import { Value } from "typebox/value";
 
 import type { TalkStorage } from "./storage.js";
 
-export const SessionRecordSchema = Type.Object({
+const STATUS_SCHEMA = Type.Union([
+  Type.Literal("idle"),
+  Type.Literal("working"),
+  Type.Literal("waiting-talk-message"),
+]);
+
+export const AgentRecordSchema = Type.Object({
+  addr: Type.String(),
+  agentId: Type.String(),
+  name: Type.String(),
+  cwd: Type.String(),
+  pid: Type.Number(),
+  pidStart: Type.Optional(Type.Number()),
+  startedAt: Type.Number(),
+  lastSeenAt: Type.Number(),
+  status: STATUS_SCHEMA,
+  offline: Type.Optional(Type.Boolean()),
+});
+export type AgentRecord = Static<typeof AgentRecordSchema>;
+
+/**
+ * Records written before the session→agent rename stored the pi session id
+ * as `sessionId`. TypeBox ignores extra properties, so this schema also
+ * matches current records; the read path checks the current schema first.
+ */
+const LegacyAgentRecordSchema = Type.Object({
   addr: Type.String(),
   sessionId: Type.String(),
   name: Type.String(),
@@ -35,14 +60,9 @@ export const SessionRecordSchema = Type.Object({
   pidStart: Type.Optional(Type.Number()),
   startedAt: Type.Number(),
   lastSeenAt: Type.Number(),
-  status: Type.Union([
-    Type.Literal("idle"),
-    Type.Literal("working"),
-    Type.Literal("waiting-talk-message"),
-  ]),
+  status: STATUS_SCHEMA,
   offline: Type.Optional(Type.Boolean()),
 });
-export type SessionRecord = Static<typeof SessionRecordSchema>;
 
 export type Presence = "live" | "offline";
 
@@ -53,8 +73,8 @@ export const SWEEP_MAIL_KEEP_MS = 30 * 24 * 60 * 60 * 1000;
 
 const ADDRESS_PATTERN = /^[a-f0-9]{12}$/;
 
-export function deriveAddr(cwd: string, sessionId: string): string {
-  return createHash("sha256").update(`${cwd}${sessionId}`).digest("hex").slice(0, 12);
+export function deriveAddr(cwd: string, agentId: string): string {
+  return createHash("sha256").update(`${cwd}${agentId}`).digest("hex").slice(0, 12);
 }
 
 /** Validate a talk address before it becomes a storage key. */
@@ -81,23 +101,26 @@ function recordKey(addr: string): string {
   return `${addr}.json`;
 }
 
-// ── Session records ──────────────────────────────────────────────────────
+// ── Agent records ────────────────────────────────────────────────────────
 
-export async function writeRecord(storage: TalkStorage, record: SessionRecord): Promise<void> {
+export async function writeRecord(storage: TalkStorage, record: AgentRecord): Promise<void> {
   await storage.writeJson(RECORDS_NS, recordKey(record.addr), record);
 }
 
-export async function readRecord(
-  storage: TalkStorage,
-  addr: string,
-): Promise<SessionRecord | null> {
+export async function readRecord(storage: TalkStorage, addr: string): Promise<AgentRecord | null> {
   const raw = await storage.readJson(RECORDS_NS, recordKey(addr));
-  return Value.Check(SessionRecordSchema, raw) ? raw : null;
+  if (Value.Check(AgentRecordSchema, raw)) return raw;
+  // Migrate legacy records in place of the `sessionId` → `agentId` rename.
+  if (Value.Check(LegacyAgentRecordSchema, raw)) {
+    const { sessionId, ...rest } = raw as { sessionId: string } & Record<string, unknown>;
+    return { ...rest, agentId: sessionId } as AgentRecord;
+  }
+  return null;
 }
 
 /** Read-only listing, oldest first. Never mutates anything. */
-export async function listRecords(storage: TalkStorage): Promise<SessionRecord[]> {
-  const out: SessionRecord[] = [];
+export async function listRecords(storage: TalkStorage): Promise<AgentRecord[]> {
+  const out: AgentRecord[] = [];
   for (const key of await storage.listKeys(RECORDS_NS)) {
     const addr = key.slice(0, -".json".length);
     if (!ADDRESS_PATTERN.test(addr)) continue;
@@ -109,7 +132,7 @@ export async function listRecords(storage: TalkStorage): Promise<SessionRecord[]
 
 /**
  * Process start time (field 22 of /proc/<pid>/stat), used to rule out pid
- * reuse: pids wrap around, so an alive pid is only the same session when its
+ * reuse: pids wrap around, so an alive pid is only the same agent when its
  * start time matches the recorded one. Returns undefined on non-Linux or when
  * the stat file is unreadable.
  */
@@ -146,7 +169,7 @@ function pidAlive(pid: number, pidStart?: number): boolean {
   return start === undefined ? true : start === pidStart;
 }
 
-export function presenceOf(record: SessionRecord): Presence {
+export function presenceOf(record: AgentRecord): Presence {
   if (record.offline) return "offline";
   if (!pidAlive(record.pid, record.pidStart)) return "offline";
   return "live";
@@ -155,20 +178,20 @@ export function presenceOf(record: SessionRecord): Presence {
 // ── Sweep ────────────────────────────────────────────────────────────────
 
 /**
- * Reclaim dead sessions' data. Rules (mail outranks tidiness):
+ * Reclaim dead agents' data. Rules (mail outranks tidiness):
  * - a record whose process is still alive is never touched;
  * - a record whose last activity was less than SWEEP_OFFLINE_GRACE_MS ago is
  *   never touched — it may be merely down or suspended, and a resume will
  *   re-register it under the same id anyway;
  * - a mailbox holding undelivered mail is kept for SWEEP_MAIL_KEEP_MS;
  * - once the grace period has passed, an empty mailbox is discarded promptly
- *   regardless of whether pi could still resume the session (resume re-creates
+ *   regardless of whether pi could still resume the agent (resume re-creates
  *   the record; with no mail nothing is lost).
  */
 export async function sweep(storage: TalkStorage, now: number = Date.now()): Promise<void> {
   for (const record of await listRecords(storage)) {
     // Without a heartbeat, lastSeenAt only tracks the last event, so an idle
-    // live session would look long-quiet — never reap a live process.
+    // live agent would look long-quiet — never reap a live process.
     if (pidAlive(record.pid, record.pidStart)) continue;
     const quietFor = now - record.lastSeenAt;
     if (quietFor < SWEEP_OFFLINE_GRACE_MS) continue;

package/src/talk/skills/multi-agent-dev/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: multi-agent-dev
-description: Coordinate multi-agent development across pi sessions using the talk extension. Explains how sessions discover and address each other, when to use talk-send vs talk-ask, and how to split work, exchange information, and review between agents. Use whenever you need to collaborate with other pi sessions or agents on the same machine.
+description: Coordinate multi-agent development across pi agents using the talk extension. Explains how agents discover and address each other, when to use talk-send vs talk-ask, and how to split work, exchange information, and review between agents. Use whenever you need to collaborate with other agents on the same machine.
 ---
 
 # Multi-Agent Development with Talk
 
 ## Concept
 
-Multi-agent development runs several independent pi sessions in parallel and coordinates them over **talk**. Every session is a complete agent workspace — its own cwd, conversation history, and context. Talk lets sessions discover each other, exchange messages, ask questions, and sync progress.
+Multi-agent development runs several independent pi agents in parallel and coordinates them over **talk**. Every agent is a complete workspace — its own cwd, conversation history, and context. Talk lets agents discover each other, exchange messages, ask questions, and sync progress.
 
-The core rule: **a peer only knows what you tell it.** Messages must be self-contained — background, goal, and constraints — because the receiving session has none of your context.
+The core rule: **a peer only knows what you tell it.** Messages must be self-contained — background, goal, and constraints — because the receiving agent has none of your context.
 
-## Session model
+## Agent model
 
 ### Discovery and addressing
 
-- `talk-list-sessions` returns sessions as JSON — **your own session is included and marked `self: true`** (also where you learn your own id):
+- `talk-list-agents` returns agents as JSON — **your own agent is included and marked `self: true`** (also where you learn your own id):
 
   ```json
   [
@@ -29,55 +29,56 @@ The core rule: **a peer only knows what you tell it.** Messages must be self-con
   ]
   ```
 
-- Addressing is **by session id only**: `talk-send` / `talk-ask` take the full `id` (pi session uuid). Names, paths, and prefixes are not accepted.
-- An unknown or invisible target is refused with `Unknown session id` — always list before sending.
+- Addressing is **by agent id only**: `talk-send` / `talk-ask` take the full `id` (pi agent uuid). Names, paths, and prefixes are not accepted.
+- An unknown or invisible target is refused with `Unknown agent id` — always list before sending.
 
 ### Status
 
 - `idle` / `working` (agent actively running) / `waiting-talk-message` (blocked in `talk-ask` waiting for a reply)
 - `offline` (process exited or marked dead)
-- `talk-list-sessions` lists every visible session — live or offline — with its current status.
+- `talk-list-agents` lists every visible agent — live or offline — with its current status.
 
 ### Visibility
 
-- Visibility is fully group-driven: a session in a group sees only its co-members; a session in no group sees only itself. Ungrouped sessions are invisible to everyone.
+- Visibility is fully group-driven: an agent in a group sees only its co-members; an agent in no group sees only itself. Ungrouped agents are invisible to everyone.
 - Groups are managed by the user from the TUI (`/talk-group-*` commands) — you cannot create, join, or leave a group yourself.
-- If a session you need to collaborate with is missing from `talk-list-sessions`, ask the user to pair the sessions into the same group.
+- When the user joins a group they can tag their agent with a display name via `/talk-group-join <group> --name <alias>` (e.g. `frontend`, `backend`). That alias is what peers see as `name` in `talk-list-agents` — prefer it over the raw agent id when describing who is who.
+- If an agent you need to collaborate with is missing from `talk-list-agents`, ask the user to pair the agents into the same group.
 
 ## Tools
 
-| Tool                 | Purpose                                                                                                                |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `talk-list-sessions` | List visible sessions (`id` / `status` / `work_dir` / `name`); only group co-members (or only yourself when ungrouped) |
-| `talk-send`          | Send a plain message to a single session id (async — the main collaboration primitive)                                 |
-| `talk-ask`           | Ask a question and block for the reply (default 30 min timeout)                                                        |
-| `talk-reply`         | Reply to a received ask; `replyTo` is the ask id shown in the delivered message                                        |
+| Tool               | Purpose                                                                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `talk-list-agents` | List visible agents (`id` / `status` / `work_dir` / `name`); only group co-members (or only yourself when ungrouped) |
+| `talk-send`        | Send a plain message to a single agent id (async — the main collaboration primitive)                                 |
+| `talk-ask`         | Ask a question and block for the reply (default 30 min timeout)                                                      |
+| `talk-reply`       | Reply to a received ask; `replyTo` is the ask id shown in the delivered message                                      |
 
-Pairing into groups is a user action (`/talk-group-*` in the TUI); you only observe its effect through `talk-list-sessions`.
+Pairing into groups is a user action (`/talk-group-*` in the TUI); you only observe its effect through `talk-list-agents`.
 
 ## Collaboration workflows
 
-### Split work between sessions
+### Split work between agents
 
-1. `talk-list-sessions` first: see which co-members exist, their `work_dir`, and status. If only yourself shows up, the peer sessions are not in your group yet — ask the user to pair them.
+1. `talk-list-agents` first: see which co-members exist, their `work_dir`, and status. If only yourself shows up, the peer agents are not in your group yet — ask the user to pair them.
 2. Assign work by module/files with `talk-send` — state the scope, boundaries, and expected output.
-3. Each session completes its slice, then sends the result or a review request.
+3. Each agent completes its slice, then sends the result or a review request.
 4. Sync progress periodically to avoid overlapping edits.
 
 ### Synchronous question/answer (need the answer to continue)
 
 - Use `talk-ask` when the next step depends on the peer's information and the peer is reachable.
 - On receiving an ask, reply with `talk-reply` using the `replyTo` id from the delivered message.
-- If two sessions ask each other simultaneously: the later asker yields — answer the peer's ask first, then re-ask.
+- If two agents ask each other simultaneously: the later asker yields — answer the peer's ask first, then re-ask.
 
 ### Async notifications
 
 - Use `talk-send` for heads-ups that do not block: send and keep working.
 - Messages deliver on the next natural turn by default (`queue`); `steer` interrupts the peer immediately — behavior depends on the `talk.deliver` setting.
 
-### Cross-session review
+### Cross-agent review
 
-- Ask another session to review your changes: `talk-send` the file paths plus a diff summary, request a review, and let it reply.
+- Ask another agent to review your changes: `talk-send` the file paths plus a diff summary, request a review, and let it reply.
 - Send paths and summaries, not whole file contents — the peer can `read` them itself.
 
 ## Message style
@@ -91,6 +92,6 @@ Pairing into groups is a user action (`/talk-group-*` in the TUI); you only obse
 ## Pitfalls
 
 - **Avoid message loops**: if the peer sent you something or is asking you, answer it before sending new ones. Two agents pinging each other deadlock.
-- **Address from known ids**: only run `talk-list-sessions` to discover sessions or verify an id. If you already hold a valid id (e.g. from an incoming message or a previous listing), send directly — an unknown or invisible id is refused with `Unknown session id`.
-- **Respect status**: asking an offline session blocks until the 30 min timeout. Prefer `talk-send` there — the message queues on disk and the peer receives it when it resumes.
-- **Visibility boundary**: you can only collaborate with sessions that share your group; ungrouped sessions and other groups' members are unreachable by design. Ask the user to pair sessions before collaborating.
+- **Address from known ids**: only run `talk-list-agents` to discover agents or verify an id. If you already hold a valid id (e.g. from an incoming message or a previous listing), send directly — an unknown or invisible id is refused with `Unknown agent id`.
+- **Respect status**: asking an offline agent blocks until the 30 min timeout. Prefer `talk-send` there — the message queues on disk and the peer receives it when it resumes.
+- **Visibility boundary**: you can only collaborate with agents that share your group; ungrouped agents and other groups' members are unreachable by design. Ask the user to pair agents before collaborating.

package/src/talk/storage.ts

@@ -45,7 +45,7 @@ export interface TalkStorage {
  * SQLite backend (Node's built-in `node:sqlite`, no npm dependency).
  *
  * A single database file holds everything; WAL mode plus a busy timeout lets
- * multiple pi sessions read and write it concurrently. SQL parameter binding
+ * multiple pi agents read and write it concurrently. SQL parameter binding
  * removes the need for path/symlink hardening entirely.
  *
  * The backend is synchronous; each method wraps its result in a resolved