@afokapu/atdd-flow 0.3.35 → 0.3.37

package/README.md

@@ -130,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>`.
 
@@ -186,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.35",
+  "version": "0.3.37",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "bun": ">=1.3.0"
   },
   "devDependencies": {
-    "@afokapu/atdd-bun": "0.10.61"
+    "@afokapu/atdd-bun": "0.10.71"
   },
   "dependencies": {
     "@typesafe-ai/sdk": "^0.6.0",

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/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[]) {