@afokapu/atdd-flow 0.3.7 → 0.3.8

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { basename, resolve } from "node:path";
-import { init, initProject, spawn, bind, useApplication, attach, launch, describe, checkpoint, migrate, openSeat, piExtensionPath } from "./seats";
+import { init, initProject, spawn, bind, useApplication, attach, describe, checkpoint, migrate, openSeat, piExtensionPath } from "./seats";
 import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
 import { required, values, words } from "./core";
@@ -9,6 +9,7 @@ import { addressBook } from "./address-book";
 import * as judgment from "./judgment";
 import * as reviews from "./reviews";
 import { status } from "./overview";
+import { multiplexer } from "./multiplexer";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
 
@@ -20,11 +21,11 @@ Usage:
   atdd-flow desk migrate
   atdd-flow project init <project>
   atdd-flow spawn <project> <role> <name> [--worktree <path>] [--branch <branch>] [--agent <legacy-executable>]
-  atdd-flow bind <address> [--application <application>] --address <native-address> [--agent <executable>] [--worktree <path>] [--wake host|native]
+  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 launch <address> --application <application> --placement <native-container-address>
   atdd-flow application use <address> <application>
+  atdd-flow multiplexer status|apply herdr [--session <name>]
   atdd-flow describe <address> --purpose <one-line responsibility>
   atdd-flow checkpoint <address> --summary <text> --next <text> [--status active|standby|blocked|complete|unverified]
   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> ...]
@@ -42,9 +43,9 @@ Usage:
   atdd-flow thread add <thread-id> <address>
   atdd-flow thread open <thread-id>
   atdd-flow message read <message-id>
-  atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--expects-result]
-  atdd-flow receipt <thread-id> <message-id> --from <address> [--body <text>]
-  atdd-flow result <thread-id> <message-id> --from <address> --body <text>
+  atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--label <non-sensitive-text>] [--expects-result]
+  atdd-flow receipt <thread-id> <message-id> --from <address> [--body <text>] [--label <non-sensitive-text>]
+  atdd-flow result <thread-id> <message-id> --from <address> --body <text> [--label <non-sensitive-text>]
   atdd-flow status [project <project>|task <project> <task-id>|seat <address>|thread <thread-id>] [--all]
   atdd-flow scout --goal <text> --path <file> [--path <file> ...] [--question <text>]
   atdd-flow focus-check <project> <task-id> --action <proposed action>
@@ -83,11 +84,11 @@ async function main() {
       if (rest[0] === "extension-path") return console.log(piExtensionPath());
       throw new Error("Use `atdd-flow pi extension-path`.");
     },
-    launch: () => launch(root, required(rest[0], "address"), rest.slice(1)),
     application: async () => {
       if (rest[0] === "use") return useApplication(root, required(rest[1], "address"), required(rest[2], "application"));
       throw new Error("Use `atdd-flow application use <address> <application>`.");
     },
