@afokapu/atdd-flow 0.3.20 → 0.3.22

package/README.md

@@ -120,6 +120,8 @@ atdd-flow task done resolver-os runtime-rollout --by coordinator@resolver-os
 
 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.
 
+For topology normalization, transfer an active task through the narrow durable command, never by editing its YAML: `atdd-flow task transfer <project> <task-id> --to <main-or-named-coordinator> --reason <text> --by <current-coordinator>`; `main@project` must additionally pass `--authorization <operator-message-id>`. That message must be an immutable `task-transfer-authorization/v1` exact tuple for the project, task, current/target coordinator, reason, and target branch/head; only `operator@desk` creates it through `atdd-flow post --task-transfer-authorization <json>`. The command appends immutable source/target/reason/exact-head/effective-time provenance, keeps earlier phase/review/message evidence intact, derives the new governed base from the accepted target head, and never moves a seat, branch, runtime, or worktree. Same-target, duplicate, nested, mismatched, unauthorized, and manually rewritten transitions fail closed.
+
 ## Communicate and hand over
 
 Threads are the durable inbox/outbox. Workflow persists a message before a best-effort host notification, so a closed pane, rate limit, or missed prompt cannot lose it.

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

@@ -77,6 +77,17 @@ content:
     coordinator lineage, mismatched base/worktree placement, and ambiguous placement rather than
     guessing. Legacy seat, task, and thread identities remain readable without rename or mutation.
 
+    Transfer active task accountability only through `atdd-flow task transfer`, never by rewriting
+    task YAML. The transition retains append-only from/to/reason/exact-head/effective-time provenance
+    and leaves prior task, phase, review, and message evidence attributable. The current coordinator
+    may transfer, while main requires one applicable immutable `operator@desk`
+    `task-transfer-authorization/v1` message. Its project, task, from, to, reason, and exact target
+    branch/head must match the requested transfer before mutation; only `operator@desk` may create
+    that typed authorization. Accept only main or a valid named integration coordinator; atomically
+    derive the new governed base from that accepted target head. Reject same-target, duplicate, nested, mismatched,
+    unauthorized, or manually rewritten transfers. A transfer never moves or changes any seat, branch,
+    runtime binding, worktree, dirty state, or evidence artifact.
+
     Drivers hand work back to their named coordinator for integration and validation. The named
     coordinator hands a reviewed integration candidate to main; only main completes normal
     integration-to-main gates and publication. No automatic merge executor, branch graph, daemon, or

package/package.json

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

