@trim21/personal-pi-extensions 0.0.208 → 0.0.210

package/src/talk/index.ts

@@ -16,13 +16,14 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
+import { type TObject, Type } from "typebox";
 
+import { type CommandResult, type CommandSpec, parseCommand } from "../lib/cli.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) {
@@ -276,88 +281,155 @@ export default function talk(pi: ExtensionAPI) {
 
   // ── /talk commands ────────────────────────────────────────────────────
 
-  pi.registerCommand("talk", {
-    description: "List registered pi sessions",
-    async handler() {
-      const text = requireInit() ?? (await core.list());
+  type OkResult<TFlags extends TObject> = Extract<CommandResult<TFlags>, { kind: "ok" }>;
+
+  /** Parse a /talk command; on help/error or init failure the text is sent, otherwise run() produces the listing text. */
+  function handleCommand<TFlags extends TObject>(
+    spec: CommandSpec<TFlags>,
+    args: string,
+    run: (parsed: OkResult<TFlags>) => Promise<string> | string,
+  ): Promise<void> {
+    const parsed = parseCommand(spec, args);
+    if (parsed.kind !== "ok") {
+      pi.sendMessage({ customType: LIST_TYPE, content: parsed.text, display: true });
+      return Promise.resolve();
+    }
+    return (async () => {
+      const initError = requireInit();
+      const text = initError ?? (await run(parsed));
       pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    })();
+  }
+
+  const TALK_SPEC = {
+    name: "talk",
+    usage: "",
+    description: "List registered pi agents",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_DEAD_SPEC = {
+    name: "talk-dead",
+    usage: "[agentId] [options]",
+    description:
+      "Mark a talk agent as dead (shown offline, swept soon): no arg = this agent, <agentId> = that agent, --all = every other visible agent",
+    flags: Type.Object({
+      all: Type.Optional(Type.Boolean({ description: "Mark every other visible agent dead" })),
+    }),
+    flagMeta: { all: { short: "a" } },
+    arity: { max: 1 },
+  };
+
+  const TALK_GROUP_JOIN_SPEC = {
+    name: "talk-group-join",
+    usage: "[group name] [options]",
+    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",
+    flags: Type.Object({
+      name: Type.Optional(Type.String({ description: "Set this agent's display name" })),
+    }),
+    flagMeta: { name: { short: "n", valuePlaceholder: "<alias>" } },
+    arity: { max: 1 },
+    examples: ["/talk-group-join frontend", "/talk-group-join --name frontend"],
+  };
+
+  const TALK_GROUP_JOIN_LAST_SPEC = {
+    name: "talk-group-join-last",
+    usage: "",
+    description: "Join the most recently created agent group (no-op when already in it).",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_LEAVE_SPEC = {
+    name: "talk-group-leave",
+    usage: "",
+    description: "Leave the current agent group (an emptied group is deleted).",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_LIST_SPEC = {
+    name: "talk-group-list",
+    usage: "",
+    description: "List all agent groups and their members, newest first.",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_DEL_SPEC = {
+    name: "talk-group-del",
+    usage: "<group name>",
+    description:
+      "Delete an agent group by name; its members become ungrouped (see only themselves).",
+    flags: Type.Object({}),
+    arity: { min: 1, max: 1 },
+  };
+
+  const TALK_GROUP_CLEAR_SPEC = {
+    name: "talk-group-clear",
+    usage: "",
+    description: "Delete every agent group; all agents become ungrouped.",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  pi.registerCommand("talk", {
+    description: TALK_SPEC.description,
+    handler: (args) => handleCommand(TALK_SPEC, args, async () => core.list()),
   });
 
   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",
-    async handler(args) {
-      const initError = requireInit();
-      const trimmed = args.trim();
-      const text =
-        initError ??
-        (trimmed === "--all"
+    description: TALK_DEAD_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_DEAD_SPEC, args, async (parsed) => {
+        if (parsed.flags.all && parsed.args.length > 0) {
+          return "--all cannot be combined with an agent id.\nTry '/talk-dead --help' for usage.";
+        }
+        return parsed.flags.all
           ? await core.markAllDead()
-          : trimmed
-            ? await core.markDead(trimmed)
-            : await core.markDead());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+          : parsed.args[0]
+            ? await core.markDead(parsed.args[0])
+            : await core.markDead();
+      }),
   });
 
   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",
-    async handler(args) {
-      const initError = requireInit();
-      const token = args.trim();
-      const text = initError ?? (await core.groupJoin(token || undefined));
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_JOIN_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_JOIN_SPEC, args, async (parsed) => {
+        const agentName = parsed.flags.name?.trim() || undefined;
+        if (agentName !== undefined) explicitName = agentName;
+        return core.groupJoin(parsed.args[0], agentName);
+      }),
   });
 
   pi.registerCommand("talk-group-join-last", {
-    description: "Join the most recently created session 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 });
-    },
+    description: TALK_GROUP_JOIN_LAST_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_JOIN_LAST_SPEC, args, async () => core.groupJoinLast()),
   });
 
   pi.registerCommand("talk-group-leave", {
-    description: "Leave the current session 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 });
-    },
+    description: TALK_GROUP_LEAVE_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_LEAVE_SPEC, args, async () => core.groupLeave()),
   });
 
   pi.registerCommand("talk-group-list", {
-    description: "List all session 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 });
-    },
+    description: TALK_GROUP_LIST_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_LIST_SPEC, args, async () => core.groupList()),
   });
 
   pi.registerCommand("talk-group-del", {
-    description:
-      "Delete a session 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 });
-    },
+    description: TALK_GROUP_DEL_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_DEL_SPEC, args, async (parsed) => core.groupDelete(parsed.args[0])),
   });
 
   pi.registerCommand("talk-group-clear", {
-    description: "Delete every session group; all sessions become ungrouped.",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupClear());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_CLEAR_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_CLEAR_SPEC, args, async () => core.groupClear()),
   });
 
   // ── Delivery card ──────────────────────────────────────────────────────

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;