@trim21/personal-pi-extensions 0.0.206 → 0.0.209

package/src/talk/index.ts

@@ -18,12 +18,12 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import { jsoncToJson } from "../lib/jsonc.js";
+import { parseArgs } from "../lib/cli-args.js";
 import { resolveHomePath } from "../lib/path.js";
-import { buildVisibilityFilter, TalkCore } from "./core.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";
@@ -103,41 +103,22 @@ function readTalkSettings(): { dbPath?: string; deliver?: "steer" | "queue" } {
   }
 }
 
-/**
- * Read the workspace visibility config from `<cwd>/.pi/talk.json`:
- * `{ "allowed": ["~/projects/company1/"] }`. Missing file/key → undefined
- * (everything visible); an explicit `"allowed": []` hides every peer.
- */
-function readWorkspaceTalkConfig(cwd: string): { allowed?: string[] } {
-  const configPath = path.join(cwd, ".pi", "talk.json");
-  try {
-    const raw = fs.readFileSync(configPath, "utf8");
-    const parsed = JSON.parse(jsoncToJson(raw)) as { allowed?: unknown };
-    if (Array.isArray(parsed.allowed)) {
-      return { allowed: parsed.allowed.filter((p): p is string => typeof p === "string") };
-    }
-    return {};
-  } catch (error) {
-    // eslint-disable-next-line no-console -- config errors must be visible, not silent
-    console.error(`Warning: could not parse ${configPath}: ${String(error)}`);
-    return {};
-  }
-}
-
 export default function talk(pi: ExtensionAPI) {
   const settings = readTalkSettings();
   const configured = process.env.PI_TALK_DB ?? settings.dbPath;
   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,
@@ -164,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.
@@ -184,20 +165,19 @@ 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,
       lastSeenAt: now,
       status: "idle",
     };
-    core.setPeerVisibility(buildVisibilityFilter(readWorkspaceTalkConfig(cwd).allowed, cwd));
     void core.start(self);
   });
 
@@ -205,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();
@@ -222,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();
@@ -240,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}` }),
@@ -267,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) {
@@ -300,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 });
@@ -309,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();
@@ -324,6 +306,69 @@ export default function talk(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("talk-group-join", {
+    description:
+      "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 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 agent group (no-op when already in it).",
+    async handler() {
+      const initError = requireInit();
+      const text = initError ?? (await core.groupJoinLast());
+      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
+    },
+  });
+
+  pi.registerCommand("talk-group-leave", {
+    description: "Leave the current agent group (an emptied group is deleted).",
+    async handler() {
+      const initError = requireInit();
+      const text = initError ?? (await core.groupLeave());
+      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
+    },
+  });
+
+  pi.registerCommand("talk-group-list", {
+    description: "List all agent groups and their members, newest first.",
+    async handler() {
+      const initError = requireInit();
+      const text = initError ?? (await core.groupList());
+      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
+    },
+  });
+
+  pi.registerCommand("talk-group-del", {
+    description:
+      "Delete an agent group by name; its members become ungrouped (see only themselves).",
+    async handler(args) {
+      const initError = requireInit();
+      const name = args.trim();
+      const text =
+        initError ?? (name ? await core.groupDelete(name) : "Usage: /talk-group-del <group name>");
+      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
+    },
+  });
+
+  pi.registerCommand("talk-group-clear", {
+    description: "Delete every agent group; all agents become ungrouped.",
+    async handler() {
+      const initError = requireInit();
+      const text = initError ?? (await core.groupClear());
+      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
+    },
+  });
+
   // ── Delivery card ──────────────────────────────────────────────────────
 
   pi.registerMessageRenderer<DeliveryDetails>(DELIVERY_TYPE, (message, _options, theme) => {

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,54 +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
 
-- Each workspace controls what it can see via `allowed` in `<cwd>/.pi/talk.json` (path prefixes). Sessions outside the prefixes are neither listed nor addressable.
-- Visibility is one-way: you seeing a session does not mean it sees you.
+- 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.
+- 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`)                          |
-| `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                                      |
 
-In the TUI: `/talk` lists sessions, `/talk-dead` marks a session as dead (shown offline, swept soon).
+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 sessions exist, their `work_dir`, and status.
+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
@@ -90,6 +92,6 @@ In the TUI: `/talk` lists sessions, `/talk-dead` marks a session as dead (shown
 ## 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 you can see; invisible sessions are unreachable by design.
+- **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

@@ -16,6 +16,8 @@
  * blindly cast.
  */
 
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
 export interface TalkStorage {
@@ -43,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
@@ -53,6 +55,10 @@ export class SqliteTalkStorage implements TalkStorage {
   private readonly db: DatabaseSync;
 
   constructor(dbPath: string) {
+    // A custom db_path may point into a directory that does not exist yet
+    // (e.g. "~/data/talk.db"); sqlite refuses to open it, so create the
+    // parent directory first.
+    mkdirSync(dirname(dbPath), { recursive: true });
     this.db = new DatabaseSync(dbPath);
     this.db.exec("PRAGMA journal_mode = WAL");
     this.db.exec("PRAGMA busy_timeout = 5000");