@afokapu/atdd-flow 0.3.49 → 0.3.51

package/conventions/atdd-flow.collaboration/atdd-flow.collaboration.convention.yaml

@@ -33,6 +33,7 @@ content:
     receipts inbound communication from any seat, but sends substantive direction, results, and
     wakes only to main@project. Only main@project executes that project repository merge; the
     operator may authorize, relay, or inspect but never merges.
+    Post decisions and open questions as messages when they happen.
   projection: >-
     Keep this full policy only in this convention. Managed AGENTS.md and CLAUDE.md blocks
     contain only its canonical pointer and preserve all user-authored content outside the

package/extensions/pi/index.ts

@@ -6,7 +6,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
 import { paths, readYaml, type Seat } from "../../src/core";
 import { directiveNotice, nextDirective } from "../../src/tasks";
-import { runtimeStartupInstruction } from "../../src/collaboration-policy";
+import { handoverThresholdInstruction, runtimeStartupInstruction, successorInstruction } from "../../src/collaboration-policy";
+import { type RecoveryMode, recoveryFor } from "../../src/recovery-bundle";
 import { contextHandoverThreshold, readHandoverReplacement } from "../../src/handover";
 
 type Thread = { id?: unknown; participants?: unknown; subject?: unknown };
@@ -318,6 +319,28 @@ export async function awaitLaunchActivation({ root, seat, piSession, herdrSessio
   throw new Error("Timed out waiting for verified Flow launch receipt and binding.");
 }
 
+/**
+ * Host-attached Pi has no launcher variables; it may activate only when Herdr's injected pane identity exactly
+ * matches the Desk seat's native scoped binding. This reads the seat and never writes or creates a binding.
+ */
+export async function hostAttachedActivation({ root, seat, herdrSession, pane, piSession, piSessionPath }: { root: string; seat: string; herdrSession?: string; pane?: string; piSession?: string; piSessionPath?: string }) {
+  if (!herdrSession || !pane) return false;
+  try {
+    const runtime = (await readYaml<Seat>(paths(root).seatFile(seat))).runtime;
+    return nativeScopedTo(runtime, herdrSession, pane) && sessionUnsetOrEqual(runtime, piSession, piSessionPath);
+  } catch { return false; }
+}
+
+function nativeScopedTo(runtime: Seat["runtime"], herdrSession: string, pane: string) {
+  const locator = runtime?.addresses.herdr;
+  return runtime?.application === "herdr" && runtime.wake === "native" && !runtime.launch_receipt
+    && typeof locator === "object" && locator.session === herdrSession && locator.pane === pane;
+}
+
+const unsetOrEqual = (recorded: string | undefined, live: string | undefined) => !recorded || recorded === live;
+const sessionUnsetOrEqual = (runtime: Seat["runtime"], piSession?: string, piSessionPath?: string) =>
+  unsetOrEqual(runtime?.pi_session, piSession) && unsetOrEqual(runtime?.pi_session_path, piSessionPath);
+
 /** Injects the current task-derived action; failure to derive never blocks mail or startup. */
 async function sendTaskDirective(pi: ExtensionAPI, root: string, seat: string) {
   try {
@@ -330,6 +353,9 @@ async function sendTaskDirective(pi: ExtensionAPI, root: string, seat: string) {
   } catch { /* The durable task remains authoritative and is re-derived at the next startup or wake. */ }
 }
 
+/** The recovery bundle is advisory; any failure falls back to the plain prompt. */
+const recovery = (root: string, seat: string, mode: RecoveryMode, session?: string) => recoveryFor(root, seat, mode, session).catch(() => undefined);
+
 /** Desk mail is authoritative; the queue is a bounded delivery index and fs.watch only shortens latency. */
 export default function (pi: ExtensionAPI) {
   const root = process.env.ATDD_WORKFLOW_ROOT;
@@ -337,6 +363,8 @@ export default function (pi: ExtensionAPI) {
   if (!root || !seat) return;
   let runtime: ReturnType<typeof createPiRuntime> | undefined;
   let handoverPrompted = false;
+  // Host-attach only: mail older than this activation is consumed without a prompt, so a long backlog cannot trigger one turn per message.
+  let hostActivatedAt: number | undefined;
   pi.on("turn_end", async (_event, ctx) => {
     if (handoverPrompted) return;
     const percent = ctx.getContextUsage()?.percent;
@@ -345,9 +373,10 @@ export default function (pi: ExtensionAPI) {
       const threshold = await contextHandoverThreshold(root);
       if (percent < threshold) return;
       handoverPrompted = true;
+      const bundle = await recovery(root, seat, "threshold", process.env.ATDD_FLOW_PI_SESSION);
       pi.sendMessage({
         customType: "atdd-flow-context-handover-replacement",
-        content: `SYSTEM: Context ${percent}% reached the Flow handover threshold (${threshold}%). Finish or undo the atomic step, record a validated handover, then stop new work; do not compact or release a session.`,
+        content: handoverThresholdInstruction(percent, threshold, bundle),
         display: true, details: { seat, threshold, percent, authority: "handover" },
       }, { triggerTurn: true, deliverAs: "followUp" });
     } catch { /* Desk policy is re-read on the next safe boundary. */ }
@@ -369,6 +398,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     runtime = createPiRuntime({ root, seat, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
       if (!sendIfOwned) return false;
+      if (hostActivatedAt !== undefined && Date.parse(typeof mail.created_at === "string" ? mail.created_at : "") < hostActivatedAt) return sendIfOwned(async () => undefined);
       return sendIfOwned(async () => {
         // Task state is re-read at every wake, so queued mail cannot carry a stale action.
         await sendTaskDirective(pi, root, seat);
@@ -383,23 +413,35 @@ export default function (pi: ExtensionAPI) {
     const piSession = process.env.ATDD_FLOW_PI_SESSION;
     const herdrSession = process.env.ATDD_FLOW_HERDR_SESSION;
     const pane = process.env.ATDD_FLOW_HERDR_PANE;
+    if (!piSession && !herdrSession && !pane) {
+      const sessionManager = (ctx as { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } }).sessionManager;
+      if (await hostAttachedActivation({ root, seat, herdrSession: process.env.HERDR_SESSION, pane: process.env.HERDR_PANE_ID, piSession: sessionManager?.getSessionId?.(), piSessionPath: sessionManager?.getSessionFile?.() })) {
+        hostActivatedAt = Date.now();
+        if (await runtime.activate()) {
+          const bundle = await recovery(root, seat, "start", sessionManager?.getSessionId?.());
+          const notice = "Notices created before this session were not replayed; run atdd-flow status seat " + seat + " for unanswered mail.";
+          pi.sendMessage({ customType: "atdd-flow-start", content: `${runtimeStartupInstruction(seat, bundle)} ${notice}`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
+        }
+      }
+      return;
+    }
     if (!piSession || !herdrSession || !pane) return;
     const current = runtime;
     void awaitLaunchActivation({
       root, seat, piSession, herdrSession, pane,
       activate: async () => {
         if (!await current.activate()) return;
-        pi.sendMessage({ customType: "atdd-flow-start", content: runtimeStartupInstruction(seat), display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
-        try {
-          const request = await readHandoverReplacement(root, seat);
-          if (request.source.pi_session !== piSession) {
-            pi.sendMessage({
-              customType: "atdd-flow-context-handover-replacement",
-              content: `SYSTEM: Path-A handover ${request.handover.id} is injected for ${seat}. Read atdd-flow handover show ${seat}, reconcile the live Desk, then report RESUMED with verified/total counts and discrepancies.`,
-              display: true, details: { seat, handover: request.handover.id, authority: "handover-replacement" },
-            }, { triggerTurn: true, deliverAs: "followUp" });
-          }
-        } catch { /* This is an ordinary launch, not a Path-A successor. */ }
+        const request = await readHandoverReplacement(root, seat).catch(() => undefined);
+        const successor = request && request.source.pi_session !== piSession ? request : undefined;
+        const bundle = await recovery(root, seat, successor ? "successor" : "start", piSession);
+        pi.sendMessage({ customType: "atdd-flow-start", content: runtimeStartupInstruction(seat, successor ? undefined : bundle), display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
+        if (successor) {
+          pi.sendMessage({
+            customType: "atdd-flow-context-handover-replacement",
+            content: successorInstruction(seat, successor.handover.id, bundle),
+            display: true, details: { seat, handover: successor.handover.id, authority: "handover-replacement" },
+          }, { triggerTurn: true, deliverAs: "followUp" });
+        }
         await sendTaskDirective(pi, root, seat);
         if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.49",
+  "version": "0.3.51",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -13,6 +13,7 @@ import { status } from "./overview";
 import { multiplexer } from "./multiplexer";
 import * as cleanup from "./ephemeral-resources";
 import * as ownerAlerts from "./owner-escalations";
+import { recoveryFor } from "./recovery-bundle";
 import { recordHandover, requestHandoverReplacement, resumedHandoverReplacement, showHandover } from "./handover";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
@@ -75,6 +76,7 @@ Usage:
   atdd-flow behavioral-review record <project> <task-id> --by <reviewer-address> --file <result-yaml>
   atdd-flow behavioral-review open <project> <task-id>
   atdd-flow open <address>
+  atdd-flow recover <address>
   atdd-flow address-book
 
 Global:
@@ -207,6 +209,7 @@ async function main() {
       throw new Error("Use `atdd-flow behavioral-review launch|record|open <project> <task-id>`.");
     },
     open: () => openSeat(root, required(rest[0], "address")),
+    recover: async () => console.log(await recoveryFor(root, required(rest[0], "address"), "start", process.env.ATDD_FLOW_PI_SESSION)),
     "address-book": () => addressBook(root),
   };
   const action = commands[command];

package/src/collaboration-policy.ts

@@ -70,7 +70,19 @@ export async function projectCollaborationPolicy(root: string) {
   }));
 }
 
+const withBundle = (text: string, bundle?: string) => bundle ? `${text}\n${bundle}` : text;
+
 /** The one startup handoff for supported Flow-managed runtimes, resolved from the canonical convention. */
-export function runtimeStartupInstruction(seat: string) {
-  return `SYSTEM: you are ${seat}. Collaboration policy: ${canonicalCollaborationPolicy()} Canonical convention: ${collaborationConventionPath}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`;
+export function runtimeStartupInstruction(seat: string, bundle?: string) {
+  return withBundle(`SYSTEM: you are ${seat}. Collaboration policy: ${canonicalCollaborationPolicy()} Canonical convention: ${collaborationConventionPath}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`, bundle);
+}
+
+/** The 80% handover prompt; the computed bundle gives the handover record exact current state. */
+export function handoverThresholdInstruction(percent: number, threshold: number, bundle?: string) {
+  return withBundle(`SYSTEM: Context ${percent}% reached the Flow handover threshold (${threshold}%). Finish or undo the atomic step, record a validated handover, then stop new work; do not compact or release a session.`, bundle);
+}
+
+/** The Path-A successor prompt; the bundle points at the predecessor session file. */
+export function successorInstruction(seat: string, handoverId: string, bundle?: string) {
+  return withBundle(`SYSTEM: Path-A handover ${handoverId} is injected for ${seat}. Read atdd-flow handover show ${seat}, reconcile the live Desk, then report RESUMED with verified/total counts and discrepancies.`, bundle);
 }

package/src/recovery-bundle.ts

@@ -0,0 +1,308 @@
+// URN: component:flow:e004:recovery-bundle:backend:application
+// Tested-By:
+// - test:atdd-flow:seat-recovery-bundle
+// - test:atdd-flow:seat-recovery-injection
+// Runtime: bun
+// Purpose: Compute one capped, read-only recovery bundle for a seat.
+
+import { readdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { type Checkpoint, type Seat, canonicalAddress, exists, paths, readYaml, runOutput, runtimeAddress, seat as readSeat } from "./core";
+import { readHandoverReplacement } from "./handover";
+import { type Task, nextDirective, seatTasks, terminal } from "./tasks";
+import { messages, pendingResponders, threadsForSeat } from "./threads";
+
+/**
+ * The bundle only reorganizes durable records (git, Desk, previous Pi session
+ * file). It never writes, never calls a model, and renders every unreadable
+ * source as an explicit `unavailable` line instead of failing.
+ */
+export type RecoveryMode = "start" | "threshold" | "successor";
+type Options = { sessionPath?: string; now?: Date };
+type Entry = { id: string; from: string; to: string; at: string; subject: string };
+
+// Hard caps keep the bundle a pointer-style summary, never a transcript.
+const maxLines = 50;
+const maxBytes = 5120;
+const maxTasks = 12;
+const maxPending = 4;
+const maxRecent = 5;
+const maxChanged = 8;
+const tailBytes = 256 * 1024;
+const commandTimeoutMs = 8000;
+const gatePattern = /\b(bun (run )?(test|check)|atdd-bun|tsc|lint)\b/;
+
+/** Collapses whitespace and shortens one value so a single field cannot dominate the cap. */
+function clip(text: string, length: number) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > length ? `${flat.slice(0, length - 1)}…` : flat;
+}
+
+function age(from: string, now: Date) {
+  const minutes = Math.floor((now.getTime() - Date.parse(from)) / 60_000);
+  if (Number.isNaN(minutes)) return "unknown";
+  if (minutes < 60) return `${Math.max(0, minutes)}m`;
+  return minutes < 1440 ? `${Math.floor(minutes / 60)}h` : `${Math.floor(minutes / 1440)}d`;
+}
+
+/** Runs one field builder; a failure becomes `<label>: unavailable (<reason>)`. */
+async function part(label: string, build: () => Promise<string[] | string>): Promise<string[]> {
+  try {
+    const built = await build();
+    return Array.isArray(built) ? built : [built];
+  } catch (error) {
+    return [`${label}: unavailable (${clip((error as Error).message, 80)})`];
+  }
+}
+
+/** `--no-optional-locks` keeps `git status` from refreshing (writing) the index. */
+const git = (cwd: string, ...args: string[]) => runOutput(["git", "--no-optional-locks", ...args], cwd);
+
+/** Shows the first few changed paths and counts the rest. */
+function listing(entries: string[]) {
+  const shown: string[] = [];
+  let used = 0;
+  for (const entry of entries) {
+    if (shown.length >= maxChanged || used + entry.length > 140) break;
+    shown.push(entry);
+    used += entry.length + 2;
+  }
+  const rest = entries.length - shown.length;
+  return `${shown.join(", ")}${rest ? ` +${rest} more` : ""}`;
+}
+
+/** Each git field is its own part so one failing command only blanks that field. */
+function gitParts(record: Seat, now: Date) {
+  const cwd = record.worktree;
+  return [
+    part("branch", async () => `branch: ${await git(cwd, "rev-parse", "--abbrev-ref", "HEAD")}`)
+      .then((lines) => lines[0]!.includes("unavailable") ? [`branch: ${record.branch} (recorded; git unavailable)`] : lines),
+    part("head", async () => `head: ${await git(cwd, "rev-parse", "--short", "HEAD")}`),
+    part("upstream", async () => {
+      const [behind, ahead] = (await git(cwd, "rev-list", "--left-right", "--count", "@{u}...HEAD")).split(/\s+/);
+      return `upstream: ahead ${ahead}, behind ${behind}`;
+    }),
+    part("changed", async () => {
+      const entries = (await git(cwd, "status", "--porcelain=v1", "-uall")).split("\n").filter(Boolean)
+        .map((line) => line.replace(/^\s*(\S+)\s+/, "$1 "));
+      return `changed: ${entries.length ? listing(entries) : "none"}`;
+    }),
+    part("last commit", async () => `last commit: ${age(await git(cwd, "log", "-1", "--format=%cI"), now)} ago`),
+  ];
+}
+
+async function checkpointLine(root: string, address: string, now: Date) {
+  const file = paths(root).checkpointFile(address);
+  if (!await exists(file)) throw new Error("no checkpoint recorded");
+  const entry = await readYaml<Checkpoint>(file);
+  return `checkpoint: ${entry.status} — ${clip(entry.summary, 100)} | next: ${clip(entry.next_action, 60)} (${age(entry.updated_at, now)} ago)`;
+}
+
+/** Tasks that need this seat now (0), other work in flight (1), then todo (2). */
+function taskGroup(task: Task, address: string) {
+  if (task.status === "todo") return 2;
+  const handoff = task.handoff?.state;
+  const coordinating = task.coordinator === address && (task.status === "review" || Boolean(task.blocker) || handoff === "awaiting_coordinator");
+  const assigned = task.assignee === address && task.status === "in_progress" && (handoff === "awaiting_assignee" || handoff === "executing");
+  return coordinating || assigned ? 0 : 1;
+}
+
+function taskLine(id: string, task: Task) {
+  const proven = `${task.done_when.filter((entry) => entry.proof).length}/${task.done_when.length}`;
+  const parts = [`task ${id}`, task.status, task.phase, task.handoff && `${task.handoff.state} ${task.handoff.evidence}`, `proof ${proven}`];
+  if (task.blocker) parts.push(`blocked: ${task.blocker}`);
+  if (task.depends_on?.length) parts.push(`deps: ${task.depends_on.join(",")}`);
+  return clip(parts.filter(Boolean).join(" "), 150);
+}
+
+const moreLine = (hidden: number, address: string) => `  +${hidden} more, run atdd-flow status seat ${address}`;
+
+async function taskLines(root: string, address: string) {
+  const record = await readSeat(root, address);
+  const rows = (await seatTasks(root, record.project, address)).filter((entry) => !terminal(entry.task))
+    .map((entry) => ({ ...entry, group: taskGroup(entry.task, address) }))
+    .sort((left, right) => left.group - right.group || left.id.localeCompare(right.id));
+  const count = (group: number) => rows.filter((row) => row.group === group).length;
+  const lines = [`tasks: ${rows.length} open (${count(0)} need you, ${count(1)} in progress, ${count(2)} todo)`];
+  lines.push(...rows.slice(0, maxTasks).map((row) => taskLine(row.id, row.task)));
+  if (rows.length > maxTasks) lines.push(moreLine(rows.length - maxTasks, address));
+  return lines;
+}
+
+async function nextLine(root: string, address: string) {
+  const directive = await nextDirective(root, address);
+  if (!directive) return "next: none (no actionable task state)";
+  return clip(`next: ${directive.project}/${directive.task} [${directive.lifecycle}] ${directive.action}${directive.command ? ` ${directive.command}` : ""}`, 200);
+}
+
+const byAge = (left: Entry, right: Entry) => left.at.localeCompare(right.at) || left.id.localeCompare(right.id);
+
+/** Unanswered expects_result messages in both directions plus the seat's own recent posts. */
+async function conversation(root: string, address: string) {
+  const inbound: Entry[] = [];
+  const outbound: Entry[] = [];
+  const own: Entry[] = [];
+  for (const { threadId, record } of await threadsForSeat(root, address)) {
+    const all = await messages(root, threadId);
+    for (const message of all) {
+      const entry = { id: message.id, from: message.from, to: message.to === "all" ? "all" : message.to.join(","), at: message.created_at, subject: record.subject };
+      if (message.from === address) own.push(entry);
+      if (!message.expects_result || record.state === "closed") continue;
+      const waiting = pendingResponders(record.participants, all, message);
+      if (waiting.includes(address)) inbound.push(entry);
+      if (message.from === address && waiting.length) outbound.push({ ...entry, to: waiting.join(",") });
+    }
+  }
+  // Recent unanswered evidence wins the cap; totals still preserve the full count.
+  return { inbound: inbound.sort(byAge).reverse(), outbound: outbound.sort(byAge).reverse(), own: own.sort(byAge).reverse() };
+}
+
+async function conversationLines(root: string, address: string, now: Date) {
+  const { inbound, outbound, own } = await conversation(root, address);
+  const render = (kind: string, entries: Entry[]) => {
+    const shown = entries.slice(0, maxPending).map((entry) => clip(`${kind} ${entry.id} ${entry.from} -> ${entry.to} ${age(entry.at, now)}`, 170));
+    return entries.length > maxPending ? [...shown, moreLine(entries.length - maxPending, address)] : shown;
+  };
+  return {
+    unanswered: [`unanswered: ${inbound.length} inbound, ${outbound.length} outbound`, ...render("inbound", inbound), ...render("outbound", outbound)],
+    recent: own.slice(0, maxRecent).map((entry) => clip(`recent ${entry.id} ${entry.subject}`, 100)),
+  };
+}
+
+/** PR/CI state for the worktree branch; `gh` is read-only here and bounded by a timeout. */
+async function prLine(cwd: string) {
+  const child = Bun.spawn(["gh", "pr", "view", "--json", "number,state,url,statusCheckRollup"], {
+    cwd, env: process.env, stdout: "pipe", stderr: "pipe", timeout: commandTimeoutMs,
+  });
+  const [out, err, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  if (code) throw new Error(err.trim().split("\n")[0] || `gh exited ${code}`);
+  const pr = JSON.parse(out) as { number: number; state: string; url: string; statusCheckRollup?: { conclusion?: string; state?: string }[] };
+  const tally = { pass: 0, fail: 0, pending: 0 };
+  for (const check of pr.statusCheckRollup ?? []) {
+    const result = (check.conclusion || check.state || "").toUpperCase();
+    if (["SUCCESS", "NEUTRAL", "SKIPPED"].includes(result)) tally.pass += 1;
+    else if (["FAILURE", "ERROR", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(result)) tally.fail += 1;
+    else tally.pending += 1;
+  }
+  return `pr: PR #${pr.number} ${pr.state} ${pr.url}; checks ${tally.pass} pass / ${tally.fail} fail / ${tally.pending} pending`;
+}
+
+type Tool = { commands: Map<string, string>; order: string[]; results: Map<string, { failed: boolean; text: string }> };
+type Item = { type?: string; id?: string; name?: string; text?: string; arguments?: { command?: unknown } };
+type Record = { role?: string; content?: unknown; toolCallId?: string; toolName?: string; isError?: boolean };
+
+function textOf(content: unknown) {
+  if (typeof content === "string") return content;
+  return Array.isArray(content) ? (content as Item[]).map((item) => item.text ?? "").join("\n") : "";
+}
+
+function recordResult(tool: Tool, message: Record) {
+  if (message.role !== "toolResult" || message.toolName !== "bash" || !message.toolCallId) return;
+  tool.results.set(message.toolCallId, { failed: Boolean(message.isError), text: textOf(message.content) });
+}
+
+function recordCalls(tool: Tool, message: Record) {
+  if (message.role !== "assistant" || !Array.isArray(message.content)) return;
+  for (const item of message.content as Item[]) {
+    const command = item.arguments?.command;
+    if (item.type !== "toolCall" || item.name !== "bash" || !item.id || typeof command !== "string") continue;
+    tool.commands.set(item.id, command);
+    tool.order.push(item.id);
+  }
+}
+
+/** Reads bash tool calls and their paired results from Pi session JSONL records. */
+function toolRecords(text: string): Tool {
+  const tool: Tool = { commands: new Map(), order: [], results: new Map() };
+  for (const line of text.split("\n")) {
+    try { const message = JSON.parse(line).message ?? {}; recordResult(tool, message); recordCalls(tool, message); } catch { /* A partial or foreign line carries no tool record. */ }
+  }
+  return tool;
+}
+
+/** Last test/gate command and its recorded outcome, from the final 256KB of the session file only. */
+async function gateLine(path: string) {
+  const size = (await stat(path)).size;
+  const start = Math.max(0, size - tailBytes);
+  const tail = await Bun.file(path).slice(start, size).text();
+  const tool = toolRecords(start > 0 ? tail.slice(tail.indexOf("\n") + 1) : tail);
+  const id = tool.order.findLast((candidate) => gatePattern.test(tool.commands.get(candidate)!));
+  if (!id) throw new Error("no test/gate command in session tail");
+  const result = tool.results.get(id);
+  const code = result?.text.match(/exited with code (\d+)/)?.[1];
+  const outcome = !result ? "result unrecorded" : result.failed ? `failed${code ? `, code ${code}` : ""}` : "ok";
+  return `gate: ${clip(tool.commands.get(id)!, 80)} — ${outcome}`;
+}
+
+function sessionOf(options: Options) {
+  if (!options.sessionPath) throw new Error("no previous session");
+  return options.sessionPath;
+}
+
+function runtimeLine(record: Seat) {
+  const runtime = record.runtime;
+  const locator = runtime?.addresses[runtime.application];
+  if (!runtime || locator === undefined) throw new Error("no runtime recorded");
+  const { address, session } = runtimeAddress(runtime.application, locator);
+  return `runtime: ${runtime.application} ${session ?? ""} ${address} | pi session ${runtime.pi_session ?? "unrecorded"}`.replace(/\s+/g, " ");
+}
+
+/** Enforces the 50-line / 5KB contract by dropping trailing (least actionable) lines. */
+function cap(lines: string[]) {
+  const kept = lines.slice(0, maxLines);
+  while (kept.length > 1 && new TextEncoder().encode(kept.join("\n")).length > maxBytes) kept.pop();
+  return kept.join("\n");
+}
+
+/** Computes the recovery bundle for `address`; unreadable sources render as `unavailable`. */
+export async function recoveryBundle(root: string, address: string, options: Options = {}) {
+  const now = options.now ?? new Date();
+  let resolved = address;
+  let record: Seat;
+  try {
+    resolved = await canonicalAddress(root, address);
+    record = await readSeat(root, resolved);
+  } catch (error) {
+    return cap([`RECOVERY BUNDLE ${resolved} | ${now.toISOString()}`, `seat: unavailable (${clip((error as Error).message, 80)})`]);
+  }
+  const talk = conversationLines(root, resolved, now).catch((error) => {
+    const reason = `unavailable (${clip((error as Error).message, 80)})`;
+    return { unanswered: [`unanswered: ${reason}`], recent: [`recent: ${reason}`] };
+  });
+  const sections = await Promise.all([
+    [`role: ${record.role} | project: ${record.project}`, `worktree: ${record.worktree}`],
+    ...gitParts(record, now),
+    part("checkpoint", () => checkpointLine(root, resolved, now)),
+    part("tasks", () => taskLines(root, resolved)),
+    part("next", () => nextLine(root, resolved)),
+    talk.then((lines) => lines.unanswered),
+    part("pr", () => prLine(record.worktree)),
+    part("gate", async () => gateLine(sessionOf(options))),
+    part("session", async () => `session: ${sessionOf(options)}`),
+    part("runtime", async () => runtimeLine(record)),
+    talk.then((lines) => lines.recent),
+  ]);
+  return cap([`RECOVERY BUNDLE ${resolved} | ${now.toISOString()}`, ...sections.flat()]);
+}
+
+/**
+ * The previous Pi session to point at: the predecessor's file for a Path-A
+ * successor, the seat's own file at the handover threshold, or the newest
+ * sibling file (excluding the running session) at an ordinary start.
+ */
+export async function previousSessionPath(root: string, address: string, mode: RecoveryMode, current?: string) {
+  const resolved = await canonicalAddress(root, address);
+  if (mode === "successor") return (await readHandoverReplacement(root, resolved)).source.pi_session_path;
+  const runtime = (await readSeat(root, resolved)).runtime;
+  const own = runtime?.pi_session_path;
+  if (!own || mode === "threshold") return own;
+  const running = current ?? runtime?.pi_session;
+  const names = (await readdir(dirname(own))).filter((name) => name.endsWith(".jsonl") && !(running && name.includes(running))).sort();
+  return names.length ? join(dirname(own), names[names.length - 1]!) : undefined;
+}
+
+/** The bundle for a prompt or CLI call; an unresolvable previous session only renders as unavailable. */
+export async function recoveryFor(root: string, address: string, mode: RecoveryMode, current?: string) {
+  const sessionPath = await previousSessionPath(root, address, mode, current).catch(() => undefined);
+  return recoveryBundle(root, address, { sessionPath });
+}

package/src/threads.ts

@@ -36,7 +36,7 @@ async function thread(root: string, threadId: string) {
   return readYaml<Thread>(paths(root).threadFile(threadId));
 }
 
-async function messages(root: string, threadId: string) {
+export async function messages(root: string, threadId: string) {
   const folder = paths(root).thread(threadId);
   const files = (await readdir(folder)).filter((file) => file.startsWith("M-") && file.endsWith(".yaml")).sort();
   return Promise.all(files.map((file) => readYaml<Message>(`${folder}/${file}`)));
@@ -366,16 +366,19 @@ export async function result(root: string, threadId: string, messageId: string,
   return post(root, threadId, args, { from, to: [target.from], kind: "result", in_reply_to: messageId, body: required(words(args, "--body"), "--body") });
 }
 
+/** Recipients that have not yet answered an expects_result message with a result. */
+export function pendingResponders(participants: string[], all: Message[], message: Message) {
+  const responders = message.to === "all" ? participants.filter((address) => address !== message.from) : message.to;
+  return responders.filter((address) => !all.some((reply) => reply.kind === "result" && reply.in_reply_to === message.id && reply.from === address));
+}
+
 export async function status(root: string) {
   const threadIds = (await readdir(paths(root).threads)).sort();
   for (const threadId of threadIds) {
     const record = await thread(root, threadId);
     const all = await messages(root, threadId);
-    const pending = all.flatMap((message) => {
-      if (!message.expects_result) return [];
-      const responders = message.to === "all" ? record.participants.filter((address) => address !== message.from) : message.to;
-      return responders.filter((address) => !all.some((reply) => reply.kind === "result" && reply.in_reply_to === message.id && reply.from === address)).map((address) => `${message.id}@${address}`);
-    });
+    const pending = all.flatMap((message) => message.expects_result
+      ? pendingResponders(record.participants, all, message).map((address) => `${message.id}@${address}`) : []);
     console.log(`${threadId}  ${record.state}  ${record.subject}${pending.length ? `  waiting:${pending.join(",")}` : ""}`);
   }
 }