@afokapu/atdd-flow 0.3.71 → 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>`.
 
@@ -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.71",
+  "version": "0.3.72",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

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";
@@ -40,6 +41,7 @@ Usage:
   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>
@@ -51,7 +53,9 @@ Usage:
   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>]
@@ -122,6 +126,12 @@ async function main() {
     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/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/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));

package/src/pi-runtime-launch.ts

@@ -43,6 +43,10 @@ export type PiRuntimeLaunchDependencies = {
   sleep?: (milliseconds: number) => Promise<void>;
   /** How long Herdr may take to report the exact session path after start. */
   sessionPathWindowMs?: number;
+  /** Herdr pane hosting this launcher process; defaults to HERDR_PANE_ID. Injectable for tests. */
+  hostPane?: string;
+  /** Pid of this launcher process; defaults to process.pid. Injectable for tests. */
+  hostPid?: number;
 };
 
 type Bind = (root: string, address: string, args: string[], selectedModel?: string, wake?: Runtime["wake"], piSession?: string, piSessionPath?: string, launchReceipt?: string) => Promise<void>;
@@ -154,7 +158,7 @@ export const piExtensionPath = () => join(import.meta.dir, "..", "extensions", "
 type HerdrRequest = { session: string; pane: string; seat: string; root: string; piSession: string; sessionPath?: string; resume: boolean; args: string[] };
 type Command = (command: string[]) => Promise<string>;
 type PaneReport = { pane: string; agent?: string; status?: string; sessionPath?: string };
-type ProcessReport = { shell?: number; processes: Array<{ name?: string; argv0?: string; cmdline?: string }> };
+type ProcessReport = { shell?: number; processes: Array<{ pid?: number; name?: string; argv0?: string; cmdline?: string }> };
 
 const object = (value: unknown): Record<string, unknown> | undefined => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
 const text = (value: unknown) => typeof value === "string" ? value : undefined;
@@ -176,7 +180,7 @@ function processReport(value: unknown): ProcessReport {
   const report = object(result(value)?.process_info) ?? result(value);
   const processes = Array.isArray(report?.foreground_processes) ? report.foreground_processes.flatMap((entry) => {
     const process = object(entry);
-    return process ? [{ name: text(process.name), argv0: text(process.argv0), cmdline: text(process.cmdline) }] : [];
+    return process ? [{ pid: number(process.pid), name: text(process.name), argv0: text(process.argv0), cmdline: text(process.cmdline) }] : [];
   }) : [];
   return { ...(number(report?.shell_pid) ? { shell: number(report?.shell_pid) } : {}), processes };
 }
@@ -305,15 +309,22 @@ function assertProjectedPane(launch: PreparedLaunch, pane: string) {
   if (replacement) assertReplacementTarget(replacement.request, options.herdrSession, pane, record.worktree);
 }
 
+const sameTerminalRefusal = "Run this from a different pane; the target pane must be an idle shell.";
+
 /** Require both Herdr metadata and process inspection to report a vacant target. */
 async function assertVacantTarget(launch: PreparedLaunch, pane: string) {
-  const { command, options } = launch;
+  const { command, options, dependencies } = launch;
+  const hostPane = dependencies.hostPane ?? process.env.HERDR_PANE_ID;
+  // The launcher typing into its own tty would corrupt the pane: refuse before any Herdr call.
+  if (hostPane === pane) throw new Error(sameTerminalRefusal);
   const [paneRaw, processRaw] = await Promise.all([
     command(herdr(options.herdrSession, "pane", "get", pane)),
     command(herdr(options.herdrSession, "pane", "process-info", "--pane", pane)),
   ]);
   const currentPane = paneReport(JSON.parse(paneRaw));
   if (currentPane.pane !== pane) throw new Error("Herdr reported a different pane; refusing runtime launch.");
+  const hostPid = dependencies.hostPid ?? process.pid;
+  if (processReport(JSON.parse(processRaw)).processes.some((entry) => entry.pid === hostPid)) throw new Error(sameTerminalRefusal);
   if (currentPane.agent || piProcess(processReport(JSON.parse(processRaw)).processes)) {
     throw new Error(options.resume ? "Resume requires the prior Pi to have exited and been released." : "New launch requires an available shell pane.");
   }

package/src/pi-wake-protocol.ts

@@ -0,0 +1,62 @@
+// URN: component:flow:e004:pi-wake-protocol:backend:domain
+// Tested-By:
+// - test:atdd-flow:fleet-model-swap-and-wake
+// Runtime: bun
+// Purpose: Name shared /flow-wake transcript entries and read a transcript's active branch.
+
+export const wakeCapabilityType = "flow-wake-capability/v1";
+export const wakeRequestType = "flow-wake-request/v1";
+export const wakeResultType = "flow-wake-result/v1";
+export const wakeStartType = "atdd-flow-start";
+/** Unique per attempt; also the only argument besides an optional portfolio candidate id the extension command accepts. */
+export const wakeRequestIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{5,127}$/;
+
+export type TranscriptEntry = {
+  type?: string;
+  id?: string;
+  parentId?: string | null;
+  timestamp?: string;
+  customType?: string;
+  data?: Record<string, unknown>;
+  details?: Record<string, unknown>;
+  provider?: string;
+  modelId?: string;
+  thinkingLevel?: string;
+};
+
+/** A line that is not complete JSON (a transcript being appended to) is ignored rather than trusted. */
+export function parseTranscript(text: string): TranscriptEntry[] {
+  const entries: TranscriptEntry[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const value = JSON.parse(line) as unknown;
+      if (value && typeof value === "object" && !Array.isArray(value)) entries.push(value as TranscriptEntry);
+    } catch { /* A partial trailing line is never evidence. */ }
+  }
+  return entries;
+}
+
+/** The chain from the most recently appended entry back through its parents, oldest first; abandoned siblings are excluded. */
+export function activeBranch(entries: TranscriptEntry[]): TranscriptEntry[] {
+  const nodes = entries.filter((entry) => entry.type !== "session" && typeof entry.id === "string");
+  const byId = new Map(nodes.map((entry) => [entry.id!, entry]));
+  const chain: TranscriptEntry[] = [];
+  const seen = new Set<string>();
+  let current = nodes.at(-1);
+  while (current && !seen.has(current.id!)) {
+    seen.add(current.id!);
+    chain.push(current);
+    current = typeof current.parentId === "string" ? byId.get(current.parentId) : undefined;
+  }
+  return chain.reverse();
+}
+
+export const customEntries = (branch: TranscriptEntry[], customType: string) =>
+  branch.filter((entry) => (entry.type === "custom" || entry.type === "custom_message") && entry.customType === customType);
+
+/** The latest model selection on the branch, as `provider/model`. */
+export function branchModel(branch: TranscriptEntry[]) {
+  const change = branch.filter((entry) => entry.type === "model_change" && entry.provider && entry.modelId).at(-1);
+  return change ? { provider: change.provider!, model: change.modelId! } : undefined;
+}

package/src/pi-wake.ts

@@ -0,0 +1,291 @@
+// URN: component:flow:e004:pi-wake:backend:application
+// Tested-By:
+// - test:atdd-flow:fleet-model-swap-and-wake
+// Runtime: bun
+// Purpose: Wake live Herdr-bound Pi seats with /flow-wake, optionally swapping model.
+
+import { readFile, readdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { addressParts, canonicalAddress, modelPortfolio, paths, piModel, readYaml, type ModelPortfolio, type Seat } from "./core";
+import { readRuntimeState } from "./runtime-state";
+import { seatTasks, terminal } from "./tasks";
+import {
+  type TranscriptEntry, activeBranch, branchModel, customEntries, parseTranscript,
+  wakeCapabilityType, wakeRequestType, wakeResultType, wakeStartType,
+} from "./pi-wake-protocol";
+
+export const wakeUsage = "Use `atdd-flow pi wake <seat>|--scope project|desk [--model-profile <name>] --by <authorized-seat>`.";
+
+type Outcome = "woke" | "swapped+woke" | "deferred" | "refused" | "skipped" | "failed";
+export type WakeRow = { seat: string; outcome: Outcome; detail?: string };
+type Options = { target?: string; scope?: "project" | "desk"; profile?: string; by: string };
+type Target = { provider: string; model: string };
+/** What Herdr reports about the bound pane; nothing here is trusted until it matches the Desk and runtime records. */
+type Pane = { agent?: string; status?: string; sessionPath?: string; pids: number[] };
+type Ready = { session: string; pane: string; sessionId: string; sessionPath: string };
+type Inspection = { row: WakeRow } | { ready: Ready };
+type Prepared = { row: WakeRow } | { record: Seat; ready: Ready; inspectedAt: number };
+
+const pollMs = 50;
+/** A runtime heartbeat older than this is not a live Pi (the extension beats every 15 s). */
+const heartbeatMs = 120_000;
+/** An inspection this recent still describes the seat; an older one is repeated just before anything is sent. */
+const freshMs = 2_000;
+
+/** Every wait is bounded; the variable exists so fixtures that never answer fail quickly. */
+const timeouts = () => {
+  const configured = Number(process.env.ATDD_FLOW_WAKE_TIMEOUT_MS);
+  const explicit = Number.isFinite(configured) && configured > 0 ? configured : undefined;
+  // A bootstrap reload may start a full resumed-work turn; waiting for the seat to be idle again is bounded separately.
+  return { step: explicit ?? 30_000, idle: explicit ?? 300_000 };
+};
+const pause = (milliseconds: number) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const row = (seat: string, outcome: Outcome, detail?: string): WakeRow => ({ seat, outcome, ...(detail ? { detail } : {}) });
+const hold = (seat: string, outcome: Outcome, detail: string): { row: WakeRow } => ({ row: row(seat, outcome, detail) });
+const object = (value: unknown): Record<string, unknown> | undefined => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const text = (value: unknown) => typeof value === "string" ? value : undefined;
+const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+/** Polls until `read` yields a value or the bound elapses; one read always happens. */
+async function until<T>(read: () => Promise<T | undefined>, timeoutMs: number) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const value = await read();
+    if (value !== undefined) return value;
+    if (Date.now() >= deadline) return undefined;
+    await pause(pollMs);
+  }
+}
+
+function flagsOf(args: string[]) {
+  const flags = new Map<string, string>(), targets: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]!, value = args[index + 1];
+    if (!argument.startsWith("--")) targets.push(argument);
+    else if (["--scope", "--model-profile", "--by"].includes(argument) && value && !value.startsWith("--") && !flags.has(argument)) { flags.set(argument, value); index += 1; }
+    else throw new Error(wakeUsage);
+  }
+  return { flags, targets };
+}
+
+/** The grammar is closed: exactly one of a seat or --scope, one --by, and an optional profile. */
+export function parseWakeArguments(args: string[]): Options {
+  const { flags, targets } = flagsOf(args);
+  const scope = flags.get("--scope"), by = flags.get("--by"), profile = flags.get("--model-profile");
+  if (!by || targets.length + (scope ? 1 : 0) !== 1) throw new Error(wakeUsage);
+  if (scope && scope !== "project" && scope !== "desk") throw new Error(wakeUsage);
+  return { ...(targets[0] ? { target: targets[0] } : {}), ...(scope ? { scope } : {}), ...(profile ? { profile } : {}), by };
+}
+
+async function herdr(session: string, ...args: string[]) {
+  const child = Bun.spawn(["herdr", "--session", session, ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  if (code !== 0) throw new Error(`herdr ${args.slice(0, 2).join(" ")} failed: ${stderr.trim() || stdout.trim()}`);
+  return stdout;
+}
+
+/** Herdr pane metadata plus foreground processes; read-only. */
+async function observe(session: string, pane: string): Promise<Pane> {
+  const [paneRaw, processRaw] = await Promise.all([herdr(session, "pane", "get", pane), herdr(session, "pane", "process-info", "--pane", pane)]);
+  const info = object(object(object(JSON.parse(paneRaw))?.result)?.pane);
+  const processResult = object(object(JSON.parse(processRaw))?.result);
+  const processes = object(processResult?.process_info)?.foreground_processes;
+  const sessionInfo = object(info?.agent_session);
+  return {
+    ...(text(info?.agent) ? { agent: text(info?.agent) } : {}),
+    ...(text(info?.agent_status) ? { status: text(info?.agent_status) } : {}),
+    ...(sessionInfo?.kind === "path" && text(sessionInfo.value) ? { sessionPath: text(sessionInfo.value) } : {}),
+    pids: (Array.isArray(processes) ? processes : []).flatMap((entry) => typeof object(entry)?.pid === "number" ? [object(entry)!.pid as number] : []),
+  };
+}
+
+/** The transcript's active branch: the chain from the newest entry, excluding abandoned siblings. */
+const readBranch = async (path: string) => activeBranch(parseTranscript(await readFile(path, "utf8")));
+
+/** Resolve a profile mapping for the seat's current model. `{}` means wake without a swap. */
+function resolveSwap(portfolio: ModelPortfolio, profile: string, branch: TranscriptEntry[]): { candidate?: string; target?: Target } | { refused: string } {
+  const current = branchModel(branch);
+  if (!current) return { refused: "no model recorded in the transcript" };
+  const migration = portfolio.model_migrations?.[profile] ?? {};
+  const exact = (id: string) => { const candidate = portfolio.models.find((entry) => entry.id === id); return candidate && piModel(candidate); };
+  const same = (target?: Target) => target?.provider === current.provider && target.model === current.model;
+  const id = migration[`${current.provider}/${current.model}`];
+  // A seat already on a mapped target needs no swap, which makes a partly applied fleet run safe to repeat.
+  if (!id) return Object.values(migration).some((target) => same(exact(target))) ? {} : { refused: `no ${profile} migration for ${current.provider}/${current.model}` };
+  const target = exact(id);
+  return !target || same(target) ? {} : { candidate: id, target };
+}
+
+function bindingOf(record: Seat) {
+  const locator = record.runtime?.addresses.herdr;
+  return record.runtime?.application === "herdr" && typeof locator === "object" && locator.session && locator.pane ? locator : undefined;
+}
+
+/** Why the live pane cannot be trusted as this seat's Pi, or undefined when it can. */
+async function identityProblem(root: string, address: string, record: Seat, live: Pane) {
+  const runtime = await readRuntimeState(root, address);
+  if (!runtime || Date.now() - Date.parse(runtime.heartbeat_at) > heartbeatMs) return "no live Pi runtime heartbeat";
+  const recorded = record.runtime;
+  if (!recorded?.pi_session || !recorded.pi_session_path) return "seat records no exact Pi session";
+  if (live.sessionPath !== recorded.pi_session_path) return "Herdr reports a different Pi session than the seat binding";
+  return live.pids.includes(runtime.pid) ? undefined : "pane foreground process is not the registered Pi runtime";
+}
+
+/** Only idle/done is a safe boundary: working defers, any blocking UI or unknown state is refused. */
+function boundary(address: string, status?: string) {
+  if (status === "idle" || status === "done") return undefined;
+  return status === "working" ? row(address, "deferred", "agent is working") : row(address, "refused", `agent is ${status ?? "in an unknown state"}`);
+}
+
+function absentAgent(live: Pane) {
+  if (!live.agent) return "no agent in the bound pane";
+  return live.agent === "pi" ? undefined : `bound pane runs ${live.agent}, not Pi`;
+}
+
+/** Read-only check that the seat's recorded pane, session and process are the live Pi at a safe boundary. */
+async function inspect(root: string, address: string, record: Seat): Promise<Inspection> {
+  const locator = bindingOf(record);
+  if (!locator) return hold(address, "skipped", "no native Herdr binding");
+  const live = await observe(locator.session, locator.pane).catch((error) => error as Error);
+  if (live instanceof Error) return hold(address, "refused", `Herdr observation failed: ${live.message}`);
+  const absent = absentAgent(live);
+  if (absent) return hold(address, "skipped", absent);
+  const problem = await identityProblem(root, address, record, live);
+  if (problem) return hold(address, "refused", problem);
+  const unsafe = boundary(address, live.status);
+  if (unsafe) return { row: unsafe };
+  return { ready: { session: locator.session, pane: locator.pane, sessionId: record.runtime!.pi_session!, sessionPath: record.runtime!.pi_session_path! } };
+}
+
+const capabilityOf = (branch: TranscriptEntry[], ready: Ready, address: string) =>
+  customEntries(branch, wakeCapabilityType).filter((entry) => entry.data?.seat === address && entry.data.pi_session === ready.sessionId && entry.data.pane === ready.pane);
+
+/** Classify one seat without sending anything; every non-eligible seat resolves to its final row. */
+async function prepare(root: string, address: string, actor: string): Promise<Prepared> {
+  if (address === actor) return hold(address, "skipped", "invoking seat");
+  const record = await readYaml<Seat>(paths(root).seatFile(address)).catch(() => undefined);
+  if (!record) return hold(address, "skipped", "no seat record");
+  if (record.retired) return hold(address, "skipped", "retired");
+  const assigned = await seatTasks(root, record.project, address).catch(() => []);
+  if (assigned.length && assigned.every((entry) => terminal(entry.task))) return hold(address, "skipped", "all assigned tasks are terminal");
+  const inspection = await inspect(root, address, record);
+  return "row" in inspection ? inspection : { record, ready: inspection.ready, inspectedAt: Date.now() };
+}
+
+/**
+ * A Pi that predates `/flow-wake` gets one `/reload` at a safe boundary; only a fresh capability entry proves it
+ * loaded, and the seat must return to idle/done (the reload may start a normal startup turn) before the wake.
+ */
+async function bootstrap(root: string, address: string, record: Seat, ready: Ready, branch: TranscriptEntry[]): Promise<WakeRow | undefined> {
+  const limit = timeouts(), known = new Set(customEntries(branch, wakeCapabilityType).map((entry) => entry.id));
+  try { await herdr(ready.session, "agent", "prompt", ready.pane, "/reload"); }
+  catch (error) { return row(address, "failed", message(error)); }
+  const fresh = await until(async () => capabilityOf(await readBranch(ready.sessionPath), ready, address).some((entry) => !known.has(entry.id)) || undefined, limit.step);
+  if (!fresh) return row(address, "failed", "no fresh flow-wake capability after /reload; the Flow extension did not activate");
+  const settled = await until(async () => {
+    const again = await inspect(root, address, record);
+    return "row" in again && again.row.outcome === "deferred" ? undefined : again;
+  }, limit.idle);
+  if (!settled) return row(address, "failed", "seat did not return to idle/done after reload");
+  return "row" in settled ? settled.row : undefined;
+}
+
+/** Dispatch one wake to an eligible seat and verify it from the seat's own transcript. */
+async function wakeOne(root: string, address: string, prepared: Extract<Prepared, { record: Seat }>, portfolio: ModelPortfolio | undefined, profile: string | undefined): Promise<WakeRow> {
+  const { record } = prepared;
+  const inspection = Date.now() - prepared.inspectedAt <= freshMs ? { ready: prepared.ready } : await inspect(root, address, record);
+  if ("row" in inspection) return inspection.row;
+  const { ready } = inspection;
+  const branch = await readBranch(ready.sessionPath).catch((error) => error as Error);
+  if (branch instanceof Error) return row(address, "refused", `cannot read the Pi transcript: ${branch.message}`);
+  const swap = profile ? resolveSwap(portfolio!, profile, branch) : {};
+  if ("refused" in swap) return row(address, "refused", swap.refused);
+  const unready = capabilityOf(branch, ready, address).length ? undefined : await bootstrap(root, address, record, ready, branch);
+  if (unready) return unready;
+
+  const requestId = `wake-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+  try { await herdr(ready.session, "agent", "prompt", ready.pane, swap.candidate ? `/flow-wake ${swap.candidate} ${requestId}` : `/flow-wake ${requestId}`); }
+  catch (error) { return row(address, "failed", message(error)); }
+  return verify(ready.sessionPath, address, requestId, swap.target, timeouts().step);
+}
+
+type Verdict = { outcome: "failed"; detail: string } | { outcome: "woke" | "swapped+woke" };
+
+/** A swap needs a native model change to exactly the target between request and result, and a result that says so. */
+function modelProblem(span: TranscriptEntry[], result: Record<string, unknown>, target: Target | undefined) {
+  const changed = span.filter((entry) => entry.type === "model_change").at(-1);
+  if (!target) return changed ? "unexpected model change during a keep-model wake" : undefined;
+  if (changed?.provider !== target.provider || changed.modelId !== target.model) return "no native model change to the requested target between request and result";
+  const reported = object(result.target);
+  return reported?.provider === target.provider && reported.model === target.model ? undefined : "result does not report the requested target";
+}
+
+/** Undefined until request, result and the one startup turn for this request id are all present in order. */
+function judge(branch: TranscriptEntry[], requestId: string, target: Target | undefined): Verdict | undefined {
+  const requestAt = branch.findIndex((entry) => entry.customType === wakeRequestType && entry.data?.request_id === requestId);
+  const resultAt = branch.findIndex((entry, index) => index > requestAt && entry.customType === wakeResultType && entry.data?.request_id === requestId);
+  if (requestAt < 0 || resultAt < 0) return undefined;
+  const result = branch[resultAt]!.data!, expected = target ? "swapped+woke" : "woke";
+  if (result.outcome === "failed") return { outcome: "failed", detail: text(result.reason) ?? "the seat reported a failed wake" };
+  const problem = result.outcome === expected ? modelProblem(branch.slice(requestAt, resultAt), result, target) : `unexpected result outcome ${String(result.outcome)}`;
+  if (problem) return { outcome: "failed", detail: problem };
+  const started = branch.slice(resultAt).some((entry) => entry.customType === wakeStartType && entry.details?.request_id === requestId);
+  return started ? { outcome: expected } : undefined;
+}
+
+/** Waits a bounded time for the complete handshake; whatever is missing is reported, never retried. */
+async function verify(sessionPath: string, address: string, requestId: string, target: Target | undefined, timeoutMs: number): Promise<WakeRow> {
+  const verdict = await until(async () => judge(await readBranch(sessionPath).catch(() => []), requestId, target), timeoutMs);
+  if (verdict) return verdict.outcome === "failed" ? row(address, "failed", verdict.detail) : row(address, verdict.outcome);
+  const branch = await readBranch(sessionPath).catch(() => []);
+  const seen = [wakeRequestType, wakeResultType].filter((type) => branch.some((entry) => entry.customType === type && entry.data?.request_id === requestId));
+  return row(address, "failed", `incomplete wake ${requestId}: observed ${seen.length ? seen.join(", ") : "nothing"}; not retried`);
+}
+
+async function seatAddresses(root: string, project: string) {
+  const entries = await readdir(paths(root).seats(project), { withFileTypes: true }).catch(() => []);
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => `${entry.name}@${project}`);
+}
+
+/** Authorization is by address: the operator may wake anything; a project main only its own project. */
+async function targetAddresses(root: string, options: Options, actor: string) {
+  const operator = actor === "operator@desk";
+  if (options.target) {
+    const target = await canonicalAddress(root, options.target), project = addressParts(target).project;
+    if (!operator && actor !== `main@${project}`) throw new Error(`${actor} is not authorized to wake ${target}; use operator@desk or main@${project}.`);
+    return [target];
+  }
+  if (options.scope === "desk") {
+    if (!operator) throw new Error("Desk scope requires --by operator@desk.");
+    const projects = await readdir(paths(root).work, { withFileTypes: true }).catch(() => []);
+    return (await Promise.all(projects.filter((entry) => entry.isDirectory()).map((entry) => seatAddresses(root, entry.name)))).flat();
+  }
+  const { local, project } = addressParts(actor);
+  if (local !== "main") throw new Error("Project scope requires --by main@<project>.");
+  return seatAddresses(root, project);
+}
+
+/** Runs the closed `pi wake` grammar; reports each seat's row in lexical order as it completes. */
+export async function wakePi(root: string, args: string[], report: (line: WakeRow) => void = () => undefined) {
+  const options = parseWakeArguments(args);
+  const actor = await canonicalAddress(root, options.by);
+  const addresses = (await targetAddresses(root, options, actor)).sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+  const portfolio = options.profile ? await modelPortfolio(root) : undefined;
+  if (options.profile && !portfolio?.model_migrations?.[options.profile]) throw new Error(`models.yaml declares no model_migrations profile ${options.profile}.`);
+
+  // Classification is read-only and concurrent; anything that sends a prompt then runs one seat at a time in lexical order.
+  const prepared = await Promise.all(addresses.map((address) => prepare(root, address, actor).catch((error) => hold(address, "failed", message(error)) as Prepared)));
+  const rows: WakeRow[] = [];
+  for (const [index, address] of addresses.entries()) {
+    const ready = prepared[index]!;
+    const outcome = "row" in ready ? ready.row : await wakeOne(root, address, ready, portfolio, options.profile).catch((error) => row(address, "failed", message(error)));
+    rows.push(outcome);
+    report(outcome);
+  }
+  // A named seat must be woken; a fleet is unsuccessful only when something was refused or failed.
+  const woke = (entry: WakeRow) => entry.outcome === "woke" || entry.outcome === "swapped+woke";
+  const success = options.target ? rows.every(woke) : rows.every((entry) => entry.outcome !== "refused" && entry.outcome !== "failed");
+  return { rows, success };
+}
+
+export const formatWakeRow = (entry: WakeRow) => `${entry.seat}  ${entry.outcome}${entry.detail ? `  ${entry.detail}` : ""}`;

