@afokapu/atdd-flow 0.3.70 → 0.3.72

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. `main@<project>` may likewise retire a coordinator seat (never main or the operator) once every task it coordinates or is assigned is `done`. A non-main coordinator sharing the primary checkout is retired as a Desk record without worktree finish; other coordinators use 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.
+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`. Add `--immediate --priority <priority> --mutation-boundary <text>` to persist and natively deliver a task-specific dispatch (task, priority, boundary, exact assignee-only `task start` command); it fails closed, writing nothing, when the assignee has no native queue. The assignee records a typed, dispatch-bound `atdd-flow task acknowledge <project> <task-id> --dispatch <message-id> --by <assignee>` (idempotent, distinct from `task start`; messages, receipts, and heartbeats never count), and the coordinator's on-demand `atdd-flow task observe-assignment` posts at most one `missing_acknowledgement` and one `missing_start` alert to the assignee. 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 or the operator) once every task it coordinates or is assigned is `done`. A non-main coordinator sharing the primary checkout is retired as a Desk record without worktree finish; other coordinators use 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>`.
 
@@ -192,7 +192,7 @@ 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 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.
+For each Desk project, apply reconciles the declared repository checkout as workspace `{project}` and gives every main, operator, and non-generic coordinator seat using it a tab and pane named `{seat.address}`. `main@{project}` is the single primary coordinator projection: when it uses the primary checkout, the preserved legacy generic `coordinator@{project}` sharing that checkout is not bulk-projected as a second tab (an explicit per-seat projection still projects it, and a project without a primary main keeps it). 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 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:
 
@@ -250,6 +250,29 @@ atdd-flow --root /path/to/desk attach driver.runtime@example-app --application h
 
 Pi receives its identity and startup task from the extension itself. Its normal TUI remains visible and manually usable; incoming Desk mail wakes it through Pi's native message API. The runtime lifecycle has one internal bounded inbox transport; it does not add a second watcher, registry, mailbox, reservation system, or routing path.
 
