@afokapu/atdd-flow 0.3.47 → 0.3.49

package/extensions/pi/index.ts

@@ -7,6 +7,7 @@ import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsR
 import { paths, readYaml, type Seat } from "../../src/core";
 import { directiveNotice, nextDirective } from "../../src/tasks";
 import { runtimeStartupInstruction } from "../../src/collaboration-policy";
+import { contextHandoverThreshold, readHandoverReplacement } from "../../src/handover";
 
 type Thread = { id?: unknown; participants?: unknown; subject?: unknown };
 export type Mail = { id?: unknown; from?: unknown; to?: unknown; subject?: unknown; created_at?: unknown };
@@ -335,6 +336,36 @@ export default function (pi: ExtensionAPI) {
   const seat = process.env.ATDD_WORKFLOW_SEAT;
   if (!root || !seat) return;
   let runtime: ReturnType<typeof createPiRuntime> | undefined;
+  let handoverPrompted = false;
+  pi.on("turn_end", async (_event, ctx) => {
+    if (handoverPrompted) return;
+    const percent = ctx.getContextUsage()?.percent;
+    if (percent === null || percent === undefined) return;
+    try {
+      const threshold = await contextHandoverThreshold(root);
+      if (percent < threshold) return;
+      handoverPrompted = true;
+      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.`,
+        display: true, details: { seat, threshold, percent, authority: "handover" },
+      }, { triggerTurn: true, deliverAs: "followUp" });
+    } catch { /* Desk policy is re-read on the next safe boundary. */ }
+  });
+  pi.on("turn_end", async (_event, ctx) => {
+    const sourceSession = process.env.ATDD_FLOW_PI_SESSION;
+    if (!sourceSession) return;
+    try {
+      const request = await readHandoverReplacement(root, seat);
+      if (request.source.pi_session !== sourceSession) return;
+      pi.sendMessage({
+        customType: "atdd-flow-context-handover-replacement",
+        content: `SYSTEM: Validated Path-A request for ${seat} observed. The successor must not start until this Pi has shut down and Herdr reports the exact source pane released.`,
+        display: true, details: { seat, handover: request.handover.id, authority: "handover-replacement" },
+      }, { triggerTurn: true, deliverAs: "followUp" });
+      ctx.shutdown();
+    } catch { /* No validated replacement request exists for this source session. */ }
+  });
   pi.on("session_start", async (_event, ctx) => {
     runtime = createPiRuntime({ root, seat, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
       if (!sendIfOwned) return false;
@@ -359,6 +390,16 @@ export default function (pi: ExtensionAPI) {
       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. */ }
         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.47",
+  "version": "0.3.49",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -13,7 +13,7 @@ import { status } from "./overview";
 import { multiplexer } from "./multiplexer";
 import * as cleanup from "./ephemeral-resources";
 import * as ownerAlerts from "./owner-escalations";
-import { recordHandover, showHandover } from "./handover";
+import { recordHandover, requestHandoverReplacement, resumedHandoverReplacement, showHandover } from "./handover";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
 
@@ -38,6 +38,8 @@ 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 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>
   atdd-flow task transfer <project> <task-id> --to <main-or-named-coordinator> --reason <text> --by <actor> [--authorization <operator-message-id>]
@@ -120,7 +122,10 @@ async function main() {
     multiplexer: () => multiplexer(root, rest),
     describe: () => describe(root, required(rest[0], "address"), rest.slice(1)),
     checkpoint: () => checkpoint(root, required(rest[0], "address"), rest.slice(1)),
-    handover: () => rest[0] === "show" ? showHandover(root, required(rest[1], "address")) : recordHandover(root, required(rest[0], "address"), rest.slice(1)),
+    handover: () => rest[0] === "show" ? showHandover(root, required(rest[1], "address"))
+      : rest[0] === "replace" ? requestHandoverReplacement(root, required(rest[1], "address"), rest.slice(2))
+      : rest[0] === "resumed" ? resumedHandoverReplacement(root, required(rest[1], "address"))
+      : recordHandover(root, required(rest[0], "address"), rest.slice(1)),
     task: async () => {
       const [subcommand, projectName, taskId, ...tail] = rest;
       if (subcommand === "add") return tasks.add(root, required(projectName, "project"), required(taskId, "task id"), tail);

package/src/core.ts

@@ -19,6 +19,8 @@ export type Desk = {
   herdr_session?: string;
   /** Optional multiplexer housekeeping; inactive driver workspaces are closed only when enabled. */
   multiplexer?: { close_inactive?: boolean };
+  /** Context percentage at which Pi asks its seat to prepare a durable replacement handover. */
+  context_handover?: { threshold_percent?: number };
   /** Named commands that model portfolio entries may resolve through. */
   executables?: Record<string, string>;
   aliases?: Record<string, string>;

package/src/handover.ts

@@ -1,5 +1,10 @@
-import { readFile } from "node:fs/promises";
-import { atomicYaml, canonicalAddress, exists, has, now, paths, readYaml, required, seat, words } from "./core";
+import { createHash } from "node:crypto";
+import { link, mkdir, readFile, readdir, 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";
+import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
+import { readRuntimeState } from "./runtime-state";
 
 export type Handover = {
   schema: "atdd-workflow/handover/v1";
@@ -88,3 +93,282 @@ export async function showHandover(root: string, address: string) {
   if (!record) throw new Error(`No handover is recorded for ${resolved}.`);
   process.stdout.write(record.text.endsWith("\n") ? record.text : `${record.text}\n`);
 }
+
+export type HandoverReplacementRequest = {
+  schema: "atdd-flow/context-handover-replacement-request/v1";
+  seat: string;
+  task: string;
+  handover: { id: string; sha256: string };
+  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;
+  };
+  created_at: string;
+};
+
+export type HandoverReplacementDependencies = {
+  command?: (command: string[]) => Promise<string>;
+  at?: () => string;
+  publish?: (file: string, content: string) => Promise<void>;
+};
+
+export const handoverReplacementPath = (root: string, address: string) => join(root, ".atdd-flow", "handover-replacements", `${encodeURIComponent(address)}.yaml`);
+const nonEmpty = (value: string | undefined, flag: string) => required(value, flag).trim();
+
+/** The threshold is Desk policy, not an instruction from transient mail. */
+export async function contextHandoverThreshold(root: string) {
+  const value = (await desk(root)).context_handover?.threshold_percent ?? 80;
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1 || value > 100) throw new Error("context_handover.threshold_percent must be an integer from 1 through 100.");
+  return value;
+}
+
+export async function isExactMainSeat(root: string, record: Seat, address: string) {
+  if (record.address !== address || record.role !== "main" || address !== `main@${record.project}` || record.branch !== "main") return false;
+  const config = await project(root, record.project);
+  return Boolean(config.repository && resolve(record.worktree) === resolve(config.repository));
+}
+
+function unboundLegacyRuntime(runtime: Runtime | undefined, pane: string) {
+  const locator = runtime?.addresses.herdr;
+  return runtime?.application === "herdr" && typeof locator === "string" && locator === pane
+    && !runtime.pi_session && !runtime.pi_session_path && !runtime.launch_receipt;
+}
+
+function snapshotMatchesRequest(snapshot: NonNullable<HandoverReplacementRequest["legacy_source"]>, request: HandoverReplacementRequest) {
+  return snapshot.authorization_hash === request.authorization.hash && snapshot.pi_session === request.source.pi_session
+    && snapshot.pi_session_path === request.source.pi_session_path && snapshot.herdr_session === request.source.herdr_session
+    && snapshot.pane === request.source.pane && snapshot.cwd === request.target.cwd && Boolean(snapshot.agent) && Boolean(snapshot.verified_at);
+}
+
+function canonicalSourceMatchesRuntime(runtime: Runtime | undefined, source: HandoverReplacementRequest["source"]) {
+  const locator = runtime?.addresses.herdr;
+  return typeof locator !== "string" && locator?.session === source.herdr_session && locator.pane === source.pane
+    && runtime?.pi_session === source.pi_session && runtime.pi_session_path === source.pi_session_path;
+}
+
+export function replacementMatchesRuntime(runtime: Runtime | undefined, request: HandoverReplacementRequest) {
+  if (!request.legacy_source) return canonicalSourceMatchesRuntime(runtime, request.source);
+  return unboundLegacyRuntime(runtime, request.source.pane) && snapshotMatchesRequest(request.legacy_source, request);
+}
+
+export async function mainLaunchEligible(root: string, record: Seat, address: string, task: Task) {
+  return task.status === "todo" && !task.blocker && task.coordinator === address && task.assignee === address
+    && await isExactMainSeat(root, record, address);
+}
+
+export async function replacementForMainLaunch(root: string, record: Seat, address: string) {
+  if (!await isExactMainSeat(root, record, address)) return undefined;
+  const request = await readHandoverReplacement(root, address).catch(() => {
+    throw new Error(`${address} requires one validated Path-A replacement request; refusing runtime launch.`);
+  });
+  const task = await readYaml<Task>(paths(root).taskFile(record.project, request.task));
+  if (!replacementMatchesRuntime(record.runtime, request) || !await mainLaunchEligible(root, record, address, task)) {
+    throw new Error("Path-A replacement source tuple no longer matches the recorded runtime or ready main takeover task.");
+  }
+  return { request, task };
+}
+
+export function assertReplacementTarget(request: HandoverReplacementRequest, herdrSession: string, pane: string, worktree: string) {
+  if (request.target.herdr_session !== herdrSession || request.target.pane !== pane || request.target.cwd !== resolve(worktree)) {
+    throw new Error("Path-A replacement request does not match the exact released target tuple.");
+  }
+}
+
+async function exactMainTakeoverTask(root: string, address: string, id: string) {
+  const record = await seat(root, address);
+  if (!await isExactMainSeat(root, record, address)) {
+    throw new Error(`Path-A replacement requires exact main@${record.project} primary-main topology.`);
+  }
+  let files: string[];
+  try { files = await readdir(paths(root).tasks(record.project)); }
+  catch { throw new Error(`Path-A replacement requires one ready self-assigned main takeover task for ${address}.`); }
+  const ready = (await Promise.all(files.filter((file) => file.endsWith(".yaml") && !file.endsWith(".reviews.yaml")).map(async (file) => {
+    const taskId = file.slice(0, -5);
+    const task = await readYaml<Task>(paths(root).taskFile(record.project, taskId));
+    if (task.schema !== "atdd-workflow/task/v1" || task.status !== "todo" || task.blocker || task.coordinator !== address || task.assignee !== address) return undefined;
+    const dependencies = await Promise.all((task.depends_on ?? []).map(async (dependency) => {
+      try { return terminal(await readYaml<Pick<Task, "status">>(paths(root).taskFile(record.project, dependency))); }
+      catch { return false; }
+    }));
+    return dependencies.every(Boolean) ? taskId : undefined;
+  }))).filter((entry): entry is string => Boolean(entry));
+  if (ready.length !== 1 || ready[0] !== id) throw new Error(`Path-A replacement requires exactly one ready self-assigned main takeover task; found: ${ready.join(", ") || "none"}.`);
+  return { record };
+}
+
+type LegacyPaneObservation = { pane: string; agent: string; sessionPath: string; cwd: string };
+const object = (value: unknown): Record<string, unknown> | undefined => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const text = (value: unknown) => typeof value === "string" ? value : undefined;
+function result(value: unknown) { const root = object(value); return object(root?.result) ?? root; }
+function herdr(session: string, ...args: string[]) { return ["herdr", "--session", session, ...args]; }
+
+function legacyPaneObservation(raw: string): LegacyPaneObservation {
+  const value = JSON.parse(raw), pane = object(result(value)?.pane) ?? result(value), session = object(pane?.agent_session);
+  const observation = { pane: text(pane?.pane_id), agent: text(pane?.agent), sessionPath: session?.kind === "path" ? text(session.value) : undefined, cwd: text(pane?.cwd) };
+  if (!observation.pane || !observation.agent || !observation.sessionPath || !observation.cwd) throw new Error("Legacy source bootstrap requires complete live Herdr pane/session/path/cwd evidence.");
+  return observation as LegacyPaneObservation;
+}
+
+function assertLegacyPane(observed: LegacyPaneObservation, source: HandoverReplacementRequest["source"], cwd: string) {
+  const match = basename(observed.sessionPath).match(/_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i);
+  if (observed.pane !== source.pane || resolve(observed.sessionPath) !== source.pi_session_path || match?.[1] !== source.pi_session || resolve(observed.cwd) !== cwd) {
+    throw new Error("Legacy source bootstrap live pane/session/path/cwd does not match the authorized source tuple.");
+  }
+}
+
+function legacyAgentName(raw: string, source: HandoverReplacementRequest["source"], cwd: string) {
+  const value = JSON.parse(raw), agent = object(result(value)?.agent) ?? result(value), session = object(agent?.agent_session);
+  const name = text(agent?.name), sessionPath = session?.kind === "path" ? text(session.value) : undefined, agentCwd = text(agent?.cwd);
+  if (!name || text(agent?.pane_id) !== source.pane || text(agent?.agent) !== "pi" || !sessionPath || resolve(sessionPath) !== source.pi_session_path
+    || !agentCwd || resolve(agentCwd) !== cwd) throw new Error("Legacy source bootstrap Pi agent does not match the authorized source pane/session/path/cwd.");
+  return name;
+}
+
+function assertSinglePiWriter(raw: string) {
+  const value = JSON.parse(raw), report = object(result(value)?.process_info) ?? result(value);
+  const processes = Array.isArray(report?.foreground_processes) ? report.foreground_processes.map(object).filter(Boolean) as Record<string, unknown>[] : [];
+  const pi = processes.filter((process) => text(process.name) === "pi" || text(process.argv0)?.endsWith("/pi") || text(process.argv0) === "pi" || /(^|\/)pi(?:\s|$)/.test(text(process.cmdline) ?? ""));
+  if (pi.length !== 1) throw new Error("Legacy source bootstrap requires exactly one live Pi writer on the authorized source pane.");
+}
+
+async function verifyLegacySource(source: HandoverReplacementRequest["source"], target: HandoverReplacementRequest["target"], authorizationHash: string, dependencies: HandoverReplacementDependencies) {
+  const command = dependencies.command ?? runOutput;
+  const pane = legacyPaneObservation(await command(herdr(source.herdr_session, "pane", "get", source.pane)));
+  assertLegacyPane(pane, source, target.cwd);
+  const [agentRaw, processRaw] = await Promise.all([
+    command(herdr(source.herdr_session, "agent", "get", source.pane)),
+    command(herdr(source.herdr_session, "pane", "process-info", "--pane", source.pane)),
+  ]);
+  const agent = legacyAgentName(agentRaw, source, target.cwd);
+  assertSinglePiWriter(processRaw);
+  return { authorization_hash: authorizationHash, ...source, cwd: target.cwd, agent, verified_at: dependencies.at?.() ?? now() };
+}
+
+function assertLegacySeat(record: Seat, source: HandoverReplacementRequest["source"]) {
+  const runtime = record.runtime, locator = runtime?.addresses.herdr;
+  if (!runtime || runtime.application !== "herdr" || typeof locator !== "string" || locator !== source.pane
+    || runtime.pi_session || runtime.pi_session_path || runtime.launch_receipt) {
+    throw new Error("Legacy source bootstrap requires the unchanged scalar Herdr placement without canonical runtime binding.");
+  }
+}
+
+async function publishCreateOnly(file: string, content: string) {
+  await mkdir(dirname(file), { recursive: true });
+  const temporary = `${file}.${crypto.randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
+    await link(temporary, file);
+  } 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"];
+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>`.");
+}
+
+async function currentReplacementHandover(root: string, resolved: string, args: string[]) {
+  const handover = await recorded(root, resolved), handoverId = nonEmpty(words(args, "--handover"), "--handover");
+  if (!handover || handover.handover_id !== handoverId) throw new Error(`Path-A replacement requires the current validated handover ${handoverId} for ${resolved}.`);
+  return handover;
+}
+
+function replacementSource(args: string[]) {
+  return {
+    pi_session: nonEmpty(words(args, "--source-pi-session"), "--source-pi-session"), pi_session_path: resolve(nonEmpty(words(args, "--source-pi-session-path"), "--source-pi-session-path")),
+    herdr_session: nonEmpty(words(args, "--source-herdr-session"), "--source-herdr-session"), pane: nonEmpty(words(args, "--source-pane"), "--source-pane"),
+  };
+}
+
+function replacementTarget(args: string[], record: Seat, source: HandoverReplacementRequest["source"]) {
+  const cwd = resolve(nonEmpty(words(args, "--target-cwd"), "--target-cwd"));
+  if (cwd !== resolve(record.worktree)) throw new Error("Path-A replacement target CWD must be the exact canonical main worktree.");
+  const target = { herdr_session: nonEmpty(words(args, "--herdr-session"), "--herdr-session"), pane: nonEmpty(words(args, "--target-pane"), "--target-pane"), cwd };
+  if (target.herdr_session !== source.herdr_session || target.pane !== source.pane) throw new Error("Path-A replacement target must be the exact released source pane.");
+  return target;
+}
+
+function assertReplacementSource(record: Seat, source: HandoverReplacementRequest["source"], legacy: boolean) {
+  if (legacy) return assertLegacySeat(record, source);
+  if (!canonicalSourceMatchesRuntime(record.runtime, source)) throw new Error("Path-A replacement source tuple must exactly match the recorded live runtime.");
+}
+
+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 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 };
+}
+
+function replacementRequest(resolved: string, intent: Awaited<ReturnType<typeof prepareReplacement>>, authorization: { id: string; hash: string }, legacySource: HandoverReplacementRequest["legacy_source"], dependencies: HandoverReplacementDependencies): HandoverReplacementRequest {
+  return {
+    schema: "atdd-flow/context-handover-replacement-request/v1", seat: resolved, task: intent.task,
+    handover: { id: intent.handover.handover_id, sha256: createHash("sha256").update(intent.handover.text).digest("hex") },
+    authorization, source: intent.source, target: intent.target,
+    ...(legacySource ? { legacy_source: legacySource } : {}), created_at: dependencies.at?.() ?? now(),
+  };
+}
+
+/**
+ * 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.
+ */
+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}.`);
+  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 legacySource = intent.legacy ? await verifyLegacySource(intent.source, intent.target, authorization.hash, dependencies) : undefined;
+  const request = replacementRequest(resolved, intent, authorization, legacySource, dependencies);
+  await (dependencies.publish ?? publishCreateOnly)(file, yaml.print(request));
+  console.log(`Recorded Path-A replacement request for ${resolved}.`);
+}
+
+/** Reports only a live receipt reconciliation; source archival remains an external, post-proof operation. */
+export async function readHandoverReplacement(root: string, address: string) {
+  const request = await readYaml<HandoverReplacementRequest>(handoverReplacementPath(root, address));
+  if (request.schema !== "atdd-flow/context-handover-replacement-request/v1" || request.seat !== address) throw new Error(`Invalid Path-A replacement request for ${address}.`);
+  return request;
+}
+
+export async function resumedHandoverReplacement(root: string, address: string) {
+  const resolved = await canonicalAddress(root, address);
+  const [request, record] = await Promise.all([readHandoverReplacement(root, resolved), seat(root, resolved)]);
+  const runtime = record.runtime;
+  const locator = runtime?.addresses.herdr;
+  const receipt = runtime?.launch_receipt && await exists(runtime.launch_receipt) ? await readYaml<Record<string, unknown>>(runtime.launch_receipt) : undefined;
+  const replacement = receipt?.handover_replacement as Record<string, unknown> | undefined;
+  const runtimeState = await readRuntimeState(root, resolved);
+  const verified = [
+    request.schema === "atdd-flow/context-handover-replacement-request/v1" && request.seat === resolved,
+    runtime?.application === "herdr" && runtime.wake === "native",
+    runtime?.pi_session !== request.source.pi_session && Boolean(runtime?.pi_session_path),
+    typeof locator !== "string" && locator?.session === request.target.herdr_session && locator?.pane === request.target.pane,
+    replacement?.successor_session === runtime?.pi_session && replacement?.request && JSON.stringify(replacement.request) === JSON.stringify(request),
+    Boolean(runtimeState && runtimeState.seat === resolved),
+  ];
+  const discrepancies = [
+    !verified[0] ? "request" : undefined,
+    !verified[1] ? "native delivery" : undefined,
+    !verified[2] ? "fresh Pi session/JSONL path" : undefined,
+    !verified[3] ? "target tuple" : undefined,
+    !verified[4] ? "successor receipt" : undefined,
+    !verified[5] ? "fresh heartbeat" : undefined,
+  ].filter((entry): entry is string => Boolean(entry));
+  console.log(`RESUMED; verified ${verified.filter(Boolean).length}/${verified.length}; discrepancies: ${discrepancies.join(", ") || "none"}.`);
+  if (discrepancies.length) throw new Error("Path-A successor is not reconciled against the live Desk.");
+}

package/src/pi-runtime-launch.ts

@@ -0,0 +1,428 @@
+// URN: component:flow:e003:pi-runtime-launch:backend:integration
+// Tested-By:
+// - test:atdd-flow:context-handover-session-replacement
+// Runtime: bun
+// Purpose: Execute generic, exact Pi/Herdr runtime launch mechanics for seats.
+
+/**
+ * This module owns only generic launch mechanics shared by driver, coordinator,
+ * and Path-A main seats. Seat policy remains in seats and handover modules.
+ *
+ * The sequence is deliberately fail-closed:
+ * - resolve the canonical seat and one eligible task;
+ * - select an installed Pi model;
+ * - project and inspect exactly one Herdr pane;
+ * - refuse any occupied pane before process start;
+ * - verify the reported Pi session, JSONL path, pane and agent;
+ * - persist a create-only receipt; then bind the seat through the injected writer.
+ *
+ * The injected bind callback keeps this orchestration independent of seat
+ * mutation while preserving the public seats API and avoiding an import cycle.
+ * It does not stop a source, attach a terminal, apply a multiplexer, or select
+ * recipients. Path-A source/authorization policy is validated before this
+ * module is invoked and appears only as receipt provenance.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
+import { type Desk, type ModelCandidate, type ModelPortfolio, type Runtime, type Seat, atomicYaml, canonicalAddress, desk, exists, fill, modelPortfolio, now, paths, project, readYaml, required, runOutput, seat, words, yaml } from "./core";
+import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
+import { type Task, seatTasks, terminal } from "./tasks";
+import { projectHerdrSeat } from "./multiplexer";
+import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
+import { assertReplacementTarget, replacementForMainLaunch } from "./handover";
+
+export type PiRuntimeLaunchDependencies = {
+  select?: (input: ModelSelectionInput) => Promise<ModelSelectionResponse>;
+  command?: (command: string[]) => Promise<string>;
+  sessionId?: () => string;
+  at?: () => string;
+};
+
+type Bind = (root: string, address: string, args: string[], selectedModel?: string, wake?: Runtime["wake"], piSession?: string, piSessionPath?: string, launchReceipt?: string) => Promise<void>;
+
+export function availableModelCandidates(config: Desk, portfolio: ModelPortfolio) {
+  return portfolio.models.filter((candidate) => {
+    if (candidate.enabled === false) return false;
+    const executable = config.executables?.[candidate.executable] ?? candidate.executable;
+    return executable.includes("/") ? existsSync(executable) : Boolean(Bun.which(executable));
+  });
+}
+
+export function resolveModelCommand(config: Desk, candidate: ModelCandidate) {
+  return { agent: config.executables?.[candidate.executable] ?? candidate.executable, args: candidate.args ?? [] };
+}
+
+async function hasUniqueCoordinatorPlacement(root: string, record: Seat, expectedWorktree: string) {
+  try {
+    const peers = await Promise.all((await readdir(paths(root).seats(record.project))).map(async (name) => {
+      try { return await readYaml<Seat>(join(paths(root).seats(record.project), name, "seat.yaml")); }
+      catch { return undefined; }
+    }));
+    return !peers.some((peer) => peer && peer.address !== record.address && peer.role === "coordinator"
+      && (peer.branch === record.branch || resolve(peer.worktree) === expectedWorktree));
+  } catch { return false; }
+}
+
+function namedCoordinatorStream(config: Awaited<ReturnType<typeof project>>, record: Seat, address: string) {
+  if (record.address !== address || record.role !== "coordinator") return undefined;
+  const role = config.roles.coordinator;
+  if (!config.repository || !role?.worktree) return undefined;
+  if (role.address !== "coordinator.{name}@{project}" || role.branch !== "integration/{name}") return undefined;
+  const local = record.address.slice(0, -`@${config.project}`.length);
+  return local.match(/^coordinator\.([a-z0-9_-]+)$/)?.[1];
+}
+
+async function namedCoordinatorWorktree(root: string, record: Seat, address: string) {
+  const config = await project(root, record.project);
+  const stream = namedCoordinatorStream(config, record, address);
+  if (!stream || !config.repository || !config.roles.coordinator?.worktree) return undefined;
+  const worktree = resolve(fill(config.roles.coordinator.worktree, {
+    project: config.project, name: stream, worktree_root: config.worktree_root ?? "", repository: config.repository,
+  }));
+  if (record.branch !== `integration/${stream}` || resolve(record.worktree) !== worktree) return undefined;
+  return worktree !== resolve(config.repository) ? worktree : undefined;
+}
+
+async function isExactNamedCoordinator(root: string, record: Seat, address: string) {
+  const worktree = await namedCoordinatorWorktree(root, record, address);
+  return Boolean(worktree && await hasUniqueCoordinatorPlacement(root, record, worktree));
+}
+
+async function launchEligibleTasks(root: string, record: Seat, address: string) {
+  const coordinator = await isExactNamedCoordinator(root, record, address);
+  const tasks = await seatTasks(root, record.project, record.address);
+  const eligible = await Promise.all(tasks.map(async (entry) => {
+    const accountable = record.role === "driver" ? entry.task.assignee === record.address
+      : coordinator && entry.task.coordinator === record.address;
+    if (!accountable || entry.task.blocker) return undefined;
+    if (entry.task.status === "in_progress") return entry;
+    if (entry.task.status !== "todo") return undefined;
+    const dependencies = await Promise.all((entry.task.depends_on ?? []).map(async (id) => {
+      try { return terminal(await readYaml<{ status: Task["status"] }>(paths(root).taskFile(record.project, id))); }
+      catch { return false; }
+    }));
+    return dependencies.every(Boolean) ? entry : undefined;
+  }));
+  return eligible.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry));
+}
+
+async function chooseLaunchModel(root: string, config: Desk, record: Seat, portfolio: ModelPortfolio, select: (input: ModelSelectionInput) => Promise<ModelSelectionResponse> = selectModel) {
+  const candidates = availableModelCandidates(config, portfolio);
+  if (!candidates.length) throw new Error("No enabled model in models.yaml has an available executable.");
+  const work = (await seatTasks(root, record.project, record.address)).filter((entry) => !terminal(entry.task));
+  const selection = await select({
+    seat: { address: record.address, role: record.role, ...(record.purpose ? { purpose: record.purpose } : {}) },
+    tasks: work.map((entry) => ({
+      id: entry.id,
+      title: entry.task.title,
+      status: entry.task.status,
+      ...(entry.task.body ? { body: entry.task.body } : {}),
+      doneWhen: entry.task.done_when.map((item) => item.text),
+      ...(entry.task.blocker ? { blocker: entry.task.blocker } : {}),
+    })),
+    candidates,
+  });
+  if (!selection.available || selection.confidence < 0.75 || !candidates.some((entry) => entry.id === selection.selected_model)) {
+    const reason = !selection.available ? selection.reason : selection.confidence < 0.75
+      ? `Jev model selection confidence is low (${selection.confidence}).`
+      : `Jev selected a model outside the available portfolio: ${selection.selected_model}.`;
+    return { candidate: candidates[0]!, selection, fallback: reason };
+  }
+  return { candidate: required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`), selection };
+}
+
+/** Pi loads this extension inside its own process, so it can wake without host text injection. */
+export const piExtensionPath = () => join(import.meta.dir, "..", "extensions", "pi", "index.ts");
+
+type HerdrRequest = { session: string; pane: string; seat: string; root: string; piSession: string; sessionPath?: string; resume: boolean; args: string[] };
+type Command = (command: string[]) => Promise<string>;
+type PaneReport = { pane: string; agent?: string; status?: string; sessionPath?: string };
+type ProcessReport = { shell?: number; processes: Array<{ name?: string; argv0?: string; cmdline?: string }> };
+
+const object = (value: unknown): Record<string, unknown> | undefined => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const text = (value: unknown) => typeof value === "string" ? value : undefined;
+const number = (value: unknown) => typeof value === "number" ? value : undefined;
+function result(value: unknown) { const root = object(value); return object(root?.result) ?? root; }
+function paneReport(value: unknown): PaneReport {
+  const pane = object(result(value)?.pane) ?? result(value);
+  const session = object(pane?.agent_session);
+  const id = text(pane?.pane_id);
+  if (!id) throw new Error("Herdr pane get did not report a pane id.");
+  return {
+    pane: id,
+    ...(text(pane?.agent) ? { agent: text(pane?.agent) } : {}),
+    ...(text(pane?.agent_status) ? { status: text(pane?.agent_status) } : {}),
+    ...(session?.kind === "path" && text(session.value) ? { sessionPath: text(session.value) } : {}),
+  };
+}
+function processReport(value: unknown): ProcessReport {
+  const report = object(result(value)?.process_info) ?? result(value);
+  const processes = Array.isArray(report?.foreground_processes) ? report.foreground_processes.flatMap((entry) => {
+    const process = object(entry);
+    return process ? [{ name: text(process.name), argv0: text(process.argv0), cmdline: text(process.cmdline) }] : [];
+  }) : [];
+  return { ...(number(report?.shell_pid) ? { shell: number(report?.shell_pid) } : {}), processes };
+}
+function agentReport(value: unknown) {
+  const agent = object(result(value)?.agent) ?? result(value);
+  const name = text(agent?.name);
+  const pane = text(agent?.pane_id);
+  if (!name || !pane) throw new Error("Herdr agent get did not report agent name and pane id.");
+  return { name, pane, status: text(agent?.agent_status) ?? text(agent?.status) ?? text(agent?.state) };
+}
+function piProcess(processes: ProcessReport["processes"]) {
+  return processes.find((entry) => entry.name === "pi" || entry.argv0?.endsWith("/pi") || entry.argv0 === "pi" || /(^|\/)pi(?:\s|$)/.test(entry.cmdline ?? ""));
+}
+/** Pi's durable JSONL session filenames end in `_<session-id>.jsonl`. */
+function sessionIdFromPiJsonlPath(path: string) {
+  const match = basename(path).match(/_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i);
+  if (!match) throw new Error("Herdr did not report a Pi JSONL path with a documented session ID.");
+  return match[1]!;
+}
+function shellQuote(value: string) { return `'${value.replaceAll("'", "'\\''")}'`; }
+function agentName(address: string) { return `flow-${address.replace(/[^a-z0-9_-]/gi, "-").toLowerCase()}`.slice(0, 32); }
+function herdr(session: string, ...args: string[]) { return ["herdr", "--session", session, ...args]; }
+function startCommand(request: HerdrRequest) {
+  const session = request.resume ? ["--session", required(request.sessionPath, "a previously verified Pi session path")] : ["--session-id", request.piSession];
+  return herdr(request.session, "agent", "start", agentName(request.seat), "--kind", "pi", "--pane", request.pane, "--", ...session, ...request.args);
+}
+function receiptPath(root: string, piSession: string) { return join(root, ".atdd-flow", "runtime-launch", `${encodeURIComponent(piSession)}-${crypto.randomUUID().slice(0, 8)}.yaml`); }
+
+async function immutableSessionBackup(root: string, sessionPath: string, piSession: string) {
+  const content = await readFile(sessionPath);
+  const sha256 = createHash("sha256").update(content).digest("hex");
+  const backup = join(root, ".atdd-flow", "runtime-launch", "backups", `${encodeURIComponent(piSession)}-${crypto.randomUUID()}.jsonl`);
+  await mkdir(dirname(backup), { recursive: true });
+  await writeFile(backup, content, { flag: "wx" });
+  return { backup, sha256 };
+}
+
+/** Validated CLI intent kept separate from runtime discovery and side effects. */
+type LaunchOptions = {
+  requestedPane?: string;
+  herdrSession: string;
+  resume: boolean;
+  dryRun: boolean;
+  adoptedSessionPath?: string;
+  sourceHerdrSession?: string;
+  sourcePane?: string;
+  authorization?: string;
+  adopting: boolean;
+};
+
+type PreparedLaunch = Awaited<ReturnType<typeof prepareLaunch>>;
+type LaunchPlan = ReturnType<typeof buildLaunchPlan>;
+
+function optionalArgument(name: string, value?: string) { return value ? [name, value] : []; }
+
+/** Parse the closed launch grammar before reading or changing external state. */
+function parseLaunchOptions(args: string[]): LaunchOptions {
+  const requestedPane = words(args, "--pane");
+  const herdrSession = required(words(args, "--herdr-session"), "--herdr-session");
+  const resume = args.includes("--resume"), dryRun = args.includes("--dry-run");
+  const adoptedSessionPath = words(args, "--adopt-session");
+  const sourceHerdrSession = words(args, "--source-herdr-session"), sourcePane = words(args, "--source-pane");
+  const authorization = words(args, "--authorization");
+  const adoptionFields = [adoptedSessionPath, sourceHerdrSession, sourcePane, authorization];
+  const adopting = adoptionFields.some(Boolean);
+  const allowed = ["--herdr-session", herdrSession, "--resume", "--dry-run", ...optionalArgument("--pane", requestedPane),
+    ...optionalArgument("--adopt-session", adoptedSessionPath), ...optionalArgument("--source-herdr-session", sourceHerdrSession),
+    ...optionalArgument("--source-pane", sourcePane), ...optionalArgument("--authorization", authorization)];
+  if (args.some((argument) => !allowed.includes(argument))) throw new Error("Use `pi runtime launch <seat> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <owner-reference>]`.");
+  if (adopting && (resume || !adoptionFields.every(Boolean))) throw new Error("Exact-session adoption requires --adopt-session, --source-herdr-session, --source-pane, and --authorization without --resume.");
+  return { requestedPane, herdrSession, resume, dryRun, adoptedSessionPath, sourceHerdrSession, sourcePane, authorization, adopting };
+}
+
+/** Legacy resume is constrained to the seat's already-recorded Herdr location. */
+function existingPaneForResume(record: Seat, options: LaunchOptions) {
+  const existingHerdr = record.runtime?.addresses.herdr;
+  const pane = typeof existingHerdr === "object" ? existingHerdr.pane : undefined;
+  const session = typeof existingHerdr === "object" ? existingHerdr.session : undefined;
+  if (options.resume && ((options.requestedPane && options.requestedPane !== pane) || options.herdrSession !== session)) {
+    throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
+  }
+  return pane;
+}
+
+/** Preserve adopted and resumed identities; mint an ID only for a new launch. */
+function launchSessionId(record: Seat, options: LaunchOptions, dependencies: PiRuntimeLaunchDependencies) {
+  if (options.adopting) return sessionIdFromPiJsonlPath(required(options.adoptedSessionPath, "an exact adopted Pi session path"));
+  if (options.resume) return record.runtime?.pi_session;
+  return (dependencies.sessionId ?? (() => crypto.randomUUID()))();
+}
+
+/** Resolve authorization against the complete immutable source and target tuple. */
+async function adoptionAuthorization(root: string, resolved: string, record: Seat, options: LaunchOptions, piSession: string, adoptedPath?: string) {
+  if (!options.adopting) return undefined;
+  return resolveExactSessionAdoptionAuthorization(root, required(options.authorization, "an immutable operator authorization record"), {
+    seat: resolved, pi_session: piSession, pi_session_path: required(adoptedPath, "an exact adopted Pi session path"),
+    source: { herdr_session: required(options.sourceHerdrSession, "a source Herdr session"), pane: required(options.sourcePane, "a source pane") },
+    target: { herdr_session: options.herdrSession, pane: required(options.requestedPane, "--pane for exact-session adoption"), cwd: resolve(record.worktree) },
+  });
+}
+
+/** Resolve launch policy inputs without projecting, starting, or binding a pane. */
+async function prepareLaunch(root: string, address: string, args: string[], dependencies: PiRuntimeLaunchDependencies) {
+  const resolved = await canonicalAddress(root, address), record = await seat(root, resolved), config = await desk(root);
+  const options = parseLaunchOptions(args), existingPane = existingPaneForResume(record, options);
+  const replacement = await replacementForMainLaunch(root, record, resolved);
+  const active = replacement ? [{ id: replacement.request.task, task: replacement.task }] : await launchEligibleTasks(root, record, resolved);
+  if (!active.length) throw new Error(`${resolved} has no launch-eligible task; refusing runtime launch.`);
+  const selection = await chooseLaunchModel(root, config, record, required(await modelPortfolio(root), "models.yaml for Pi runtime launch"), dependencies.select);
+  const model = resolveModelCommand(config, selection.candidate);
+  if (basename(model.agent) !== "pi") throw new Error(`Pi runtime launch requires a Pi candidate, received ${selection.candidate.id}.`);
+  const command = dependencies.command ?? runOutput;
+  const piSession = launchSessionId(record, options, dependencies);
+  if (!piSession) throw new Error("Resume requires the exact Pi session stored on the seat.");
+  const adoptedPath = options.adopting ? resolve(required(options.adoptedSessionPath, "an exact adopted Pi session path")) : undefined;
+  const authorizationRecord = await adoptionAuthorization(root, resolved, record, options, piSession, adoptedPath);
+  return { root, resolved, record, options, existingPane, replacement, active, selection, model, command, piSession, adoptedPath, authorizationRecord, dependencies };
+}
+
+/** Match the seat-scoped projection to all caller and replacement assertions. */
+function assertProjectedPane(launch: PreparedLaunch, pane: string) {
+  const { options, existingPane, replacement, record } = launch;
+  if (options.resume && pane !== existingPane) throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
+  if (options.requestedPane && options.requestedPane !== pane) throw new Error("The asserted --pane does not match the seat-scoped Herdr projection.");
+  if (replacement) assertReplacementTarget(replacement.request, options.herdrSession, pane, record.worktree);
+}
+
+/** Require both Herdr metadata and process inspection to report a vacant target. */
+async function assertVacantTarget(launch: PreparedLaunch, pane: string) {
+  const { command, options } = launch;
+  const [paneRaw, processRaw] = await Promise.all([
+    command(herdr(options.herdrSession, "pane", "get", pane)),
+    command(herdr(options.herdrSession, "pane", "process-info", "--pane", pane)),
+  ]);
+  const currentPane = paneReport(JSON.parse(paneRaw));
+  if (currentPane.pane !== pane) throw new Error("Herdr reported a different pane; refusing runtime launch.");
+  if (currentPane.agent || piProcess(processReport(JSON.parse(processRaw)).processes)) {
+    throw new Error(options.resume ? "Resume requires the prior Pi to have exited and been released." : "New launch requires an available shell pane.");
+  }
+}
+
+/** Resume only from a Flow receipt that names this exact runtime tuple. */
+async function assertResumeReceipt(launch: PreparedLaunch, pane: string) {
+  const { options, record, resolved, piSession } = launch;
+  if (!options.resume) return;
+  const prior = record.runtime?.launch_receipt;
+  if (!prior) throw new Error("Resume requires an existing Flow launch receipt.");
+  try {
+    const receipt = await readYaml<{ seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string }>(prior);
+    if (receipt.seat !== resolved || receipt.pi_session !== piSession || receipt.pi_session_path !== record.runtime?.pi_session_path
+      || receipt.herdr_session !== options.herdrSession || receipt.pane !== pane) throw new Error("receipt does not match seat/session/path/pane");
+  } catch (error) { throw new Error(`Resume requires a valid Flow launch receipt: ${(error as Error).message}`); }
+}
+
+/** Select the immutable path that Herdr must report after a continued launch. */
+function priorSessionPath(launch: PreparedLaunch) {
+  if (launch.options.adopting) return required(launch.adoptedPath, "an exact adopted Pi session path");
+  if (launch.options.resume) return required(launch.record.runtime?.pi_session_path, "a previously verified Pi session path");
+  return undefined;
+}
+
+/** Recheck source release immediately before creating an adoption launch plan. */
+async function assertAdoptionSourceReleased(launch: PreparedLaunch) {
+  const { options, command } = launch;
+  if (!options.adopting) return;
+  const sourceSession = required(options.sourceHerdrSession, "a source Herdr session"), sourcePane = required(options.sourcePane, "a source pane");
+  const [paneRaw, processRaw] = await Promise.all([
+    command(herdr(sourceSession, "pane", "get", sourcePane)),
+    command(herdr(sourceSession, "pane", "process-info", "--pane", sourcePane)),
+  ]);
+  const report = paneReport(JSON.parse(paneRaw));
+  if (report.pane !== sourcePane || report.agent || piProcess(processReport(JSON.parse(processRaw)).processes)) {
+    throw new Error("Exact-session adoption requires proof that the source Pi has exited and been released.");
+  }
+}
+
+/** Materialize the exact command and receipt path shared by dry and live runs. */
+function buildLaunchPlan(launch: PreparedLaunch, pane: string, sessionPath?: string) {
+  const { root, resolved, options, piSession, model, selection } = launch;
+  const request: HerdrRequest = { session: options.herdrSession, pane, seat: resolved, root, piSession,
+    ...(sessionPath ? { sessionPath } : {}), resume: options.resume || options.adopting, args: [...model.args, "--extension", piExtensionPath()] };
+  const plan = { candidate: selection.candidate.id, piSession, pane, herdrSession: options.herdrSession,
+    receipt: receiptPath(root, piSession), command: startCommand(request), ...(options.dryRun ? { dryRun: true } : {}) };
+  return { request, plan };
+}
+
+async function startRuntime(launch: PreparedLaunch, pane: string, request: HerdrRequest) {
+  const { root, resolved, options, piSession, adoptedPath, command } = launch;
+  // Snapshot is a pre-migration prerequisite: never start a target without its recovery copy.
+  const relocation = options.adopting ? await immutableSessionBackup(root, required(adoptedPath, "an exact adopted Pi session path"), piSession) : undefined;
+  await command(herdr(options.herdrSession, "pane", "run", pane, `export ATDD_WORKFLOW_ROOT=${shellQuote(root)} ATDD_WORKFLOW_SEAT=${shellQuote(resolved)} ATDD_FLOW_PI_SESSION=${shellQuote(piSession)} ATDD_FLOW_HERDR_SESSION=${shellQuote(options.herdrSession)} ATDD_FLOW_HERDR_PANE=${shellQuote(pane)}`));
+  await command(startCommand(request));
+  return relocation;
+}
+
+/** Bind only a documented Pi JSONL path with the requested immutable identity. */
+function assertVerifiedSession(launch: PreparedLaunch, verifiedPane: PaneReport, priorPath?: string) {
+  const sessionPath = verifiedPane.sessionPath;
+  if (!sessionPath) throw new Error("Herdr did not report an exact Pi session path; seat binding was not changed.");
+  if (sessionIdFromPiJsonlPath(sessionPath) !== launch.piSession) throw new Error("Herdr did not verify the exact requested Pi session ID; seat binding was not changed.");
+  if ((launch.options.resume || launch.options.adopting) && sessionPath !== priorPath) throw new Error("Herdr did not verify the exact requested Pi session path; seat binding was not changed.");
+  return sessionPath;
+}
+
+function assertVerifiedProcess(launch: PreparedLaunch, pane: string, agent: ReturnType<typeof agentReport>, verifiedPane: PaneReport, verifiedProcess: ReturnType<typeof piProcess>) {
+  const statusVerified = [agent.status, verifiedPane.status].every((status) => status === "idle" || status === "done");
+  if (agent.name !== agentName(launch.resolved) || agent.pane !== pane || !statusVerified || verifiedPane.pane !== pane || !verifiedProcess) {
+    throw new Error("Herdr did not verify the replacement Pi process; seat binding was not changed.");
+  }
+}
+
+/** Corroborate the started runtime through agent, pane, and process reports. */
+async function verifyRuntime(launch: PreparedLaunch, pane: string, priorPath?: string) {
+  const { command, options, resolved } = launch;
+  const [agentRaw, paneRaw, processRaw] = await Promise.all([
+    command(herdr(options.herdrSession, "agent", "get", agentName(resolved))),
+    command(herdr(options.herdrSession, "pane", "get", pane)),
+    command(herdr(options.herdrSession, "pane", "process-info", "--pane", pane)),
+  ]);
+  const agent = agentReport(JSON.parse(agentRaw)), verifiedPane = paneReport(JSON.parse(paneRaw));
+  const verifiedProcess = piProcess(processReport(JSON.parse(processRaw)).processes);
+  const sessionPath = assertVerifiedSession(launch, verifiedPane, priorPath);
+  assertVerifiedProcess(launch, pane, agent, verifiedPane, verifiedProcess);
+  return sessionPath;
+}
+
+function receiptSelection(launch: PreparedLaunch) {
+  const { selection } = launch;
+  if (selection.fallback) return { result: "fallback", reason: selection.fallback };
+  return { result: "selected", confidence: selection.selection.confidence,
+    ...(selection.selection.available && selection.selection.model ? { model: selection.selection.model } : {}) };
+}
+
+/** Persist the verified receipt before delegating the final seat binding mutation. */
+async function persistLaunch(launch: PreparedLaunch, plan: LaunchPlan["plan"], sessionPath: string, relocation: Awaited<ReturnType<typeof immutableSessionBackup>> | undefined, bind: Bind) {
+  const { root, resolved, options, piSession, active, selection, replacement, authorizationRecord, dependencies } = launch;
+  const receiptRecord = {
+    schema: "atdd-flow/pi-runtime-launch-receipt/v1", seat: resolved, tasks: active.map((entry) => entry.id), candidate: selection.candidate.id,
+    selection: receiptSelection(launch), pi_session: piSession, pi_session_path: sessionPath, herdr_session: options.herdrSession, pane: plan.pane,
+    ...(replacement ? { handover_replacement: { request: replacement.request, successor_session: piSession } } : {}),
+    ...(relocation ? { relocation: { source_herdr_session: options.sourceHerdrSession, source_pane: options.sourcePane, authorization: authorizationRecord, backup: relocation.backup, backup_sha256: relocation.sha256 } } : {}),
+    created_at: dependencies.at?.() ?? now(),
+  };
+  await mkdir(dirname(plan.receipt), { recursive: true });
+  await writeFile(plan.receipt, yaml.print(receiptRecord), { encoding: "utf8", flag: "wx" });
+  await bind(root, resolved, ["--application", "herdr", "--address", plan.pane, "--session", options.herdrSession], selection.candidate.id, "native", piSession, sessionPath, plan.receipt);
+}
+
+/** A deliberately narrow Pi+Herdr launch using only installed CLI commands on an existing shell pane. */
+export async function launchPiRuntimeImplementation(root: string, address: string, args: string[], bind: Bind, dependencies: PiRuntimeLaunchDependencies = {}) {
+  const launch = await prepareLaunch(root, address, args, dependencies);
+  const pane = (await projectHerdrSeat(root, launch.resolved, launch.options.herdrSession, launch.command)).pane;
+  assertProjectedPane(launch, pane);
+  await assertVacantTarget(launch, pane);
+  await assertResumeReceipt(launch, pane);
+  const priorPath = priorSessionPath(launch);
+  await assertAdoptionSourceReleased(launch);
+  const { request, plan } = buildLaunchPlan(launch, pane, priorPath);
+  if (launch.options.dryRun) return plan;
+  const relocation = await startRuntime(launch, pane, request);
+  const sessionPath = await verifyRuntime(launch, pane, priorPath);
+  await persistLaunch(launch, plan, sessionPath, relocation, bind);
+  return plan;
+}

package/src/seats.ts

@@ -14,6 +14,7 @@ import { misplacedSeats, projectHerdrSeat } from "./multiplexer";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { projectCollaborationPolicy } from "./collaboration-policy";
+import { assertReplacementTarget, replacementForMainLaunch } from "./handover";
 
 const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
@@ -434,259 +435,12 @@ export async function attach(root: string, address: string, args: string[]) {
   await bind(root, address, ["--application", application, "--address", nativeAddress, ...(session ? ["--session", session] : []), ...(wake ? ["--wake", wake] : [])]);
 }
 
-export function availableModelCandidates(config: Desk, portfolio: ModelPortfolio) {
-  return portfolio.models.filter((candidate) => {
-    if (candidate.enabled === false) return false;
-    const executable = resolveExecutable(config, candidate.executable);
-    return executable.includes("/") ? existsSync(executable) : Boolean(Bun.which(executable));
-  });
-}
-
-export function resolveModelCommand(config: Desk, candidate: ModelCandidate) {
-  return { agent: resolveExecutable(config, candidate.executable), args: candidate.args ?? [] };
-}
-
-async function isExactNamedCoordinator(root: string, record: Seat, address: string) {
-  if (record.address !== address || record.role !== "coordinator") return false;
-  const config = await project(root, record.project);
-  const role = config.roles.coordinator;
-  const suffix = `@${config.project}`;
-  const local = record.address.endsWith(suffix) ? record.address.slice(0, -suffix.length) : "";
-  const match = local.match(/^coordinator\.([a-z0-9_-]+)$/);
-  if (!config.repository || role?.address !== "coordinator.{name}@{project}" || role.branch !== "integration/{name}" || !role.worktree || !match) return false;
-  const stream = match[1]!;
-  const expectedWorktree = resolve(fill(role.worktree, {
-    project: config.project, name: stream, worktree_root: config.worktree_root ?? "", repository: config.repository,
-  }));
-  if (record.branch !== `integration/${stream}` || resolve(record.worktree) !== expectedWorktree || expectedWorktree === resolve(config.repository)) return false;
-
-  try {
-    const peers = await Promise.all((await readdir(paths(root).seats(config.project))).map(async (name) => {
-      try { return await readYaml<Seat>(join(paths(root).seats(config.project), name, "seat.yaml")); }
-      catch { return undefined; }
-    }));
-    return !peers.some((peer) => peer && peer.address !== record.address && peer.role === "coordinator"
-      && (peer.branch === record.branch || resolve(peer.worktree) === expectedWorktree));
-  } catch { return false; }
-}
-
-async function launchEligibleTasks(root: string, record: Seat, address: string) {
-  const coordinator = await isExactNamedCoordinator(root, record, address);
-  const tasks = await seatTasks(root, record.project, record.address);
-  const eligible = await Promise.all(tasks.map(async (entry) => {
-    const accountable = record.role === "driver" ? entry.task.assignee === record.address
-      : coordinator && entry.task.coordinator === record.address;
-    if (!accountable || entry.task.blocker) return undefined;
-    if (entry.task.status === "in_progress") return entry;
-    if (entry.task.status !== "todo") return undefined;
-    const dependencies = await Promise.all((entry.task.depends_on ?? []).map(async (id) => {
-      try { return terminal(await readYaml<{ status: Task["status"] }>(paths(root).taskFile(record.project, id))); }
-      catch { return false; }
-    }));
-    return dependencies.every(Boolean) ? entry : undefined;
-  }));
-  return eligible.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry));
-}
-
-async function chooseLaunchModel(root: string, config: Desk, record: Seat, portfolio: ModelPortfolio, select: (input: ModelSelectionInput) => Promise<ModelSelectionResponse> = selectModel) {
-  const candidates = availableModelCandidates(config, portfolio);
-  if (!candidates.length) throw new Error("No enabled model in models.yaml has an available executable.");
-  const work = (await seatTasks(root, record.project, record.address)).filter((entry) => !terminal(entry.task));
-  const selection = await select({
-    seat: { address: record.address, role: record.role, ...(record.purpose ? { purpose: record.purpose } : {}) },
-    tasks: work.map((entry) => ({
-      id: entry.id,
-      title: entry.task.title,
-      status: entry.task.status,
-      ...(entry.task.body ? { body: entry.task.body } : {}),
-      doneWhen: entry.task.done_when.map((item) => item.text),
-      ...(entry.task.blocker ? { blocker: entry.task.blocker } : {}),
-    })),
-    candidates,
-  });
-  if (!selection.available || selection.confidence < 0.75 || !candidates.some((entry) => entry.id === selection.selected_model)) {
-    const reason = !selection.available ? selection.reason : selection.confidence < 0.75
-      ? `Jev model selection confidence is low (${selection.confidence}).`
-      : `Jev selected a model outside the available portfolio: ${selection.selected_model}.`;
-    return { candidate: candidates[0]!, selection, fallback: reason };
-  }
-  return { candidate: required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`), selection };
-}
-
-/** Pi loads this extension inside its own process, so it can wake without host text injection. */
-export const piExtensionPath = () => join(import.meta.dir, "..", "extensions", "pi", "index.ts");
-
-type HerdrRequest = { session: string; pane: string; seat: string; root: string; piSession: string; sessionPath?: string; resume: boolean; args: string[] };
-type Command = (command: string[]) => Promise<string>;
-export type PiRuntimeLaunchDependencies = {
-  select?: (input: ModelSelectionInput) => Promise<ModelSelectionResponse>;
-  command?: Command;
-  sessionId?: () => string;
-  at?: () => string;
-};
-
-type PaneReport = { pane: string; agent?: string; status?: string; sessionPath?: string };
-type ProcessReport = { shell?: number; processes: Array<{ name?: string; argv0?: string; cmdline?: string }> };
-
-const object = (value: unknown): Record<string, unknown> | undefined => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
-const text = (value: unknown) => typeof value === "string" ? value : undefined;
-const number = (value: unknown) => typeof value === "number" ? value : undefined;
-function result(value: unknown) { const root = object(value); return object(root?.result) ?? root; }
-function paneReport(value: unknown): PaneReport {
-  const pane = object(result(value)?.pane) ?? result(value);
-  const session = object(pane?.agent_session);
-  const id = text(pane?.pane_id);
-  if (!id) throw new Error("Herdr pane get did not report a pane id.");
-  return {
-    pane: id,
-    ...(text(pane?.agent) ? { agent: text(pane?.agent) } : {}),
-    ...(text(pane?.agent_status) ? { status: text(pane?.agent_status) } : {}),
-    ...(session?.kind === "path" && text(session.value) ? { sessionPath: text(session.value) } : {}),
-  };
-}
-function processReport(value: unknown): ProcessReport {
-  const report = object(result(value)?.process_info) ?? result(value);
-  const processes = Array.isArray(report?.foreground_processes) ? report.foreground_processes.flatMap((entry) => {
-    const process = object(entry);
-    return process ? [{ name: text(process.name), argv0: text(process.argv0), cmdline: text(process.cmdline) }] : [];
-  }) : [];
-  return { ...(number(report?.shell_pid) ? { shell: number(report?.shell_pid) } : {}), processes };
-}
-function agentReport(value: unknown) {
-  const agent = object(result(value)?.agent) ?? result(value);
-  const name = text(agent?.name);
-  const pane = text(agent?.pane_id);
-  if (!name || !pane) throw new Error("Herdr agent get did not report agent name and pane id.");
-  return { name, pane, status: text(agent?.agent_status) ?? text(agent?.status) ?? text(agent?.state) };
-}
-function piProcess(processes: ProcessReport["processes"]) {
-  return processes.find((entry) => entry.name === "pi" || entry.argv0?.endsWith("/pi") || entry.argv0 === "pi" || /(^|\/)pi(?:\s|$)/.test(entry.cmdline ?? ""));
-}
-/** Pi's durable JSONL session filenames end in `_<session-id>.jsonl`. */
-function sessionIdFromPiJsonlPath(path: string) {
-  const match = basename(path).match(/_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i);
-  if (!match) throw new Error("Herdr did not report a Pi JSONL path with a documented session ID.");
-  return match[1]!;
-}
-function shellQuote(value: string) { return `'${value.replaceAll("'", "'\\''")}'`; }
-function agentName(address: string) { return `flow-${address.replace(/[^a-z0-9_-]/gi, "-").toLowerCase()}`.slice(0, 32); }
-function herdr(session: string, ...args: string[]) { return ["herdr", "--session", session, ...args]; }
-function startCommand(request: HerdrRequest) {
-  const session = request.resume ? ["--session", required(request.sessionPath, "a previously verified Pi session path")] : ["--session-id", request.piSession];
-  return herdr(request.session, "agent", "start", agentName(request.seat), "--kind", "pi", "--pane", request.pane, "--", ...session, ...request.args);
-}
-function receiptPath(root: string, piSession: string) { return join(root, ".atdd-flow", "runtime-launch", `${encodeURIComponent(piSession)}-${crypto.randomUUID().slice(0, 8)}.yaml`); }
-
-async function immutableSessionBackup(root: string, sessionPath: string, piSession: string) {
-  const content = await readFile(sessionPath);
-  const sha256 = createHash("sha256").update(content).digest("hex");
-  const backup = join(root, ".atdd-flow", "runtime-launch", "backups", `${encodeURIComponent(piSession)}-${crypto.randomUUID()}.jsonl`);
-  await mkdir(dirname(backup), { recursive: true });
-  await writeFile(backup, content, { flag: "wx" });
-  return { backup, sha256 };
-}
+export { availableModelCandidates, piExtensionPath, resolveModelCommand, type PiRuntimeLaunchDependencies } from "./pi-runtime-launch";
 
-/** A deliberately narrow Pi+Herdr launch using only installed CLI commands on an existing shell pane. */
-export async function launchPiRuntime(root: string, address: string, args: string[], dependencies: PiRuntimeLaunchDependencies = {}) {
-  const resolved = await canonicalAddress(root, address);
-  const record = await seat(root, resolved);
-  const config = await desk(root);
-  const requestedPane = words(args, "--pane");
-  const herdrSession = required(words(args, "--herdr-session"), "--herdr-session");
-  const resume = args.includes("--resume");
-  const dryRun = args.includes("--dry-run");
-  const adoptedSessionPath = words(args, "--adopt-session");
-  const sourceHerdrSession = words(args, "--source-herdr-session");
-  const sourcePane = words(args, "--source-pane");
-  const authorization = words(args, "--authorization");
-  const adoptionFields = [adoptedSessionPath, sourceHerdrSession, sourcePane, authorization];
-  const adopting = adoptionFields.some(Boolean);
-  const allowed = ["--herdr-session", herdrSession, "--resume", "--dry-run", ...(requestedPane ? ["--pane", requestedPane] : []),
-    ...(adoptedSessionPath ? ["--adopt-session", adoptedSessionPath] : []), ...(sourceHerdrSession ? ["--source-herdr-session", sourceHerdrSession] : []),
-    ...(sourcePane ? ["--source-pane", sourcePane] : []), ...(authorization ? ["--authorization", authorization] : [])];
-  if (args.some((argument) => !allowed.includes(argument))) throw new Error("Use `pi runtime launch <seat> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <owner-reference>]`.");
-  if (adopting && (resume || !adoptionFields.every(Boolean))) throw new Error("Exact-session adoption requires --adopt-session, --source-herdr-session, --source-pane, and --authorization without --resume.");
-  const existingHerdr = record.runtime?.addresses.herdr;
-  const existingPane = typeof existingHerdr === "object" ? existingHerdr.pane : undefined;
-  const existingSession = typeof existingHerdr === "object" ? existingHerdr.session : undefined;
-  if (resume && ((requestedPane && requestedPane !== existingPane) || herdrSession !== existingSession)) {
-    throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
-  }
-  const active = await launchEligibleTasks(root, record, resolved);
-  if (!active.length) throw new Error(`${resolved} has no launch-eligible task; refusing runtime launch.`);
-  const selection = await chooseLaunchModel(root, config, record, required(await modelPortfolio(root), "models.yaml for Pi runtime launch"), dependencies.select);
-  const model = resolveModelCommand(config, selection.candidate);
-  if (basename(model.agent) !== "pi") throw new Error(`Pi runtime launch requires a Pi candidate, received ${selection.candidate.id}.`);
-  const command = dependencies.command ?? runOutput;
-  const piSession = adopting ? sessionIdFromPiJsonlPath(required(adoptedSessionPath, "an exact adopted Pi session path")) : resume ? record.runtime?.pi_session : (dependencies.sessionId ?? (() => crypto.randomUUID()))();
-  if (!piSession) throw new Error("Resume requires the exact Pi session stored on the seat.");
-  const canonicalAdoptedSessionPath = adopting ? resolve(required(adoptedSessionPath, "an exact adopted Pi session path")) : undefined;
-  const authorizationRecord = adopting
-    ? await resolveExactSessionAdoptionAuthorization(root, required(authorization, "an immutable operator authorization record"), {
-      seat: resolved, pi_session: piSession, pi_session_path: required(canonicalAdoptedSessionPath, "an exact adopted Pi session path"),
-      source: { herdr_session: required(sourceHerdrSession, "a source Herdr session"), pane: required(sourcePane, "a source pane") },
-      target: { herdr_session: herdrSession, pane: required(requestedPane, "--pane for exact-session adoption"), cwd: resolve(record.worktree) },
-    })
-    : undefined;
-  const projection = await projectHerdrSeat(root, resolved, herdrSession, command);
-  if (resume && projection.pane !== existingPane) throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
-  if (requestedPane && requestedPane !== projection.pane) throw new Error("The asserted --pane does not match the seat-scoped Herdr projection.");
-  const pane = projection.pane;
-  const [paneRaw, processRaw] = await Promise.all([command(herdr(herdrSession, "pane", "get", pane)), command(herdr(herdrSession, "pane", "process-info", "--pane", pane))]);
-  const currentPane = paneReport(JSON.parse(paneRaw));
-  const currentProcess = processReport(JSON.parse(processRaw));
-  if (currentPane.pane !== pane) throw new Error("Herdr reported a different pane; refusing runtime launch.");
-  if (currentPane.agent || piProcess(currentProcess.processes)) throw new Error(resume ? "Resume requires the prior Pi to have exited and been released." : "New launch requires an available shell pane.");
-  if (resume) {
-    const prior = record.runtime?.launch_receipt;
-    if (!prior) throw new Error("Resume requires an existing Flow launch receipt.");
-    try {
-      const receipt = await readYaml<{ seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string }>(prior);
-      if (receipt.seat !== resolved || receipt.pi_session !== piSession || receipt.pi_session_path !== record.runtime?.pi_session_path || receipt.herdr_session !== herdrSession || receipt.pane !== pane) throw new Error("receipt does not match seat/session/path/pane");
-    } catch (error) { throw new Error(`Resume requires a valid Flow launch receipt: ${(error as Error).message}`); }
-  }
-  const priorSessionPath = adopting ? required(canonicalAdoptedSessionPath, "an exact adopted Pi session path") : resume ? required(record.runtime?.pi_session_path, "a previously verified Pi session path") : undefined;
-  if (adopting) {
-    const [sourcePaneRaw, sourceProcessRaw] = await Promise.all([
-      command(herdr(required(sourceHerdrSession, "a source Herdr session"), "pane", "get", required(sourcePane, "a source pane"))),
-      command(herdr(required(sourceHerdrSession, "a source Herdr session"), "pane", "process-info", "--pane", required(sourcePane, "a source pane"))),
-    ]);
-    const sourceReport = paneReport(JSON.parse(sourcePaneRaw));
-    const sourceProcess = processReport(JSON.parse(sourceProcessRaw));
-    if (sourceReport.pane !== sourcePane || sourceReport.agent || piProcess(sourceProcess.processes)) {
-      throw new Error("Exact-session adoption requires proof that the source Pi has exited and been released.");
-    }
-  }
-  const request: HerdrRequest = { session: herdrSession, pane, seat: resolved, root, piSession, ...(priorSessionPath ? { sessionPath: priorSessionPath } : {}), resume: resume || adopting, args: [...model.args, "--extension", piExtensionPath()] };
-  const plan = { candidate: selection.candidate.id, piSession, pane, herdrSession, receipt: receiptPath(root, piSession), command: startCommand(request), ...(dryRun ? { dryRun: true } : {}) };
-  if (dryRun) return plan;
-  // The source snapshot is a pre-migration prerequisite: never start a target
-  // Pi when its immutable recovery copy cannot be created.
-  const relocation = adopting ? await immutableSessionBackup(root, required(canonicalAdoptedSessionPath, "an exact adopted Pi session path"), piSession) : undefined;
-  await command(herdr(herdrSession, "pane", "run", pane, `export ATDD_WORKFLOW_ROOT=${shellQuote(root)} ATDD_WORKFLOW_SEAT=${shellQuote(resolved)} ATDD_FLOW_PI_SESSION=${shellQuote(piSession)} ATDD_FLOW_HERDR_SESSION=${shellQuote(herdrSession)} ATDD_FLOW_HERDR_PANE=${shellQuote(pane)}`));
-  await command(startCommand(request));
-  const [agentRaw, verifiedPaneRaw, verifiedProcessRaw] = await Promise.all([command(herdr(herdrSession, "agent", "get", agentName(resolved))), command(herdr(herdrSession, "pane", "get", pane)), command(herdr(herdrSession, "pane", "process-info", "--pane", pane))]);
-  const agent = agentReport(JSON.parse(agentRaw));
-  const verifiedPane = paneReport(JSON.parse(verifiedPaneRaw));
-  const verifiedProcess = piProcess(processReport(JSON.parse(verifiedProcessRaw)).processes);
-  const sessionPath = verifiedPane.sessionPath;
-  if (!sessionPath) throw new Error("Herdr did not report an exact Pi session path; seat binding was not changed.");
-  const reportedId = sessionIdFromPiJsonlPath(sessionPath);
-  if (reportedId !== piSession) throw new Error("Herdr did not verify the exact requested Pi session ID; seat binding was not changed.");
-  if ((resume || adopting) && sessionPath !== priorSessionPath) throw new Error("Herdr did not verify the exact requested Pi session path; seat binding was not changed.");
-  if (agent.name !== agentName(resolved) || agent.pane !== pane || ![agent.status, verifiedPane.status].every((status) => status === "idle" || status === "done") || verifiedPane.pane !== pane || !verifiedProcess) throw new Error("Herdr did not verify the replacement Pi process; seat binding was not changed.");
-  const receipt = plan.receipt;
-  const receiptRecord = {
-    schema: "atdd-flow/pi-runtime-launch-receipt/v1", seat: resolved, tasks: active.map((entry) => entry.id), candidate: selection.candidate.id,
-    selection: selection.fallback ? { result: "fallback", reason: selection.fallback } : { result: "selected", confidence: selection.selection.confidence, ...(selection.selection.available && selection.selection.model ? { model: selection.selection.model } : {}) },
-    pi_session: piSession, pi_session_path: sessionPath, herdr_session: herdrSession, pane,
-    ...(relocation ? { relocation: { source_herdr_session: sourceHerdrSession, source_pane: sourcePane, authorization: authorizationRecord, backup: relocation.backup, backup_sha256: relocation.sha256 } } : {}),
-    created_at: dependencies.at?.() ?? now(),
-  };
-  await mkdir(dirname(receipt), { recursive: true });
-  await writeFile(receipt, yaml.print(receiptRecord), { encoding: "utf8", flag: "wx" });
-  await bind(root, resolved, ["--application", "herdr", "--address", pane, "--session", herdrSession], selection.candidate.id, "native", piSession, sessionPath, receipt);
-  return plan;
+/** Delegates generic Pi/Herdr mechanics while seats retain the public launch API and bind authority. */
+export async function launchPiRuntime(root: string, address: string, args: string[], dependencies: import("./pi-runtime-launch").PiRuntimeLaunchDependencies = {}) {
+  const { launchPiRuntimeImplementation } = await import("./pi-runtime-launch");
+  return launchPiRuntimeImplementation(root, address, args, bind, dependencies);
 }
 
 export async function describe(root: string, address: string, args: string[]) {