+    multiplexer: () => multiplexer(root, rest),
     describe: () => describe(root, required(rest[0], "address"), rest.slice(1)),
     checkpoint: () => checkpoint(root, required(rest[0], "address"), rest.slice(1)),
     task: async () => {

package/src/core.ts

@@ -48,7 +48,15 @@ export type Project = {
  * while the relevant bridge is responsible for using their native format.
  */
 /** `native` means the agent runtime wakes itself from the durable Desk. */
-export type Runtime = { application: string; addresses: Record<string, string>; attached_at?: string; model?: string; wake?: "host" | "native" };
+export type HerdrLocator = { session: string; pane: string };
+/** Strings are legacy native addresses; new Herdr bindings retain their session. */
+export type RuntimeAddress = string | HerdrLocator;
+export type Runtime = { application: string; addresses: Record<string, RuntimeAddress>; attached_at?: string; model?: string; wake?: "host" | "native" };
+
+export function runtimeAddress(application: string, value: RuntimeAddress, legacyHerdrSession?: string) {
+  if (application !== "herdr" || typeof value === "string") return { address: value, ...(application === "herdr" && legacyHerdrSession ? { session: legacyHerdrSession } : {}) };
+  return { address: value.pane, session: value.session };
+}
 export type Seat = {
   schema: string;
   address: string;
@@ -73,7 +81,31 @@ export type Checkpoint = {
 };
 
 export const now = () => new Date().toISOString();
-export const id = (prefix: "T" | "M" | "R") => `${prefix}-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+
+/** Converts human input into the stable, filesystem-safe part of a durable ID. */
+export function kebabCase(value: string, fallback: string) {
+  const slug = value.normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || fallback;
+}
+
+function utcSecond(value: Date) {
+  return value.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+
+/**
+ * New thread/message IDs are readable without sacrificing independent-process
+ * allocation: UUID entropy keeps simultaneous same-second allocations distinct.
+ * Review IDs retain their established format because this migration is T/M-only.
+ */
+export const id = (prefix: "T" | "M" | "R", label?: string, timestamp = new Date()) => {
+  if (prefix === "R") return `${prefix}-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+  const fallback = prefix === "T" ? "thread" : "message";
+  return `${prefix}-${utcSecond(timestamp)}-${kebabCase(label ?? fallback, fallback)}_${randomUUID().replace(/-/g, "").slice(0, 8)}`;
+};
 export const words = (args: string[], flag: string) => {
   const index = args.indexOf(flag);
   return index < 0 ? undefined : args[index + 1];

package/src/multiplexer.ts

@@ -0,0 +1,204 @@
+import { readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { exists, paths, project, readYaml, runOutput, type Project, type Seat } from "./core";
+import { seatTasks } from "./tasks";
+
+export type HerdrPolicy = {
+  schema: "atdd-workflow/multiplexer/herdr/v1";
+  projection: {
+    primary: {
+      worktree: "primary";
+      workspace_label: "{project}";
+      seats: { roles: string[]; 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}";
+      };
+    };
+  };
+};
+
+type Workspace = { workspace_id: string; label?: string; worktree?: { checkout_path?: string } };
+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 };
+
+const policyFile = () => join(import.meta.dir, "..", "multiplexer", "herdr.yaml");
+const selectedSession = (args: string[], environment: Record<string, string | undefined> = process.env) => {
+  const index = args.indexOf("--session");
+  return index < 0 ? environment.HERDR_SESSION : args[index + 1];
+};
+
+/** The policy is deliberately instance-free; all concrete data comes from Desk records at apply time. */
+export async function herdrPolicy() {
+  const file = policyFile();
+  if (!await exists(file)) throw new Error(`Herdr multiplexer policy is missing: ${file}`);
+  const value = await readYaml<HerdrPolicy>(file);
+  const keys = (entry: object, expected: string[]) => expected.length === Object.keys(entry).length && expected.every((key) => key in entry);
+  const expected = keys(value, ["schema", "projection"])
+    && keys(value.projection ?? {}, ["primary", "linked_worktree"])
+    && keys(value.projection?.primary ?? {}, ["worktree", "workspace_label", "seats"])
+    && keys(value.projection?.primary?.seats ?? {}, ["roles", "tab_label", "pane_label"])
+    && keys(value.projection?.linked_worktree ?? {}, ["worktree", "seats"])
+    && keys(value.projection?.linked_worktree?.seats ?? {}, ["coordinator", "driver", "workspace_label", "tab_label", "pane_label"])
+    && value.schema === "atdd-workflow/multiplexer/herdr/v1"
+    && value.projection?.primary?.worktree === "primary"
+    && value.projection.primary.workspace_label === "{project}"
+    && Array.isArray(value.projection.primary.seats?.roles)
+    && value.projection.primary.seats.roles.length === 2
+    && value.projection.primary.seats.roles.includes("main")
+    && value.projection.primary.seats.roles.includes("coordinator")
+    && value.projection.primary.seats.tab_label === "{seat.address}"
+    && value.projection.primary.seats.pane_label === "{seat.address}"
+    && value.projection.linked_worktree?.worktree === "linked"
+    && value.projection.linked_worktree.seats?.coordinator === "always"
+    && value.projection.linked_worktree.seats.driver === "active_or_assigned"
+    && value.projection.linked_worktree.seats.workspace_label === "{seat.address}"
+    && value.projection.linked_worktree.seats.tab_label === "{seat.address}"
+    && value.projection.linked_worktree.seats.pane_label === "{seat.address}";
+  if (!expected) throw new Error("Invalid generic Herdr multiplexer policy.");
+  return value;
+}
+
+async function projectSeats(root: string, projectName: string) {
+  const folder = paths(root).seats(projectName);
+  let names: string[];
+  try { names = await readdir(folder); }
+  catch { return []; }
+  const seats = await Promise.all(names.map(async (name) => {
+    const file = join(folder, name, "seat.yaml");
+    return await exists(file) ? readYaml<Seat>(file) : undefined;
+  }));
+  return seats.filter((entry): entry is Seat => Boolean(entry && entry.schema === "atdd-workflow/seat/v2" && !entry.retired));
+}
+
+async function targets(root: string): Promise<Target[]> {
+  let projects: string[];
+  try { projects = await readdir(paths(root).work); }
+  catch { return []; }
+  const result: Target[] = [];
+  for (const name of projects) {
+    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) {
+        result.push({ project: name, worktree: primary, workspaceLabel: name, seat: entry });
+        continue;
+      }
+      if (entry.role === "coordinator" && resolve(entry.worktree) !== primary) {
+        result.push({ project: name, worktree: resolve(entry.worktree), workspaceLabel: entry.address, seat: entry });
+        continue;
+      }
+      if (entry.role === "driver") {
+        const active = (await seatTasks(root, name, entry.address)).some(({ task }) => task.assignee === entry.address && task.status !== "done");
+        if (active) result.push({ project: name, worktree: resolve(entry.worktree), workspaceLabel: entry.address, seat: entry });
+      }
+    }
+  }
+  return result;
+}
+
+function command(session: string, args: string[]) {
+  return runOutput(["herdr", "--session", session, ...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 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;
+}
+
+async function liveWorkspaces(session: string) {
+  const value = json(await command(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[]) {
+  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"]));
+    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]);
+    current.label = target.workspaceLabel;
+  }
+  return current.workspace_id;
+}
+
+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);
+  let pane: string | undefined;
+  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 };
+    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;
+  if (!first) throw new Error(`Herdr tab ${tab.tab_id} has no pane to label.`);
+  await command(session, ["pane", "rename", first, target.seat.address]);
+}
+
+export async function multiplexer(root: string, args: string[]) {
+  const action = args[0];
+  const application = args[1];
+  if (!(["status", "apply"] as string[]).includes(action) || application !== "herdr") {
+    throw new Error("Use `atdd-flow multiplexer status|apply herdr [--session <name>]`.");
+  }
+  await herdrPolicy();
+  const session = selectedSession(args.slice(2));
+  if (!session) {
+    console.log("No Herdr session selected; projection was not run.");
+    return;
+  }
+  const desired = await targets(root);
+  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));
+    return;
+  }
+  const workspaces = await liveWorkspaces(session);
+  for (const target of desired) {
+    const workspace = await ensureWorkspace(session, target, workspaces);
+    if (target.seat) await ensureSeatTab(session, workspace, target);
+  }
+  console.log(`Projected ${desired.length} Desk seat worktree(s) into Herdr session ${session}.`);
+}

