@afokapu/atdd-flow 0.3.34 → 0.3.36

package/README.md

@@ -109,6 +109,8 @@ atdd-flow spawn example-app driver runtime
 
 `spawn` creates missing driver worktrees through Git: this example creates `/Users/you/Github/worktrees/example-app/runtime` on `delivery/runtime`. ATDD Bun owns safe retirement, not creation. A seat can own several tasks.
 
+For the canonical named-coordinator topology, create an unassigned `todo` task first, then use `atdd-flow spawn <project> driver <name> --task <task-id>`. Flow derives the fresh `delivery/<name>` worktree from the task coordinator's exact `integration/<stream>` head (or `main` for `main@project`), records that commit as `governed_base`, assigns the task, and reports the integration return branch. It refuses existing seats, worktrees, or branches and invalid, dirty, stale, generic, nested, or cross-project coordinator lineage rather than reusing history.
+
 ## Deliver work
 
 ```text
@@ -128,7 +130,7 @@ atdd-flow task review example-app runtime-rollout --by driver.runtime@example-ap
 atdd-flow task done example-app runtime-rollout --by coordinator@example-app
 ```
 
-Proof is a compact PR, CI run, report, commit range, deployment, or thread reference. Dependencies gate prerequisites; independent tasks are parallel-ready. A coordinator can staff an unassigned ready task with `atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address>`; assignment is allowed only once while the task is `todo`. Use `task block` only for a real external blocker, then checkpoint exact state and next action. Once the blocker is resolved, only that coordinator can clear it with `atdd-flow task unblock <project> <task-id> --by <coordinator-address>` while the task remains `in_progress`. For deliveries explicitly governed by the `workflow` ATDD Bun profile, `review → done` additionally requires a durable final behavioral-review result with decision `APPROVE` for the current clean delivery commit. For an idle driver’s final task, `task done ... --retire-assignee` delegates clean-and-merged worktree retirement to ATDD Bun.
+Proof is a compact PR, CI run, report, commit range, deployment, or thread reference. Dependencies gate prerequisites; independent tasks are parallel-ready. A coordinator can staff an unassigned ready task with `atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address>`; assignment is allowed only once while the task is `todo`. Use `task block` only for a real external blocker, then checkpoint exact state and next action. Once the blocker is resolved, only that coordinator can clear it with `atdd-flow task unblock <project> <task-id> --by <coordinator-address>` while the task remains `in_progress`. For deliveries explicitly governed by the `workflow` ATDD Bun profile, `review → done` additionally requires a durable final behavioral-review result with decision `APPROVE` for the current clean delivery commit. For an idle driver’s final task, `task done ... --retire-assignee` delegates clean-and-merged worktree retirement to ATDD Bun. A driver whose assigned tasks are all already `done` is retired with `atdd-flow seat retire <address> --by <coordinator-or-main>`, using the same checks. When every assigned task is `done` and the recorded worktree is absent from disk and from `git worktree list`, `seat retire` records the retirement without running worktree finish, deleting the branch, or recreating the worktree; a missing worktree that Git still registers fails closed. Both paths fail closed on unfinished tasks or a dirty or unmerged worktree; on success they record `retired` and a checkpoint, then close the driver's Herdr workspace when `close_inactive` is enabled.
 
 At 80% context usage a seat writes a structured handover (template and process rules in the lifecycle convention), checks it with `atdd-flow handover <address> --check --file <path>`, and records it with `atdd-flow handover <address> --file <path>`. The seat keeps one durable `handover.yaml` beside its unchanged checkpoint. Recording rejects a missing header, Runtime line, or section, sections out of order, more than 150 lines, vague references such as `latest` or `that PR` without an exact ID, and a `supersedes` value that does not match the recorded handover id. A fresh session bound to the same seat reads it with `atdd-flow handover show <address>`.
 
@@ -184,7 +186,16 @@ atdd-flow multiplexer apply herdr --session forge
 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.