package/src/adoption-authorizations.ts

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { now, required, words, yaml } from "./core";
+
+export const authorizationSchema = "atdd-flow/exact-session-adoption-authorization/v1" as const;
+export type ExactSessionAdoptionAuthorization = {
+  schema: typeof authorizationSchema;
+  id: string;
+  issued_by: "operator@desk";
+  created_at: string;
+  seat: string;
+  pi_session: string;
+  pi_session_path: string;
+  source: { herdr_session: string; pane: string };
+  target: { herdr_session: string; pane: string; cwd: string };
+};
+
+const validId = (value: string) => /^A-[A-Za-z0-9_-]+$/.test(value);
+const nonEmpty = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
+const path = (root: string, id: string) => join(root, ".atdd-flow", "exact-session-adoption-authorizations", `${id}.yaml`);
+const hashPath = (root: string, id: string) => join(root, ".atdd-flow", "exact-session-adoption-authorizations", `${id}.sha256`);
+const digest = (content: string) => createHash("sha256").update(content).digest("hex");
+
+function tuple(record: ExactSessionAdoptionAuthorization) {
+  return record.schema === authorizationSchema && validId(record.id) && record.issued_by === "operator@desk" && nonEmpty(record.created_at)
+    && nonEmpty(record.seat) && nonEmpty(record.pi_session) && nonEmpty(record.pi_session_path)
+    && nonEmpty(record.source?.herdr_session) && nonEmpty(record.source?.pane)
+    && nonEmpty(record.target?.herdr_session) && nonEmpty(record.target?.pane) && nonEmpty(record.target?.cwd);
+}
+
+export async function createExactSessionAdoptionAuthorization(root: string, id: string, args: string[]) {
+  if (!validId(id)) throw new Error("Exact-session adoption authorization id must use A- followed by letters, numbers, underscores, or hyphens.");
+  if (words(args, "--by") !== "operator@desk") throw new Error("Only operator@desk may issue an exact-session adoption authorization.");
+  const record: ExactSessionAdoptionAuthorization = {
+    schema: authorizationSchema, id, issued_by: "operator@desk", created_at: now(),
+    seat: required(words(args, "--seat"), "--seat"), pi_session: required(words(args, "--pi-session"), "--pi-session"),
+    pi_session_path: resolve(required(words(args, "--pi-session-path"), "--pi-session-path")),
+    source: { herdr_session: required(words(args, "--source-herdr-session"), "--source-herdr-session"), pane: required(words(args, "--source-pane"), "--source-pane") },
+    target: { herdr_session: required(words(args, "--target-herdr-session"), "--target-herdr-session"), pane: required(words(args, "--target-pane"), "--target-pane"), cwd: resolve(required(words(args, "--target-cwd"), "--target-cwd")) },
+  };
+  const file = path(root, id);
+  const content = yaml.print(record);
+  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);
+}
+
+function same(record: ExactSessionAdoptionAuthorization, expected: Omit<ExactSessionAdoptionAuthorization, "schema" | "id" | "issued_by" | "created_at">) {
+  return record.seat === expected.seat && record.pi_session === expected.pi_session && record.pi_session_path === expected.pi_session_path
+    && record.source.herdr_session === expected.source.herdr_session && record.source.pane === expected.source.pane
+    && record.target.herdr_session === expected.target.herdr_session && record.target.pane === expected.target.pane && record.target.cwd === expected.target.cwd;
+}
+
+async function used(root: string, id: string) {
+  const folder = join(root, ".atdd-flow", "runtime-launch");
+  try {
+    const files = await readdir(folder);
+    for (const file of files.filter((entry) => entry.endsWith(".yaml"))) {
+      try {
+        const value = yaml.parse<Record<string, unknown>>(await readFile(join(folder, file), "utf8"));
+        const authorization = value.relocation && typeof value.relocation === "object" ? (value.relocation as Record<string, unknown>).authorization : undefined;
+        if (authorization && typeof authorization === "object" && (authorization as Record<string, unknown>).id === id) return true;
+      } catch { /* Malformed receipts never authorize reuse. */ }
+    }
+  } catch { /* No previous receipt means unused. */ }
+  return false;
+}
+
+/** Resolve only a create-only operator record whose complete tuple matches before runtime projection. */
+export async function resolveExactSessionAdoptionAuthorization(root: string, id: string, expected: Omit<ExactSessionAdoptionAuthorization, "schema" | "id" | "issued_by" | "created_at">) {
+  if (!validId(id)) throw new Error("Exact-session adoption requires an immutable operator authorization record id.");
+  let raw: string;
+  try { raw = await readFile(path(root, id), "utf8"); }
+  catch { throw new Error("Exact-session adoption requires an existing immutable operator authorization record."); }
+  let record: ExactSessionAdoptionAuthorization;
+  try { record = yaml.parse<ExactSessionAdoptionAuthorization>(raw); }
+  catch { throw new Error("Exact-session adoption requires a well-formed immutable operator authorization record."); }
+  let storedHash: string;
+  try { storedHash = (await readFile(hashPath(root, id), "utf8")).trim(); }
+  catch { throw new Error("Exact-session adoption requires a create-only immutable operator authorization record."); }
+  if (!/^[a-f0-9]{64}$/i.test(storedHash) || storedHash !== digest(raw)) throw new Error("Exact-session adoption requires an immutable operator authorization record.");
+  if (!tuple(record) || record.id !== id || !same(record, expected)) throw new Error("Exact-session adoption requires an immutable operator authorization record bound to the exact adoption tuple.");
+  if (await used(root, id)) throw new Error("Exact-session adoption authorization record was already used.");
+  return { id, hash: storedHash };
+}

package/src/cli.ts