package/src/overview.ts

@@ -1,6 +1,7 @@
 import { readdir } from "node:fs/promises";
 import { canonicalAddress, desk, exists, paths, readYaml, type Checkpoint, type Seat } from "./core";
 import { type Task, type TaskStatus } from "./tasks";
+import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { type Message, type Thread } from "./threads";
 
 type ListedTask = { project: string; id: string; task: Task; waiting: string[] };
@@ -331,6 +332,8 @@ async function seatDashboard(root: string, address: string) {
   const runtime = entry.record.runtime;
   if (!runtime) console.log(`  ${muted("No live application is currently attached.")}`);
   for (const [application, nativeAddress] of Object.entries(runtime?.addresses ?? {})) console.log(`  ${application}${application === runtime?.application ? " *" : "  "} ${nativeAddress}`);
+  const advisory = await readRuntimeState(root, resolved);
+  if (advisory) console.log(`  pi advisory  ${isRuntimeStateStale(advisory, 60_000) ? "stale" : "active"} · ${advisory.model} · pid ${advisory.pid} · heartbeat ${advisory.heartbeat_at}`);
   rule("RESPONSIBILITIES", String(owned.length));
   if (!owned.length) console.log(`  ${muted("No task currently names this seat.")}`);
   for (const task of owned.slice(0, 6)) console.log(`  ${tone("●", taskPhase(task))} ${task.id}  ${taskPhase(task)}${task.task.assignee === resolved ? "  owner" : "  coordinator"}`);

package/src/runtime-state.ts

@@ -0,0 +1,182 @@
+import { mkdir, readFile, rm, stat, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { addressParts, atomicYaml, yaml } from "./core";
+
+/**
+ * A local, advisory observation of one runtime for one already-authoritative
+ * Desk seat. This record is deliberately not a registry: it cannot select a
+ * recipient, deliver mail, or change any Desk-owned state.
+ */
+export type RuntimeState = {
+  schema: "atdd-flow/pi-runtime-state/v1";
+  seat: string;
+  owner_token: string;
+  pid: number;
+  model: string;
+  cwd: string;
+  started_at: string;
+  heartbeat_at: string;
+};
+
+export type RuntimeStateRegistration = Pick<RuntimeState, "seat" | "owner_token" | "pid" | "model" | "cwd">;
+
+const schema = "atdd-flow/pi-runtime-state/v1" as const;
+const lockStaleMs = 5 * 60_000;
+const lockAttempts = 2_000;
+const pause = (milliseconds: number) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function timestamp(value: unknown): value is string {
+  return nonEmpty(value) && Number.isFinite(Date.parse(value));
+}
+
+function valid(value: unknown): value is RuntimeState {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return record.schema === schema
+    && nonEmpty(record.seat)
+    && nonEmpty(record.owner_token)
+    && Number.isInteger(record.pid) && (record.pid as number) > 0
+    && nonEmpty(record.model)
+    && nonEmpty(record.cwd)
+    && timestamp(record.started_at)
+    && timestamp(record.heartbeat_at);
+}
+
+function assertRegistration(value: RuntimeStateRegistration) {
+  addressParts(value.seat);
+  if (!nonEmpty(value.owner_token)) throw new Error("Runtime state requires a non-empty owner token.");
+  if (!Number.isInteger(value.pid) || value.pid <= 0) throw new Error("Runtime state requires a positive integer pid.");
+  if (!nonEmpty(value.model)) throw new Error("Runtime state requires a model.");
+  if (!nonEmpty(value.cwd)) throw new Error("Runtime state requires a cwd.");
+}
+
+/** A mkdir lock serializes state mutation and final wake authorization across Pi processes. */
+async function exclusive<T>(file: string, work: () => Promise<T>): Promise<T> {
+  const lock = `${file}.lock`;
+  await mkdir(dirname(file), { recursive: true });
+  for (let attempt = 0; attempt < lockAttempts; attempt += 1) {
+    try {
+      await mkdir(lock);
+      try { return await work(); }
+      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 > lockStaleMs) await rm(lock, { recursive: true, force: true });
+        else await pause(5);
+      } catch { await pause(5); }
+    }
+  }
+  throw new Error(`Timed out waiting for runtime-state lock ${file}`);
+}
+
+/** A deterministic, per-seat local advisory state path; it never resolves Desk membership. */
+export function runtimeStatePath(root: string, seat: string) {
+  addressParts(seat);
+  return join(root, ".atdd-flow", "pi-runtime", `${encodeURIComponent(seat)}.yaml`);
+}
+
+/** Generate an opaque token for a runtime owner that needs one. */
+export function runtimeOwnerToken() {
+  return randomUUID();
+}
+
+/**
+ * Atomically publish a new advisory observation for this seat. A later
+ * registration replaces the record and therefore fences a prior owner token.
+ */
+export async function registerRuntimeState(root: string, registration: RuntimeStateRegistration, at = new Date().toISOString()) {
+  assertRegistration(registration);
+  if (!timestamp(at)) throw new Error("Runtime state requires a valid timestamp.");
+  const file = runtimeStatePath(root, registration.seat);
+  const state: RuntimeState = { schema, ...registration, started_at: at, heartbeat_at: at };
+  return exclusive(file, async () => {
+    await atomicYaml(file, state);
+    return state;
+  });
+}
+
+/** Read an advisory record. Missing or invalid local state is deliberately treated as absent. */
+export async function readRuntimeState(root: string, seat: string): Promise<RuntimeState | undefined> {
+  const file = runtimeStatePath(root, seat);
+  try {
+    const value = yaml.parse<unknown>(await readFile(file, "utf8"));
+    return valid(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** True only while this token owns the current advisory record; never a governance decision. */
+export async function ownsRuntimeState(root: string, seat: string, ownerToken: string) {
+  return (await readRuntimeState(root, seat))?.owner_token === ownerToken;
+}
+
+/**
+ * Invoke a wake action only while this process still owns the current record.
+ * The filesystem lock is shared by separate Pi processes and is held through
+ * the action, so registration cannot replace the owner mid-wake.
+ */
+export async function withOwnedRuntimeState<T>(root: string, seat: string, ownerToken: string, action: () => Promise<T> | T) {
+  const file = runtimeStatePath(root, seat);
+  return exclusive(file, async () => {
+    if (!await ownsRuntimeState(root, seat, ownerToken)) return { owned: false as const };
+    return { owned: true as const, value: await action() };
+  });
+}
+
+/** Remove an abandoned advisory observation only when its heartbeat has expired. */
+export async function clearStaleRuntimeState(root: string, seat: string, maxAgeMs: number, observedAt = new Date()) {
+  const file = runtimeStatePath(root, seat);
+  return exclusive(file, async () => {
+    const current = await readRuntimeState(root, seat);
+    if (!current || !isRuntimeStateStale(current, maxAgeMs, observedAt)) return false;
+    try {
+      await unlink(file);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Update activity only if this owner still holds the current advisory record. */
+export async function heartbeatRuntimeState(root: string, seat: string, ownerToken: string, at = new Date().toISOString()) {
+  if (!nonEmpty(ownerToken)) throw new Error("Runtime state requires a non-empty owner token.");
+  if (!timestamp(at)) throw new Error("Runtime state requires a valid timestamp.");
+  const file = runtimeStatePath(root, seat);
+  return exclusive(file, async () => {
+    const current = await readRuntimeState(root, seat);
+    if (!current || current.owner_token !== ownerToken) return undefined;
+    const next = { ...current, heartbeat_at: at };
+    await atomicYaml(file, next);
+    return next;
+  });
+}
+
+/** Remove local advisory state only if this owner still owns it. */
+export async function clearRuntimeState(root: string, seat: string, ownerToken: string) {
+  if (!nonEmpty(ownerToken)) throw new Error("Runtime state requires a non-empty owner token.");
+  const file = runtimeStatePath(root, seat);
+  return exclusive(file, async () => {
+    const current = await readRuntimeState(root, seat);
+    if (!current || current.owner_token !== ownerToken) return false;
+    try {
+      await unlink(file);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** This local age calculation is informational only and cannot govern Desk work. */
+export function isRuntimeStateStale(state: RuntimeState, maxAgeMs: number, observedAt = new Date()) {
+  if (!Number.isFinite(maxAgeMs) || maxAgeMs < 0) throw new Error("Runtime state max age must be a non-negative number.");
+  return observedAt.getTime() - Date.parse(state.heartbeat_at) >= maxAgeMs;
+}

package/src/seats.ts

@@ -1,11 +1,11 @@
 import { existsSync } from "node:fs";
 import { mkdir, readdir } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
-import { discoverAddress, launchedAddress, launchCommand, notify } from "./adapters";
+import { dirname, join, resolve } from "node:path";
+import { discoverAddress, discoverHerdrLocator, notify } from "./adapters";
 import {
   type Checkpoint, type Desk, type ModelCandidate, type ModelPortfolio, type Project, type Role, type Runtime, type Seat,
   atomicYaml, canonicalAddress, desk, exists, fill, migrateDesk, modelPortfolio, now, paths, project, readYaml,
-  required, run, runOutput, seat, words, yaml,
+  required, run, runtimeAddress, seat, words, yaml,
 } from "./core";
 import { selectModel } from "./judgment";
 import { seatTasks } from "./tasks";
@@ -13,20 +13,19 @@ import { seatTasks } from "./tasks";
 const defaultRoles = (dynamicModels = true): Record<string, Role> => ({
   coordinator: {
     address: "coordinator@{project}", branch: "main", worktree: "{repository}",
-    ...(dynamicModels ? {} : { agent: "claude" }),
+    ...(dynamicModels ? {} : { agent: "pi" }),
   },
   driver: {
     address: "driver.{name}@{project}", branch: "delivery/{name}", base: "main", worktree: "{worktree_root}/{name}",
-    ...(dynamicModels ? {} : { agent: "codex" }),
+    ...(dynamicModels ? {} : { agent: "pi" }),
   },
 });
 
-const defaultExecutables = () => ({ claude: "claude", codex: "codex", pi: "pi", kimi: "kimi", glm: "glm" });
+const defaultExecutables = () => ({ pi: "pi" });
 const defaultModels = (): ModelPortfolio => ({
   schema: "atdd-workflow/models/v1",
   models: [
-    { id: "claude", executable: "claude", description: "Default high-capability candidate; replace or refine this portfolio for the local environment." },
-    { id: "codex", executable: "codex", description: "Default lower-cost candidate." },
+    { id: "pi", executable: "pi", description: "Default coding runtime. Configure Pi model arguments here when local policy requires a specific model." },
   ],
 });
 
@@ -39,7 +38,7 @@ export async function init(root: string, name: string, args: string[]) {
   if (await exists(paths(root).desk)) {
     throw new Error(`Desk registry already exists at ${paths(root).desk}; refusing to overwrite it. Use an existing Desk command, or choose a new directory.`);
   }
-  const config = { schema: "atdd-workflow/desk/v1" as const, desk: name, application: "tuios", executables: defaultExecutables() };
+  const config = { schema: "atdd-workflow/desk/v1" as const, desk: name, application: "herdr", executables: defaultExecutables() };
   await Promise.all([mkdir(paths(root).work, { recursive: true }), mkdir(paths(root).threads, { recursive: true })]);
   await Promise.all([atomicYaml(paths(root).desk, config), atomicYaml(paths(root).models, defaultModels())]);
   if (args.includes("--git") && !await exists(join(root, ".git"))) await run(["git", "init", "--initial-branch=main", root]);
@@ -105,11 +104,13 @@ export async function bind(root: string, address: string, args: string[], select
   const selectedWake = wake ?? requestedWake as Runtime["wake"] | undefined;
   if (!/^[a-z][a-z0-9_-]*$/.test(application)) throw new Error(`Application must use lowercase letters, numbers, underscores, or hyphens: ${application}`);
   const nativeAddress = required(words(args, "--address"), "--address");
+  const requestedSession = words(args, "--session");
   const addresses = record.runtime?.addresses ?? {};
+  const runtimeBinding = application === "herdr" && requestedSession ? { session: requestedSession, pane: nativeAddress } : nativeAddress;
   record.runtime = {
     ...record.runtime,
     application,
-    addresses: { ...addresses, [application]: nativeAddress },
+    addresses: { ...addresses, [application]: runtimeBinding },
     attached_at: now(),
     ...(selectedModel ? { model: selectedModel } : {}),
     ...(selectedWake ? { wake: selectedWake } : {}),
@@ -130,17 +131,20 @@ export async function useApplication(root: string, address: string, application:
   const resolved = await canonicalAddress(root, address);
   const record = await seat(root, resolved);
   const runtime = required(record.runtime, `a runtime binding for ${resolved}`);
-  if (!runtime.addresses[application]) throw new Error(`${resolved} has no ${application} address. Bind it first.`);
+  const stored = runtime.addresses[application];
+  if (!stored) throw new Error(`${resolved} has no ${application} address. Bind it first.`);
   record.runtime = { ...runtime, application, attached_at: now() };
   await atomicYaml(paths(root).seatFile(resolved), record);
-  console.log(`Using ${application}:${record.runtime.addresses[application]} for ${resolved}`);
+  const locator = runtimeAddress(application, stored, (await desk(root)).herdr_session);
+  console.log(`Using ${application}:${locator.session ? `${locator.session}/` : ""}${locator.address} for ${resolved}`);
 }
 
 export async function attach(root: string, address: string, args: string[]) {
   const application = words(args, "--application") ?? (await desk(root)).application;
   const nativeAddress = discoverAddress(application);
   const wake = words(args, "--wake");
-  await bind(root, address, ["--application", application, "--address", nativeAddress, ...(wake ? ["--wake", wake] : [])]);
+  const session = application === "herdr" ? discoverHerdrLocator().session : undefined;
+  await bind(root, address, ["--application", application, "--address", nativeAddress, ...(session ? ["--session", session] : []), ...(wake ? ["--wake", wake] : [])]);
 }
 
 export function availableModelCandidates(config: Desk, portfolio: ModelPortfolio) {
@@ -178,48 +182,8 @@ async function chooseLaunchModel(root: string, config: Desk, record: Seat, portf
   return required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`);
 }
 
-export const launchNotice = (address: string) =>
-  `SYSTEM: you are ${address}. Read your durable seat and assigned task with: atdd-flow open ${address}. Use the installed atdd-flow command; never use bunx to replace it or run atdd-flow init against an existing Desk. Routing: operator@desk is the human authority; drivers report to coordinators, and main seats are the normal technical gateway to the operator. Continue assigned in_progress work until it is review-ready or explicitly blocked.`;
-
 /** 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");
-export const isPiExecutable = (agent: string) => basename(agent) === "pi";
-export const piLaunchArgs = (agent: string, args: string[]) => isPiExecutable(agent) ? [...args, "--extension", piExtensionPath()] : args;
-
-export async function launch(root: string, address: string, args: string[]) {
-  const resolved = await canonicalAddress(root, address);
-  const record = await seat(root, resolved);
-  const config = await desk(root);
-  const application = required(words(args, "--application"), "--application");
-  const placement = required(words(args, "--placement"), "--placement");
-  const portfolio = await modelPortfolio(root);
-  let agent: string;
-  let modelArgs: string[] = [];
-  let selectedModel: string;
-  if (portfolio) {
-    const selected = await chooseLaunchModel(root, config, record, portfolio);
-    const command = resolveModelCommand(config, selected);
-    agent = command.agent;
-    modelArgs = command.args;
-    selectedModel = selected.id;
-  } else {
-    const legacyAgent = required(record.agent, "models.yaml or a legacy seat agent");
-    agent = resolveExecutable(config, legacyAgent);
-    selectedModel = legacyAgent;
-  }
-  const wake: Runtime["wake"] = isPiExecutable(agent) ? "native" : "host";
-  modelArgs = piLaunchArgs(agent, modelArgs);
-  const output = await runOutput(launchCommand({
-    application, placement, name: resolved, worktree: record.worktree,
-    agent, args: modelArgs, root, seat: resolved,
-  }));
-  const nativeAddress = launchedAddress(application, placement, output);
-  await bind(root, resolved, ["--application", application, "--address", nativeAddress], selectedModel, wake);
-  if (wake === "native") return;
-  const notice = launchNotice(resolved);
-  try { await notify(application, nativeAddress, notice, config.herdr_session); }
-  catch (error) { console.warn(`Launch notification for ${resolved} was not delivered: ${(error as Error).message}`); }
-}
 
 export async function describe(root: string, address: string, args: string[]) {
   const resolved = await canonicalAddress(root, address);
@@ -247,6 +211,10 @@ export async function openSeat(root: string, address: string) {
   const resolved = await canonicalAddress(root, address);
   const record = await seat(root, resolved);
   console.log(yaml.print(record));
+  // Keep the native pane visible to scripts and operators that consumed the
+  // legacy scalar form while the durable record now carries its session too.
+  const herdr = record.runtime?.addresses.herdr;
+  if (herdr && typeof herdr !== "string") console.log(`herdr: ${herdr.pane} (session: ${herdr.session})`);
   const checkpointFile = paths(root).checkpointFile(resolved);
   if (await exists(checkpointFile)) console.log(yaml.print(await readYaml<Checkpoint>(checkpointFile)));
   const threadIds = await readdir(paths(root).threads);