@afokapu/atdd-flow 0.3.50 → 0.3.52

package/README.md

@@ -134,6 +134,12 @@ Proof is a compact PR, CI run, report, commit range, deployment, or thread refer
 
 At 80% context usage a seat writes a structured handover (template and process rules in the lifecycle convention), checks it with `atdd-flow handover <address> --check --file <path>`, and records it with `atdd-flow handover <address> --file <path>`. The seat keeps one durable `handover.yaml` beside its unchanged checkpoint. Recording rejects a missing header, Runtime line, or section, sections out of order, more than 150 lines, vague references such as `latest` or `that PR` without an exact ID, and a `supersedes` value that does not match the recorded handover id. A fresh session bound to the same seat reads it with `atdd-flow handover show <address>`.
 
+A project main seat can perform a second Path-A replacement without deleting or editing the consumed active request. Use the normal `handover replace` arguments with the explicit `--supersede-consumed` flag, a fresh exact-session adoption authorization, the current validated handover, and exactly one ready self-assigned takeover task. Without the flag, replacement remains create-only and refuses an existing active request.
+
+Before observing Herdr, supersession requires the prior request's takeover task to be terminal and the canonical runtime receipt to embed that exact request and successor. It also requires unchanged main topology, canonical pane and worktree placement, and a matching current handover lineage. Read-only Herdr checks then prove the freshly authorized live Pi session, JSONL path, pane, cwd, agent, and exactly one Pi writer. The command never stops, launches, binds, or changes a runtime.
+
+Supersession serializes publication per seat. It stages a byte-identical copy of the prior request and launch receipt under `.atdd-flow/handover-replacement-archive/<encoded-seat>/<prior-request-sha256>/`, publishes that complete immutable archive first, then atomically replaces the active request. Validation, staging, archive, swap, and concurrent-attempt failures preserve the original active request, receipt, seat, and runtime. After the source extension observes the new request and exits, use the unchanged `pi runtime launch` adoption path; do not hand-edit Desk records or rebind the seat.
+
 For topology normalization, transfer an active task through the narrow durable command, never by editing its YAML: `atdd-flow task transfer <project> <task-id> --to <main-or-named-coordinator> --reason <text> --by <current-coordinator>`; `main@project` must additionally pass `--authorization <operator-message-id>`. That message must be an immutable `task-transfer-authorization/v1` exact tuple for the project, task, current/target coordinator, reason, and target branch/head; only `operator@desk` creates it through `atdd-flow post --task-transfer-authorization <json>`. The command appends immutable source/target/reason/exact-head/effective-time provenance, keeps earlier phase/review/message evidence intact, derives the new governed base from the accepted target head, and never moves a seat, branch, runtime, or worktree. Same-target, duplicate, nested, mismatched, unauthorized, and manually rewritten transitions fail closed.
 
 ## Communicate and hand over

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 };
@@ -352,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;
@@ -369,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. */ }
@@ -412,7 +417,11 @@ export default function (pi: ExtensionAPI) {
       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()) pi.sendMessage({ customType: "atdd-flow-start", content: `Native mail active for ${seat} (host-attached). Notices created before this session were not replayed; run atdd-flow status seat ${seat} for unanswered mail.`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
+        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;
     }
@@ -422,17 +431,17 @@ export default function (pi: ExtensionAPI) {
       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.50",
+  "version": "0.3.52",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -1,4 +1,9 @@
 #!/usr/bin/env bun
+// URN: component:flow:e005:cli:backend:presentation
+// Tested-By:
+// - test:atdd-flow:repeat-handover-replacement-supersession
+// Runtime: bun
+// Purpose: Route supported Desk commands and publish their exact CLI grammar.
 
 import { basename, resolve } from "node:path";
 import { init, initProject, configureProject, migrateNamedCoordinatorTopology, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
@@ -13,6 +18,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
@@ -38,7 +44,7 @@ Usage:
   atdd-flow checkpoint <address> --summary <text> --next <text> [--status active|standby|blocked|complete|unverified]
   atdd-flow handover <address> --file <path> [--check]
   atdd-flow handover show <address>
-  atdd-flow handover replace <address> [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>
+  atdd-flow handover replace <address> [--supersede-consumed] [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>
   atdd-flow handover resumed <address>
   atdd-flow task add <project> <task-id> --title <text> --coordinator <address> [--assignee <address>] [--body <text>] [--source <reference>] [--depends-on <task-id,...>] --done-when <text> [--done-when <text> ...]
   atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address>
@@ -75,6 +81,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 +214,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/handover.ts

@@ -1,5 +1,11 @@
+// URN: component:flow:e005:handover:backend:integration
+// Tested-By:
+// - test:atdd-flow:repeat-handover-replacement-supersession
+// Runtime: bun
+// Purpose: Validate, preserve, publish, and reconcile governed context handover evidence.
+
 import { createHash } from "node:crypto";
-import { link, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { link, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { type Runtime, type Seat, atomicYaml, canonicalAddress, desk, exists, has, now, paths, project, readYaml, required, runOutput, seat, words, yaml } from "./core";
 import { type Task, terminal } from "./tasks";
@@ -102,23 +108,33 @@ export type HandoverReplacementRequest = {
   authorization: { id: string; hash: string };
   source: { pi_session: string; pi_session_path: string; herdr_session: string; pane: string };
   target: { herdr_session: string; pane: string; cwd: string };
-  legacy_source?: {
-    authorization_hash: string;
-    pi_session: string;
-    pi_session_path: string;
-    herdr_session: string;
-    pane: string;
-    cwd: string;
-    agent: string;
-    verified_at: string;
+  legacy_source?: LiveSourceProof;
+  supersession?: {
+    prior_request: { path: string; sha256: string; task: string; handover: string; handover_sha256: string; archive: string };
+    prior_receipt: { path: string; sha256: string; successor_session: string };
+    canonical_source: { pi_session: string; pi_session_path: string; herdr_session: string; pane: string; cwd: string; launch_receipt: string };
+    live_source: LiveSourceProof;
   };
   created_at: string;
 };
 
+type LiveSourceProof = {
+  authorization_hash: string;
+  pi_session: string;
+  pi_session_path: string;
+  herdr_session: string;
+  pane: string;
+  cwd: string;
+  agent: string;
+  verified_at: string;
+};
+
 export type HandoverReplacementDependencies = {
   command?: (command: string[]) => Promise<string>;
   at?: () => string;
   publish?: (file: string, content: string) => Promise<void>;
+  publishArchive?: (staging: string, destination: string) => Promise<void>;
+  replaceActive?: (staged: string, active: string) => Promise<void>;
 };
 
 export const handoverReplacementPath = (root: string, address: string) => join(root, ".atdd-flow", "handover-replacements", `${encodeURIComponent(address)}.yaml`);
@@ -155,7 +171,37 @@ function canonicalSourceMatchesRuntime(runtime: Runtime | undefined, source: Han
     && runtime?.pi_session === source.pi_session && runtime.pi_session_path === source.pi_session_path;
 }
 
+type SupersessionProof = NonNullable<HandoverReplacementRequest["supersession"]>;
+
+function supersessionPlacementMatches(runtime: Runtime | undefined, proof: SupersessionProof) {
+  const locator = runtime?.addresses.herdr;
+  return runtime?.application === "herdr" && typeof locator !== "string"
+    && locator?.session === proof.canonical_source.herdr_session && locator.pane === proof.canonical_source.pane;
+}
+
+function supersessionSessionMatches(runtime: Runtime | undefined, proof: SupersessionProof) {
+  return runtime?.pi_session === proof.canonical_source.pi_session
+    && runtime.pi_session_path === proof.canonical_source.pi_session_path
+    && runtime.launch_receipt === proof.canonical_source.launch_receipt
+    && proof.prior_receipt.path === runtime.launch_receipt
+    && proof.prior_receipt.successor_session === runtime.pi_session;
+}
+
+function supersessionEvidenceMatches(request: HandoverReplacementRequest, proof: SupersessionProof) {
+  return proof.canonical_source.cwd === request.target.cwd
+    && proof.canonical_source.herdr_session === request.target.herdr_session
+    && proof.canonical_source.pane === request.target.pane
+    && snapshotMatchesRequest(proof.live_source, request)
+    && /^[a-f0-9]{64}$/i.test(proof.prior_request.sha256)
+    && /^[a-f0-9]{64}$/i.test(proof.prior_request.handover_sha256)
+    && /^[a-f0-9]{64}$/i.test(proof.prior_receipt.sha256)
+    && basename(proof.prior_request.archive) === proof.prior_request.sha256
+    && Boolean(proof.prior_request.task && proof.prior_request.handover);
+}
+
 export function replacementMatchesRuntime(runtime: Runtime | undefined, request: HandoverReplacementRequest) {
+  const proof = request.supersession;
+  if (proof) return supersessionPlacementMatches(runtime, proof) && supersessionSessionMatches(runtime, proof) && supersessionEvidenceMatches(request, proof);
   if (!request.legacy_source) return canonicalSourceMatchesRuntime(runtime, request.source);
   return unboundLegacyRuntime(runtime, request.source.pane) && snapshotMatchesRequest(request.legacy_source, request);
 }
@@ -270,9 +316,10 @@ async function publishCreateOnly(file: string, content: string) {
   } finally { await rm(temporary, { force: true }); }
 }
 
-const replacementFlags = ["--legacy-source-bootstrap", "--handover", "--authorization", "--takeover-task", "--source-pi-session", "--source-pi-session-path", "--source-herdr-session", "--source-pane", "--herdr-session", "--target-pane", "--target-cwd"];
+const replacementFlags = ["--supersede-consumed", "--legacy-source-bootstrap", "--handover", "--authorization", "--takeover-task", "--source-pi-session", "--source-pi-session-path", "--source-herdr-session", "--source-pane", "--herdr-session", "--target-pane", "--target-cwd"];
 function validateReplacementArgs(args: string[]) {
-  if (args.some((arg) => arg.startsWith("--") && !replacementFlags.includes(arg))) throw new Error("Use `handover replace <main-seat> [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>`.");
+  if (args.some((arg) => arg.startsWith("--") && !replacementFlags.includes(arg))) throw new Error("Use `handover replace <main-seat> [--supersede-consumed] [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>`.");
+  if (has(args, "--supersede-consumed") && has(args, "--legacy-source-bootstrap")) throw new Error("Consumed replacement supersession cannot use legacy source bootstrap.");
 }
 
 async function currentReplacementHandover(root: string, resolved: string, args: string[]) {
@@ -303,12 +350,13 @@ function assertReplacementSource(record: Seat, source: HandoverReplacementReques
 
 async function prepareReplacement(root: string, resolved: string, args: string[]) {
   validateReplacementArgs(args);
-  const legacy = args.includes("--legacy-source-bootstrap"), handover = await currentReplacementHandover(root, resolved, args);
+  const legacy = has(args, "--legacy-source-bootstrap"), supersede = has(args, "--supersede-consumed");
+  const handover = await currentReplacementHandover(root, resolved, args);
   const task = nonEmpty(words(args, "--takeover-task"), "--takeover-task");
   const { record } = await exactMainTakeoverTask(root, resolved, task);
   const source = replacementSource(args), target = replacementTarget(args, record, source);
-  assertReplacementSource(record, source, legacy);
-  return { legacy, handover, task, source, target };
+  if (!supersede) assertReplacementSource(record, source, legacy);
+  return { legacy, supersede, handover, task, record, source, target };
 }
 
 function replacementRequest(resolved: string, intent: Awaited<ReturnType<typeof prepareReplacement>>, authorization: { id: string; hash: string }, legacySource: HandoverReplacementRequest["legacy_source"], dependencies: HandoverReplacementDependencies): HandoverReplacementRequest {
@@ -320,6 +368,322 @@ function replacementRequest(resolved: string, intent: Awaited<ReturnType<typeof
   };
 }
 
+type ReplacementLaunchReceipt = {
+  schema?: string;
+  seat?: string;
+  tasks?: string[];
+  pi_session?: string;
+  pi_session_path?: string;
+  herdr_session?: string;
+  pane?: string;
+  handover_replacement?: { request?: HandoverReplacementRequest; successor_session?: string };
+};
+
+type ConsumedReplacement = {
+  request: HandoverReplacementRequest;
+  requestBytes: string;
+  requestHash: string;
+  receiptBytes: string;
+  receiptHash: string;
+  receiptPath: string;
+  canonical: NonNullable<NonNullable<HandoverReplacementRequest["supersession"]>["canonical_source"]>;
+  archive: string;
+};
+
+function validConsumedRequest(request: HandoverReplacementRequest, resolved: string) {
+  return request.schema === "atdd-flow/context-handover-replacement-request/v1" && request.seat === resolved
+    && Boolean(request.task && request.handover?.id && request.handover.sha256);
+}
+
+async function readConsumedRequest(file: string, resolved: string) {
+  let bytes: string;
+  try { bytes = await readFile(file, "utf8"); }
+  catch { throw new Error(`Consumed Path-A replacement request does not exist for ${resolved}.`); }
+  let request: HandoverReplacementRequest;
+  try { request = yaml.parse<HandoverReplacementRequest>(bytes); }
+  catch { throw new Error(`Consumed Path-A replacement request is malformed for ${resolved}.`); }
+  if (!validConsumedRequest(request, resolved)) throw new Error(`Consumed Path-A replacement request is invalid for ${resolved}.`);
+  return { bytes, request };
+}
+
+function completeCanonicalRuntime(intent: Awaited<ReturnType<typeof prepareReplacement>>) {
+  const runtime = intent.record.runtime, locator = runtime?.addresses.herdr;
+  if (runtime?.application !== "herdr" || typeof locator === "string" || !locator
+    || !runtime.pi_session || !runtime.pi_session_path || !runtime.launch_receipt) {
+    throw new Error("Consumed Path-A replacement requires a complete canonical main runtime receipt.");
+  }
+  return { runtime, locator };
+}
+
+function assertCanonicalPlacement(intent: Awaited<ReturnType<typeof prepareReplacement>>, request: HandoverReplacementRequest, locator: { session: string; pane: string }) {
+  if (locator.session !== intent.target.herdr_session || locator.pane !== intent.target.pane
+    || request.target?.herdr_session !== locator.session || request.target.pane !== locator.pane
+    || resolve(request.target.cwd) !== resolve(intent.record.worktree)) {
+    throw new Error("Consumed Path-A replacement does not match the unchanged canonical main runtime and placement.");
+  }
+  if (intent.handover.supersedes !== request.handover.id) throw new Error("Consumed Path-A replacement does not match the current handover lineage.");
+}
+
+function canonicalRuntimeForSupersession(intent: Awaited<ReturnType<typeof prepareReplacement>>, request: HandoverReplacementRequest) {
+  const { runtime, locator } = completeCanonicalRuntime(intent);
+  assertCanonicalPlacement(intent, request, locator);
+  return {
+    pi_session: runtime.pi_session!, pi_session_path: runtime.pi_session_path!,
+    herdr_session: locator.session, pane: locator.pane, cwd: resolve(intent.record.worktree), launch_receipt: runtime.launch_receipt!,
+  };
+}
+
+async function assertTerminalPriorTask(root: string, projectName: string, taskId: string) {
+  const priorTask = await readYaml<Task>(paths(root).taskFile(projectName, taskId));
+  if (priorTask.schema !== "atdd-workflow/task/v1" || !terminal(priorTask)) {
+    throw new Error("Consumed Path-A replacement requires its prior takeover task to be terminal.");
+  }
+}
+
+async function readReplacementReceipt(path: string) {
+  try {
+    const bytes = await readFile(path, "utf8");
+    return { bytes, receipt: yaml.parse<ReplacementLaunchReceipt>(bytes) };
+  } catch { throw new Error("Consumed Path-A replacement requires its immutable prior launch receipt."); }
+}
+
+function receiptMatchesCanonical(receipt: ReplacementLaunchReceipt, resolved: string, canonical: ConsumedReplacement["canonical"]) {
+  return receipt.schema === "atdd-flow/pi-runtime-launch-receipt/v1" && receipt.seat === resolved
+    && receipt.pi_session === canonical.pi_session && receipt.pi_session_path === canonical.pi_session_path
+    && receipt.herdr_session === canonical.herdr_session && receipt.pane === canonical.pane;
+}
+
+function receiptProvesRequest(receipt: ReplacementLaunchReceipt, request: HandoverReplacementRequest, canonical: ConsumedReplacement["canonical"]) {
+  return Array.isArray(receipt.tasks) && receipt.tasks.includes(request.task)
+    && receipt.handover_replacement?.successor_session === canonical.pi_session
+    && JSON.stringify(receipt.handover_replacement.request) === JSON.stringify(request);
+}
+
+async function consumedReplacement(root: string, resolved: string, file: string, intent: Awaited<ReturnType<typeof prepareReplacement>>) {
+  const { bytes: requestBytes, request } = await readConsumedRequest(file, resolved);
+  const canonical = canonicalRuntimeForSupersession(intent, request);
+  await assertTerminalPriorTask(root, intent.record.project, request.task);
+  const { bytes: receiptBytes, receipt } = await readReplacementReceipt(canonical.launch_receipt);
+  if (!receiptMatchesCanonical(receipt, resolved, canonical) || !receiptProvesRequest(receipt, request, canonical)) {
+    throw new Error("Consumed Path-A replacement prior receipt does not prove the exact request, task, and canonical successor.");
+  }
+  const requestHash = createHash("sha256").update(requestBytes).digest("hex");
+  const receiptHash = createHash("sha256").update(receiptBytes).digest("hex");
+  return {
+    request, requestBytes, requestHash, receiptBytes, receiptHash, canonical,
+    receiptPath: canonical.launch_receipt,
+    archive: join(root, ".atdd-flow", "handover-replacement-archive", encodeURIComponent(resolved), requestHash),
+  } satisfies ConsumedReplacement;
+}
+
+function supersessionManifest(resolved: string, file: string, consumed: ConsumedReplacement) {
+  return yaml.print({
+    schema: "atdd-flow/context-handover-replacement-supersession/v1", seat: resolved,
+    prior_request: { path: file, sha256: consumed.requestHash, task: consumed.request.task, handover: consumed.request.handover.id, handover_sha256: consumed.request.handover.sha256 },
+    prior_receipt: { path: consumed.receiptPath, sha256: consumed.receiptHash, successor_session: consumed.canonical.pi_session },
+  });
+}
+
+async function archiveMatches(destination: string, requestBytes: string, receiptBytes: string, manifest: string) {
+  try {
+    const [files, request, receipt, proof] = await Promise.all([
+      readdir(destination), readFile(join(destination, "request.yaml"), "utf8"),
+      readFile(join(destination, "launch-receipt.yaml"), "utf8"), readFile(join(destination, "supersession.yaml"), "utf8"),
+    ]);
+    return files.sort().join("\n") === ["launch-receipt.yaml", "request.yaml", "supersession.yaml"].join("\n")
+      && request === requestBytes && receipt === receiptBytes && proof === manifest;
+  } catch { return false; }
+}
+
+async function restoreActive(file: string, priorBytes: string) {
+  let current: string | undefined;
+  try { current = await readFile(file, "utf8"); } catch { /* Restore an absent active request below. */ }
+  if (current === priorBytes) return;
+  const rollback = join(dirname(file), `.${basename(file)}.${crypto.randomUUID()}.rollback.tmp`);
+  try {
+    await writeFile(rollback, priorBytes, { encoding: "utf8", flag: "wx" });
+    await rename(rollback, file);
+  } finally { await rm(rollback, { force: true }); }
+}
+
+function supersedingRequest(resolved: string, file: string, intent: Awaited<ReturnType<typeof prepareReplacement>>, authorization: { id: string; hash: string }, consumed: ConsumedReplacement, liveSource: LiveSourceProof, dependencies: HandoverReplacementDependencies): HandoverReplacementRequest {
+  return {
+    ...replacementRequest(resolved, intent, authorization, undefined, dependencies),
+    supersession: {
+      prior_request: {
+        path: file, sha256: consumed.requestHash, task: consumed.request.task,
+        handover: consumed.request.handover.id, handover_sha256: consumed.request.handover.sha256, archive: consumed.archive,
+      },
+      prior_receipt: { path: consumed.receiptPath, sha256: consumed.receiptHash, successor_session: consumed.canonical.pi_session },
+      canonical_source: consumed.canonical, live_source: liveSource,
+    },
+  };
+}
+
+type SupersessionTransaction = {
+  consumed: ConsumedReplacement;
+  archiveStage: string;
+  successorStage: string;
+  archiveExisted: boolean;
+  activeSwapAttempted: boolean;
+};
+
+async function stageSupersession(file: string, request: HandoverReplacementRequest, consumed: ConsumedReplacement, manifest: string, dependencies: HandoverReplacementDependencies) {
+  const archiveParent = dirname(consumed.archive);
+  const archiveStage = join(archiveParent, `.${basename(consumed.archive)}.${crypto.randomUUID()}.tmp`);
+  const successorStage = join(dirname(file), `.${basename(file)}.${crypto.randomUUID()}.tmp`);
+  await mkdir(archiveParent, { recursive: true });
+  try {
+    await mkdir(archiveStage);
+    const successorWrite = dependencies.publish
+      ? dependencies.publish(successorStage, yaml.print(request))
+      : writeFile(successorStage, yaml.print(request), { encoding: "utf8", flag: "wx" });
+    await Promise.all([
+      writeFile(join(archiveStage, "request.yaml"), consumed.requestBytes, { encoding: "utf8", flag: "wx" }),
+      writeFile(join(archiveStage, "launch-receipt.yaml"), consumed.receiptBytes, { encoding: "utf8", flag: "wx" }),
+      writeFile(join(archiveStage, "supersession.yaml"), manifest, { encoding: "utf8", flag: "wx" }),
+      successorWrite,
+    ]);
+    return { archiveStage, successorStage };
+  } catch (error) {
+    await rm(archiveStage, { recursive: true, force: true });
+    await rm(successorStage, { force: true });
+    throw error;
+  }
+}
+
+async function publishArchiveEvidence(transaction: SupersessionTransaction, manifest: string, dependencies: HandoverReplacementDependencies) {
+  const { consumed, archiveStage, archiveExisted } = transaction;
+  if (archiveExisted) {
+    if (!await archiveMatches(consumed.archive, consumed.requestBytes, consumed.receiptBytes, manifest)) {
+      throw new Error("Consumed Path-A replacement archive collides with different immutable evidence.");
+    }
+    return;
+  }
+  await (dependencies.publishArchive ?? rename)(archiveStage, consumed.archive);
+  if (!await archiveMatches(consumed.archive, consumed.requestBytes, consumed.receiptBytes, manifest)) {
+    throw new Error("Consumed Path-A replacement archive publication was incomplete.");
+  }
+}
+
+async function rollbackSupersession(file: string, transaction: SupersessionTransaction) {
+  if (transaction.activeSwapAttempted) await restoreActive(file, transaction.consumed.requestBytes);
+  if (!transaction.archiveExisted) await rm(transaction.consumed.archive, { recursive: true, force: true });
+}
+
+async function cleanupSupersession(transaction: SupersessionTransaction | undefined) {
+  if (!transaction) return;
+  await rm(transaction.archiveStage, { recursive: true, force: true });
+  await rm(transaction.successorStage, { force: true });
+}
+
+const supersessionLockSchema = "atdd-flow/handover-replacement-supersession-lock/v1" as const;
+type SupersessionLock = { schema: typeof supersessionLockSchema; seat: string; active_request_sha256: string; pid: number; token: string };
+const errorCode = (error: unknown) => typeof error === "object" && error !== null && "code" in error ? String((error as { code: unknown }).code) : undefined;
+
+function validSupersessionLock(value: unknown, resolved: string, activeHash: string): value is SupersessionLock {
+  const record = object(value);
+  return record?.schema === supersessionLockSchema && record.seat === resolved && record.active_request_sha256 === activeHash
+    && Number.isInteger(record.pid) && Number(record.pid) > 0 && typeof record.token === "string" && Boolean(record.token);
+}
+
+function liveProcess(pid: number) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) {
+    if (errorCode(error) === "ESRCH") return false;
+    if (errorCode(error) === "EPERM") return true;
+    throw error;
+  }
+}
+
+/**
+ * Recovery keeps the lock fail-closed without requiring a manual Desk edit.
+ * The active-request hash binds a dead owner to the immutable request it saw.
+ * A live PID, EPERM result, malformed record, or changed identity always refuses.
+ * A hard-link recovery marker is create-only, so one contender owns cleanup.
+ * New contenders observe that marker before attempting ordinary acquisition.
+ * A contender already between its marker check and `wx` may win the lock, but
+ * the recovery owner then loses its own `wx`; in either ordering only one wins.
+ * The marker also closes the remove/reacquire gap for later contenders.
+ */
+async function createSupersessionLock(lock: string, content: string) {
+  try { await writeFile(lock, content, { encoding: "utf8", flag: "wx" }); return true; }
+  catch (error) {
+    if (errorCode(error) === "EEXIST") return false;
+    throw error;
+  }
+}
+
+async function staleSupersessionLock(lock: string, resolved: string, activeHash: string) {
+  const observed = await readFile(lock, "utf8");
+  let prior: unknown;
+  try { prior = yaml.parse<unknown>(observed); }
+  catch { throw new Error(`Path-A replacement supersession lock is malformed for ${resolved}.`); }
+  if (!validSupersessionLock(prior, resolved, activeHash)) throw new Error(`Path-A replacement supersession lock identity changed for ${resolved}.`);
+  if (liveProcess(prior.pid)) throw new Error(`A Path-A replacement supersession is already in progress for ${resolved}.`);
+  return observed;
+}
+
+async function recoverSupersessionLock(file: string, lock: string, recovery: string, resolved: string, activeHash: string, observed: string, content: string) {
+  try { await link(lock, recovery); }
+  catch { throw new Error(`Path-A replacement lock recovery is already in progress for ${resolved}.`); }
+  try {
+    const [currentLock, currentActive] = await Promise.all([readFile(lock, "utf8"), readFile(file, "utf8")]);
+    if (currentLock !== observed || createHash("sha256").update(currentActive).digest("hex") !== activeHash) {
+      throw new Error(`Path-A replacement supersession lock changed during recovery for ${resolved}.`);
+    }
+    await rm(lock);
+    if (!await createSupersessionLock(lock, content)) throw new Error(`A Path-A replacement supersession is already in progress for ${resolved}.`);
+  } finally { await rm(recovery, { force: true }); }
+}
+
+async function acquireSupersessionLock(file: string, resolved: string) {
+  const lock = `${file}.lock`, recovery = `${lock}.recovery`;
+  const activeHash = createHash("sha256").update(await readFile(file, "utf8")).digest("hex");
+  const record: SupersessionLock = { schema: supersessionLockSchema, seat: resolved, active_request_sha256: activeHash, pid: process.pid, token: crypto.randomUUID() };
+  const content = yaml.print(record);
+  if (await exists(recovery)) throw new Error(`Path-A replacement lock recovery is already in progress for ${resolved}.`);
+  if (await createSupersessionLock(lock, content)) return { lock, content };
+  if (await exists(recovery)) throw new Error(`Path-A replacement lock recovery is already in progress for ${resolved}.`);
+  const observed = await staleSupersessionLock(lock, resolved, activeHash);
+  await recoverSupersessionLock(file, lock, recovery, resolved, activeHash, observed, content);
+  return { lock, content };
+}
+
+async function releaseSupersessionLock(lock: string, content: string) {
+  let current: string;
+  try { current = await readFile(lock, "utf8"); } catch { return; }
+  if (current === content) await rm(lock);
+}
+
+async function supersedeConsumedReplacement(root: string, resolved: string, file: string, intent: Awaited<ReturnType<typeof prepareReplacement>>, args: string[], dependencies: HandoverReplacementDependencies) {
+  await mkdir(dirname(file), { recursive: true });
+  const ownedLock = await acquireSupersessionLock(file, resolved);
+  let transaction: SupersessionTransaction | undefined;
+  try {
+    const consumed = await consumedReplacement(root, resolved, file, intent);
+    const authorization = await resolveExactSessionAdoptionAuthorization(root, nonEmpty(words(args, "--authorization"), "--authorization"), {
+      seat: resolved, pi_session: intent.source.pi_session, pi_session_path: intent.source.pi_session_path,
+      source: { herdr_session: intent.source.herdr_session, pane: intent.source.pane }, target: intent.target,
+    });
+    const liveSource = await verifyLegacySource(intent.source, intent.target, authorization.hash, dependencies);
+    const request = supersedingRequest(resolved, file, intent, authorization, consumed, liveSource, dependencies);
+    const manifest = supersessionManifest(resolved, file, consumed);
+    const staging = await stageSupersession(file, request, consumed, manifest, dependencies);
+    transaction = { consumed, ...staging, archiveExisted: await exists(consumed.archive), activeSwapAttempted: false };
+    await publishArchiveEvidence(transaction, manifest, dependencies);
+    transaction.activeSwapAttempted = true;
+    await (dependencies.replaceActive ?? rename)(transaction.successorStage, file);
+    console.log(`Recorded superseding Path-A replacement request for ${resolved}.`);
+  } catch (error) {
+    if (transaction) await rollbackSupersession(file, transaction);
+    throw error;
+  } finally {
+    await cleanupSupersession(transaction);
+    await releaseSupersessionLock(ownedLock.lock, ownedLock.content);
+  }
+}
+
 /**
  * Creates the single immutable intent that an old Pi may observe before it voluntarily exits.
  * It deliberately does not stop, bind, attach, project, or launch any process.
@@ -327,7 +691,8 @@ function replacementRequest(resolved: string, intent: Awaited<ReturnType<typeof
 export async function requestHandoverReplacement(root: string, address: string, args: string[], dependencies: HandoverReplacementDependencies = {}) {
   const resolved = await canonicalAddress(root, address), intent = await prepareReplacement(root, resolved, args);
   const file = handoverReplacementPath(root, resolved);
-  if (intent.legacy && await exists(file)) throw new Error(`Path-A replacement request already exists for ${resolved}.`);
+  if (intent.supersede) return supersedeConsumedReplacement(root, resolved, file, intent, args, dependencies);
+  if (await exists(file)) throw new Error(`Path-A replacement request already exists for ${resolved}.`);
   const authorization = await resolveExactSessionAdoptionAuthorization(root, nonEmpty(words(args, "--authorization"), "--authorization"), {
     seat: resolved, pi_session: intent.source.pi_session, pi_session_path: intent.source.pi_session_path,
     source: { herdr_session: intent.source.herdr_session, pane: intent.source.pane }, target: intent.target,

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(",")}` : ""}`);
   }
 }