@@ -2,6 +2,7 @@
 
 import { basename, resolve } from "node:path";
 import { init, initProject, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
+import { createExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
 import { required, values, words, yaml } from "./core";
@@ -26,13 +27,15 @@ 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 runtime launch <address> [--pane <asserted-herdr-pane>] --herdr-session <session> [--resume] [--dry-run]
+  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>
   atdd-flow multiplexer status|apply herdr [--session <name>]
   atdd-flow describe <address> --purpose <one-line responsibility>
   atdd-flow checkpoint <address> --summary <text> --next <text> [--status active|standby|blocked|complete|unverified]
   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 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>]
   atdd-flow task start|review|return <project> <task-id> --by <address>
@@ -52,7 +55,7 @@ Usage:
   atdd-flow thread add <thread-id> <address>
   atdd-flow thread open <thread-id>
   atdd-flow message read <message-id>
-  atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--label <non-sensitive-text>] [--expects-result]
+  atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--label <non-sensitive-text>] [--expects-result] [--task-transfer-authorization <json>]
   atdd-flow receipt <thread-id> <message-id> --from <address> [--body <text>] [--label <non-sensitive-text>]
   atdd-flow result <thread-id> <message-id> --from <address> --body <text> [--label <non-sensitive-text>]
   atdd-flow status [project <project>|task <project> <task-id>|seat <address>|thread <thread-id>] [--all]
@@ -91,13 +94,14 @@ 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] === "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));
         if (plan.dryRun) console.log(yaml.print(plan));
         else console.log(`Launched Pi runtime for ${required(rest[2], "address")} with ${plan.candidate}.`);
         return;
       }