+### Wake or migrate live Pi seats
+
+`atdd-flow pi wake` replaces the manual `/model` → `/reload` → inbox/task prompt chain with one command per seat or fleet. It sends only the local extension command `/flow-wake` through Herdr (no model prompt) and verifies Pi's own session transcript.
+
+```sh
+atdd-flow pi wake driver.runtime@example-app --by operator@desk                          # keep model, reconcile, wake once
+atdd-flow pi wake driver.runtime@example-app --model-profile restore --by main@example-app # swap to the mapped model first
+atdd-flow pi wake --scope project --by main@example-app                                   # every live seat of the project
+atdd-flow pi wake --scope desk --by operator@desk                                         # every live seat of the Desk
+```
+
+`--by` must be `operator@desk` or the project's `main@<project>`; `--scope desk` requires the operator. A profile is declared in `models.yaml` and must map a source `provider/model` to an existing, enabled portfolio candidate that names one exact Pi `--provider`/`--model`; anything else is rejected when `models.yaml` is read:
+
+```yaml
+model_migrations:
+  restore:
+    anthropic/claude-sonnet-4-5: strong
+```
+
+The extension re-checks the target against Pi's authenticated model registry, calls `setModel`, preserves the thinking level, and reloads. On reload the unmatched request is reconstructed from the active transcript branch; Flow reactivates mail, writes the result, and injects the recovery bundle plus the authoritative task directive as exactly one resumed-work turn. A seat whose Pi predates `/flow-wake` is first sent one `/reload` at a safe boundary, and only a fresh `flow-wake-capability/v1` transcript entry lets the wake proceed.
+
+Seats are handled in lexical order, one at a time, and every seat gets exactly one row: `woke`, `swapped+woke`, `deferred` (agent working), `refused` (blocked/question UI, stale pane/session/process, unmapped model), `skipped` (retired, terminal task, no agent or binding, the invoking seat), or `failed` (unavailable target, partial model/reload evidence; never retried). A named seat exits non-zero unless it woke; a fleet exits non-zero only on `refused` or `failed`. No fallback model, relaunch, compaction, seat reassignment, or session replacement exists, and Desk, seat, runtime and repository records are never written; only Pi's native model-change and flow-wake entries are appended to the transcript. `ATDD_FLOW_WAKE_TIMEOUT_MS` bounds each wait (default 30 s; 5 min for a seat to return to idle after a bootstrap reload).
+
 The lifecycle and recovery design was informed by [nicobailon/pi-messenger](https://github.com/nicobailon/pi-messenger) at `09937ed647a1b07a3b595bf75943feacb80ff123` (MIT). No pi-messenger source is copied here. Flow keeps Desk identity, recipient selection, immutable mail, and governance authoritative; any future copied source must carry its MIT notice.
 
 With ATDD Bun, enable the Workflow profile:

package/extensions/pi/index.ts

@@ -4,9 +4,10 @@ import { basename, dirname, join } from "node:path";
 import { parse, stringify } from "yaml";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, recordMailActivation, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
-import { paths, readYaml, type Seat } from "../../src/core";
+import { modelPortfolio, paths, piModel, readYaml, type Seat } from "../../src/core";
+import { type TranscriptEntry, customEntries, wakeCapabilityType, wakeRequestIdPattern, wakeRequestType, wakeResultType, wakeStartType } from "../../src/pi-wake-protocol";
 import { activationNotice, diagnoseMailActivation, expectsNativeMail } from "../../src/mail-activation-notice";
-import { type NoticeState, createNoticeState, refreshDelivered, sendSettledDirective, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
+import { type NoticeState, createNoticeState, deliveredDirectiveText, refreshDelivered, sendSettledDirective, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
 import { handoverThresholdInstruction, runtimeStartupInstruction, successorInstruction } from "../../src/collaboration-policy";
 import { type RecoveryMode, recoveryFor } from "../../src/recovery-bundle";
 import { contextHandoverThreshold, readHandoverReplacement } from "../../src/handover";
@@ -362,6 +363,49 @@ const unsetOrEqual = (recorded: string | undefined, live: string | undefined) =>
 const sessionUnsetOrEqual = (runtime: Seat["runtime"], piSession?: string, piSessionPath?: string) =>
   unsetOrEqual(runtime?.pi_session, piSession) && unsetOrEqual(runtime?.pi_session_path, piSessionPath);
 
+
+type WakeIdentity = { seat: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string };
+type WakeContext = {
+  model?: { provider: string; id: string };
+  thinkingLevel?: string;
+  modelRegistry?: { find(provider: string, id: string): unknown; hasConfiguredAuth(model: never): boolean };
+  sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined; getBranch?: () => unknown[] };
+  reload?: () => Promise<void>;
+};
+
+/** The live Pi/Herdr identity: launcher variables first, then Herdr's host-injected pane identity. */
+function wakeIdentity(seat: string, ctx: WakeContext): WakeIdentity {
+  const manager = ctx.sessionManager;
+  return {
+    seat,
+    pi_session: process.env.ATDD_FLOW_PI_SESSION ?? manager?.getSessionId?.(),
+    pi_session_path: manager?.getSessionFile?.(),
+    herdr_session: process.env.ATDD_FLOW_HERDR_SESSION ?? process.env.HERDR_SESSION,
+    pane: process.env.ATDD_FLOW_HERDR_PANE ?? process.env.HERDR_PANE_ID,
+  };
+}
+
+/** A wake may act only for the exact seat, Pi session and Herdr pane that the Desk binds together. */
+async function boundToLiveIdentity(root: string, identity: WakeIdentity) {
+  if (!identity.pi_session || !identity.herdr_session || !identity.pane) return false;
+  try {
+    const runtime = (await readYaml<Seat>(paths(root).seatFile(identity.seat))).runtime;
+    const locator = runtime?.addresses.herdr;
+    return runtime?.application === "herdr" && typeof locator === "object" && locator.session === identity.herdr_session && locator.pane === identity.pane
+      && unsetOrEqual(runtime.pi_session, identity.pi_session);
+  } catch { return false; }
+}
+
+const branchOf = (ctx: WakeContext) => (ctx.sessionManager?.getBranch?.() ?? []) as TranscriptEntry[];
+
+/** The single unmatched request on the active branch that was issued for this exact live identity. */
+function unmatchedWakeRequest(branch: TranscriptEntry[], identity: WakeIdentity) {
+  const matched = new Set(customEntries(branch, wakeResultType).map((entry) => entry.data?.request_id));
+  const request = customEntries(branch, wakeRequestType).map((entry) => entry.data).filter((data) => data && !matched.has(data.request_id)).at(-1);
+  if (!request || typeof request.request_id !== "string") return undefined;
+  return request.seat === identity.seat && request.pi_session === identity.pi_session && request.pane === identity.pane ? request : undefined;
+}
+
 /** The recovery bundle is advisory; any failure falls back to the plain prompt. */
 const recovery = (root: string, seat: string, mode: RecoveryMode, session?: string) => recoveryFor(root, seat, mode, session).catch(() => undefined);
 
@@ -417,7 +461,75 @@ export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = proc
       ctx.shutdown();
     } catch { /* No validated replacement request exists for this source session. */ }
   });
