@trim21/personal-pi-extensions 0.0.202 → 0.0.204

package/README.md

@@ -230,23 +230,23 @@ index.ts     —— pi adapter：把 core 接到 pi 的 sendMessage / 生命周
 
 ### 工具（LLM 可见）
 
-| 工具                 | 作用                                                                                                                       |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `talk-list-sessions` | 列出其他 session，返回 JSON 数组（`status` / `work_dir` / `id` / `name`）；默认只列有心跳的，`includeOffline: true` 列全部 |
-| `talk-ask`           | 向某个 session 提问并阻塞等待回复（默认 30 分钟超时）                                                                      |
-| `talk-send`          | 发送纯文本消息（`to: "*"` 广播所有，`to: "cwd"` 广播同 cwd）                                                               |
-| `talk-reply`         | 回复一个 ask（`replyTo` 为 ask id，显式关联、不推断）                                                                      |
+| 工具                 | 作用                                                                                                                                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `talk-list-sessions` | 列出会话，返回 JSON 数组（`status` / `work_dir` / `id` / `name`，自己带 `self: true`）；始终列出所有可见会话，`status` 区分 live（`idle` / `working` / `waiting-talk-message`）与 `offline` |
+| `talk-ask`           | 向某个 session 提问并阻塞等待回复（默认 30 分钟超时）                                                                                                                                       |
+| `talk-send`          | 发送纯文本消息到单个 session（`to` 只接受明确的 session id，不支持广播）                                                                                                                    |
+| `talk-reply`         | 回复一个 ask（`replyTo` 为 ask id，显式关联、不推断）                                                                                                                                       |
 
 对端消息自动投递（无需主动拉取）：投递方式由 `talk.deliver` 配置，`steer` 在模型工作过程中打断/唤醒，`queue` 排队到 session 下一轮自然 turn 时注入。
 
 **定位只认 session id**：`talk-send` / `talk-ask` / `talk-watch` 的 `to` 只接受 `talk-list-sessions` 返回的 `id`（pi 的 session uuid）精确匹配，不做 name/路径/前缀匹配。
 
-**标记废弃 session**：`/talk-dead` 把 session 的 `lastSeenAt` 置 0（从默认列表消失，下次 sweep 无 mail 即回收）：无参标记当前 session（同时停止其心跳），`/talk-dead <sessionId>` 标记指定 session，`/talk-dead --all` 标记所有其他可见 session。
+**标记废弃 session**：`/talk-dead` 给 session 打 `offline` 标志并把 `lastSeenAt` 置 0（列表显示为 offline，下次 sweep 无 mail 即回收）：无参标记当前 session，`/talk-dead <sessionId>` 标记指定 session，`/talk-dead --all` 标记所有其他可见 session。
 
 ### 关键设计
 
-- **心跳即活跃**：每个 session 每 15s 写一次 `lastSeenAt`；`talk-list-sessions` 默认只显示最近 15 分钟内有心跳的 session，已结束/挂起的 session 自动从默认列表消失（`includeOffline: true` 可见全部）。`status` 用 45s 心跳阈值区分 live / not responding / offline，并显示 `working` / `waiting-talk-message`（`talk-ask` 阻塞等待回复中）/ `idle`。
-- **定期清理**：心跳停止超过 24h 且无未投递 mail 的记录会被定期 sweep（30 分钟一次）回收；有 mail 的保留 30 天。resume 后 session 会自动重新注册，无 mail 即无损失。
+- **presence 不靠心跳**：presence 由 `offline` 标志 + 进程 pid 存活判定；pid 存活时还校验进程启动时间（`/proc/<pid>/stat`），排除 pid 回卷复用造成的误判。未标记 offline 且进程存活即 live，否则 offline；没有心跳，进程挂死（wedged）与健康空闲不可区分。`status` 在 live 时显示 `working` / `waiting-talk-message`（`talk-ask` 阻塞等待回复中）/ `idle`。
+- **定期清理**：进程仍存活的记录永不回收；进程已死且最后活跃超过 24h 且无未投递 mail 的记录会被定期 sweep（30 分钟一次）回收；有 mail 的保留 30 天。resume 后 session 会自动重新注册，无 mail 即无损失。
 - **投递成功才消费**：信件只在成功交给 `sendMessage` 后才从 inbox 删除，投递失败留在 inbox 下次重试——不会因 `sendMessage` 吞异常而静默丢信。
 - **双向 ask 仲裁**：`talk-ask` 发起前先检查收件箱（有对方消息就先读/先回）；阻塞等待期间若收到对方的 ask（而非 reply），按两个 ask 的 `ts` 字段仲裁——先 ask 者主导继续等，后 ask 者让位并先回复对方。`ts` 是信件内固定字段，双方读到同一对值，结论天然对称；同毫秒碰撞用 `session dir + session id` 字符串比较兜底。
 - **typebox runtime 验证**：所有从存储读出的值经 TypeBox schema 校验，损坏/伪造数据被拒绝，不做 `as T` 强转。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.202",