+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 active drivers become linked-worktree workspaces named `{seat.address}`, with an equally named tab and pane. A driver is active only while it has an unblocked `in_progress` assigned task or a bound Herdr pane that still runs an agent; never-started, blocked, and finished drivers get no workspace. An explicit per-seat projection such as `pi runtime launch` still projects its own seat. A missing linked worktree is skipped and reported under `unprojected` instead of aborting the Desk. Unbound worktrees are ignored, and apply never focuses or guesses about other sessions.
+
+A workspace is stale when it is labelled with a Desk driver seat address, that driver is retired or inactive, and its checkout is a linked worktree of the seat's Desk project or no longer exists. `multiplexer status` reports the `stale` count. `multiplexer apply` closes stale workspaces only when `desk.yaml` enables it:
+
+```yaml
+multiplexer:
+  close_inactive: true
+```
+
+Apply never closes a stale workspace while one of its agents is `working` or `blocked`; it reports it instead. Primary, main, coordinator, operator, and unrelated workspaces are never stale. The bundled `multiplexer/herdr.yaml` policy is unchanged.
 
 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.
 

package/package.json

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

package/src/cli.ts

@@ -44,6 +44,7 @@ Usage:
   atdd-flow task import <project> <task-id> --proof <reference> [--proof <reference> ...] [--done-when <text> ...] [--source <reference>]
   atdd-flow task start|review|return <project> <task-id> --by <address>
   atdd-flow task done <project> <task-id> --by <address> [--retire-assignee]
+  atdd-flow seat retire <address> --by <coordinator-or-main>
   atdd-flow task prove <project> <task-id> --by <address> --item <number> --proof <reference>
   atdd-flow task handoff <project> <task-id> --by <assignee> --phase <plan|red|green|refactor> --evidence <message-or-reference>
   atdd-flow task respond <project> <task-id> --by <coordinator> --outcome <accept|return> --phase <plan|red|green|refactor>
@@ -136,6 +137,10 @@ async function main() {
       if (subcommand === "open") return tasks.open(root, required(projectName, "project"), required(taskId, "task id"));
       throw new Error("Use `atdd-flow task add|assign|transfer|amend|import|start|prove|handoff|respond|review|return|done|block|unblock|list|open`.");
     },