+  const safeThinking = (ctx?: WakeContext) => ctx?.thinkingLevel ?? (typeof pi.getThinkingLevel === "function" ? pi.getThinkingLevel() : undefined);
+  const wakeResult = (requestId: string, outcome: string, extra: Record<string, unknown> = {}) => pi.appendEntry(wakeResultType, { request_id: requestId, outcome, ...extra });
+  // Request, optional authenticated model swap, thinking restore, then reload; the post-reload session_start writes the result and the one resumed-work turn.
+  // The command is registered only on hosts that expose it; `/reload` keeps the old instance terminal, so nothing runs after it here.
+  (pi as { registerCommand?: ExtensionAPI["registerCommand"] }).registerCommand?.("flow-wake", {
+    description: "Flow: optionally swap to a mapped model, reload, reconcile, and wake this seat once",
+    handler: async (args: string, rawContext: unknown) => {
+      const ctx = rawContext as WakeContext & { hasUI?: boolean; ui?: { notify(message: string, level: string): void } };
+      const words = args.trim().split(/\s+/).filter(Boolean);
+      const requestId = words.at(-1);
+      if (words.length < 1 || words.length > 2 || !requestId || !wakeRequestIdPattern.test(requestId)) {
+        if (ctx.hasUI) ctx.ui?.notify("Usage: /flow-wake [portfolio-candidate] <request-id>", "error");
+        return;
+      }
+      const candidate = words.length === 2 ? words[0]! : undefined;
+      const identity = wakeIdentity(seat, ctx);
+      if (customEntries(branchOf(ctx), wakeRequestType).some((entry) => entry.data?.request_id === requestId)) {
+        wakeResult(requestId, "failed", { reason: "duplicate request id" });
+        return;
+      }
+      const source = { provider: ctx.model?.provider, model: ctx.model?.id, thinking: safeThinking(ctx) };
+      pi.appendEntry(wakeRequestType, { request_id: requestId, ...identity, ...(candidate ? { candidate } : {}), source });
+      try {
+        if (!await boundToLiveIdentity(root, identity)) return wakeResult(requestId, "failed", { reason: "Desk binding does not match the live seat, session and pane" });
+        if (candidate) {
+          const entry = (await modelPortfolio(root))?.models.find((model) => model.id === candidate);
+          const exact = entry && entry.enabled !== false ? piModel(entry) : undefined;
+          if (!exact) return wakeResult(requestId, "failed", { reason: `candidate ${candidate} is not an enabled exact Pi model` });
+          const model = ctx.modelRegistry?.find(exact.provider, exact.model);
+          if (!model || !ctx.modelRegistry!.hasConfiguredAuth(model as never)) return wakeResult(requestId, "failed", { reason: `${exact.provider}/${exact.model} is not available and authenticated in Pi` });
+          const thinking = pi.getThinkingLevel();
+          if (!await pi.setModel(model as never)) return wakeResult(requestId, "failed", { reason: `Pi did not accept ${exact.provider}/${exact.model}` });
+          pi.setThinkingLevel(thinking);
+        }
+        await ctx.reload?.();
+      } catch (error) {
+        wakeResult(requestId, "failed", { reason: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
   pi.on("session_start", async (_event, ctx) => {
+    const wakeContext = ctx as unknown as WakeContext;
+    const identity = wakeIdentity(seat, wakeContext);
+    const wake = unmatchedWakeRequest(branchOf(wakeContext), identity);
+    // Capability is evidence of a verified activation under this extension version; it never lives in runtime state.
+    const announceCapability = () => { try { pi.appendEntry(wakeCapabilityType, { seat, pi_session: identity.pi_session, pane: identity.pane }); } catch { /* The host re-checks capability; absence only forces a reload. */ } };
+    // One reload-reconstructed result and one combined recovery + task-directive turn replace the plain startup message.
+    let wakeSettled = false;
+    const completeWake = async () => {
+      if (!wake) return false;
+      wakeSettled = true;
+      const requestId = String(wake.request_id), candidate = typeof wake.candidate === "string" ? wake.candidate : undefined;
+      const target = { provider: wakeContext.model?.provider, model: wakeContext.model?.id, thinking: safeThinking(wakeContext) };
+      if (candidate) {
+        const entry = (await modelPortfolio(root).catch(() => undefined))?.models.find((model) => model.id === candidate);
+        const exact = entry && entry.enabled !== false ? piModel(entry) : undefined;
+        if (!exact || exact.provider !== target.provider || exact.model !== target.model) { wakeResult(requestId, "failed", { reason: "model after reload is not the requested candidate", target }); return true; }
+      }
+      const bundle = await recovery(root, seat, "start", identity.pi_session);
+      const directive = await deliveredDirectiveText(root, seat, notices);
+      wakeResult(requestId, candidate ? "swapped+woke" : "woke", { target });
+      pi.sendMessage({
+        customType: wakeStartType,
+        content: `${runtimeStartupInstruction(seat, bundle)}${directive ? `\n${directive}` : ""}`,
+        display: true, details: { seat, root, request_id: requestId, wake: true },
+      }, { triggerTurn: true, deliverAs: "followUp" });
+      return true;
+    };
+    const failWake = (reason: string) => { if (wake && !wakeSettled) { wakeSettled = true; wakeResult(String(wake.request_id), "failed", { reason }); } };
     const sessionManager = (ctx as { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } }).sessionManager;
     const liveSession = environment.ATDD_FLOW_PI_SESSION ?? sessionManager?.getSessionId?.();
     // One display-only notice per session: a refused, timed-out or failed activation must never be silent, and never wakes the agent.
@@ -456,10 +568,13 @@ export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = proc
       if (await hostAttachedActivation({ root, seat, herdrSession: environment.HERDR_SESSION, pane: environment.HERDR_PANE_ID, piSession: sessionManager?.getSessionId?.(), piSessionPath: sessionManager?.getSessionFile?.() })) {
         hostActivatedAt = Date.now();
         if (await runtime.activate()) {
+          announceCapability();
+          if (await completeWake()) return;
           const bundle = await recovery(root, seat, "start", sessionManager?.getSessionId?.());
           const notice = "Notices created before this session were not replayed; run atdd-flow status seat " + seat + " for unanswered mail.";
           pi.sendMessage({ customType: "atdd-flow-start", content: `${runtimeStartupInstruction(seat, bundle)} ${notice}`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
         }
+        else failWake("native mail activation was refused");
       } else if (await expectsNativeMail(root, seat)) await noticeActivation("inactive");
       return;
     }
@@ -468,7 +583,12 @@ export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = proc
     void awaitLaunchActivation({
       root, seat, piSession, herdrSession, pane,
       activate: async () => {
-        if (!await activateWithRetry(() => current.activate())) return;
+        if (!await activateWithRetry(() => current.activate())) return failWake("native mail activation was refused");
+        announceCapability();
+        if (await completeWake()) {
+          if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
+          return;
+        }
         const request = await readHandoverReplacement(root, seat).catch(() => undefined);
         const successor = request && request.source.pi_session !== piSession ? request : undefined;
         const bundle = await recovery(root, seat, successor ? "successor" : "start", piSession);
@@ -483,7 +603,7 @@ export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = proc
         await sendTaskDirective(host, root, seat, notices);
         if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
       },
-    }).catch((error) => error instanceof ActivationTimeout
+    }).catch((error) => (failWake(error instanceof Error ? error.message : String(error)), error instanceof ActivationTimeout)
       ? noticeActivation("inactive")
       : noticeActivation(current.active ? "active" : "inactive", error instanceof Error ? error.message : String(error)));
   });

package/package.json

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

package/src/address-book.ts

@@ -26,11 +26,11 @@ export async function addressBook(root: string) {
       catch { /* A partially removed legacy seat is not an address-book entry. */ }
     }
   }
-  console.log("# Desk address book\n");
-  console.log("`operator@desk` is the human authority. Drivers route normal work through coordinators; main seats are the normal technical gateway to the operator.\n");
-  console.log("| Address | Identity | Purpose / authority |\n| --- | --- | --- |");
+  process.stdout.write("# Desk address book\n\n");
+  process.stdout.write("`operator@desk` is the human authority. Drivers route normal work through coordinators; main seats are the normal technical gateway to the operator.\n\n");
+  process.stdout.write("| Address | Identity | Purpose / authority |\n| --- | --- | --- |\n");
   for (const record of records.sort((left, right) => left.address.localeCompare(right.address))) {
     const purpose = (record.purpose ?? authority(record)).replaceAll("|", "\\|");
-    console.log(`| ${record.address} | ${identity(record.address)} | ${purpose} |`);
+    process.stdout.write(`| ${record.address} | ${identity(record.address)} | ${purpose} |\n`);
   }
 }

package/src/adoption-authorizations.ts

@@ -1,3 +1,9 @@
+// URN: component:flow:e006:adoption-authorizations:backend:integration
+// Tested-By:
+// - test:flow:exact-adoption-resumed-proof-and-relaunch
+// Runtime: bun
+// Purpose: Create and resolve exact-session adoption authorizations.
+
 import { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -44,7 +50,7 @@ export async function createExactSessionAdoptionAuthorization(root: string, id:
   await mkdir(dirname(file), { recursive: true });
   await writeFile(file, content, { encoding: "utf8", flag: "wx" });
   await writeFile(hashPath(root, id), `${digest(content)}\n`, { encoding: "utf8", flag: "wx" });
-  console.log(id);
+  process.stdout.write(`${id}\n`);
 }
 
 function same(record: ExactSessionAdoptionAuthorization, expected: Omit<ExactSessionAdoptionAuthorization, "schema" | "id" | "issued_by" | "created_at">) {

package/src/cli.ts

@@ -7,6 +7,7 @@
 
 import { basename, resolve } from "node:path";
 import { init, initProject, configureProject, migrateNamedCoordinatorTopology, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
+import { formatWakeRow, wakePi } from "./pi-wake";
 import { createExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
@@ -34,12 +35,13 @@ Usage:
   atdd-flow desk migrate
   atdd-flow project init <project>
   atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]
-  atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary] [--dry-run]
+  atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary [--retain-large-primary-file <path>:<sha256>:<bytes>:<mode> ...]] [--dry-run]
   atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>
   atdd-flow spawn <project> <role> <name> [--worktree <path>] [--branch <branch>] [--agent <legacy-executable>]
   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 pi wake <seat>|--scope project|desk [--model-profile <name>] --by <authorized-seat>
   atdd-flow pi runtime authorize-adoption <id> --by operator@desk --seat <seat> --pi-session <id> --pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --target-herdr-session <session> --target-pane <pane> --target-cwd <path>
   atdd-flow pi runtime launch <address> [--pane <asserted-herdr-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <record-id>]
   atdd-flow application use <address> <application>
@@ -48,10 +50,12 @@ Usage:
   atdd-flow checkpoint <address> --summary <text> --next <text> [--status active|standby|blocked|complete|unverified]
   atdd-flow handover <address> --file <path> [--check]
   atdd-flow handover show <address>
-  atdd-flow handover replace <address> [--supersede-consumed] [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>
+  atdd-flow handover replace <address> [--supersede-consumed] [--recover-stale-main] [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>
   atdd-flow handover resumed <address>
   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> ...]
-  atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address>
+  atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address> [--immediate --priority <priority> --mutation-boundary <text>]
+  atdd-flow task acknowledge <project> <task-id> --dispatch <message-id> --by <assignee>
+  atdd-flow task observe-assignment <project> <task-id> --by <coordinator-address>
   atdd-flow task transfer <project> <task-id> --to <main-or-named-coordinator> --reason <text> --by <actor> [--authorization <operator-message-id>]
   atdd-flow task amend <project> <task-id> [--title <text>] [--body <text>] [--source <reference>] [--depends-on <task-id,...>]
   atdd-flow task import <project> <task-id> --proof <reference> [--proof <reference> ...] [--done-when <text> ...] [--source <reference>]
@@ -115,13 +119,19 @@ async function main() {
       if (rest[0] === "configure") return configureProject(root, required(rest[1], "project"), rest.slice(2));
       if (rest[0] === "migrate-vcs") return migrateProjectVcs(root, required(rest[1], "project"), rest.slice(2));
       if (rest[0] === "migrate-named-coordinator-topology") return migrateNamedCoordinatorTopology(root, required(rest[1], "project"), rest.slice(2));
-      throw new Error("Use `atdd-flow project init <project>`, `atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]`, `atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary] [--dry-run]`, or `atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>`.");
+      throw new Error("Use `atdd-flow project init <project>`, `atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]`, `atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary [--retain-large-primary-file <path>:<sha256>:<bytes>:<mode> ...]] [--dry-run]`, or `atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>`.");
     },
     spawn: () => spawn(root, required(rest[0], "project"), required(rest[1], "role"), required(rest[2], "name"), rest.slice(3)),
     bind: () => bind(root, required(rest[0], "address"), rest.slice(1)),
     attach: () => attach(root, required(rest[0], "address"), rest.slice(1)),
     pi: async () => {
       if (rest[0] === "extension-path") return console.log(piExtensionPath());
+      if (rest[0] === "wake") {
+        const { rows, success } = await wakePi(root, rest.slice(1), (entry) => console.log(formatWakeRow(entry)));
+        if (!success) process.exitCode = 1;
+        if (rows.length !== 1) console.log(`pi wake: ${rows.length} seat(s) — ${["woke", "swapped+woke", "deferred", "refused", "skipped", "failed"].map((outcome) => [outcome, rows.filter((entry) => entry.outcome === outcome).length] as const).filter(([, count]) => count).map(([outcome, count]) => `${count} ${outcome}`).join(", ") || "none"}`);
+        return;
+      }
       if (rest[0] === "runtime" && rest[1] === "authorize-adoption") return createExactSessionAdoptionAuthorization(root, required(rest[2], "authorization id"), rest.slice(3));
       if (rest[0] === "runtime" && rest[1] === "launch") {
         const plan = await launchPiRuntime(root, required(rest[2], "address"), rest.slice(3));
@@ -129,7 +139,7 @@ async function main() {
         else console.log(`Launched Pi runtime for ${required(rest[2], "address")} with ${plan.candidate}.`);
         return;
       }
-      throw new Error("Use `pi extension-path`, `pi runtime authorize-adoption <id> ...`, or `pi runtime launch <address> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <record-id>]`.");
+      throw new Error("Use `pi extension-path`, `pi wake <seat>|--scope project|desk [--model-profile <name>] --by <authorized-seat>`, `pi runtime authorize-adoption <id> ...`, or `pi runtime launch <address> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <record-id>]`.");
     },
     application: async () => {
       if (rest[0] === "use") return useApplication(root, required(rest[1], "address"), required(rest[2], "application"));
@@ -146,6 +156,8 @@ async function main() {
       const [subcommand, projectName, taskId, ...tail] = rest;
       if (subcommand === "add") return tasks.add(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "assign") return tasks.assign(root, required(projectName, "project"), required(taskId, "task id"), tail);
+      if (subcommand === "acknowledge") return tasks.acknowledge(root, required(projectName, "project"), required(taskId, "task id"), tail);
+      if (subcommand === "observe-assignment") return tasks.observeAssignment(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "transfer") return tasks.transfer(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "amend") return tasks.amend(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "import") return tasks.importCompleted(root, required(projectName, "project"), required(taskId, "task id"), tail);
@@ -163,7 +175,7 @@ async function main() {
       if (subcommand === "unblock") return tasks.unblock(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "list") return tasks.list(root, required(projectName, "project"), rest.slice(2));
       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|supersede|reject|defer|unblock|list|open`.");
+      throw new Error("Use `atdd-flow task add|assign|acknowledge|observe-assignment|transfer|amend|import|start|prove|handoff|respond|review|return|done|block|supersede|reject|defer|unblock|list|open`.");
     },
     seat: async () => {
       if (rest[0] === "retire") return tasks.retireSeat(root, required(rest[1], "address"), rest.slice(2));

package/src/collaboration-policy.ts

@@ -1,3 +1,9 @@
+// URN: component:flow:e004:collaboration-policy:backend:application
+// Tested-By:
+// - test:atdd-flow:seat-recovery-bundle
+// Runtime: bun
+// Purpose: Define the project collaboration policy and its startup instruction.
+
 import { readFileSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";

package/src/core.ts

@@ -39,6 +39,8 @@ export type ModelPortfolio = {
   schema: "atdd-workflow/models/v1";
   /** Ordered strongest to weakest. Workflow prefers the weakest sufficient enabled candidate. */
   models: ModelCandidate[];
+  /** Named, machine-readable migrations: profile -> source `provider/model` -> existing enabled candidate id. */
+  model_migrations?: Record<string, Record<string, string>>;
 };
 type LegacyCoordination = { schema: "atdd-workflow/coordination/v2"; site: string; application: string; aliases?: Record<string, string> };
 export type Project = {
@@ -262,6 +264,40 @@ export async function migrateDesk(root: string) {
   return true;
 }
 
+/** The one exact Pi provider/model a candidate selects; undefined when it is not Pi or is ambiguous. */
+export function piModel(candidate: ModelCandidate): { provider: string; model: string } | undefined {
+  if (basename(candidate.executable) !== "pi") return undefined;
+  const args = candidate.args ?? [];
+  const flagValues = (flag: string) => args.flatMap((argument, index) => argument === flag ? [args[index + 1]] : []);
+  const [provider, ...otherProviders] = flagValues("--provider"), [model, ...otherModels] = flagValues("--model");
+  if (otherProviders.length || otherModels.length) return undefined;
+  const exact = (value: string | undefined): value is string => Boolean(value?.trim()) && !value!.startsWith("--");
+  return exact(provider) && exact(model) ? { provider, model } : undefined;
+}
+
+function assertMigrationTarget(where: string, target: unknown, models: ModelCandidate[]) {
+  const candidate = models.find((entry) => entry.id === target);
+  if (!candidate) throw new Error(`${where} targets an unknown candidate: ${String(target)}`);
+  if (candidate.enabled === false) throw new Error(`${where} targets a disabled candidate: ${candidate.id}`);
+  if (!piModel(candidate)) throw new Error(`${where} targets a candidate without one exact Pi provider and model: ${candidate.id}`);
+}
+
+const isRecord = (entry: unknown): entry is Record<string, unknown> => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry);
+
+function assertMigration(profile: string, migration: unknown, models: ModelCandidate[]) {
+  if (!profile.trim() || !isRecord(migration)) throw new Error(`model_migrations.${profile || "<empty>"} must be a named map of source provider/model to a candidate id.`);
+  for (const [source, target] of Object.entries(migration)) {
+    if (!/^[^/\s]+\/\S+$/.test(source)) throw new Error(`model_migrations.${profile}: source must be provider/model: ${source}`);
+    assertMigrationTarget(`model_migrations.${profile}.${source}`, target, models);
+  }
+}
+
+function assertModelMigrations(value: unknown, models: ModelCandidate[]) {
+  if (value === undefined) return;
+  if (!isRecord(value)) throw new Error("model_migrations must map profile names to migrations.");
+  for (const [profile, migration] of Object.entries(value)) assertMigration(profile, migration, models);
+}
+
 export async function modelPortfolio(root: string): Promise<ModelPortfolio | undefined> {
   const file = paths(root).models;
   if (!await exists(file)) return undefined;
@@ -274,6 +310,7 @@ export async function modelPortfolio(root: string): Promise<ModelPortfolio | und
     if (ids.has(model.id)) throw new Error(`Duplicate model id in models.yaml: ${model.id}`);
     ids.add(model.id);
   }
+  assertModelMigrations(value.model_migrations, value.models);
   return value;
 }
 

package/src/exact-adoption-recovery.ts

@@ -10,6 +10,7 @@ import { basename, join, resolve } from "node:path";
 import { type Seat, paths, readYaml, yaml } from "./core";
 import type { HandoverReplacementRequest } from "./handover";
 import { readRuntimeState } from "./runtime-state";
+import { archivedReceiptMatches, recoveryEvidenceMatches } from "./stale-main-recovery";
 import type { Task } from "./tasks";
 
 type ReplacementLaunchReceipt = {
@@ -90,6 +91,9 @@ function validConsumedRequest(request: HandoverReplacementRequest, seat: string)
 
 /** Rebuild and compare every archived supersession byte and identity. */
 async function exactArchiveMatches(request: HandoverReplacementRequest) {
+  // Stale-main recovery proves its evidence by the hash-archived stale receipt, not a consumed request.
+  const recovery = request.stale_main_recovery;
+  if (recovery) return recoveryEvidenceMatches(request, recovery) && await archivedReceiptMatches(request, recovery);
   const proof = request.supersession;
   if (!proof) return false;
   try {
@@ -147,7 +151,7 @@ async function uniqueAdoptionReceipt(root: string, authorizationId: string, expe
 function exactAdoptionRuntimeMatches(record: Seat, request: HandoverReplacementRequest) {
   const runtime = record.runtime, locator = runtime?.addresses.herdr;
   const observed = {
-    supersession: Boolean(request.supersession), application: runtime?.application, wake: runtime?.wake,
+    supersession: Boolean(request.supersession || request.stale_main_recovery), application: runtime?.application, wake: runtime?.wake,
     session: runtime?.pi_session, sessionPath: runtime?.pi_session_path,
     herdrSession: typeof locator === "string" ? undefined : locator?.session,
     pane: typeof locator === "string" ? undefined : locator?.pane,

package/src/handover.ts

@@ -14,6 +14,7 @@ import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizati
 import { exactFailedAdoptionProof } from "./exact-adoption-recovery";
 import { isExactOperatorSeat, operatorActivation, operatorRelaunchSection } from "./operator-launch";
 import { readRuntimeState } from "./runtime-state";
+import { type StaleMainRecovery, buildStaleMainRecovery, replaceActiveRequest, staleRecoveryMatches } from "./stale-main-recovery";
 
 export type Handover = {
   schema: "atdd-workflow/handover/v1";
@@ -119,10 +120,11 @@ export type HandoverReplacementRequest = {
     canonical_source: { pi_session: string; pi_session_path: string; herdr_session: string; pane: string; cwd: string; launch_receipt: string };
     live_source: LiveSourceProof;
   };
+  stale_main_recovery?: StaleMainRecovery;
   created_at: string;
 };
 
-type LiveSourceProof = {
+export type LiveSourceProof = {
   authorization_hash: string;
   pi_session: string;
   pi_session_path: string;
@@ -204,6 +206,7 @@ function supersessionEvidenceMatches(request: HandoverReplacementRequest, proof:
 }
 
 export function replacementMatchesRuntime(runtime: Runtime | undefined, request: HandoverReplacementRequest) {
+  if (request.stale_main_recovery) return staleRecoveryMatches(runtime, request, request.stale_main_recovery);
   const proof = request.supersession;
   if (proof) return supersessionPlacementMatches(runtime, proof) && supersessionSessionMatches(runtime, proof) && supersessionEvidenceMatches(request, proof);
   if (!request.legacy_source) return canonicalSourceMatchesRuntime(runtime, request.source);
@@ -360,10 +363,11 @@ async function publishCreateOnly(file: string, content: string) {
   } finally { await rm(temporary, { force: true }); }
 }
 
-const replacementFlags = ["--supersede-consumed", "--legacy-source-bootstrap", "--handover", "--authorization", "--takeover-task", "--source-pi-session", "--source-pi-session-path", "--source-herdr-session", "--source-pane", "--herdr-session", "--target-pane", "--target-cwd"];
+const replacementFlags = ["--supersede-consumed", "--recover-stale-main", "--legacy-source-bootstrap", "--handover", "--authorization", "--takeover-task", "--source-pi-session", "--source-pi-session-path", "--source-herdr-session", "--source-pane", "--herdr-session", "--target-pane", "--target-cwd"];
 function validateReplacementArgs(args: string[]) {
-  if (args.some((arg) => arg.startsWith("--") && !replacementFlags.includes(arg))) throw new Error("Use `handover replace <main-seat> [--supersede-consumed] [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>`.");
+  if (args.some((arg) => arg.startsWith("--") && !replacementFlags.includes(arg))) throw new Error("Use `handover replace <main-seat> [--supersede-consumed] [--recover-stale-main] [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>`.");
   if (has(args, "--supersede-consumed") && has(args, "--legacy-source-bootstrap")) throw new Error("Consumed replacement supersession cannot use legacy source bootstrap.");
+  if (has(args, "--recover-stale-main") && (has(args, "--supersede-consumed") || has(args, "--legacy-source-bootstrap"))) throw new Error("Stale main recovery cannot be combined with consumed supersession or legacy source bootstrap.");
 }
 
 async function currentReplacementHandover(root: string, resolved: string, args: string[]) {
@@ -394,13 +398,13 @@ function assertReplacementSource(record: Seat, source: HandoverReplacementReques
 
 async function prepareReplacement(root: string, resolved: string, args: string[]) {
   validateReplacementArgs(args);
-  const legacy = has(args, "--legacy-source-bootstrap"), supersede = has(args, "--supersede-consumed");
+  const legacy = has(args, "--legacy-source-bootstrap"), supersede = has(args, "--supersede-consumed"), recover = has(args, "--recover-stale-main");
   const handover = await currentReplacementHandover(root, resolved, args);
   const task = nonEmpty(words(args, "--takeover-task"), "--takeover-task");
   const { record } = await exactMainTakeoverTask(root, resolved, task);
   const source = replacementSource(args), target = replacementTarget(args, record, source);
-  if (!supersede) assertReplacementSource(record, source, legacy);
-  return { legacy, supersede, handover, task, record, source, target };
+  if (!supersede && !recover) assertReplacementSource(record, source, legacy);
+  return { legacy, supersede, recover, handover, task, record, source, target };
 }
 
 function replacementRequest(resolved: string, intent: Awaited<ReturnType<typeof prepareReplacement>>, authorization: { id: string; hash: string }, legacySource: HandoverReplacementRequest["legacy_source"], dependencies: HandoverReplacementDependencies): HandoverReplacementRequest {
@@ -735,14 +739,15 @@ export async function requestHandoverReplacement(root: string, address: string,
   const resolved = await canonicalAddress(root, address), intent = await prepareReplacement(root, resolved, args);
   const file = handoverReplacementPath(root, resolved);
   if (intent.supersede) return supersedeConsumedReplacement(root, resolved, file, intent, args, dependencies);
-  if (await exists(file)) throw new Error(`Path-A replacement request already exists for ${resolved}.`);
+  if (!intent.recover && await exists(file)) throw new Error(`Path-A replacement request already exists for ${resolved}.`);
   const authorization = await resolveExactSessionAdoptionAuthorization(root, nonEmpty(words(args, "--authorization"), "--authorization"), {
     seat: resolved, pi_session: intent.source.pi_session, pi_session_path: intent.source.pi_session_path,
     source: { herdr_session: intent.source.herdr_session, pane: intent.source.pane }, target: intent.target,
   });
   const legacySource = intent.legacy ? await verifyLegacySource(intent.source, intent.target, authorization.hash, dependencies) : undefined;
-  const request = replacementRequest(resolved, intent, authorization, legacySource, dependencies);
-  await (dependencies.publish ?? publishCreateOnly)(file, yaml.print(request));
+  const recovery = intent.recover ? await buildStaleMainRecovery(root, resolved, intent, { file, isLive: (prior) => replacementMatchesRuntime(intent.record.runtime, prior) }, (canonical) => verifyLegacySource(intent.source, intent.target, authorization.hash, dependencies, canonical)) : undefined;
+  const request = { ...replacementRequest(resolved, intent, authorization, legacySource, dependencies), ...(recovery ? { stale_main_recovery: recovery } : {}) };
+  await (recovery?.prior_request ? replaceActiveRequest : dependencies.publish ?? publishCreateOnly)(file, yaml.print(request));
   console.log(`Recorded Path-A replacement request for ${resolved}.`);
 }
 

package/src/multiplexer.ts

@@ -164,13 +164,19 @@ async function targets(root: string, options: { strict?: string; unprojected?: U
     if (!config.repository) continue;
     const primary = resolve(config.repository);
     result.push({ project: name, worktree: primary, workspaceLabel: name });
-    for (const entry of await projectSeats(root, name)) {
+    const seats = await projectSeats(root, name);
+    const mainOnPrimary = seats.some((entry) => entry.role === "main" && resolve(entry.worktree) === primary);
+    for (const entry of seats) {
       try { assertNewTopologyPlacement(config, entry, primary); }
       catch (error) {
         if (entry.address === options.strict) throw error;
         options.unprojected?.push({ address: entry.address, reason: (error as Error).message });
         continue;
       }
+      // main@project is the single primary coordinator projection: the preserved legacy generic
+      // coordinator@project shares its checkout and is not bulk-projected as a second tab. An explicit
+      // per-seat projection still projects it, and a project without a primary main keeps it.
+      if (mainOnPrimary && entry.role === "coordinator" && entry.address === `coordinator@${name}` && entry.address !== options.strict && resolve(entry.worktree) === primary) continue;
       if ((entry.role === "main" || entry.role === "coordinator" || entry.role === "operator") && resolve(entry.worktree) === primary) {
         result.push({ project: name, worktree: primary, workspaceLabel: name, seat: entry });
         continue;

package/src/next-action-notices.ts

@@ -52,6 +52,22 @@ export async function sendTaskDirective(host: NoticeHost, root: string, seat: st
   }
 }
 
+/**
+ * The current task-derived action as text for a message the caller sends itself (a wake's single combined turn).
+ * Recording it as delivered keeps the settled-turn nudge from repeating the same directive.
+ */
+export async function deliveredDirectiveText(root: string, seat: string, state: NoticeState) {
+  try {
+    const directive = await nextDirective(root, seat);
+    if (!directive) return undefined;
+    const key = directiveKey(directive);
+    state.lastDelivered = key;
+    state.settledNudged = undefined;
+    if (directive.lifecycle === "BLOCKED") state.blockers.add(key);
+    return directiveNotice(seat, directive);
+  } catch { return undefined; }
+}
+
 /** A settled model turn is not task completion. Give one additional nudge for a
  * still-actionable directive, but never loop on unchanged task state. */
 export async function sendSettledDirective(host: NoticeHost, root: string, seat: string, state: NoticeState) {

package/src/operator-launch.ts

@@ -26,7 +26,7 @@ export async function operatorRelaunchSection(root: string, record: Seat) {
   const locator = record.runtime?.addresses.herdr;
   const session = (typeof locator === "object" ? locator.session : undefined) ?? (await desk(root)).herdr_session;
   const command = session ? canonicalLaunchCommand(record.address, session) : "UNAVAILABLE: no Herdr session is recorded for this seat or Desk.";
-  return `\nCANONICAL RELAUNCH COMMAND (generated by Flow; run it in a vacant shell pane after this Pi exits, then run \`atdd-flow handover resumed ${record.address}\`):\n${command}\n`;
+  return `\nCANONICAL RELAUNCH COMMAND (generated by Flow. Exit Pi in the operator pane so it is an idle shell, then run this from a DIFFERENT pane (e.g. another pane in this workspace), never inside the target pane; afterwards run \`atdd-flow handover resumed ${record.address}\`):\n${command}\n`;
 }
 
 const notBefore = (value: string | undefined, floor: string | undefined) => Boolean(value && floor && Date.parse(value) >= Date.parse(floor));