@afokapu/atdd-flow 0.3.7 → 0.3.8

package/README.md

@@ -50,12 +50,9 @@ an absolute command path when the host does not guarantee a shared `PATH`:
 ```yaml
 schema: atdd-workflow/desk/v1
 desk: desk
-application: tuios
+application: herdr
 executables:
-  claude: /Users/you/.local/bin/claude
-  codex: /opt/homebrew/bin/codex
   pi: /opt/homebrew/bin/pi
-  kimi: /Users/you/.kimi-code/bin/kimi
 ```
 
 The executable registry is transport configuration, not model allocation. New seats do not pin an
@@ -64,25 +61,18 @@ agent. Instead, `models.yaml` declares the launchable model portfolio in descend
 ```yaml
 schema: atdd-workflow/models/v1
 models:
-  - id: frontier
-    executable: claude
-    args: [--model, opus]
-  - id: standard
-    executable: claude
-    args: [--model, sonnet]
-  - id: codex
-    executable: codex
-  - id: glm
-    executable: glm
-    enabled: false
+  - id: pi
+    executable: pi
+# Add Pi --model arguments here when local policy selects a specific Pi model.
 ```
 
-Order is policy: strongest first, weakest last. Entries whose executable is unavailable, or whose
+Order is policy: strongest first, weakest last. New Desks use Pi for every entry; add Pi `--model`
+arguments when local policy selects a specific model. Entries whose executable is unavailable, or whose
 `enabled` flag is false, are excluded. For ordinary phase work, Jev sees the seat's active work and
-selects the weakest available model sufficient for that responsibility. If model selection is unavailable
-or low-confidence, Workflow conservatively launches the strongest available model. Final behavioral
-review has its own bounded routing step described below. Older Desks without `models.yaml` continue
-to honor a legacy seat `agent` through the executable registry.
+selects the weakest available configured Pi model sufficient for that responsibility. If model selection is
+unavailable or low-confidence, Workflow conservatively selects the strongest available configured Pi
+model. Final behavioral review has its own bounded routing step described below. Older Desks without
+`models.yaml` continue to honor a legacy seat `agent` through the executable registry.
 
 ## Configure worktrees and seats
 
@@ -124,9 +114,7 @@ atdd-flow task add resolver-os runtime-rollout --title 'Complete runtime rollout
 atdd-flow task start resolver-os runtime-rollout --by driver.runtime@resolver-os
 atdd-flow task prove resolver-os runtime-rollout --by driver.runtime@resolver-os --item 1 --proof 'CI run 42'
 atdd-flow task review resolver-os runtime-rollout --by driver.runtime@resolver-os
-atdd-flow behavioral-review launch resolver-os runtime-rollout --by coordinator@resolver-os \
-  --application tuios --placement resolver-os --gate 'CI run 42'
-# the reviewer persists APPROVE, RETURN, or ESCALATE through behavioral-review record
+# An independently attached reviewer persists APPROVE, RETURN, or ESCALATE through behavioral-review record
 atdd-flow task done resolver-os runtime-rollout --by coordinator@resolver-os
 ```
 
@@ -140,10 +128,19 @@ Threads are the durable inbox/outbox. Workflow persists a message before a best-
 atdd-flow thread start --with coordinator@resolver-os,driver.runtime@resolver-os \
   --subject 'Runtime rollout' --task resolver-os/runtime-rollout
 atdd-flow post T-... --from coordinator@resolver-os --to driver.runtime@resolver-os \
-  --expects-result --body 'Implement the task and return proof references.'
-atdd-flow result T-... M-... --from driver.runtime@resolver-os --body 'CI run 42; PR #81.'
+  --label 'implementation request' --expects-result --body 'Implement the task and return proof references.'
+atdd-flow result T-... M-... --from driver.runtime@resolver-os --label 'proof returned' --body 'CI run 42; PR #81.'
 ```
 
+New durable thread and message IDs are human-readable: `T-` or `M-`, a UTC-second
+stamp (`YYYYMMDDTHHMMSSZ`), a kebab-case slug, and a short random suffix, such as
+`M-20261010T122049Z-rollover-review_7e5e12ab`. Thread slugs derive from `--subject`.
+`post`, `receipt`, and `result` optionally accept `--label` for the message slug; it
+defaults to the message kind (`message`, `receipt`, or `result`). Labels are durable
+metadata, so provide only non-sensitive text. Message bodies are never used in IDs.
+Existing Desk thread and message filenames retain their legacy IDs unchanged and remain
+readable.
+
 For a shared boundary: driver → coordinator → affected coordinator(s) → minimum agreement in a thread → driver. `--to all` broadcasts; requested results remain outstanding until every recipient replies. Checkpoints are short handoffs, not logs; update at responsibility transitions and before replacing an agent.
 
 ## Inspect, host, and guide agents
