@afokapu/atdd-flow 0.3.38 → 0.3.40

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. 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.
+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. `main@<project>` may likewise retire a coordinator seat (never main, the operator, or a seat on the primary checkout) once every task it coordinates or is assigned is `done`, through the same worktree-finish, absent-and-unregistered, and fail-closed paths. Retirement runs in the seat worktree with ATDD Bun from the primary checkout's `node_modules/.bin`, else the primary checkout's own source when it is the ATDD Bun package, else `PATH`; never the seat worktree's copy, which may pin an older toolkit.
 
 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>`.
 
@@ -188,7 +188,7 @@ 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 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:
+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 and, read-only, lists each one under `stale_workspaces` with its `address`, `workspace_id`, `reason` (`retired` or `no active task`), current pane `agents` and `agent_status`, and the `outcome` apply would take (`close` or `keep`, with `because` for a kept workspace). Review that list before running apply. `multiplexer apply` closes stale workspaces only when `desk.yaml` enables it:
 
 ```yaml
 multiplexer:

package/conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml

@@ -246,8 +246,9 @@ content:
     review and writes a blocked checkpoint for investigation.
 
     Before working in or retiring a driver worktree, install that repository's local dependencies there.
-    Retirement resolves ATDD Bun from the worktree's local node_modules/.bin so it does not depend on a
-    developer's global executable installation.
+    Retirement runs in the seat worktree but resolves ATDD Bun from the primary checkout's local
+    node_modules/.bin, then the primary checkout's own source when it is the ATDD Bun package, then PATH.
+    It never uses the seat worktree's copy, which may pin an older toolkit that refuses its own retirement.
 
     Use the atdd-flow CLI to mutate workflow records. Read task, seat, checkpoint, and thread YAML
     before acting; do not treat terminal pane history, a multiplexer, an optional judgment helper, or an

package/package.json

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

package/src/multiplexer.ts

@@ -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; agent_status?: string };
+type Pane = { pane_id: string; tab_id: string; label?: string; agent?: 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>;
@@ -307,7 +307,7 @@ export async function projectHerdrSeat(root: string, address: string, session: s
   return (await ensureTarget(session, target, workspaces, command, primary))!;
 }
 
-type StaleWorkspace = { workspace: Workspace; address: string };
+type StaleWorkspace = { workspace: Workspace; address: string; reason: "retired" | "no active task" };
 
 async function commonDirectory(path: string) {
   return runOutput(["git", "-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"]);
@@ -344,19 +344,42 @@ async function staleWorkspaces(root: string, workspaces: Workspace[], activeDriv
       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 });
+        if (await linkedOrMissing(checkout, primary)) result.push({ workspace, address: entry.address, reason: entry.retired ? "retired" : "no active task" });
       }
     }
   }
   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}`;
+type StaleDecision = {
+  address: string;
+  workspace_id: string;
+  reason: StaleWorkspace["reason"];
+  agents: Array<Pick<Pane, "pane_id" | "agent" | "agent_status">>;
+  outcome: "close" | "keep";
+  because?: string;
+};
+
+const closeInactiveOff = "close_inactive is off";
+
+/**
+ * Read-only decision for one stale workspace, shared by `status` and `apply`: it is closed only when
+ * close_inactive is on and none of its agents is working or blocked.
+ */
+async function decideStale(session: string, stale: StaleWorkspace, close: boolean, command: HerdrCommand): Promise<StaleDecision> {
+  const agents = (await panes(session, stale.workspace.workspace_id, command))
+    .map(({ pane_id, agent, agent_status }) => ({ pane_id, ...(agent ? { agent } : {}), ...(agent_status ? { agent_status } : {}) }));
+  const busy = agents.find((entry) => entry.agent_status === "working" || entry.agent_status === "blocked");
+  const because = !close ? closeInactiveOff : busy ? `agent in ${busy.pane_id} is ${busy.agent_status}` : undefined;
+  return { address: stale.address, workspace_id: stale.workspace.workspace_id, reason: stale.reason, agents, outcome: because ? "keep" : "close", ...(because ? { because } : {}) };
+}
+
+/** Acts on one stale-workspace decision: closes it, or reports why it is kept. */
+async function applyStale(session: string, decision: StaleDecision, command: HerdrCommand) {
+  const label = `${decision.address}  ${decision.workspace_id}`;
+  if (decision.outcome === "keep") return `${decision.because === closeInactiveOff ? "stale" : "kept"}  ${label}: ${decision.because}`;
+  await command(["herdr", "--session", session, "workspace", "close", decision.workspace_id]);
+  return `closed  ${label}`;
 }
 
 const closeInactive = async (root: string) => (await desk(root)).multiplexer?.close_inactive === true;
@@ -374,7 +397,7 @@ export async function closeRetiredDriverWorkspace(root: string, entry: Seat, com
     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));
+    for (const stale of await staleWorkspaces(root, workspaces, new Set())) console.log(await applyStale(session, await decideStale(session, stale, true, command), command));
   } catch (error) {
     console.log(`Workspace close for ${entry.address} was not completed: ${(error as Error).message}`);
   }
@@ -406,15 +429,16 @@ export async function multiplexer(root: string, args: string[]) {
   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);
+  const stale = await staleWorkspaces(root, workspaces, activeDrivers);
+  const decide = (entry: StaleWorkspace) => decideStale(session, entry, close, command);
   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, stale: stale.length, close_inactive: close, 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, stale_workspaces: await Promise.all(stale.map(decide)), close_inactive: close, unprojected }, null, 2));
     return;
   }
   const primary = new Map<string, WorkspaceState>();
@@ -429,8 +453,7 @@ 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`);
-  }
+  // Decided at close time with the same read-only rule `status` reports.
+  for (const entry of stale) console.log(await applyStale(session, await decide(entry), command));
   console.log(`Projected ${desired.length} Desk seat worktree(s) into Herdr session ${session}.`);
 }