+  "version": "0.0.204",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -67,6 +67,9 @@
       "src/opencode-todo.ts",
       "src/question.ts",
       "src/talk/index.ts"
+    ],
+    "skills": [
+      "src/talk/skills"
     ]
   },
   "lint-staged": {

package/src/talk/core.ts

@@ -34,11 +34,11 @@ import {
 } from "./mailbox.js";
 import { inboundAccepts, OutboundPolicy } from "./policy.js";
 import {
-  LIST_ACTIVE_MS,
   listRecords,
   type Presence,
   presenceOf,
   readRecord,
+  readStartTime,
   type SessionRecord,
   sweep,
   writeRecord,
@@ -64,7 +64,6 @@ export interface TalkCoreOptions {
 }
 
 const INBOX_POLL_MS = 3000;
-const HEARTBEAT_MS = 15_000;
 const WATCH_POLL_MS = 5000;
 const DELIVERY_BACKOFF_MS = 5000;
 const INITIAL_DRAIN_DELAY_MS = 1200;
@@ -124,11 +123,10 @@ export class TalkCore {
   private readonly deliveredIds = new Set<string>();
   /** Visibility gate over peer working directories; defaults to everything visible. */
   private isPeerVisible: (peerCwd: string) => boolean = () => true;
-  /** Manually marked dead: heartbeat stopped, lastSeenAt pinned to 0. */
+  /** Manually marked dead: offline flag set, lastSeenAt pinned to 0. */
   private dead = false;
 
   private inboxPoll: ReturnType<typeof setInterval> | undefined;
-  private heartbeat: ReturnType<typeof setInterval> | undefined;
   private watchPoller: ReturnType<typeof setInterval> | undefined;
   private sweeper: ReturnType<typeof setInterval> | undefined;
   private lastDeliveryFailureAt = 0;
@@ -158,18 +156,16 @@ export class TalkCore {
 
   async start(self: SessionRecord): Promise<void> {
     await this.storage.init();
-    this.self = self;
-    await writeRecord(this.storage, self);
+    // Record the process start time so presence can rule out pid reuse later.
+    const pidStart = readStartTime(self.pid);
+    this.self = pidStart === undefined ? self : { ...self, pidStart };
+    await writeRecord(this.storage, this.self);
     try {
       await sweep(this.storage, this.now());
     } catch {
       // sweep failure never breaks the session
     }
     this.startInboxPoll();
-    this.heartbeat = setInterval(() => {
-      void this.writeSelf({});
-    }, HEARTBEAT_MS);
-    this.heartbeat.unref();
     // Reclaim dead records periodically, not just at startup.
     this.sweeper = setInterval(() => {
       void sweep(this.storage, this.now());
@@ -184,7 +180,6 @@ export class TalkCore {
   }
 
   async stop(): Promise<void> {
-    if (this.heartbeat) clearInterval(this.heartbeat);
     if (this.watchPoller) clearInterval(this.watchPoller);
     if (this.inboxPoll) clearInterval(this.inboxPoll);
     if (this.sweeper) clearInterval(this.sweeper);
@@ -221,7 +216,7 @@ export class TalkCore {
     try {
       await writeRecord(this.storage, this.self);
     } catch {
-      // heartbeat/registration failures never break the session
+      // registration failures never break the session
     }
   }
 
@@ -375,7 +370,7 @@ export class TalkCore {
     return {
       ok: true,
       letter,
-      verdict: `queued (target ${presence === "stalled" ? "is not responding" : "is offline"} — waits on disk)`,
+      verdict: `queued (target is offline — waits on disk)`,
     };
   }
 
@@ -441,7 +436,7 @@ export class TalkCore {
     this.askWaiters.delete(myAsk.askId);
     waiter({
       replied: false,
-      reason: `peer asked first (their ask id ${letter.id.slice(0, 8)}) — answer it with talk-reply before re-asking`,
+      reason: `peer asked first (their ask id ${letter.id.slice(-8)}) — answer it with talk-reply before re-asking`,
     });
     await clearAsk(this.storage, self.addr, myAsk.askId);
   }
@@ -449,32 +444,30 @@ export class TalkCore {
   // ── Tool actions ───────────────────────────────────────────────────────
 
   /**
-   * JSON listing of visible peer sessions. Defaults to sessions whose
-   * heartbeat is fresh (within LIST_ACTIVE_MS); pass includeOffline to show
-   * every visible peer regardless of last contact.
+   * JSON listing of visible sessions, including self (marked `self: true`).
+   * Every visible record is listed, live or offline; presence decides the
+   * per-session status.
    */
-  async list(includeOffline = false): Promise<string> {
+  async list(): Promise<string> {
     const self = this.requireSelf();
-    const now = this.now();
     const all = await listRecords(this.storage);
-    const records = all.filter(
-      (r) => this.isPeerVisible(r.cwd) && (includeOffline || now - r.lastSeenAt < LIST_ACTIVE_MS),
-    );
-    return formatListing(records, self.addr, (r) => presenceOf(r, now));
+    const records = all.filter((r) => {
+      if (r.addr === self.addr) return !this.dead;
+      return this.isPeerVisible(r.cwd);
+    });
+    return formatListing(records, self.addr, presenceOf);
   }
 
   /** Same as list(), filtered to one working directory. */
-  async listCwd(cwd: string, includeOffline = false): Promise<string> {
+  async listCwd(cwd: string): Promise<string> {
     const self = this.requireSelf();
-    const now = this.now();
     const records = await listRecords(this.storage);
-    const filtered = records.filter(
-      (r) =>
-        r.cwd === cwd &&
-        this.isPeerVisible(r.cwd) &&
-        (includeOffline || now - r.lastSeenAt < LIST_ACTIVE_MS),
-    );
-    return formatListing(filtered, self.addr, (r) => presenceOf(r, now));
+    const filtered = records.filter((r) => {
+      if (r.cwd !== cwd) return false;
+      if (r.addr === self.addr) return !this.dead;
+      return this.isPeerVisible(r.cwd);
+    });
+    return formatListing(filtered, self.addr, presenceOf);
   }
 
   /** Visible peer records (excluding self), e.g. for command completions. */
@@ -485,24 +478,20 @@ export class TalkCore {
   }
 
   /**
-   * Mark a session as dead by pinning lastSeenAt to 0: it vanishes from the
-   * default listing and the next sweep reaps it (empty mailbox). Without a
-   * target, marks this session — its heartbeat is stopped and later
-   * writeSelf calls no longer refresh lastSeenAt.
+   * Mark a session 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
+   * record stays offline for peers.
    */
   async markDead(target?: string): Promise<string> {
     if (!target) {
       this.dead = true;
-      if (this.heartbeat) {
-        clearInterval(this.heartbeat);
-        this.heartbeat = undefined;
-      }
-      await this.writeSelf({});
+      await this.writeSelf({ offline: true });
       return "Marked this session as dead.";
     }
     const resolved = await this.resolveTarget(target);
     if (!resolved.ok) return resolved.error;
-    await writeRecord(this.storage, { ...resolved.record, lastSeenAt: 0 });
+    await writeRecord(this.storage, { ...resolved.record, lastSeenAt: 0, offline: true });
     return `Marked "${resolved.record.name}" as dead.`;
   }
 
@@ -510,7 +499,7 @@ export class TalkCore {
   async markAllDead(): Promise<string> {
     const peers = await this.listPeers();
     for (const peer of peers) {
-      await writeRecord(this.storage, { ...peer, lastSeenAt: 0 });
+      await writeRecord(this.storage, { ...peer, lastSeenAt: 0, offline: true });
     }
     return `Marked ${peers.length} session(s) as dead.`;
   }
@@ -518,40 +507,21 @@ export class TalkCore {
   async send(to: string, body: string): Promise<string> {
     if (!to) return 'send requires "to".';
     if (!body) return 'send requires "message".';
-    const self = this.requireSelf();
-    // Broadcast: N atomic deposits through the existing deposit path so
-    // rate/dedupe caps still bind (per-peer dedupe; rate caps total fan-out).
     if (to === "*" || to === "cwd") {
-      const records = await listRecords(this.storage);
-      const peers = records.filter((r) => {
-        if (r.addr === self.addr) return false;
-        if (!this.isPeerVisible(r.cwd)) return false;
-        return to === "*" ? true : r.cwd === self.cwd;
-      });
-      if (peers.length === 0) return "No other sessions to broadcast to.";
-      const ok: string[] = [];
-      const failed: string[] = [];
-      for (const peer of peers) {
-        const sent = await this.sendLetter(peer, "message", body);
-        if (sent.ok) ok.push(`"${peer.name}"`);
-        else failed.push(`"${peer.name}": ${sent.error}`);
-      }
-      const head = `Broadcast to ${ok.length}/${peers.length} session${peers.length === 1 ? "" : "s"}.`;
-      const detail = failed.length > 0 ? ` Refused: ${failed.join("; ")}.` : "";
-      return head + detail;
+      return "send requires a single session id; broadcasting is disabled.";
     }
     const resolved = await this.resolveTarget(to);
     if (!resolved.ok) return resolved.error;
     const sent = await this.sendLetter(resolved.record, "message", body);
     if (!sent.ok) return sent.error;
-    return `Sent to "${resolved.record.name}" (${shortAddr(resolved.record.addr)}) [id ${sent.letter.id.slice(0, 8)}]: ${sent.verdict}.`;
+    return `Sent to "${resolved.record.name}" (${shortAddr(resolved.record.addr)}) [id ${sent.letter.id.slice(-8)}]: ${sent.verdict}.`;
   }
 
   async ask(to: string, body: string, timeoutMs: number, signal?: AbortSignal): Promise<string> {
     if (!to) return 'ask requires "to".';
     if (!body) return 'ask requires "message".';
     if (to === "*" || to === "cwd") {
-      return 'ask is 1:1 and cannot broadcast; use send with to: "*" or "cwd".';
+      return "ask is 1:1 and cannot broadcast.";
     }
     const self = this.requireSelf();
     const resolved = await this.resolveTarget(to);
@@ -578,7 +548,7 @@ export class TalkCore {
       const outcome = await this.waitForReply(sent.letter.id, Math.max(1000, timeoutMs), signal);
       await clearAsk(this.storage, self.addr, sent.letter.id);
       if (!outcome.replied)
-        return `Ask ${sent.letter.id.slice(0, 8)} to "${record.name}": ${outcome.reason}.`;
+        return `Ask ${sent.letter.id.slice(-8)} to "${record.name}": ${outcome.reason}.`;
       return `"${record.name}" replied:\n\n${outcome.body}`;
     } finally {
       // The ask tool call is still part of a running agent turn.
@@ -600,7 +570,7 @@ export class TalkCore {
     const sent = await this.sendLetter(target, "reply", body, ask.id);
     if (!sent.ok) return sent.error;
     await clearAsk(this.storage, self.addr, ask.id);
-    return `Replied to "${target.name}" (ask ${ask.id.slice(0, 8)}): ${sent.verdict}.`;
+    return `Replied to "${target.name}" (ask ${ask.id.slice(-8)}): ${sent.verdict}.`;
   }
 
   /** Build a minimal record from a letter's sender when the peer record is gone. */
@@ -644,8 +614,7 @@ export class TalkCore {
       if (now === prev) continue;
       this.watched.set(addr, now);
       const label = rec ? `"${rec.name}"` : shortAddr(addr);
-      const state =
-        now === "live" ? (rec?.status ?? "idle") : now === "stalled" ? "not responding" : "offline";
+      const state = now === "live" ? (rec?.status ?? "idle") : "offline";
       this.events.notify(`talk watch: ${label} is now ${state}.`);
     }
   }

package/src/talk/format.ts

@@ -31,27 +31,30 @@ export function formatDelivery(letter: Letter, now: number = Date.now()): string
   return `${BOUNDARY_PREAMBLE}\n\n${header}:\n\n${letter.body}\n\n${meta}${hint}`;
 }
 
-/** One peer 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. */
+/** 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 {
   status: string;
   work_dir: string;
   id: string;
   name?: string;
+  self?: boolean;
 }
 
-/** Machine-readable JSON listing of peer sessions (what the model sees). */
+/** Machine-readable JSON listing of sessions (what the model sees). */
 export function formatListing(
   records: SessionRecord[],
   selfAddr: string,
   presence: (r: SessionRecord) => Presence,
 ): string {
-  const others = records.filter((r) => r.addr !== selfAddr);
-  if (others.length === 0) return "[]";
-  const items: SessionListItem[] = others.map((r) => {
+  if (records.length === 0) return "[]";
+  const items: SessionListItem[] = records.map((r) => {
     const p = presence(r);
-    const status = p === "live" ? r.status : p === "stalled" ? "not responding" : "offline";
-    return { status, work_dir: r.cwd, id: r.sessionId, name: r.name };
+    const status = p === "live" ? r.status : "offline";
+    const item: SessionListItem = { status, work_dir: r.cwd, id: r.sessionId, name: r.name };
+    if (r.addr === selfAddr) item.self = true;
+    return item;
   });
   return JSON.stringify(items, null, 2);
 }

package/src/talk/index.ts

@@ -11,6 +11,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
@@ -31,6 +32,9 @@ const NOTIFY_TYPE = "talk:notify";
 
 const ASK_TIMEOUT_MS = 30 * 60 * 1000;
 
+/** Guide the model to the multi-agent workflow skill shipped with this package. */
+const SKILL_PATH = fileURLToPath(new URL("skills/multi-agent-dev/SKILL.md", import.meta.url));
+
 function toolResult(text: string) {
   return { content: [{ type: "text" as const, text }], details: {} };
 }
@@ -200,6 +204,14 @@ export default function talk(pi: ExtensionAPI) {
   pi.on("agent_start", () => core.setWorking());
   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
+    // 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.`,
+    };
+  });
   pi.on("session_info_changed", () => {
     if (self) core.setSessionName(pi.getSessionName() ?? self.name);
   });
@@ -212,24 +224,15 @@ export default function talk(pi: ExtensionAPI) {
   pi.registerTool({
     name: "talk-list-sessions",
     label: "List Talk Sessions",
-    description:
-      "List other pi sessions with a recent heartbeat (id, status, work_dir, name). Pass includeOffline to also list stale sessions.",
+    description: "List visible pi sessions (id, status, work_dir, name).",
     promptSnippet: "List other pi sessions on this machine",
     parameters: Type.Object({
       cwd: Type.Optional(Type.String({ description: "Only list sessions in this directory" })),
-      includeOffline: Type.Optional(
-        Type.Boolean({ description: "Include sessions without a recent heartbeat" }),
-      ),
     }),
     async execute(_toolCallId, params) {
       const initError = requireInit();
       if (initError) return toolResult(initError);
-      const includeOffline = params.includeOffline === true;
-      return toolResult(
-        params.cwd
-          ? await core.listCwd(params.cwd, includeOffline)
-          : await core.list(includeOffline),
-      );
+      return toolResult(params.cwd ? await core.listCwd(params.cwd) : await core.list());
     },
   });
 
@@ -264,12 +267,10 @@ export default function talk(pi: ExtensionAPI) {
     name: "talk-send",
     label: "Send Talk Message",
     description:
-      'Send a plain-text message to another pi session. Plain text only, ≤32KB — send a summary and a path, never file contents. `to: "*"` broadcasts to every session; `to: "cwd"` broadcasts to sessions in this cwd.',
+      "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",
     parameters: Type.Object({
-      to: Type.String({
-        description: 'Target session (name/address/@alias; "*" or "cwd" to broadcast)',
-      }),
+      to: Type.String({ description: "Target session id (from talk-list-sessions)" }),
       message: Type.String({ description: "Message body" }),
     }),
     async execute(_toolCallId, params) {
@@ -308,7 +309,7 @@ export default function talk(pi: ExtensionAPI) {
 
   pi.registerCommand("talk-dead", {
     description:
-      "Mark a talk session as dead (removed from listings, swept soon): no arg = this session, <sessionId> = that session, --all = every other visible session",
+      "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();
@@ -336,13 +337,13 @@ export default function talk(pi: ExtensionAPI) {
     ) {
       return; // pre-renderer entries: keep pi's default custom-message box
     }
-    const id8 = d.id.slice(0, 8);
+    const idTail = d.id.slice(-8);
     const chip = theme.inverse(` ${d.kind.toUpperCase()} `);
     const header = `${theme.fg("accent", theme.bold(displayName(d.from.name)))} ${theme.fg("dim", `(${shortCwd(d.from.cwd)})`)} ${chip}`;
-    const footer = theme.fg("dim", `id ${id8} · ${d.kind} · ${relativeTime(d.ts)}`);
+    const footer = theme.fg("dim", `id ${idTail} · ${d.kind} · ${relativeTime(d.ts)}`);
     const out = [header, sanitizeTerminal(d.body), "", footer];
     if (d.kind === "ask") {
-      out.push(theme.fg("dim", `└─ reply via talk-reply, replyTo: "${id8}"`));
+      out.push(theme.fg("dim", `└─ reply via talk-reply, replyTo: "${idTail}"`));
     }
     const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
     box.addChild(new Text(out.join("\n"), 0, 0));

package/src/talk/mailbox.ts

@@ -247,7 +247,7 @@ export async function pendingAsks(storage: TalkStorage, addr: string): Promise<L
   return out;
 }
 
-/** Outgoing ask ids, used by the adapter for prefix resolution. */
+/** Outgoing ask ids, used by the core for interlock arbitration. */
 export async function outgoingAskIds(storage: TalkStorage, addr: string): Promise<string[]> {
   const out: string[] = [];
   for (const key of await storage.listKeys(asksNs(addr))) {
@@ -257,15 +257,19 @@ export async function outgoingAskIds(storage: TalkStorage, addr: string): Promis
   return out;
 }
 
-/** Resolve a pending ask by explicit replyTo id or unique prefix. No inference. */
+/**
+ * Resolve a pending ask by explicit replyTo id or unique suffix. No inference.
+ * Matching is on the suffix: the prefix of a time-ordered (v7-style) id is the
+ * timestamp part and collides easily, the suffix is the random part.
+ */
 export async function resolveAskByRef(
   storage: TalkStorage,
   addr: string,
   replyTo: string,
 ): Promise<Letter | null> {
-  if (!replyTo) return null; // empty prefix matches every id — an explicit ref is required
+  if (!replyTo) return null; // empty suffix matches every id — an explicit ref is required
   const asks = await pendingAsks(storage, addr);
-  return asks.find((a) => a.id === replyTo || a.id.startsWith(replyTo)) ?? null;
+  return asks.find((a) => a.id === replyTo || a.id.endsWith(replyTo)) ?? null;
 }
 
 // ── Audit log ────────────────────────────────────────────────────────────

package/src/talk/policy.ts

@@ -28,8 +28,7 @@ export class OutboundPolicy {
    * Gate one outbound letter. `unreadBacklog` is the target's current
    * unread count (report 0 when the target is idle — an idle agent has by
    * definition worked through what it was handed). `target` scopes the
-   * identical-body dedupe to a single peer (loop-breaking) so a broadcast
-   * of one body to N peers is not deduped after the first.
+   * identical-body dedupe to a single peer (loop-breaking).
    */
   check(body: string, unreadBacklog: number, target?: string): OutboundVerdict {
     if (body.length > MAX_BODY_CHARS) {

package/src/talk/registry.ts

@@ -8,14 +8,18 @@
  *   two sessions on one directory never share an inbox.
  * - A record outlives the process that wrote it — that's what makes a session
  *   addressable while it's down (mail waits on disk).
- * - Presence is a pid PLUS a heartbeat: pid alone can't tell wedged from
- *   healthy (and pids get reused); heartbeat alone can't tell crash from pause.
+ * - 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)
+ *   and not flagged offline is live; everything else is offline. There is no
+ *   heartbeat, so a wedged process is indistinguishable from a healthy idle
+ *   one.
  * - Listing has NO side effects.
  *
  * All values read from storage are validated with TypeBox before use.
  */
 
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
@@ -28,6 +32,7 @@ export const SessionRecordSchema = Type.Object({
   name: Type.String(),
   cwd: Type.String(),
   pid: Type.Number(),
+  pidStart: Type.Optional(Type.Number()),
   startedAt: Type.Number(),
   lastSeenAt: Type.Number(),
   status: Type.Union([
@@ -39,12 +44,9 @@ export const SessionRecordSchema = Type.Object({
 });
 export type SessionRecord = Static<typeof SessionRecordSchema>;
 
-export type Presence = "live" | "stalled" | "offline";
+export type Presence = "live" | "offline";
 
-export const HEARTBEAT_STALE_MS = 45_000;
-/** A session is shown in the default listing while its heartbeat is this fresh. */
-export const LIST_ACTIVE_MS = 15 * 60 * 1000;
-/** Sweep leaves a record alone until its heartbeat has been quiet this long. */
+/** Sweep leaves a record alone until its last activity was this long ago. */
 export const SWEEP_OFFLINE_GRACE_MS = 24 * 60 * 60 * 1000;
 /** A mailbox holding undelivered mail is kept this long after last contact. */
 export const SWEEP_MAIL_KEEP_MS = 30 * 24 * 60 * 60 * 1000;
@@ -105,29 +107,58 @@ export async function listRecords(storage: TalkStorage): Promise<SessionRecord[]
   return out.toSorted((a, b) => a.startedAt - b.startedAt);
 }
 
-function pidAlive(pid: number): boolean {
+/**
+ * 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
+ * start time matches the recorded one. Returns undefined on non-Linux or when
+ * the stat file is unreadable.
+ */
+export function readStartTime(pid: number): number | undefined {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // comm sits in parens and may contain spaces: split after the last ')'.
+    // starttime is field 22 (1-indexed); pid and (comm) consumed two tokens,
+    // so it sits at index 19 of the remainder.
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    const starttime = Number(fields[19]);
+    return Number.isFinite(starttime) ? starttime : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether the recorded process is really alive. `pidStart` guards against
+ * pid wrap-around: when present, an alive pid only counts as live if its
+ * current start time matches. Without it (legacy records) — or when /proc is
+ * unreadable — we fall back to the bare pid check.
+ */
+function pidAlive(pid: number, pidStart?: number): boolean {
   if (!Number.isSafeInteger(pid) || pid <= 0) return false;
   try {
     process.kill(pid, 0);
-    return true;
   } catch (error) {
     // EPERM means the process exists but isn't ours — still alive
     return (error as NodeJS.ErrnoException)?.code === "EPERM";
   }
+  if (pidStart === undefined) return true;
+  const start = readStartTime(pid);
+  return start === undefined ? true : start === pidStart;
 }
 
-export function presenceOf(record: SessionRecord, now: number = Date.now()): Presence {
+export function presenceOf(record: SessionRecord): Presence {
   if (record.offline) return "offline";
-  if (!pidAlive(record.pid)) return "offline";
-  return now - record.lastSeenAt < HEARTBEAT_STALE_MS ? "live" : "stalled";
+  if (!pidAlive(record.pid, record.pidStart)) return "offline";
+  return "live";
 }
 
 // ── Sweep ────────────────────────────────────────────────────────────────
 
 /**
  * Reclaim dead sessions' data. Rules (mail outranks tidiness):
- * - a record whose heartbeat went quiet less than SWEEP_OFFLINE_GRACE_MS ago
- *   is never touched — it may be merely down or suspended, and a resume will
+ * - 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
@@ -136,6 +167,9 @@ export function presenceOf(record: SessionRecord, now: number = Date.now()): Pre
  */
 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.
+    if (pidAlive(record.pid, record.pidStart)) continue;
     const quietFor = now - record.lastSeenAt;
     if (quietFor < SWEEP_OFFLINE_GRACE_MS) continue;
     const hasMail =

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

@@ -0,0 +1,94 @@
+---
+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.
+---
+
+# 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.
+
+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.
+
+## Session 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):
+
+  ```json
+  [
+    {
+      "status": "idle",
+      "work_dir": "/path/to/cwd",
+      "id": "0193a2f5-...",
+      "name": "...",
+      "self": true
+    }
+  ]
+  ```
+
+- 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.
+
+### 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.
+
+### 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.
+
+## 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        |
+
+In the TUI: `/talk` lists sessions, `/talk-dead` marks a session as dead (shown offline, swept soon).
+
+## Collaboration workflows
+
+### Split work between sessions
+
+1. `talk-list-sessions` first: see which sessions exist, their `work_dir`, and status.
+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.
+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.
+
+### 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
+
+- Ask another session 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
+
+- Plain text, ≤32KB. Send a summary and paths, never the full file or large code blocks.
+- Self-contained: background, goal, constraints — the peer has none of your context.
+- Make the ask explicit: "please review", "please implement", or "FYI only".
+- One topic per message so the reply stays focused.
+
+## 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.