package/src/tasks.ts

@@ -29,6 +29,19 @@ export type CoordinatorTransfer = {
 };
 export type TerminalDisposition = { kind: "superseded" | "rejected"; by: string; at: string; reason: string };
 export type DeferredDisposition = { by: string; at: string; reason: string; owner: string; trigger: string; review_at: string };
+export type DispatchAlert = { key: string; message: string; observed_at: string };
+/** Persisted evidence for an immediate assignment; each field is written only by its own typed command. */
+export type ImmediateDispatch = {
+  thread: string;
+  message: string;
+  priority: string;
+  mutation_boundary: string;
+  assignee: string;
+  status: "dispatched";
+  acknowledgement?: { dispatch: string; by: string; acknowledged_at: string };
+  start?: { by: string; transitioned_at: string };
+  alerts?: { missing_acknowledgement?: DispatchAlert; missing_start?: DispatchAlert };
+};
 export type Task = {
   schema: "atdd-workflow/task/v1";
   title: string;
@@ -51,6 +64,8 @@ export type Task = {
   disposition?: TerminalDisposition;
   /** Bounded hold with an accountable owner, trigger, and review point. */
   deferred?: DeferredDisposition;
+  /** Absent unless assigned with `--immediate`. */
+  immediate_dispatch?: ImmediateDispatch;
   done_when: DoneWhen[];
 };
 
@@ -346,11 +361,95 @@ export async function assign(root: string, projectName: string, id: string, args
   if (task.status !== "todo") throw new Error(`Task ${id} can only be assigned while todo.`);
   if (task.assignee) throw new Error(`Task ${id} is already assigned to ${task.assignee}.`);
   const assignee = await canonicalAddress(root, required(words(args, "--assignee"), "--assignee"));
-  const base = await evidenceBase(root, projectName, task.coordinator, await eligibleAssignee(root, projectName, assignee));
+  const target = await eligibleAssignee(root, projectName, assignee);
+  const base = await evidenceBase(root, projectName, task.coordinator, target);
+  const immediate = args.includes("--immediate") ? await dispatchImmediately(root, projectName, id, task, target, args) : undefined;
   task.assignee = assignee;
   if (base) task.governed_base = base;
+  if (immediate) task.immediate_dispatch = immediate;
+  await writeTask(root, projectName, id, task);
+  console.log(`${id}  assigned  ${assignee}${immediate ? "  dispatched" : ""}`);
+}
+
+/** The assignee's todo -> in_progress transition is the only writer of start evidence. */
+function recordDispatchStart(task: Task, next: TaskStatus, actor: string) {
+  if (next === "in_progress" && task.status === "todo" && task.immediate_dispatch) {
+    task.immediate_dispatch.start = { by: actor, transitioned_at: now() };
+  }
+}
+
+async function quietly<T>(run: () => Promise<T>) {
+  const log = console.log;
+  console.log = () => {};
+  try { return await run(); }
+  finally { console.log = log; }
+}
+
+/**
+ * Fails closed before any write when the assignee has no native queue, then persists one task-linked
+ * dispatch through the existing native mail path. The task write that claims "dispatched" happens last.
+ */
+async function dispatchImmediately(root: string, projectName: string, id: string, task: Task, target: Seat, args: string[]): Promise<ImmediateDispatch> {
+  const priority = required(words(args, "--priority"), "--priority");
+  const boundary = required(words(args, "--mutation-boundary"), "--mutation-boundary");
+  const threads = await import("./threads");
+  if (!threads.hasNativeQueue(target)) throw new Error(`Assignee ${target.address} has no native queue; immediate assignment needs a native Flow inbox.`);
+  const thread = await quietly(() => threads.startThread(root, [
+    "--with", `${task.coordinator},${target.address}`, "--subject", `Immediate assignment ${projectName}/${id}`, "--task", `${projectName}/${id}`,
+  ]));
+  const body = [
+    `Immediate assignment: ${projectName}/${id}`, `Priority: ${priority}`, `Mutation boundary: ${boundary}`,
+    `Acknowledge (typed, not prose): atdd-flow task acknowledge ${projectName} ${id} --dispatch <this message id> --by ${target.address}`,
+    `Start: atdd-flow task start ${projectName} ${id} --by ${target.address}`,
+  ].join("\n");
+  const message = await quietly(() => threads.post(root, thread, ["--from", task.coordinator, "--to", target.address, "--label", "dispatch", "--expects-result", "--body", body]));
+  return { thread, message, priority, mutation_boundary: boundary, assignee: target.address, status: "dispatched" };
+}
+
+/** Binds an acknowledgement to the exact stored dispatch and assignee; it never changes task status. */
+export async function acknowledge(root: string, projectName: string, id: string, args: string[]) {
+  const task = await readTask(root, projectName, taskId(id));
+  const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
+  const dispatch = required(words(args, "--dispatch"), "--dispatch");
+  const stored = task.immediate_dispatch;
+  if (!stored) throw new Error(`Task ${id} has no immediate dispatch.`);
+  if (dispatch !== stored.message) throw new Error(`${dispatch} is not the dispatch for task ${id}.`);
+  if (actor !== stored.assignee || actor !== task.assignee) throw new Error(`Only ${stored.assignee} may acknowledge task ${id}.`);
+  if (terminal(task)) throw new Error(`Task ${id} is already ${task.status}.`);
+  if (!stored.acknowledgement) {
+    stored.acknowledgement = { dispatch, by: actor, acknowledged_at: now() };
+    await writeTask(root, projectName, id, task);
+  }
+  console.log(`${id}  acknowledged  ${actor}`);
+}
+
+function missingSignal(task: Task): "missing_acknowledgement" | "missing_start" | undefined {
+  const stored = task.immediate_dispatch;
+  if (!stored || terminal(task)) return undefined;
+  if (!stored.acknowledgement) return "missing_acknowledgement";
+  return task.status === "todo" ? "missing_start" : undefined;
+}
+
+/** On demand and bounded: posts at most one alert per missing state, then returns the stored one. */
+export async function observeAssignment(root: string, projectName: string, id: string, args: string[]) {
+  const task = await readTask(root, projectName, taskId(id));
+  const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
+  if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may observe the assignment of task ${id}.`);
+  const stored = task.immediate_dispatch;
+  if (!stored) throw new Error(`Task ${id} has no immediate dispatch.`);
+  const state = missingSignal(task);
+  if (!state) { console.log(`${id}  no missing signal`); return; }
+  const existing = stored.alerts?.[state];
+  if (existing) { console.log(`${id}  ${state}  ${existing.message}`); return; }
+  const action = state === "missing_acknowledgement"
+    ? `atdd-flow task acknowledge ${projectName} ${id} --dispatch ${stored.message} --by ${stored.assignee}`
+    : `atdd-flow task start ${projectName} ${id} --by ${stored.assignee}`;
+  const { post } = await import("./threads");
+  const message = await quietly(() => post(root, stored.thread, ["--from", task.coordinator, "--to", stored.assignee, "--label", state, "--expects-result", "--body",
+    `Alert ${state} for ${projectName}/${id} (dispatch ${stored.message}). Run: ${action}`]));
+  stored.alerts = { ...stored.alerts, [state]: { key: `${stored.message}/${state}`, message, observed_at: now() } };
   await writeTask(root, projectName, id, task);
-  console.log(`${id}  assigned  ${assignee}`);
+  console.log(`${id}  ${state}  ${message}`);
 }
 
 type TransferAuthorization = {
@@ -512,6 +611,7 @@ async function transition(root: string, projectName: string, id: string, next: T
     await assertAcceptedBehavioralReview(root, projectName, id, task);
     if (retire) await retireAssignee(root, projectName, id, task);
   }
+  recordDispatchStart(task, next, actor);
   task.status = next;
   if (next !== "in_progress") { delete task.blocker; delete task.deferred; }
   await writeTask(root, projectName, id, task);

package/src/threads.ts

@@ -234,9 +234,13 @@ export async function publishNativeMail(root: string, address: string, _segment:
   });
 }
 
+/** The single predicate for a durable native inbox queue: an explicit native wake or a Pi-designated seat. */
+export const hasNativeQueue = (target: { agent?: string; runtime?: { wake?: string } }) =>
+  target.runtime?.wake === "native" || target.agent === "pi";
+
 async function prepareNativeMail(root: string, address: string, message: Message, threadId: string) {
   const target = await seat(root, address);
-  if (target.runtime?.wake !== "native" && target.agent !== "pi") return;
+  if (!hasNativeQueue(target)) return;
   const segment = await enqueueNativeMail(root, address, { thread: threadId, message: message.id, created_at: message.created_at });
   return { address, segment };
 }
@@ -244,7 +248,7 @@ async function prepareNativeMail(root: string, address: string, message: Message
 async function inject(root: string, address: string, message: Message, threadId: string, queued = false) {
   const target = await seat(root, address);
   const runtime = target.runtime;
-  if (runtime?.wake === "native" || target.agent === "pi") {
+  if (hasNativeQueue(target)) {
     if (!queued) await enqueueNativeMail(root, address, { thread: threadId, message: message.id, created_at: message.created_at, published: true });
     if (!runtime || runtime.wake === "native") return;
   }