@afokapu/atdd-flow 0.3.14 → 0.3.16

package/extensions/pi/index.ts

@@ -4,6 +4,7 @@ import { basename, dirname, join } from "node:path";
 import { parse, stringify } from "yaml";
 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";
 
 type Thread = { id?: unknown; participants?: unknown; subject?: unknown };
 export type Mail = { id?: unknown; from?: unknown; to?: unknown; subject?: unknown; created_at?: unknown };
@@ -40,12 +41,27 @@ export type PiRuntimeOptions = {
   staleAfterMs?: number;
   deliver: InboxOptions["deliver"];
   createTransport?: (options: InboxOptions) => FlowInboxTransport;
+  /** Flow-launched Pi instances register and heartbeat before their verified launch activates inbox delivery. */
+  deferActivation?: boolean;
+};
+
+export type LaunchActivationOptions = {
+  root: string;
+  seat: string;
+  piSession: string;
+  herdrSession: string;
+  pane: string;
+  activate: () => Promise<void>;
+  intervalMs?: number;
+  timeoutMs?: number;
 };
 
 const defaultBatchSize = 32;
 const defaultIntervalMs = 30_000;
 const defaultHeartbeatMs = 15_000;
 const defaultStaleAfterMs = 60_000;
+const defaultActivationIntervalMs = 25;
+const defaultActivationTimeoutMs = 60_000;
 
 function participants(thread: Thread) {
   return Array.isArray(thread.participants) && thread.participants.every((entry) => typeof entry === "string") ? thread.participants as string[] : [];
@@ -216,11 +232,12 @@ export const createInboxReconciler = createInboxTransport;
  */
 export function createPiRuntime({
   root, seat, pid = process.pid, model = process.env.PI_MODEL ?? "pi", cwd = process.cwd(),
-  heartbeatMs = defaultHeartbeatMs, staleAfterMs = defaultStaleAfterMs, deliver, createTransport = createInboxTransport,
+  heartbeatMs = defaultHeartbeatMs, staleAfterMs = defaultStaleAfterMs, deliver, createTransport = createInboxTransport, deferActivation = false,
 }: PiRuntimeOptions) {
   const ownerToken = runtimeOwnerToken();
   let transport: FlowInboxTransport | undefined;
   let heartbeat: ReturnType<typeof setInterval> | undefined;
+  let activated = false;
 
   const owned = () => ownsRuntimeState(root, seat, ownerToken);
   const stop = async () => {
@@ -234,11 +251,9 @@ export function createPiRuntime({
     if (!transport || !await owned()) return;
     await transport.reconcile();
   };
-  const start = async () => {
-    // This removes only an expired local observation. Registration itself is
-    // replacement-safe and does not alter the authoritative Desk seat.
-    await clearStaleRuntimeState(root, seat, staleAfterMs);
-    await registerRuntimeState(root, { seat, owner_token: ownerToken, pid, model, cwd });
+  const activate = async () => {
+    if (!await owned()) return false;
+    if (activated) return true;
     transport = createTransport({
       root, seat, batchSize: defaultBatchSize, intervalMs: defaultIntervalMs,
       deliver: async (mail, thread, path) => {
@@ -257,13 +272,47 @@ export function createPiRuntime({
       },
     });
     await transport.start();
+    activated = true;
+    return true;
+  };
+  const start = async () => {
+    // This removes only an expired local observation. Registration itself is
+    // replacement-safe and does not alter the authoritative Desk seat.
+    await clearStaleRuntimeState(root, seat, staleAfterMs);
+    await registerRuntimeState(root, { seat, owner_token: ownerToken, pid, model, cwd });
     heartbeat = setInterval(() => {
       void heartbeatRuntimeState(root, seat, ownerToken).then((state) => {
         if (!state) void stop();
       });
     }, heartbeatMs);
+    if (!deferActivation) await activate();
   };
-  return { ownerToken, start, stop, reconcile, get transport() { return transport; } };
+  return { ownerToken, start, activate, stop, reconcile, get transport() { return transport; } };
+}
+
+type LaunchReceipt = { seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string };
+
+/** Wait only for the launcher's already-verified receipt and exact Desk binding; this never creates either record. */
+export async function awaitLaunchActivation({ root, seat, piSession, herdrSession, pane, activate, intervalMs = defaultActivationIntervalMs, timeoutMs = defaultActivationTimeoutMs }: LaunchActivationOptions) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    try {
+      const record = await readYaml<Seat>(paths(root).seatFile(seat));
+      const runtime = record.runtime;
+      const locator = runtime?.addresses.herdr;
+      if (runtime?.application === "herdr" && typeof locator !== "string" && locator?.session === herdrSession && locator.pane === pane
+        && runtime.pi_session === piSession && runtime.pi_session_path && runtime.launch_receipt) {
+        const receipt = await readYaml<LaunchReceipt>(runtime.launch_receipt);
+        if (receipt.seat === seat && receipt.pi_session === piSession && receipt.pi_session_path === runtime.pi_session_path
+          && receipt.herdr_session === herdrSession && receipt.pane === pane) {
+          await activate();
+          return;
+        }
+      }
+    } catch { /* Binding and receipt are written after Herdr verification; wait within this finite window. */ }
+    await pause(intervalMs);
+  }
+  throw new Error("Timed out waiting for verified Flow launch receipt and binding.");
 }
 
 /** Desk mail is authoritative; the queue is a bounded delivery index and fs.watch only shortens latency. */
@@ -273,7 +322,7 @@ export default function (pi: ExtensionAPI) {
   if (!root || !seat) return;
   let runtime: ReturnType<typeof createPiRuntime> | undefined;
   pi.on("session_start", async (_event, ctx) => {
-    runtime = createPiRuntime({ root, seat, deliver: async (mail, thread, path, sendIfOwned) => {
+    runtime = createPiRuntime({ root, seat, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
       if (!sendIfOwned) return false;
       return sendIfOwned(() => {
         pi.sendMessage({
@@ -284,8 +333,19 @@ export default function (pi: ExtensionAPI) {
       });
     } });
     await runtime.start();
-    pi.sendMessage({ customType: "atdd-flow-start", content: `SYSTEM: you are ${seat}. 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.`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
-    if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
+    const piSession = process.env.ATDD_FLOW_PI_SESSION;
+    const herdrSession = process.env.ATDD_FLOW_HERDR_SESSION;
+    const pane = process.env.ATDD_FLOW_HERDR_PANE;
+    if (!piSession || !herdrSession || !pane) return;
+    const current = runtime;
+    void awaitLaunchActivation({
+      root, seat, piSession, herdrSession, pane,
+      activate: async () => {
+        if (!await current.activate()) return;
+        pi.sendMessage({ customType: "atdd-flow-start", content: `SYSTEM: you are ${seat}. 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.`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
+        if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
+      },
+    }).catch(() => undefined);
   });
   pi.on("session_shutdown", () => { void runtime?.stop(); });
 }

package/package.json

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

package/src/cli.ts

@@ -25,7 +25,7 @@ Usage:
   atdd-flow bind <address> [--application <application>] --address <native-address> [--session <name>] [--agent <executable>] [--worktree <path>] [--wake host|native]
   atdd-flow attach <address> [--application <application>] [--wake host|native]
   atdd-flow pi extension-path
-  atdd-flow pi runtime launch <address> --pane <existing-herdr-pane> --herdr-session <session> [--resume] [--dry-run]
+  atdd-flow pi runtime launch <address> [--pane <asserted-herdr-pane>] --herdr-session <session> [--resume] [--dry-run]
   atdd-flow application use <address> <application>
   atdd-flow multiplexer status|apply herdr [--session <name>]
   atdd-flow describe <address> --purpose <one-line responsibility>
@@ -92,7 +92,7 @@ async function main() {
         else console.log(`Launched Pi runtime for ${required(rest[2], "address")} with ${plan.candidate}.`);
         return;
       }
-      throw new Error("Use `pi extension-path` or `pi runtime launch <address> --pane <pane> --herdr-session <session> [--resume] [--dry-run]`.");
+      throw new Error("Use `pi extension-path` or `pi runtime launch <address> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run]`.");
     },
     application: async () => {
       if (rest[0] === "use") return useApplication(root, required(rest[1], "address"), required(rest[2], "application"));

package/src/multiplexer.ts

@@ -28,6 +28,17 @@ type Workspace = { workspace_id: string; label?: string; worktree?: { checkout_p
 type Tab = { tab_id: string; workspace_id: string; label?: string };
 type Pane = { pane_id: string; tab_id: string; label?: string };
 type Target = { project: string; worktree: string; workspaceLabel: string; seat?: Seat };
+type WorkspaceState = { id: string; label: string; worktree: string; rootTab?: string; rootPane?: string };
+type HerdrCommand = (command: string[]) => Promise<string>;
+
+export type HerdrSeatProjection = {
+  session: string;
+  workspace: string;
+  tab: string;
+  pane: string;
+  worktree: string;
+  label: string;
+};
 
 const policyFile = () => join(import.meta.dir, "..", "multiplexer", "herdr.yaml");
 const selectedSession = (args: string[], environment: Record<string, string | undefined> = process.env) => {
@@ -87,11 +98,8 @@ async function targets(root: string): Promise<Target[]> {
     let config: Project;
     try { config = await project(root, name); }
     catch { continue; }
-    // A repository is the Desk's explicit primary-checkout declaration. Do not infer one.
     if (!config.repository) continue;
     const primary = resolve(config.repository);
-    // The primary checkout is explicitly declared by the project even if no
-    // primary-worktree seat currently occupies it.
     result.push({ project: name, worktree: primary, workspaceLabel: name });
     for (const entry of await projectSeats(root, name)) {
       if ((entry.role === "main" || entry.role === "coordinator") && resolve(entry.worktree) === primary) {
@@ -111,68 +119,110 @@ async function targets(root: string): Promise<Target[]> {
   return result;
 }
 
-function command(session: string, args: string[]) {
-  return runOutput(["herdr", "--session", session, ...args]);
-}
-
+const herdr: HerdrCommand = (args) => runOutput(args);
 function json(output: string): any {
   try { return JSON.parse(output).result; }
   catch { throw new Error("Herdr returned invalid JSON; projection did not guess a target."); }
 }
-
 function workspaceId(value: any) {
   const found = value?.workspace?.workspace_id ?? value?.workspace_id;
   if (typeof found !== "string") throw new Error("Herdr did not return a workspace id.");
   return found;
 }
-
+function tabId(value: any) {
+  const found = value?.root_tab?.tab_id ?? value?.tab?.tab_id;
+  return typeof found === "string" ? found : undefined;
+}
 function paneId(value: any) {
   const found = value?.root_pane?.pane_id ?? value?.pane?.pane_id;
-  if (typeof found !== "string") throw new Error("Herdr did not return a pane id.");
-  return found;
+  return typeof found === "string" ? found : undefined;
 }
-
-async function liveWorkspaces(session: string) {
-  const value = json(await command(session, ["workspace", "list"]));
+async function liveWorkspaces(session: string, command: HerdrCommand) {
+  const value = json(await command(["herdr", "--session", session, "workspace", "list"]));
   if (!Array.isArray(value?.workspaces)) throw new Error("Herdr workspace list response is invalid.");
   return value.workspaces as Workspace[];
 }
 
-async function ensureWorkspace(session: string, target: Target, workspaces: Workspace[]) {
+async function ensureWorkspace(session: string, target: Target, workspaces: Workspace[], command: HerdrCommand, primary?: WorkspaceState) {
   let current = workspaces.find((entry) => resolve(entry.worktree?.checkout_path ?? "") === target.worktree);
   if (!current) {
-    const created = target.workspaceLabel === target.project
-      ? json(await command(session, ["workspace", "create", "--cwd", target.worktree, "--label", target.workspaceLabel, "--no-focus"]))
-      : json(await command(session, ["worktree", "open", "--path", target.worktree, "--label", target.workspaceLabel, "--no-focus"]));
+    const args = target.workspaceLabel === target.project
+      ? ["workspace", "create", "--cwd", target.worktree, "--label", target.workspaceLabel, "--no-focus"]
+      : ["worktree", "open", "--workspace", primary?.id ?? "", "--cwd", primary?.worktree ?? "", "--path", target.worktree, "--label", target.workspaceLabel, "--no-focus"];
+    if (args.includes("")) throw new Error(`Project primary workspace is required to open linked worktree ${target.worktree}.`);
+    const created = json(await command(["herdr", "--session", session, ...args]));
     current = { workspace_id: workspaceId(created), label: target.workspaceLabel, worktree: { checkout_path: target.worktree } };
     workspaces.push(current);
-  } else if (current.label !== target.workspaceLabel) {
-    await command(session, ["workspace", "rename", current.workspace_id, target.workspaceLabel]);
+    return { id: current.workspace_id, label: target.workspaceLabel, worktree: target.worktree, ...(tabId(created) ? { rootTab: tabId(created) } : {}), ...(paneId(created) ? { rootPane: paneId(created) } : {}) };
+  }
+  if (current.label !== target.workspaceLabel) {
+    await command(["herdr", "--session", session, "workspace", "rename", current.workspace_id, target.workspaceLabel]);
     current.label = target.workspaceLabel;
   }
-  return current.workspace_id;
+  return { id: current.workspace_id, label: target.workspaceLabel, worktree: target.worktree };
 }
 
-async function ensureSeatTab(session: string, workspace: string, target: Target & { seat: Seat }) {
-  const tabsResult = json(await command(session, ["tab", "list", "--workspace", workspace]));
-  const tabs = tabsResult?.tabs as Tab[];
-  if (!Array.isArray(tabs)) throw new Error("Herdr tab list response is invalid.");
-  let tab = tabs.find((entry) => entry.label === target.seat.address);
+async function tabs(session: string, workspace: string, command: HerdrCommand) {
+  const result = json(await command(["herdr", "--session", session, "tab", "list", "--workspace", workspace]));
+  if (!Array.isArray(result?.tabs)) throw new Error("Herdr tab list response is invalid.");
+  return result.tabs as Tab[];
+}
+async function panes(session: string, workspace: string, command: HerdrCommand) {
+  const result = json(await command(["herdr", "--session", session, "pane", "list", "--workspace", workspace]));
+  if (!Array.isArray(result?.panes)) throw new Error("Herdr pane list response is invalid.");
+  return result.panes as Pane[];
+}
+
+async function ensureSeatTab(session: string, workspace: WorkspaceState, target: Target & { seat: Seat }, command: HerdrCommand): Promise<HerdrSeatProjection> {
+  let entries = await tabs(session, workspace.id, command);
+  let tab = entries.find((entry) => entry.label === target.seat.address);
   let pane: string | undefined;
+  if (!tab && workspace.rootTab) {
+    tab = entries.find((entry) => entry.tab_id === workspace.rootTab) ?? { tab_id: workspace.rootTab, workspace_id: workspace.id };
+    await command(["herdr", "--session", session, "tab", "rename", tab.tab_id, target.seat.address]);
+    tab.label = target.seat.address;
+  }
   if (!tab) {
-    const created = json(await command(session, ["tab", "create", "--workspace", workspace, "--cwd", target.worktree, "--label", target.seat.address, "--no-focus"]));
-    tab = { tab_id: created?.tab?.tab_id, workspace_id: workspace, label: target.seat.address };
+    const created = json(await command(["herdr", "--session", session, "tab", "create", "--workspace", workspace.id, "--cwd", target.worktree, "--label", target.seat.address, "--no-focus"]));
+    const id = tabId(created);
+    if (!id) throw new Error("Herdr did not return a tab id.");
+    tab = { tab_id: id, workspace_id: workspace.id, label: target.seat.address };
     pane = paneId(created);
-    if (!tab.tab_id) throw new Error("Herdr did not return a tab id.");
   }
-  const panesResult = json(await command(session, ["pane", "list", "--workspace", workspace]));
-  const panes = panesResult?.panes as Pane[];
-  if (!Array.isArray(panes)) throw new Error("Herdr pane list response is invalid.");
-  const labelled = panes.find((entry) => entry.tab_id === tab!.tab_id && entry.label === target.seat.address);
-  if (labelled) return;
-  const first = pane ?? panes.find((entry) => entry.tab_id === tab!.tab_id)?.pane_id;
+  const entriesPanes = await panes(session, workspace.id, command);
+  const labelled = entriesPanes.find((entry) => entry.tab_id === tab!.tab_id && entry.label === target.seat.address);
+  if (labelled) return { session, workspace: workspace.id, tab: tab.tab_id, pane: labelled.pane_id, worktree: target.worktree, label: target.seat.address };
+  const first = pane ?? workspace.rootPane ?? entriesPanes.find((entry) => entry.tab_id === tab!.tab_id)?.pane_id;
   if (!first) throw new Error(`Herdr tab ${tab.tab_id} has no pane to label.`);
-  await command(session, ["pane", "rename", first, target.seat.address]);
+  await command(["herdr", "--session", session, "pane", "rename", first, target.seat.address]);
+  return { session, workspace: workspace.id, tab: tab.tab_id, pane: first, worktree: target.worktree, label: target.seat.address };
+}
+
+async function ensureTarget(session: string, target: Target, workspaces: Workspace[], command: HerdrCommand, primary: WorkspaceState) {
+  const workspace = target.workspaceLabel === target.project ? primary : await ensureWorkspace(session, target, workspaces, command, primary);
+  return target.seat ? ensureSeatTab(session, workspace, target as Target & { seat: Seat }, command) : undefined;
+}
+
+/** Reconciles exactly one Desk seat into a labeled Herdr workspace/tab/pane. */
+export async function projectHerdrSeat(root: string, address: string, session: string, command: HerdrCommand = herdr): Promise<HerdrSeatProjection> {
+  await herdrPolicy();
+  const desired = await targets(root);
+  const target = desired.find((entry) => entry.seat?.address === address);
+  if (!target?.seat) throw new Error(`No active Desk projection target exists for ${address}.`);
+  const primaryTarget = desired.find((entry) => entry.project === target.project && entry.workspaceLabel === target.project && !entry.seat);
+  if (!primaryTarget) throw new Error(`Project ${target.project} has no declared primary workspace.`);
+  const workspaces = await liveWorkspaces(session, command);
+  const primary = await ensureWorkspace(session, primaryTarget, workspaces, command);
+  return (await ensureTarget(session, target, workspaces, command, primary))!;
+}
+
+async function topologyCompliant(session: string, target: Target, workspace: Workspace, command: HerdrCommand) {
+  if (workspace.label !== target.workspaceLabel) return false;
+  if (!target.seat) return true;
+  const entries = await tabs(session, workspace.workspace_id, command);
+  const tab = entries.find((entry) => entry.label === target.seat!.address);
+  if (!tab) return false;
+  return (await panes(session, workspace.workspace_id, command)).some((entry) => entry.tab_id === tab.tab_id && entry.label === target.seat!.address);
 }
 
 export async function multiplexer(root: string, args: string[]) {
@@ -188,17 +238,27 @@ export async function multiplexer(root: string, args: string[]) {
     return;
   }
   const desired = await targets(root);
+  const command: HerdrCommand = herdr;
+  const workspaces = await liveWorkspaces(session, command);
   if (action === "status") {
-    // Status deliberately has no reconciliation side effects.
-    const workspaces = await liveWorkspaces(session);
     const present = desired.filter((target) => workspaces.some((entry) => resolve(entry.worktree?.checkout_path ?? "") === target.worktree));
-    console.log(JSON.stringify({ schema: "atdd-workflow/multiplexer-status/v1", application: "herdr", session, desired: desired.length, present: present.length }, null, 2));
+    const topology = await Promise.all(desired.map(async (target) => {
+      const workspace = workspaces.find((entry) => resolve(entry.worktree?.checkout_path ?? "") === target.worktree);
+      return workspace ? topologyCompliant(session, target, workspace, command) : false;
+    }));
+    console.log(JSON.stringify({ schema: "atdd-workflow/multiplexer-status/v1", application: "herdr", session, desired: desired.length, present: present.length, topology_compliant: topology.filter(Boolean).length }, null, 2));
     return;
   }
-  const workspaces = await liveWorkspaces(session);
+  const primary = new Map<string, WorkspaceState>();
   for (const target of desired) {
-    const workspace = await ensureWorkspace(session, target, workspaces);
-    if (target.seat) await ensureSeatTab(session, workspace, target);
+    let projectPrimary = primary.get(target.project);
+    if (!projectPrimary) {
+      const primaryTarget = desired.find((entry) => entry.project === target.project && entry.workspaceLabel === target.project && !entry.seat);
+      if (!primaryTarget) throw new Error(`Project ${target.project} has no declared primary workspace.`);
+      projectPrimary = await ensureWorkspace(session, primaryTarget, workspaces, command);
+      primary.set(target.project, projectPrimary);
+    }
+    await ensureTarget(session, target, workspaces, command, projectPrimary);
   }
   console.log(`Projected ${desired.length} Desk seat worktree(s) into Herdr session ${session}.`);
 }

package/src/seats.ts

@@ -9,6 +9,7 @@ import {
 } from "./core";
 import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
 import { seatTasks } from "./tasks";
+import { projectHerdrSeat } from "./multiplexer";
 
 const defaultRoles = (dynamicModels = true): Record<string, Role> => ({
   coordinator: {
@@ -246,7 +247,7 @@ function agentReport(value: unknown) {
   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?.status) ?? text(agent?.state) };
+  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 ?? ""));
@@ -271,17 +272,21 @@ export async function launchPiRuntime(root: string, address: string, args: strin
   const resolved = await canonicalAddress(root, address);
   const record = await seat(root, resolved);
   const config = await desk(root);
-  const pane = required(words(args, "--pane"), "--pane");
+  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");
-  if (args.some((argument) => !["--pane", pane, "--herdr-session", herdrSession, "--resume", "--dry-run"].includes(argument))) throw new Error("Use `pi runtime launch <seat> --pane <existing-pane> --herdr-session <session> [--resume] [--dry-run]`.");
+  const allowed = ["--herdr-session", herdrSession, "--resume", "--dry-run", ...(requestedPane ? ["--pane", requestedPane] : [])];
+  if (args.some((argument) => !allowed.includes(argument))) throw new Error("Use `pi runtime launch <seat> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run]`.");
   const active = await launchEligibleTasks(root, record);
   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 projection = await projectHerdrSeat(root, resolved, herdrSession, command);
+  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));
@@ -301,7 +306,7 @@ export async function launchPiRuntime(root: string, address: string, args: strin
   const request: HerdrRequest = { session: herdrSession, pane, seat: resolved, root, piSession, ...(priorSessionPath ? { sessionPath: priorSessionPath } : {}), resume, 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;
-  await command(herdr(herdrSession, "pane", "run", pane, `export ATDD_WORKFLOW_ROOT=${shellQuote(root)} ATDD_WORKFLOW_SEAT=${shellQuote(resolved)}`));
+  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));