@@ -154,24 +151,38 @@ atdd-flow status seat driver.runtime@resolver-os
 atdd-flow open driver.runtime@resolver-os
 ```
 
-TUIOS is the primary live host; tmux and Herdr have notification adapters. TUIOS launch targets the named session, never the focused session:
+Herdr and tmux can notify an already attached host pane. Flow does not create host panes: the operator starts the agent in its declared worktree with `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, then attaches that pane deterministically.
 
 ```sh
-atdd-flow attach driver.runtime@resolver-os --application tuios
-atdd-flow launch driver.runtime@resolver-os --application tuios --placement resolver-os
+atdd-flow attach driver.runtime@resolver-os --application herdr
 ```
 
-Launch selects a model from `models.yaml`, starts that model's executable in the seat's declared worktree, passes `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, records the selected model on the live runtime binding, and asks the agent to read its seat. Other hosts remain correct without an adapter; their operator supplies that prompt.
+### Optional Herdr worktree projection
+
+`multiplexer/herdr.yaml` is a compact, instance-free policy: it describes only primary versus linked worktree role placement. The Desk remains authoritative for projects, seats, tasks, branches, and worktrees. Herdr is an optional display/runtime projection and never becomes a second registry.
+
+An operator must select the target session explicitly, or run from a Herdr pane that supplies `HERDR_SESSION`; Flow never chooses a Desk-wide or focused session. Status is read-only and apply uses `--no-focus`:
+
+```sh
+atdd-flow multiplexer status herdr --session forge
+atdd-flow multiplexer apply herdr --session forge
+# Inside a Herdr pane, the inherited HERDR_SESSION is sufficient:
+atdd-flow multiplexer apply herdr
+```
+
+For each Desk project, apply reconciles the declared repository checkout as workspace `{project}` and gives every main/coordinator seat using it a tab and pane named `{seat.address}`. Linked coordinator worktrees and drivers with a non-done assigned task become linked-worktree workspaces named `{seat.address}`, with an equally named tab and pane. Unbound worktrees are ignored. Apply neither focuses, closes, nor guesses about other workspaces or sessions.
+
+New Herdr attachments store both the inherited session and pane id. Older scalar pane bindings remain readable and use their legacy Desk session only when one exists, so a bare `w1:p1` from one session cannot be mistaken for the same pane in another newly attached session.
 
 ### Pi-native Desk mail
 
-When Flow launches the `pi` executable, it automatically loads its bundled Pi extension. Pi remains a normal, interactive agent in its host pane, but the extension watches the immutable Desk mail files and wakes Pi internally with `pi.sendMessage()`—not terminal text injection.
+When Pi starts with Flow’s bundled extension, it remains a normal, interactive agent in its host pane, but the extension watches the immutable Desk mail files and wakes Pi internally with `pi.sendMessage()`—not terminal text injection.
 
 The Pi seat records both concepts independently:
 
 ```yaml
 runtime:
-  application: herdr # or tuios
+  application: herdr
   addresses:
     herdr: w9:p1
   model: pi
@@ -188,7 +199,11 @@ atdd-flow message read M-...
 
 The output includes only the message and its thread ID/subject; Flow rejects missing or ambiguous message IDs.
 