+    seat: async () => {
+      if (rest[0] === "retire") return tasks.retireSeat(root, required(rest[1], "address"), rest.slice(2));
+      throw new Error("Use `atdd-flow seat retire <address> --by <coordinator-or-main>`.");
+    },
     cleanup: async () => {
       const [subcommand, projectName, taskId] = rest;
       if (subcommand === "status") return console.log(Bun.YAML.stringify(await cleanup.coordinatorStatus(root, required(projectName, "project"))));

package/src/core.ts

@@ -17,6 +17,8 @@ export type Desk = {
   application: string;
   /** Native Herdr session used for Desk notifications when application is herdr. */
   herdr_session?: string;
+  /** Optional multiplexer housekeeping; inactive driver workspaces are closed only when enabled. */
+  multiplexer?: { close_inactive?: boolean };
   /** Named commands that model portfolio entries may resolve through. */
   executables?: Record<string, string>;
   aliases?: Record<string, string>;

package/src/multiplexer.ts

@@ -1,6 +1,6 @@
 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 { desk, exists, paths, project, readYaml, runOutput, type Project, type Seat } from "./core";
 import { seatTasks } from "./tasks";
 
 export type HerdrPolicy = {
@@ -26,7 +26,7 @@ export type HerdrPolicy = {
 
 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 Pane = { pane_id: string; tab_id: string; label?: string; agent_status?: 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>;
@@ -77,7 +77,7 @@ export async function herdrPolicy() {
   return value;
 }
 
-async function projectSeats(root: string, projectName: string) {
+async function projectSeats(root: string, projectName: string, includeRetired = false) {
   const folder = paths(root).seats(projectName);
   let names: string[];
   try { names = await readdir(folder); }
@@ -86,7 +86,29 @@ async function projectSeats(root: string, projectName: string) {
     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));
+  return seats.filter((entry): entry is Seat => Boolean(entry && entry.schema === "atdd-workflow/seat/v2" && (includeRetired || !entry.retired)));
+}
+
+type Liveness = (entry: Seat) => Promise<boolean>;
+
+/** A bound Herdr pane is live only when Herdr still reports that exact pane running an agent. */
+const livePane = (session: string, command: HerdrCommand): Liveness => async (entry) => {
+  const binding = entry.runtime?.addresses?.herdr;
+  if (!binding) return false;
+  const pane = typeof binding === "string" ? binding : binding.pane;
+  const owner = typeof binding === "string" ? session : binding.session;
+  try {
+    const value = json(await command(["herdr", "--session", owner, "pane", "get", pane]));
+    const report = value?.pane ?? value;
+    return report?.pane_id === pane && typeof report.agent === "string" && report.agent !== "";
+  } catch { return false; }
+};
+
+/** A driver is active for blanket projection only with unblocked in-progress work or a live bound runtime. */
+async function activeDriver(root: string, projectName: string, entry: Seat, live?: Liveness) {
+  const owned = (await seatTasks(root, projectName, entry.address)).filter(({ task }) => task.assignee === entry.address);
+  if (owned.some(({ task }) => task.status === "in_progress" && !task.blocker)) return true;
+  return live ? live(entry) : false;
 }
 
 export type UnprojectedSeat = { address: string; reason: string };
@@ -130,7 +152,7 @@ function assertNewTopologyPlacement(config: Project, entry: Seat, primary: strin
  * A misplaced seat is skipped and recorded in `unprojected` so it never aborts projection of other
  * seats; requesting that seat explicitly (`strict`) still rejects.
  */
-async function targets(root: string, options: { strict?: string; unprojected?: UnprojectedSeat[] } = {}): Promise<Target[]> {
+async function targets(root: string, options: { strict?: string; unprojected?: UnprojectedSeat[]; live?: Liveness; activeDrivers?: Set<string> } = {}): Promise<Target[]> {
   let projects: string[];
   try { projects = await readdir(paths(root).work); }
   catch { return []; }
@@ -153,14 +175,20 @@ async function targets(root: string, options: { strict?: string; unprojected?: U
         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;
-      }
+      let linked = entry.role === "coordinator" && resolve(entry.worktree) !== primary;
       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 });
+        // An explicit per-seat projection keeps the established assigned-work rule.
+        linked = entry.address === options.strict
+          ? (await seatTasks(root, name, entry.address)).some(({ task }) => task.assignee === entry.address && task.status !== "done")
+          : await activeDriver(root, name, entry, options.live);
+        if (linked) options.activeDrivers?.add(entry.address);
+      }
+      if (!linked) continue;
+      if (entry.address !== options.strict && !await exists(entry.worktree)) {
+        options.unprojected?.push({ address: entry.address, reason: `Worktree ${resolve(entry.worktree)} does not exist.` });
+        continue;
       }
+      result.push({ project: name, worktree: resolve(entry.worktree), workspaceLabel: entry.address, seat: entry });
     }
   }
   return result;
@@ -279,6 +307,79 @@ export async function projectHerdrSeat(root: string, address: string, session: s
   return (await ensureTarget(session, target, workspaces, command, primary))!;
 }
 
+type StaleWorkspace = { workspace: Workspace; address: string };
+
+async function commonDirectory(path: string) {
+  return runOutput(["git", "-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"]);
+}
+async function topLevel(path: string) {
+  return runOutput(["git", "-C", path, "rev-parse", "--show-toplevel"]);
+}
+
+/** True when a checkout no longer exists or is a linked (non-primary) worktree of the primary repository. */
+async function linkedOrMissing(checkout: string, primary: string) {
+  if (!await exists(checkout)) return true;
+  try {
+    return await commonDirectory(checkout) === await commonDirectory(primary) && await topLevel(checkout) !== await topLevel(primary);
+  } catch { return false; }
+}
+
+/**
+ * A stale workspace carries a Desk driver seat label (retired or inactive) and a checkout that is a
+ * linked worktree of that seat's Desk project, or no longer exists. Every other workspace is ignored.
+ */
+async function staleWorkspaces(root: string, workspaces: Workspace[], activeDrivers: Set<string>) {
+  let projects: string[];
+  try { projects = await readdir(paths(root).work); }
+  catch { return []; }
+  const result: StaleWorkspace[] = [];
+  for (const name of projects) {
+    let config: Project;
+    try { config = await project(root, name); }
+    catch { continue; }
+    if (!config.repository) continue;
+    const primary = resolve(config.repository);
+    const drivers = (await projectSeats(root, name, true)).filter((entry) => entry.role === "driver" && !activeDrivers.has(entry.address));
+    for (const entry of drivers) {
+      for (const workspace of workspaces.filter((candidate) => candidate.label === entry.address)) {
+        const checkout = workspace.worktree?.checkout_path;
+        if (typeof checkout !== "string" || checkout === "" || resolve(checkout) === primary) continue;
+        if (await linkedOrMissing(checkout, primary)) result.push({ workspace, address: entry.address });
+      }
+    }
+  }
+  return result;
+}
+
+/** Closes one stale workspace unless any of its agents is working or blocked. */
+async function closeStale(session: string, stale: StaleWorkspace, command: HerdrCommand) {
+  const busy = (await panes(session, stale.workspace.workspace_id, command)).find((entry) => entry.agent_status === "working" || entry.agent_status === "blocked");
+  if (busy) return `kept  ${stale.address}  ${stale.workspace.workspace_id}: agent in ${busy.pane_id} is ${busy.agent_status}`;
+  await command(["herdr", "--session", session, "workspace", "close", stale.workspace.workspace_id]);
+  return `closed  ${stale.address}  ${stale.workspace.workspace_id}`;
+}
+
+const closeInactive = async (root: string) => (await desk(root)).multiplexer?.close_inactive === true;
+
+/**
+ * Closes the workspace of a just-retired driver when the Desk enables close_inactive. Closing is
+ * best-effort housekeeping: it reports, and never undoes the completed retirement.
+ */
+export async function closeRetiredDriverWorkspace(root: string, entry: Seat, command: HerdrCommand = herdr, environment: Record<string, string | undefined> = process.env) {
+  try {
+    const config = await desk(root);
+    if (config.multiplexer?.close_inactive !== true) return;
+    const binding = entry.runtime?.addresses?.herdr;
+    const session = (binding && typeof binding !== "string" ? binding.session : undefined) ?? environment.HERDR_SESSION ?? config.herdr_session;
+    if (!session) return;
+    const workspaces = (await liveWorkspaces(session, command)).filter((workspace) => workspace.label === entry.address);
+    if (!workspaces.length) return;
+    for (const stale of await staleWorkspaces(root, workspaces, new Set())) console.log(await closeStale(session, stale, command));
+  } catch (error) {
+    console.log(`Workspace close for ${entry.address} was not completed: ${(error as Error).message}`);
+  }
+}
+
 async function topologyCompliant(session: string, target: Target, workspace: Workspace, command: HerdrCommand) {
   if (workspace.label !== target.workspaceLabel) return false;
   if (!target.seat) return true;
@@ -301,16 +402,19 @@ export async function multiplexer(root: string, args: string[]) {
     return;
   }
   const unprojected: UnprojectedSeat[] = [];
-  const desired = await targets(root, { unprojected });
   const command: HerdrCommand = herdr;
+  const activeDrivers = new Set<string>();
+  const desired = await targets(root, { unprojected, live: livePane(session, command), activeDrivers });
   const workspaces = await liveWorkspaces(session, command);
+  const stale = await staleWorkspaces(root, workspaces, activeDrivers);
+  const close = await closeInactive(root);
   if (action === "status") {
     const present = desired.filter((target) => matchWorkspace(workspaces, target));
     const topology = await Promise.all(desired.map(async (target) => {
       const workspace = matchWorkspace(workspaces, target);
       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, unprojected }, null, 2));
+    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, stale: stale.length, close_inactive: close, unprojected }, null, 2));
     return;
   }
   const primary = new Map<string, WorkspaceState>();
@@ -325,5 +429,8 @@ export async function multiplexer(root: string, args: string[]) {
     await ensureTarget(session, target, workspaces, command, projectPrimary);
   }
   for (const entry of unprojected) console.log(`unprojected  ${entry.address}: ${entry.reason}`);
+  for (const entry of stale) {
+    console.log(close ? await closeStale(session, entry, command) : `stale  ${entry.address}  ${entry.workspace.workspace_id}: close_inactive is off`);
+  }
   console.log(`Projected ${desired.length} Desk seat worktree(s) into Herdr session ${session}.`);
 }

package/src/seats.ts

@@ -1,15 +1,15 @@
 import { existsSync, realpathSync } from "node:fs";
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { basename, 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, runtimeAddress, seat, words, yaml,
+  atomicYaml, canonicalAddress, desk, exists, fill, has, migrateDesk, modelPortfolio, now, paths, project, readYaml,
+  required, run, runOutput, runtimeAddress, seat, taskId, words, yaml,
 } from "./core";
 import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
-import { seatTasks } from "./tasks";
+import { type Task, seatTasks } from "./tasks";
 import { misplacedSeats, projectHerdrSeat } from "./multiplexer";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
@@ -112,9 +112,98 @@ async function ensureWorktree(config: Project, role: Role, worktree: string, bra
   await run(command, true);
 }
 
+async function noBranch(config: Project, branch: string) {
+  const probe = Bun.spawn(["git", "-C", required(config.repository, "project repository"), "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+  if (await probe.exited === 0) throw new Error(`Driver branch ${branch} already exists; refusing to reuse it.`);
+}
+
+async function taskCoordinatorBase(root: string, config: Project, task: Task) {
+  const coordinatorAddress = await canonicalAddress(root, task.coordinator);
+  const suffix = `@${config.project}`;
+  if (!coordinatorAddress.endsWith(suffix)) throw new Error(`Task coordinator ${coordinatorAddress} is outside project ${config.project}.`);
+  const coordinator = await seat(root, coordinatorAddress);
+  const primary = resolve(required(config.repository, "project repository"));
+  let branch: string;
+  if (coordinator.role === "main") {
+    if (coordinator.address !== `main@${config.project}` || coordinator.branch !== "main" || resolve(coordinator.worktree) !== primary) {
+      throw new Error(`Main coordinator ${coordinator.address} has mismatched primary lineage.`);
+    }
+    branch = "main";
+  } else if (coordinator.role === "coordinator") {
+    const match = coordinator.address.match(new RegExp(`^coordinator\\.([a-z0-9_-]+)@${config.project}$`));
+    if (!match || coordinator.branch !== `integration/${match[1]}` || resolve(coordinator.worktree) === primary) {
+      throw new Error(`Coordinator ${coordinator.address} has mismatched, generic, or nested integration lineage.`);
+    }
+    branch = coordinator.branch;
+  } else {
+    throw new Error(`Task coordinator ${coordinator.address} must be main or a named coordinator.`);
+  }
+  if (coordinator.project !== config.project) throw new Error(`Task coordinator ${coordinator.address} is outside project ${config.project}.`);
+  if (await runOutput(["git", "-C", coordinator.worktree, "status", "--porcelain"])) {
+    throw new Error(`Coordinator ${coordinator.address} worktree is dirty.`);
+  }
+  const checkedOut = await runOutput(["git", "-C", coordinator.worktree, "branch", "--show-current"]);
+  if (checkedOut !== branch) throw new Error(`Coordinator ${coordinator.address} is not checked out at ${branch}.`);
+  const head = await runOutput(["git", "-C", coordinator.worktree, "rev-parse", "HEAD"]);
+  const branchHead = await runOutput(["git", "-C", required(config.repository, "project repository"), "rev-parse", branch]);
+  if (head !== branchHead) throw new Error(`Coordinator ${coordinator.address} head is stale relative to ${branch}.`);
+  return { coordinator, branch, commit: head };
+}
+
+/** Creates a fresh driver and assigns its existing todo task from the task coordinator's exact head. */
+async function spawnTaskDriver(root: string, config: Project, role: Role, name: string, args: string[]) {
+  if (role.address !== "driver.{name}@{project}" || role.branch !== "delivery/{name}" || !role.worktree) {
+    throw new Error("Task-aware driver spawn requires the canonical driver role topology.");
+  }
+  if (has(args, "--worktree") || has(args, "--branch")) throw new Error("Task-aware driver spawn derives its worktree and branch; do not provide --worktree or --branch.");
+  const id = taskId(required(words(args, "--task"), "--task"));
+  const task = await readYaml<Task>(paths(root).taskFile(config.project, id));
+  if (task.schema !== "atdd-workflow/task/v1") throw new Error(`Unsupported task schema: ${id}`);
+  if (task.status !== "todo" || task.assignee) throw new Error(`Task ${id} must be an unassigned todo task.`);
+  const entries = { project: config.project, name, worktree_root: config.worktree_root ?? "" };
+  const address = fill(role.address, entries);
+  const branch = fill(role.branch, entries);
+  const worktree = resolve(fill(role.worktree, { ...entries, repository: config.repository ?? "" }));
+  if (await exists(paths(root).seatFile(address))) throw new Error(`Driver seat ${address} already exists; refusing to reuse it.`);
+  if (await exists(worktree)) throw new Error(`Driver worktree ${worktree} already exists; refusing to reuse it.`);
+  await noBranch(config, branch);
+  const base = await taskCoordinatorBase(root, config, task);
+  const portfolio = await modelPortfolio(root);
+  const requestedAgent = words(args, "--agent");
+  if (portfolio && requestedAgent) throw new Error("--agent is a legacy pin and cannot be used when models.yaml owns model allocation.");
+  const legacyAgent = portfolio ? undefined : requestedAgent ?? role.agent;
+  const purpose = words(args, "--purpose") ?? (role.purpose ? fill(role.purpose, entries) : undefined);
+  const record: Seat = {
+    schema: "atdd-workflow/seat/v2", address, role: "driver", project: config.project, worktree, branch,
+    ...(legacyAgent ? { agent: legacyAgent } : {}), ...(purpose ? { purpose } : {}),
+  };
+  task.assignee = address;
+  task.governed_base = { coordinator: base.coordinator.address, branch: base.branch, commit: base.commit };
+  let created = false;
+  try {
+    await mkdir(dirname(worktree), { recursive: true });
+    await run(["git", "-C", required(config.repository, "project repository"), "worktree", "add", "-b", branch, worktree, base.commit], true);
+    created = true;
+    const current = await runOutput(["git", "-C", base.coordinator.worktree, "rev-parse", "HEAD"]);
+    const currentBranch = await runOutput(["git", "-C", required(config.repository, "project repository"), "rev-parse", base.branch]);
+    if (current !== base.commit || currentBranch !== base.commit) throw new Error(`Coordinator ${base.coordinator.address} advanced during driver provisioning.`);
+    await atomicYaml(paths(root).seatFile(address), record);
+    await atomicYaml(paths(root).taskFile(config.project, id), task);
+  } catch (error) {
+    if (created) await run(["git", "-C", required(config.repository, "project repository"), "worktree", "remove", "--force", worktree], true).catch(() => undefined);
+    await rm(paths(root).seat(address), { recursive: true, force: true });
+    throw error;
+  }
+  console.log(`${address}  assigned ${id}  return ${base.branch}`);
+}
+
 export async function spawn(root: string, projectName: string, roleName: string, name: string, args: string[]) {
   const config = await project(root, projectName);
   const role = required(config.roles[roleName], `role ${roleName}`);
+  if (words(args, "--task")) {
+    if (roleName !== "driver") throw new Error("--task is supported only for driver spawn.");
+    return spawnTaskDriver(root, config, role, name, args);
+  }
   const entries = { project: config.project, name, worktree_root: config.worktree_root ?? "" };
   // Retain the historical primary coordinator command for existing Desks while
   // new defaults make main@project the only new primary identity.

package/src/tasks.ts

@@ -1,7 +1,7 @@
-import { readdir } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readdir, realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import {
-  type Checkpoint, type Seat, atomicYaml, canonicalAddress, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
+  type Checkpoint, type Seat, atomicYaml, canonicalAddress, exists, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
 } from "./core";
 
 export type TaskStatus = "todo" | "in_progress" | "review" | "done";
@@ -142,15 +142,47 @@ async function governedBase(root: string, projectName: string, coordinatorAddres
 }
 
 async function retireAssignee(root: string, projectName: string, id: string, task: Task) {
-  const assignee = required(task.assignee, `an assignee for task ${id}`);
+  return retireDriver(root, projectName, required(task.assignee, `an assignee for task ${id}`), id);
+}
+
+/**
+ * Retires an idle driver: every other assigned task must be done, ATDD Bun removes the clean and
+ * merged worktree, the seat records retirement and a checkpoint, then its workspace may close.
+ */
+/** Resolves symlinks through the nearest existing ancestor so an absent path compares with Git's paths. */
+async function canonicalPath(path: string): Promise<string> {
+  const absolute = resolve(path);
+  try { return await realpath(absolute); }
+  catch { return dirname(absolute) === absolute ? absolute : join(await canonicalPath(dirname(absolute)), basename(absolute)); }
+}
+
+/**
+ * A recorded worktree that is absent from disk and from the repository's `git worktree list` has
+ * nothing left to finish. Any other state, including a registered-but-missing path, fails closed.
+ */
+async function absentUnregisteredWorktree(root: string, projectName: string, owner: Seat) {
+  if (await exists(owner.worktree)) return undefined;
+  const repository = required((await project(root, projectName)).repository, `a repository for project ${projectName}`);
+  const target = await canonicalPath(owner.worktree);
+  const listed = (await runOutput(["git", "-C", repository, "worktree", "list", "--porcelain"])).split("\n")
+    .filter((line) => line.startsWith("worktree ")).map((line) => line.slice("worktree ".length));
+  for (const path of listed) {
+    if (await canonicalPath(path) === target) throw new Error(`Worktree ${owner.worktree} is missing but still registered with Git; prune or restore it before retiring ${owner.address}.`);
+  }
+  return `Worktree ${owner.worktree} is absent and unregistered; retired without worktree finish; branch ${owner.branch} retained.`;
+}
+
+async function retireDriver(root: string, projectName: string, assignee: string, id: string, allowAbsentWorktree = false) {
   const unfinished = (await allTasks(root, projectName))
     .filter((entry) => entry.id !== id && entry.task.assignee === assignee && entry.task.status !== "done")
     .map((entry) => entry.id);
   if (unfinished.length) throw new Error(`Cannot retire ${assignee}; it still owns unfinished tasks: ${unfinished.join(", ")}.`);
 
   const owner = await seat(root, assignee);
+  if (owner.retired) throw new Error(`Seat ${assignee} is already retired.`);
   try {
-    const summary = await runOutput(["atdd-bun", "worktree", "finish", "--delete-branch"], owner.worktree);
+    const summary = (allowAbsentWorktree ? await absentUnregisteredWorktree(root, projectName, owner) : undefined)
+      ?? await runOutput(["atdd-bun", "worktree", "finish", "--delete-branch"], owner.worktree);
     owner.retired = { task: `${projectName}/${id}`, completed_at: now(), summary };
     await atomicYaml(paths(root).seatFile(assignee), owner);
     const checkpoint: Checkpoint = {
@@ -170,6 +202,26 @@ async function retireAssignee(root: string, projectName: string, id: string, tas
     await atomicYaml(paths(root).checkpointFile(assignee), checkpoint);
     throw error;
   }
+  const { closeRetiredDriverWorkspace } = await import("./multiplexer");
+  await closeRetiredDriverWorkspace(root, owner);
+}
+
+/** Retires a driver whose assigned tasks are all already done. */
+export async function retireSeat(root: string, address: string, args: string[]) {
+  const resolved = await canonicalAddress(root, address);
+  const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
+  const owner = await seat(root, resolved);
+  if (owner.role !== "driver") throw new Error(`Only driver seats can be retired; ${resolved} is ${owner.role}.`);
+  if (owner.retired) throw new Error(`Seat ${resolved} is already retired.`);
+  const owned = (await allTasks(root, owner.project)).filter((entry) => entry.task.assignee === resolved);
+  if (!owned.length) throw new Error(`Cannot retire ${resolved}; it has no assigned tasks.`);
+  const unfinished = owned.filter((entry) => entry.task.status !== "done").map((entry) => entry.id);
+  if (unfinished.length) throw new Error(`Cannot retire ${resolved}; it still owns unfinished tasks: ${unfinished.join(", ")}.`);
+  if (actor !== `main@${owner.project}` && owned.some((entry) => entry.task.coordinator !== actor)) {
+    throw new Error(`Only main@${owner.project} or the coordinator of every task assigned to ${resolved} may retire it.`);
+  }
+  await retireDriver(root, owner.project, resolved, owned.at(-1)!.id, true);
+  console.log(`${resolved}  retired`);
 }
 
 export async function add(root: string, projectName: string, id: string, args: string[]) {