package/src/tasks.ts

@@ -172,9 +172,26 @@ async function absentUnregisteredWorktree(root: string, projectName: string, own
   return `Worktree ${owner.worktree} is absent and unregistered; retired without worktree finish; branch ${owner.branch} retained.`;
 }
 
+/**
+ * Resolves the ATDD Bun that retires a seat: the primary checkout's local copy, then the primary
+ * checkout's package source when it is ATDD Bun itself, then PATH. A seat worktree copy is never used:
+ * a finished branch may pin an older toolkit that refuses the seat being retired.
+ */
+async function retirementBun(root: string, projectName: string) {
+  const primary = resolve(required((await project(root, projectName)).repository, `a repository for project ${projectName}`));
+  const local = join(primary, "node_modules", ".bin", "atdd-bun");
+  if (await exists(local)) return [local];
+  const source = join(primary, "src", "cli.ts");
+  try {
+    if ((await Bun.file(join(primary, "package.json")).json()).name === "@afokapu/atdd-bun" && await exists(source)) return [process.execPath, source];
+  } catch { /* no readable package manifest; fall through to PATH */ }
+  // Absolute so command execution never substitutes the seat worktree's local copy.
+  return [required(Bun.which("atdd-bun") ?? undefined, "atdd-bun in the primary checkout node_modules/.bin or on PATH")];
+}
+
 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")
+    .filter((entry) => entry.id !== id && (entry.task.assignee === assignee || entry.task.coordinator === 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(", ")}.`);
 
@@ -182,7 +199,7 @@ async function retireDriver(root: string, projectName: string, assignee: string,
   if (owner.retired) throw new Error(`Seat ${assignee} is already retired.`);
   try {
     const summary = (allowAbsentWorktree ? await absentUnregisteredWorktree(root, projectName, owner) : undefined)
-      ?? await runOutput(["atdd-bun", "worktree", "finish", "--delete-branch"], owner.worktree);
+      ?? await runOutput([...await retirementBun(root, projectName), "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 = {
@@ -206,20 +223,40 @@ async function retireDriver(root: string, projectName: string, assignee: string,
   await closeRetiredDriverWorkspace(root, owner);
 }
 
-/** Retires a driver whose assigned tasks are all already done. */
+/**
+ * Only main retires a coordinator, and never one seated on the primary checkout; a driver may also be
+ * retired by the coordinator of every task assigned to it.
+ */
+async function assertRetireAuthority(root: string, owner: Seat, actor: string, owned: ListedTask[]) {
+  const main = `main@${owner.project}`;
+  if (owner.role === "coordinator") {
+    if (actor !== main) throw new Error(`Only ${main} may retire coordinator ${owner.address}.`);
+    const primary = (await project(root, owner.project)).repository;
+    if (primary && await canonicalPath(owner.worktree) === await canonicalPath(primary)) {
+      throw new Error(`Cannot retire ${owner.address}; its worktree is the primary checkout.`);
+    }
+  } else if (actor !== main && owned.some((entry) => entry.task.coordinator !== actor)) {
+    throw new Error(`Only ${main} or the coordinator of every task assigned to ${owner.address} may retire it.`);
+  }
+}
+
+/**
+ * Retires a driver whose assigned tasks are all already done, or, for main only, a coordinator
+ * (never main or the primary checkout) whose coordinated and assigned tasks are all 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}.`);
+  const coordinator = owner.role === "coordinator";
+  if (owner.role !== "driver" && !coordinator) throw new Error(`Only driver or coordinator 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 owned = (await allTasks(root, owner.project))
+    .filter((entry) => entry.task.assignee === resolved || (coordinator && entry.task.coordinator === resolved));
+  if (!owned.length) throw new Error(`Cannot retire ${resolved}; it has no ${coordinator ? "coordinated or " : ""}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 assertRetireAuthority(root, owner, actor, owned);
   await retireDriver(root, owner.project, resolved, owned.at(-1)!.id, true);
   console.log(`${resolved}  retired`);
 }