-Pi’s native wake-up is intentionally lightweight: no daemon, duplicate mailbox, or separate extension installation. The extension is shipped inside the Flow package. Its in-memory message-id guard tolerates duplicate filesystem events; the Desk thread files remain the source of truth.
+Pi’s native wake-up is intentionally lightweight: no daemon, duplicate mailbox, or separate extension installation. The extension is shipped inside the Flow package. Desk thread files remain the source of truth.
+
+At session start, the extension records one local, token-fenced **advisory** runtime observation at `.atdd-flow/pi-runtime/<encoded-seat>.yaml`. It contains only its opaque owner token, PID, model, cwd, start time, and heartbeat. A replacement Pi process atomically supersedes the prior observation; the old process can neither heartbeat, clear, nor consume queued mail after it loses its token. Shutdown and expired-heartbeat cleanup remove only the matching advisory observation. This file never selects recipients or changes a Desk seat, task, thread, checkpoint, branch, worktree, or immutable mail. `atdd-flow status seat` may display its active/stale activity as read-only information.
+
+Native mail is loss-tolerant rather than watcher-dependent. When Flow persists a message for a native or Pi-designated unbound seat, it also appends a small per-seat reference to an ordered, fixed-size pending segment under `.atdd-flow/pi-inbox/<encoded-seat>`; immutable thread `M-*.yaml` files remain the authoritative message source. On session start/reload and at a bounded interval, the extension reads only the durable queue head and consumes a fixed batch in `created_at`/message-ID order, removing a reference only after Pi accepts delivery. The pending queue shrinks after delivery, so periodic recovery neither scans nor retains the complete Desk history. `fs.watch` on that queue remains a low-latency fast path; an unavailable watcher or restarted Pi is recovered by reconciliation. Existing Pi processes still require `/reload` or restart after a Flow package upgrade to load the bundled extension.
 
 To host Pi in Herdr, create a pane with the durable Desk and seat identity, then start Pi with the extension supplied by the installed Flow package:
 