-      throw new Error("Use `pi extension-path` or `pi runtime launch <address> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run]`.");
+      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>]`.");
     },
     application: async () => {
       if (rest[0] === "use") return useApplication(root, required(rest[1], "address"), required(rest[2], "application"));
@@ -110,6 +114,7 @@ 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 === "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);
       if (subcommand === "start") return tasks.start(root, required(projectName, "project"), required(taskId, "task id"), tail);
@@ -123,7 +128,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|amend|import|start|prove|handoff|respond|review|return|done|block|unblock|list|open`.");
+      throw new Error("Use `atdd-flow task add|assign|transfer|amend|import|start|prove|handoff|respond|review|return|done|block|unblock|list|open`.");
     },
     cleanup: async () => {
       const [subcommand, projectName, taskId] = rest;

package/src/seats.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
-import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { basename, dirname, join, resolve } from "node:path";
 import { discoverAddress, discoverHerdrLocator, notify } from "./adapters";
 import {
@@ -11,6 +12,7 @@ import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } fr
 import { seatTasks } from "./tasks";
 import { projectHerdrSeat } from "./multiplexer";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
+import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 
 const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
@@ -291,6 +293,15 @@ function startCommand(request: HerdrRequest) {
 }
 function receiptPath(root: string, piSession: string) { return join(root, ".atdd-flow", "runtime-launch", `${encodeURIComponent(piSession)}-${crypto.randomUUID().slice(0, 8)}.yaml`); }
 
+async function immutableSessionBackup(root: string, sessionPath: string, piSession: string) {
+  const content = await readFile(sessionPath);
+  const sha256 = createHash("sha256").update(content).digest("hex");
+  const backup = join(root, ".atdd-flow", "runtime-launch", "backups", `${encodeURIComponent(piSession)}-${crypto.randomUUID()}.jsonl`);
+  await mkdir(dirname(backup), { recursive: true });
+  await writeFile(backup, content, { flag: "wx" });
+  return { backup, sha256 };
+}
+
 /** A deliberately narrow Pi+Herdr launch using only installed CLI commands on an existing shell pane. */
 export async function launchPiRuntime(root: string, address: string, args: string[], dependencies: PiRuntimeLaunchDependencies = {}) {
   const resolved = await canonicalAddress(root, address);
@@ -300,15 +311,41 @@ export async function launchPiRuntime(root: string, address: string, args: strin
   const herdrSession = required(words(args, "--herdr-session"), "--herdr-session");
   const resume = args.includes("--resume");
   const dryRun = args.includes("--dry-run");
-  const allowed = ["--herdr-session", herdrSession, "--resume", "--dry-run", ...(requestedPane ? ["--pane", requestedPane] : [])];
-  if (args.some((argument) => !allowed.includes(argument))) throw new Error("Use `pi runtime launch <seat> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run]`.");
+  const adoptedSessionPath = words(args, "--adopt-session");
+  const sourceHerdrSession = words(args, "--source-herdr-session");
+  const sourcePane = words(args, "--source-pane");
+  const authorization = words(args, "--authorization");
+  const adoptionFields = [adoptedSessionPath, sourceHerdrSession, sourcePane, authorization];
+  const adopting = adoptionFields.some(Boolean);
+  const allowed = ["--herdr-session", herdrSession, "--resume", "--dry-run", ...(requestedPane ? ["--pane", requestedPane] : []),
+    ...(adoptedSessionPath ? ["--adopt-session", adoptedSessionPath] : []), ...(sourceHerdrSession ? ["--source-herdr-session", sourceHerdrSession] : []),
+    ...(sourcePane ? ["--source-pane", sourcePane] : []), ...(authorization ? ["--authorization", authorization] : [])];
+  if (args.some((argument) => !allowed.includes(argument))) throw new Error("Use `pi runtime launch <seat> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <owner-reference>]`.");
+  if (adopting && (resume || !adoptionFields.every(Boolean))) throw new Error("Exact-session adoption requires --adopt-session, --source-herdr-session, --source-pane, and --authorization without --resume.");
+  const existingHerdr = record.runtime?.addresses.herdr;
+  const existingPane = typeof existingHerdr === "object" ? existingHerdr.pane : undefined;
+  const existingSession = typeof existingHerdr === "object" ? existingHerdr.session : undefined;
+  if (resume && ((requestedPane && requestedPane !== existingPane) || herdrSession !== existingSession)) {
+    throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
+  }
   const active = await launchEligibleTasks(root, record);
   if (!active.length) throw new Error(`${resolved} has no launch-eligible task; refusing runtime launch.`);
   const selection = await chooseLaunchModel(root, config, record, required(await modelPortfolio(root), "models.yaml for Pi runtime launch"), dependencies.select);
   const model = resolveModelCommand(config, selection.candidate);
   if (basename(model.agent) !== "pi") throw new Error(`Pi runtime launch requires a Pi candidate, received ${selection.candidate.id}.`);
   const command = dependencies.command ?? runOutput;
+  const piSession = adopting ? sessionIdFromPiJsonlPath(required(adoptedSessionPath, "an exact adopted Pi session path")) : resume ? record.runtime?.pi_session : (dependencies.sessionId ?? (() => crypto.randomUUID()))();
+  if (!piSession) throw new Error("Resume requires the exact Pi session stored on the seat.");
+  const canonicalAdoptedSessionPath = adopting ? resolve(required(adoptedSessionPath, "an exact adopted Pi session path")) : undefined;
+  const authorizationRecord = adopting
+    ? await resolveExactSessionAdoptionAuthorization(root, required(authorization, "an immutable operator authorization record"), {
+      seat: resolved, pi_session: piSession, pi_session_path: required(canonicalAdoptedSessionPath, "an exact adopted Pi session path"),
+      source: { herdr_session: required(sourceHerdrSession, "a source Herdr session"), pane: required(sourcePane, "a source pane") },
+      target: { herdr_session: herdrSession, pane: required(requestedPane, "--pane for exact-session adoption"), cwd: resolve(record.worktree) },
+    })
+    : undefined;
   const projection = await projectHerdrSeat(root, resolved, herdrSession, command);
+  if (resume && projection.pane !== existingPane) throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
   if (requestedPane && requestedPane !== projection.pane) throw new Error("The asserted --pane does not match the seat-scoped Herdr projection.");
   const pane = projection.pane;
   const [paneRaw, processRaw] = await Promise.all([command(herdr(herdrSession, "pane", "get", pane)), command(herdr(herdrSession, "pane", "process-info", "--pane", pane))]);
@@ -316,8 +353,6 @@ export async function launchPiRuntime(root: string, address: string, args: strin
   const currentProcess = processReport(JSON.parse(processRaw));
   if (currentPane.pane !== pane) throw new Error("Herdr reported a different pane; refusing runtime launch.");
   if (currentPane.agent || piProcess(currentProcess.processes)) throw new Error(resume ? "Resume requires the prior Pi to have exited and been released." : "New launch requires an available shell pane.");
-  const piSession = resume ? record.runtime?.pi_session : (dependencies.sessionId ?? (() => crypto.randomUUID()))();
-  if (!piSession) throw new Error("Resume requires the exact Pi session stored on the seat.");
   if (resume) {
     const prior = record.runtime?.launch_receipt;
     if (!prior) throw new Error("Resume requires an existing Flow launch receipt.");
@@ -326,10 +361,24 @@ export async function launchPiRuntime(root: string, address: string, args: strin
       if (receipt.seat !== resolved || receipt.pi_session !== piSession || receipt.pi_session_path !== record.runtime?.pi_session_path || receipt.herdr_session !== herdrSession || receipt.pane !== pane) throw new Error("receipt does not match seat/session/path/pane");
     } catch (error) { throw new Error(`Resume requires a valid Flow launch receipt: ${(error as Error).message}`); }
   }
-  const priorSessionPath = resume ? required(record.runtime?.pi_session_path, "a previously verified Pi session path") : undefined;
-  const request: HerdrRequest = { session: herdrSession, pane, seat: resolved, root, piSession, ...(priorSessionPath ? { sessionPath: priorSessionPath } : {}), resume, args: [...model.args, "--extension", piExtensionPath()] };
+  const priorSessionPath = adopting ? required(canonicalAdoptedSessionPath, "an exact adopted Pi session path") : resume ? required(record.runtime?.pi_session_path, "a previously verified Pi session path") : undefined;
+  if (adopting) {
+    const [sourcePaneRaw, sourceProcessRaw] = await Promise.all([
+      command(herdr(required(sourceHerdrSession, "a source Herdr session"), "pane", "get", required(sourcePane, "a source pane"))),
+      command(herdr(required(sourceHerdrSession, "a source Herdr session"), "pane", "process-info", "--pane", required(sourcePane, "a source pane"))),
+    ]);
+    const sourceReport = paneReport(JSON.parse(sourcePaneRaw));
+    const sourceProcess = processReport(JSON.parse(sourceProcessRaw));
+    if (sourceReport.pane !== sourcePane || sourceReport.agent || piProcess(sourceProcess.processes)) {
+      throw new Error("Exact-session adoption requires proof that the source Pi has exited and been released.");
+    }
+  }
+  const request: HerdrRequest = { session: herdrSession, pane, seat: resolved, root, piSession, ...(priorSessionPath ? { sessionPath: priorSessionPath } : {}), resume: resume || adopting, args: [...model.args, "--extension", piExtensionPath()] };
   const plan = { candidate: selection.candidate.id, piSession, pane, herdrSession, receipt: receiptPath(root, piSession), command: startCommand(request), ...(dryRun ? { dryRun: true } : {}) };
   if (dryRun) return plan;
+  // The source snapshot is a pre-migration prerequisite: never start a target
+  // Pi when its immutable recovery copy cannot be created.
+  const relocation = adopting ? await immutableSessionBackup(root, required(canonicalAdoptedSessionPath, "an exact adopted Pi session path"), piSession) : undefined;
   await command(herdr(herdrSession, "pane", "run", pane, `export ATDD_WORKFLOW_ROOT=${shellQuote(root)} ATDD_WORKFLOW_SEAT=${shellQuote(resolved)} ATDD_FLOW_PI_SESSION=${shellQuote(piSession)} ATDD_FLOW_HERDR_SESSION=${shellQuote(herdrSession)} ATDD_FLOW_HERDR_PANE=${shellQuote(pane)}`));
   await command(startCommand(request));
   const [agentRaw, verifiedPaneRaw, verifiedProcessRaw] = await Promise.all([command(herdr(herdrSession, "agent", "get", agentName(resolved))), command(herdr(herdrSession, "pane", "get", pane)), command(herdr(herdrSession, "pane", "process-info", "--pane", pane))]);
@@ -340,13 +389,15 @@ export async function launchPiRuntime(root: string, address: string, args: strin
   if (!sessionPath) throw new Error("Herdr did not report an exact Pi session path; seat binding was not changed.");
   const reportedId = sessionIdFromPiJsonlPath(sessionPath);
   if (reportedId !== piSession) throw new Error("Herdr did not verify the exact requested Pi session ID; seat binding was not changed.");
-  if (resume && sessionPath !== record.runtime?.pi_session_path) throw new Error("Herdr did not verify the exact requested Pi session path; seat binding was not changed.");
+  if ((resume || adopting) && sessionPath !== priorSessionPath) throw new Error("Herdr did not verify the exact requested Pi session path; seat binding was not changed.");
   if (agent.name !== agentName(resolved) || agent.pane !== pane || ![agent.status, verifiedPane.status].every((status) => status === "idle" || status === "done") || verifiedPane.pane !== pane || !verifiedProcess) throw new Error("Herdr did not verify the replacement Pi process; seat binding was not changed.");
   const receipt = plan.receipt;
   const receiptRecord = {
     schema: "atdd-flow/pi-runtime-launch-receipt/v1", seat: resolved, tasks: active.map((entry) => entry.id), candidate: selection.candidate.id,
     selection: selection.fallback ? { result: "fallback", reason: selection.fallback } : { result: "selected", confidence: selection.selection.confidence, ...(selection.selection.available && selection.selection.model ? { model: selection.selection.model } : {}) },
-    pi_session: piSession, pi_session_path: sessionPath, herdr_session: herdrSession, pane, created_at: dependencies.at?.() ?? now(),
+    pi_session: piSession, pi_session_path: sessionPath, herdr_session: herdrSession, pane,
+    ...(relocation ? { relocation: { source_herdr_session: sourceHerdrSession, source_pane: sourcePane, authorization: authorizationRecord, backup: relocation.backup, backup_sha256: relocation.sha256 } } : {}),
+    created_at: dependencies.at?.() ?? now(),
   };
   await mkdir(dirname(receipt), { recursive: true });
   await writeFile(receipt, yaml.print(receiptRecord), { encoding: "utf8", flag: "wx" });

package/src/tasks.ts

@@ -12,6 +12,16 @@ export type HandoffState = "executing" | "awaiting_coordinator" | "awaiting_assi
 export type TaskHandoff = { state: HandoffState; evidence: string; updated_at: string };
 export type DoneWhen = { text: string; proof?: string };
 export type GovernedBase = { coordinator: string; branch: string; commit: string };
+/** An append-only accountability decision; prior coordinator evidence remains untouched. */
+export type CoordinatorTransfer = {
+  from: string;
+  to: string;
+  reason: string;
+  /** Required when main executes the transfer; references an operator@desk message. */
+  authorization?: string;
+  exact_head: { branch: string; commit: string };
+  effective_at: string;
+};
 export type Task = {
   schema: "atdd-workflow/task/v1";
   title: string;
@@ -28,6 +38,8 @@ export type Task = {
   handoff?: TaskHandoff;
   /** Exact named-coordinator or main head from which an assigned driver is governed. */
   governed_base?: GovernedBase;
+  /** Absent on legacy tasks; later entries never rewrite earlier coordinator evidence. */
+  coordinator_transfers?: CoordinatorTransfer[];
   done_when: DoneWhen[];
 };
 
@@ -40,9 +52,29 @@ const transitions: Record<TaskStatus, TaskStatus[]> = {
   done: [],
 };
 
+function assertCoordinatorIntegrity(task: Task, id: string) {
+  const transfers = task.coordinator_transfers;
+  if (transfers && !Array.isArray(transfers)) throw new Error(`Task ${id} has invalid immutable transfer provenance.`);
+  const latest = transfers?.at(-1);
+  if (latest) {
+    if (!latest.from || !latest.to || !latest.reason || !latest.effective_at || !latest.exact_head?.branch || !latest.exact_head.commit) {
+      throw new Error(`Task ${id} has invalid immutable transfer provenance.`);
+    }
+    if (task.coordinator !== latest.to || !task.governed_base
+      || task.governed_base.coordinator !== latest.to
+      || task.governed_base.branch !== latest.exact_head.branch
+      || task.governed_base.commit !== latest.exact_head.commit) {
+      throw new Error(`Task ${id} coordinator is not backed by immutable transfer provenance.`);
+    }
+  } else if (task.governed_base && task.governed_base.coordinator !== task.coordinator) {
+    throw new Error(`Task ${id} coordinator is not backed by immutable transfer provenance.`);
+  }
+}
+
 async function readTask(root: string, projectName: string, id: string) {
   const record = await readYaml<Task>(paths(root).taskFile(projectName, id));
   if (record.schema !== "atdd-workflow/task/v1") throw new Error(`Unsupported task schema: ${id}`);
+  assertCoordinatorIntegrity(record, id);
   return record;
 }
 
@@ -182,6 +214,92 @@ export async function assign(root: string, projectName: string, id: string, args
   console.log(`${id}  assigned  ${assignee}`);
 }
 
+type TransferAuthorization = {
+  schema: "atdd-workflow/task-transfer-authorization/v1";
+  project: string;
+  task: string;
+  from: string;
+  to: string;
+  reason: string;
+  exact_head: { branch: string; commit: string };
+};
+
+async function operatorAuthorization(root: string, reference: string, main: string, expected: TransferAuthorization) {
+  type AuthorizationMessage = { schema?: string; id?: string; from?: string; to?: "all" | string[]; authorization?: TransferAuthorization };
+  type AuthorizationThread = { schema?: string; participants?: string[] };
+  const folders = await readdir(paths(root).threads, { withFileTypes: true });
+  const matches = (await Promise.all(folders.filter((entry) => entry.isDirectory() && entry.name.startsWith("T-"))
+    .map(async (entry) => {
+      try {
+        const [thread, message] = await Promise.all([
+          readYaml<AuthorizationThread>(paths(root).threadFile(entry.name)),
+          readYaml<AuthorizationMessage>(paths(root).message(entry.name, reference)),
+        ]);
+        return { thread, message };
+      } catch { return undefined; }
+    }))).filter((entry): entry is NonNullable<typeof entry> =>
+      entry?.thread.schema === "atdd-workflow/thread/v1" && entry.thread.participants?.includes(main) === true
+      && entry.message.schema === "atdd-workflow/message/v1" && entry.message.id === reference);
+  if (matches.length !== 1 || matches[0]?.message.from !== "operator@desk") {
+    throw new Error(`Authorization ${reference} is not an owner-authorized topology plan.`);
+  }
+  if (matches[0].message.to !== "all" && !matches[0].message.to?.includes(main)) {
+    throw new Error(`Authorization ${reference} is not applicable to ${main}.`);
+  }
+  const authorization = matches[0].message.authorization;
+  if (!authorization || authorization.schema !== expected.schema
+    || authorization.project !== expected.project || authorization.task !== expected.task
+    || authorization.from !== expected.from || authorization.to !== expected.to
+    || authorization.reason !== expected.reason
+    || authorization.exact_head?.branch !== expected.exact_head.branch
+    || authorization.exact_head.commit !== expected.exact_head.commit) {
+    throw new Error(`Authorization ${reference} is not an exact transfer authorization.`);
+  }
+}
+
+/**
+ * Changes only the current task accountability projection. The record is
+ * append-only and validates the target's existing topology; it never creates,
+ * moves, cleans, or binds a seat/worktree.
+ */
+export async function transfer(root: string, projectName: string, id: string, args: string[]) {
+  const task = await readTask(root, projectName, taskId(id));
+  const config = await project(root, projectName);
+  const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
+  const target = await canonicalAddress(root, required(words(args, "--to"), "--to"));
+  const main = `main@${config.project}`;
+  if (target === task.coordinator) throw new Error(`Task ${id} is already accountable to ${target}.`);
+  if (actor !== main && actor !== task.coordinator) throw new Error(`Only ${main} or the current coordinator may transfer task ${id}.`);
+
+  // governedBase confirms main/named-coordinator identity, exact branch head,
+  // and the driver's descendant relationship before accountability changes.
+  const base = await governedBase(root, projectName, target, task.assignee);
+  if (!base) throw new Error(`Task ${id} needs an assigned driver and governed repository before transfer.`);
+  const authorization = actor === main ? required(words(args, "--authorization"), "an owner-authorized topology plan") : undefined;
+  if (authorization) await operatorAuthorization(root, authorization, main, {
+    schema: "atdd-workflow/task-transfer-authorization/v1",
+    project: config.project,
+    task: id,
+    from: task.coordinator,
+    to: target,
+    reason: required(words(args, "--reason"), "--reason"),
+    exact_head: { branch: base.branch, commit: base.commit },
+  });
+  const transfer: CoordinatorTransfer = {
+    from: task.coordinator,
+    to: target,
+    reason: required(words(args, "--reason"), "--reason"),
+    ...(authorization ? { authorization } : {}),
+    exact_head: { branch: base.branch, commit: base.commit },
+    effective_at: now(),
+  };
+  task.coordinator = target;
+  task.governed_base = base;
+  task.coordinator_transfers = [...(task.coordinator_transfers ?? []), transfer];
+  await writeTask(root, projectName, taskId(id), task);
+  console.log(`${id}  coordinator transferred  ${transfer.from} -> ${transfer.to}`);
+}
+
 export async function amend(root: string, projectName: string, id: string, args: string[]) {
   const task = await readTask(root, projectName, taskId(id));
   const title = words(args, "--title");

package/src/threads.ts

@@ -8,6 +8,15 @@ import {
 
 export type Thread = { schema: string; id: string; subject: string; participants: string[]; state: "open" | "closed"; summary?: string; task?: string };
 export type Kind = "message" | "receipt" | "result";
+export type TransferAuthorization = {
+  schema: "atdd-workflow/task-transfer-authorization/v1";
+  project: string;
+  task: string;
+  from: string;
+  to: string;
+  reason: string;
+  exact_head: { branch: string; commit: string };
+};
 export type Message = {
   schema: string;
   id: string;
@@ -18,6 +27,8 @@ export type Message = {
   expects_result?: boolean;
   created_at: string;
   body: string;
+  /** Immutable owner authorization for one exact coordinator-transfer tuple. */
+  authorization?: TransferAuthorization;
 };
 
 async function thread(root: string, threadId: string) {
@@ -212,6 +223,21 @@ async function inject(root: string, address: string, message: Message, threadId:
   catch (error) { console.warn(`Notification for ${address} was not delivered: ${(error as Error).message}`); }
 }
 
+function transferAuthorization(args: string[], from: string) {
+  const encoded = words(args, "--task-transfer-authorization");
+  if (!encoded) return undefined;
+  if (from !== "operator@desk") throw new Error("Only operator@desk may create a task transfer authorization.");
+  let authorization: unknown;
+  try { authorization = JSON.parse(encoded); }
+  catch { throw new Error("--task-transfer-authorization must be valid JSON."); }
+  const value = authorization as Partial<TransferAuthorization>;
+  if (!value || value.schema !== "atdd-workflow/task-transfer-authorization/v1"
+    || ![value.project, value.task, value.from, value.to, value.reason, value.exact_head?.branch, value.exact_head?.commit].every((entry) => typeof entry === "string" && entry.length)) {
+    throw new Error("--task-transfer-authorization must contain one exact task-transfer-authorization/v1 tuple.");
+  }
+  return value as TransferAuthorization;
+}
+
 async function post(root: string, threadId: string, args: string[], overrides: Partial<Message> = {}) {
   const record = await thread(root, threadId);
   const from = await canonicalAddress(root, required(overrides.from ?? words(args, "--from"), "--from"));
@@ -221,11 +247,13 @@ async function post(root: string, threadId: string, args: string[], overrides: P
   if (recipients.some((address) => !record.participants.includes(address))) throw new Error("Recipients must be thread participants.");
   await assertRoute(root, from, recipients.filter((address) => address !== from));
   const kind = overrides.kind ?? "message";
+  const authorization = overrides.authorization ?? transferAuthorization(args, from);
   // Labels are an explicit, non-sensitive operator hint; message bodies never enter durable IDs.
   const label = words(args, "--label") ?? kind;
   const message: Message = {
     schema: "atdd-workflow/message/v1", id: id("M", label), from, to: toValue === "all" ? "all" : recipients,
     kind,
+    ...(authorization ? { authorization } : {}),
     ...(overrides.in_reply_to ? { in_reply_to: overrides.in_reply_to } : {}),
     ...(overrides.expects_result || has(args, "--expects-result") ? { expects_result: true } : {}),
     created_at: now(), body: required(overrides.body ?? words(args, "--body"), "--body"),