@@ -202,7 +217,9 @@ herdr agent start pi-runtime --kind pi --pane <pane-id> -- --extension "$PI_EXTE
 atdd-flow --root /path/to/desk attach driver.runtime@resolver-os --application herdr --wake native
 ```
 
-Pi receives its identity and startup task from the extension itself. Its normal TUI remains visible and manually usable; incoming Desk mail wakes it through Pi's native message API.
+Pi receives its identity and startup task from the extension itself. Its normal TUI remains visible and manually usable; incoming Desk mail wakes it through Pi's native message API. The runtime lifecycle has one internal bounded inbox transport; it does not add a second watcher, registry, mailbox, reservation system, or routing path.
+
+The lifecycle and recovery design was informed by [nicobailon/pi-messenger](https://github.com/nicobailon/pi-messenger) at `09937ed647a1b07a3b595bf75943feacb80ff123` (MIT). No pi-messenger source is copied here. Flow keeps Desk identity, recipient selection, immutable mail, and governance authoritative; any future copied source must carry its MIT notice.
 
 With ATDD Bun, enable the Workflow profile:
 

package/extensions/pi/index.ts

@@ -1,18 +1,54 @@
 import * as fs from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { parse } from "yaml";
+import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+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";
 
-type Thread = { participants?: unknown; subject?: unknown };
-type Mail = { id?: unknown; from?: unknown; to?: unknown; subject?: unknown };
+type Thread = { id?: unknown; participants?: unknown; subject?: unknown };
+export type Mail = { id?: unknown; from?: unknown; to?: unknown; subject?: unknown; created_at?: unknown };
+type InboxMail = Mail & { id: string; created_at: string };
+type PendingReference = { schema?: unknown; thread?: unknown; message?: unknown; created_at?: unknown };
+type PendingSegment = { schema?: unknown; entries?: unknown; next?: unknown };
+type PendingQueue = { schema?: unknown; head?: unknown; tail?: unknown };
+type WakeAction = () => void | Promise<void>;
+type SendIfOwned = (action: WakeAction) => Promise<boolean>;
+type InboxOptions = {
+  root: string;
+  seat: string;
+  /** Return false when this runtime has been replaced; the durable reference remains queued. */
+  deliver: (mail: InboxMail, thread: Thread, path: string, sendIfOwned?: SendIfOwned) => boolean | void | Promise<boolean | void>;
+  batchSize?: number;
+  intervalMs?: number;
+};
 
-const finalMail = /^M-[^.]+\.yaml$/;
+/** The sole internal delivery transport: one durable queue with watcher-as-fast-path recovery. */
+export type FlowInboxTransport = {
+  reconcile: () => Promise<void>;
+  start: () => Promise<void>;
+  stop: () => void;
+  watermarkFile: string;
+};
+
+export type PiRuntimeOptions = {
+  root: string;
+  seat: string;
+  pid?: number;
+  model?: string;
+  cwd?: string;
+  heartbeatMs?: number;
+  staleAfterMs?: number;
+  deliver: InboxOptions["deliver"];
+  createTransport?: (options: InboxOptions) => FlowInboxTransport;
+};
+
+const defaultBatchSize = 32;
+const defaultIntervalMs = 30_000;
+const defaultHeartbeatMs = 15_000;
+const defaultStaleAfterMs = 60_000;
 
 function participants(thread: Thread) {
-  return Array.isArray(thread.participants) && thread.participants.every((entry) => typeof entry === "string")
-    ? thread.participants as string[]
-    : [];
+  return Array.isArray(thread.participants) && thread.participants.every((entry) => typeof entry === "string") ? thread.participants as string[] : [];
 }
 
 export function addressedTo(mail: Mail, thread: Thread, seat: string) {
@@ -30,91 +66,226 @@ export function mailNotice(threadId: string, mail: Mail) {
   return `SYSTEM: Flow mail ${id} | thread ${threadId}${subject ? ` (${subject})` : ""} | ${from} → ${recipients}. Read: atdd-flow message read ${id}`;
 }
 
+function inboxDirectory(root: string, seat: string) {
+  return join(root, ".atdd-flow", "pi-inbox", encodeURIComponent(seat));
+}
+
+function pendingDirectory(root: string, seat: string) { return join(inboxDirectory(root, seat), "pending"); }
+function queuePath(root: string, seat: string) { return join(inboxDirectory(root, seat), "queue.yaml"); }
+function segmentPath(root: string, seat: string, segment: string) { return join(pendingDirectory(root, seat), `${segment}.yaml`); }
+
+async function atomicYaml(path: string, value: unknown) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = join(dirname(path), `.${basename(path)}.${crypto.randomUUID()}.tmp`);
+  await writeFile(temporary, stringify(value), "utf8");
+  await rename(temporary, path);
+}
+
+const pause = (milliseconds: number) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function withInboxLock<T>(directory: string, action: () => Promise<T>) {
+  await mkdir(directory, { recursive: true });
+  const lock = join(directory, "queue.lock");
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    try {
+      await mkdir(lock);
+      try { return await action(); }
+      finally { await rm(lock, { recursive: true, force: true }); }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - (await stat(lock)).mtimeMs > 30_000) await rm(lock, { recursive: true, force: true });
+        else await pause(5);
+      } catch { await pause(5); }
+    }
+  }
+  throw new Error(`Timed out waiting for inbox queue lock ${directory}`);
+}
+
+function validMail(value: Mail): value is InboxMail {
+  return typeof value.id === "string" && typeof value.created_at === "string";
+}
+
+function validReference(value: PendingReference): value is Required<Pick<PendingReference, "thread" | "message" | "created_at">> {
+  return typeof value.thread === "string" && typeof value.message === "string" && typeof value.created_at === "string";
+}
+
+function validQueue(value: PendingQueue): value is Required<Pick<PendingQueue, "head">> {
+  return typeof value.head === "string";
+}
+
+function references(value: PendingSegment): PendingReference[] {
+  return Array.isArray(value.entries) ? value.entries.filter((entry): entry is PendingReference => Boolean(entry) && typeof entry === "object") : [];
+}
+
 /**
- * A Pi-native wake adapter. The Desk remains authoritative: this extension
- * only observes final immutable mail files and tells Pi where to read them.
+ * Reconciles a bounded, durable queue of immutable Desk-message references.
+ * The queue is appended when Flow persists mail, so recovery never rescans historical threads.
  */
-export default function (pi: ExtensionAPI) {
-  const root = process.env.ATDD_WORKFLOW_ROOT;
-  const seat = process.env.ATDD_WORKFLOW_SEAT;
-  if (!root || !seat) return;
-
-  const threads = join(root, "threads");
+export function createInboxTransport({ root, seat, deliver, batchSize = defaultBatchSize, intervalMs = defaultIntervalMs }: InboxOptions): FlowInboxTransport {
+  let watcher: fs.FSWatcher | undefined;
+  let interval: ReturnType<typeof setInterval> | undefined;
   const delivered = new Set<string>();
-  const pending = new Set<string>();
-  const threadWatchers = new Map<string, fs.FSWatcher>();
-  let threadsWatcher: fs.FSWatcher | undefined;
-
-  const deliver = (threadId: string, fileName: string) => {
-    const key = `${threadId}/${fileName}`;
-    if (delivered.has(key) || pending.has(key)) return;
-    pending.add(key);
-    setTimeout(async () => {
+  let serial = Promise.resolve();
+
+  const reconcileNow = async () => withInboxLock(inboxDirectory(root, seat), async () => {
+    let queue: PendingQueue;
+    try { queue = parse(await readFile(queuePath(root, seat), "utf8")) as PendingQueue; }
+    catch { return; }
+    if (!validQueue(queue)) return;
+    const path = segmentPath(root, seat, queue.head);
+    let segment: PendingSegment;
+    try { segment = parse(await readFile(path, "utf8")) as PendingSegment; }
+    catch { return; }
+    const entries = references(segment);
+    // A segment contains at most 32 references. A tick reads one durable head segment and at most batchSize mail records.
+    for (let count = 0; count < batchSize && entries.length; count += 1) {
+      const reference = entries[0];
+      if (!validReference(reference)) { entries.shift(); await atomicYaml(path, { ...segment, entries }); continue; }
+      const key = `${reference.thread}/${reference.message}`;
       try {
-        const folder = join(threads, threadId);
+        const folder = join(root, "threads", reference.thread);
         const [rawThread, rawMail] = await Promise.all([
           readFile(join(folder, "thread.yaml"), "utf8"),
-          readFile(join(folder, fileName), "utf8"),
+          readFile(join(folder, `${reference.message}.yaml`), "utf8"),
         ]);
         const thread = parse(rawThread) as Thread;
         const mail = parse(rawMail) as Mail;
-        if (!addressedTo(mail, thread, seat)) return;
-        const id = typeof mail.id === "string" ? mail.id : fileName.slice(0, -5);
-        const file = join(folder, fileName);
+        if (validMail(mail) && addressedTo(mail, thread, seat) && !delivered.has(key)) {
+          const accepted = await deliver(mail, thread, join(folder, `${reference.message}.yaml`));
+          // A replaced runtime must not consume the shared durable reference.
+          if (accepted === false) return;
+        }
         delivered.add(key);
-        pi.sendMessage({
-          customType: "atdd-flow-mail",
-          content: mailNotice(threadId, { ...mail, id, subject: typeof thread.subject === "string" ? thread.subject : undefined }),
-          display: true,
-          details: { thread: threadId, message: id, path: file },
-        }, { triggerTurn: true, deliverAs: "followUp" });
-      } catch {
-        // A later filesystem event can retry an atomic-write race.
-      } finally {
-        pending.delete(key);
+        entries.shift();
+        await atomicYaml(path, { ...segment, entries });
+      } catch (error) {
+        // A crash before message persistence leaves an unpublished prepare record. Retain it briefly for an in-flight post, then discard only the non-authoritative orphan.
+        const age = Date.now() - Date.parse(reference.created_at);
+        if (reference.published !== true && (error as NodeJS.ErrnoException).code === "ENOENT") {
+          entries.shift();
+          if (Number.isFinite(age) && age > 30_000) {
+            await atomicYaml(path, { ...segment, entries });
+            continue;
+          }
+          // A fresh pre-message intent is not mail. Move it behind ready entries so a crashed writer never head-of-line blocks durable Desk mail.
+          entries.push(reference);
+          await atomicYaml(path, { ...segment, entries });
+        }
+        // Keep authoritative references until Pi accepts them; a fresh intent is retried on the next bounded tick.
+        return;
       }
-    }, 25);
-  };
-
-  const watchThread = (threadId: string) => {
-    if (threadWatchers.has(threadId)) return;
-    try {
-      const watcher = fs.watch(join(threads, threadId), (_event, file) => {
-        const name = file?.toString();
-        if (name && finalMail.test(name)) deliver(threadId, name);
-      });
-      threadWatchers.set(threadId, watcher);
-    } catch {
-      // A concurrent thread deletion is harmless.
     }
+    if (entries.length) return;
+    const next = typeof segment.next === "string" ? segment.next : undefined;
+    await unlink(path);
+    if (next) {
+      await atomicYaml(queuePath(root, seat), { ...queue, head: next });
+    } else {
+      await unlink(queuePath(root, seat));
+    }
+  });
+
+  const reconcile = () => {
+    const scheduled = serial.then(reconcileNow, reconcileNow);
+    serial = scheduled.catch(() => undefined);
+    return scheduled;
+  };
+  const start = async () => {
+    await reconcile();
+    try { watcher = fs.watch(pendingDirectory(root, seat), () => { void reconcile(); }); }
+    catch { /* Periodic reconciliation recovers unavailable watchers. */ }
+    interval = setInterval(() => { void reconcile(); }, intervalMs);
+  };
+  const stop = () => {
+    watcher?.close();
+    watcher = undefined;
+    if (interval) clearInterval(interval);
+    interval = undefined;
   };
+  return { reconcile, start, stop, watermarkFile: pendingDirectory(root, seat) };
+}
 
-  const discoverThreads = async () => {
-    try {
-      for (const entry of await readdir(threads, { withFileTypes: true })) {
-        if (entry.isDirectory() && entry.name.startsWith("T-")) watchThread(entry.name);
-      }
-    } catch {
-      // The Desk may be created after Pi starts.
-    }
+/** Backward-compatible name for the one internal FlowInboxTransport implementation. */
+export const createInboxReconciler = createInboxTransport;
+
+/**
+ * Binds a Pi process lifecycle to one non-authoritative, token-fenced runtime
+ * observation. Losing the token stops this instance from consuming mail; the
+ * single durable inbox transport remains the only delivery path.
+ */
+export function createPiRuntime({
+  root, seat, pid = process.pid, model = process.env.PI_MODEL ?? "pi", cwd = process.cwd(),
+  heartbeatMs = defaultHeartbeatMs, staleAfterMs = defaultStaleAfterMs, deliver, createTransport = createInboxTransport,
+}: PiRuntimeOptions) {
+  const ownerToken = runtimeOwnerToken();
+  let transport: FlowInboxTransport | undefined;
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+
+  const owned = () => ownsRuntimeState(root, seat, ownerToken);
+  const stop = async () => {
+    if (heartbeat) clearInterval(heartbeat);
+    heartbeat = undefined;
+    transport?.stop();
+    transport = undefined;
+    await clearRuntimeState(root, seat, ownerToken);
+  };
+  const reconcile = async () => {
+    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 });
+    transport = createTransport({
+      root, seat, batchSize: defaultBatchSize, intervalMs: defaultIntervalMs,
+      deliver: async (mail, thread, path) => {
+        // The application supplies the wake action, but this shared filesystem
+        // lock performs the final ownership check immediately around it.
+        let ownership: boolean | undefined;
+        const accepted = await deliver(mail, thread, path, async (wake) => {
+          if (ownership !== undefined) return false;
+          const result = await withOwnedRuntimeState(root, seat, ownerToken, wake);
+          ownership = result.owned;
+          return result.owned;
+        });
+        // A callback cannot accidentally consume mail by ignoring a rejected
+        // authorization result or by attempting more than one wake action.
+        return ownership === true && accepted !== false;
+      },
+    });
+    await transport.start();
+    heartbeat = setInterval(() => {
+      void heartbeatRuntimeState(root, seat, ownerToken).then((state) => {
+        if (!state) void stop();
+      });
+    }, heartbeatMs);
   };
+  return { ownerToken, start, stop, reconcile, get transport() { return transport; } };
+}
 
+/** Desk mail is authoritative; the queue is a bounded delivery index and fs.watch only shortens latency. */
+export default function (pi: ExtensionAPI) {
+  const root = process.env.ATDD_WORKFLOW_ROOT;
+  const seat = process.env.ATDD_WORKFLOW_SEAT;
+  if (!root || !seat) return;
+  let runtime: ReturnType<typeof createPiRuntime> | undefined;
   pi.on("session_start", async (_event, ctx) => {
-    await discoverThreads();
-    try { threadsWatcher = fs.watch(threads, () => { void discoverThreads(); }); }
-    catch { /* The startup prompt still makes the missing Desk visible. */ }
-    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" });
+    runtime = createPiRuntime({ root, seat, deliver: async (mail, thread, path, sendIfOwned) => {
+      if (!sendIfOwned) return false;
+      return sendIfOwned(() => {
+        pi.sendMessage({
+          customType: "atdd-flow-mail",
+          content: mailNotice(typeof thread.id === "string" ? thread.id : "unknown", { ...mail, subject: typeof thread.subject === "string" ? thread.subject : undefined }),
+          display: true, details: { thread: thread.id, message: mail.id, path },
+        }, { triggerTurn: true, deliverAs: "followUp" });
+      });
+    } });
+    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");
   });
-
-  pi.on("session_shutdown", () => {
-    threadsWatcher?.close();
-    for (const watcher of threadWatchers.values()) watcher.close();
-    threadWatchers.clear();
-  });
+  pi.on("session_shutdown", () => { void runtime?.stop(); });
 }

package/multiplexer/herdr.yaml

@@ -0,0 +1,17 @@
+schema: atdd-workflow/multiplexer/herdr/v1
+projection:
+  primary:
+    worktree: primary
+    workspace_label: "{project}"
+    seats:
+      roles: [main, coordinator]
+      tab_label: "{seat.address}"
+      pane_label: "{seat.address}"
+  linked_worktree:
+    worktree: linked
+    seats:
+      coordinator: always
+      driver: active_or_assigned
+      workspace_label: "{seat.address}"
+      tab_label: "{seat.address}"
+      pane_label: "{seat.address}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
     "extensions",
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "multiplexer"
   ],
   "keywords": [
     "atdd",

package/src/adapters.ts

@@ -17,13 +17,17 @@ export function discoverAddress(application: string, environment: Environment =
   const discoverers: Record<string, () => string> = {
     herdr: () => value(environment, "HERDR_PANE_ID", "Herdr"),
     tmux: () => value(environment, "TMUX_PANE", "tmux"),
-    tuios: () => `${value(environment, "TUIOS_SESSION", "TUIOS")}/${value(environment, "TUIOS_WINDOW_ID", "TUIOS")}`,
   };
   const discover = discoverers[application];
   if (!discover) throw new Error(`No deterministic discovery adapter is installed for ${application}.`);
   return discover();
 }
 
+/** Herdr pane ids are only unique inside a session, so new bindings record both. */
+export function discoverHerdrLocator(environment: Environment = process.env) {
+  return { session: value(environment, "HERDR_SESSION", "Herdr"), pane: value(environment, "HERDR_PANE_ID", "Herdr") };
+}
+
 export function notificationCommand(application: string, address: string, notice: string, herdrSession?: string): string[] | undefined {
   const commands: Record<string, () => string[] | undefined> = {
     tmux: () => ["tmux", "send-keys", "-t", address, notice, "Enter"],
@@ -32,11 +36,6 @@ export function notificationCommand(application: string, address: string, notice
     // pane text injection: a Desk message remains durable when an older host
     // cannot provide agent.prompt.
     herdr: () => ["herdr", ...(herdrSession ? ["--session", herdrSession] : []), "agent", "prompt", address, notice],
-    tuios: () => {
-      const separator = address.indexOf("/");
-      if (separator < 1 || separator === address.length - 1) return undefined;
-      return ["tuios", "queue", "-s", address.slice(0, separator), "-w", address.slice(separator + 1), notice];
-    },
   };
   return commands[application]?.();
 }
@@ -53,33 +52,13 @@ export type LaunchRequest = {
   seat: string;
 };
 
-/** A launch placement names a host container, never the currently visible UI. */
-export function launchCommand(request: LaunchRequest): string[] {
-  const environment = [
-    "/usr/bin/env",
-    `ATDD_WORKFLOW_ROOT=${request.root}`,
-    `ATDD_WORKFLOW_SEAT=${request.seat}`,
-    ...Object.entries(request.environment ?? {}).map(([key, value]) => `${key}=${value}`),
-    request.agent,
-    ...(request.args ?? []),
-  ];
-  if (request.application === "tuios") {
-    return [
-      "tuios", "new-window", request.name,
-      "-s", request.placement,
-      "--cwd", request.worktree,
-      "--no-focus", "--print-id", "--",
-      ...environment,
-    ];
-  }
-  throw new Error(`No deterministic launch adapter is installed for ${request.application}.`);
+/** Flow no longer owns host-pane creation; attach a host-created pane instead. */
+export function launchCommand(_request: LaunchRequest): string[] {
+  throw new Error("No deterministic launch adapter is installed.");
 }
 
-export function launchedAddress(application: string, placement: string, output: string) {
-  if (application !== "tuios") throw new Error(`No deterministic launch adapter is installed for ${application}.`);
-  const window = output.split(/\s+/)[0];
-  if (!window) throw new Error("TUIOS created a window without returning its id.");
-  return `${placement}/${window}`;
+export function launchedAddress(_application: string, _placement: string, _output: string): string {
+  throw new Error("No deterministic launch adapter is installed.");
 }
 
 export async function notify(application: string, address: string, notice: string, herdrSession?: string) {