@afokapu/atdd-flow 0.3.76 → 0.3.78

package/package.json

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

package/src/cli.ts

@@ -67,6 +67,7 @@ Usage:
   atdd-flow task respond <project> <task-id> --by <coordinator> --outcome <accept|return> --phase <plan|red|green|refactor>
   atdd-flow task block <project> <task-id> --by <address> --reason <text>
   atdd-flow task supersede|reject <project> <task-id> --by <coordinator-address> --reason <text>
+  atdd-flow task supersede <project> <task-id> --by main@<project> --reason <text> --authorization <operator-message-id>
   atdd-flow task defer <project> <task-id> --by <coordinator-address> --reason <text> --owner <address> --trigger <text> --review-at <ISO-8601>
   atdd-flow task unblock <project> <task-id> --by <coordinator-address>
   atdd-flow task list <project> [--coordinator <address>] [--assignee <address>]
@@ -83,7 +84,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] [--task-transfer-authorization <json>]
+  atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--label <non-sensitive-text>] [--expects-result] [--task-transfer-authorization <json>] [--task-supersede-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]

package/src/core.ts

@@ -75,6 +75,8 @@ export type Runtime = {
   pi_session_path?: string;
   /** Immutable, non-secret receipt for that selected launch. */
   launch_receipt?: string;
+  /** Operator-recorded binding mode for an adopted runtime whose receipt is not launcher-generated. */
+  binding_mode?: string;
 };
 
 export function runtimeAddress(application: string, value: RuntimeAddress, legacyHerdrSession?: string) {

package/src/exact-adoption-recovery.ts

@@ -10,7 +10,7 @@ import { basename, join, resolve } from "node:path";
 import { type Seat, paths, readYaml, yaml } from "./core";
 import type { HandoverReplacementRequest } from "./handover";
 import { readRuntimeState } from "./runtime-state";
-import { archivedReceiptMatches, recoveryEvidenceMatches } from "./stale-main-recovery";
+import { archivedReceiptMatches, backupIsTranscriptPrefix, recoveryEvidenceMatches } from "./stale-main-recovery";
 import type { Task } from "./tasks";
 
 type ReplacementLaunchReceipt = {
@@ -188,12 +188,8 @@ function exactAdoptionReceiptMatches(receipt: ReplacementLaunchReceipt, activeBy
 }
 
 /** Prove the immutable recovery copy is the prefix of the adopted source JSONL. */
-async function exactBackupMatches(receipt: ReplacementLaunchReceipt, request: HandoverReplacementRequest) {
-  const relocation = receipt.relocation!;
-  const [backup, source] = await Promise.all([readFile(relocation.backup!), readFile(request.source.pi_session_path)]);
-  return digest(backup) === relocation.backup_sha256
-    && source.length >= backup.length
-    && source.subarray(0, backup.length).equals(backup);
+function exactBackupMatches(receipt: ReplacementLaunchReceipt, request: HandoverReplacementRequest) {
+  return backupIsTranscriptPrefix({ path: receipt.relocation!.backup, sha256: receipt.relocation!.backup_sha256 }, request.source.pi_session_path);
 }
 
 /** A live same-identity adoption is fresh only after its receipt and start. */

package/src/handover.ts

@@ -14,7 +14,7 @@ import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizati
 import { exactFailedAdoptionProof } from "./exact-adoption-recovery";
 import { isExactOperatorSeat, operatorActivation, operatorRelaunchSection } from "./operator-launch";
 import { readRuntimeState } from "./runtime-state";
-import { type StaleMainRecovery, buildStaleMainRecovery, replaceActiveRequest, staleRecoveryMatches } from "./stale-main-recovery";
+import { type StaleMainRecovery, buildStaleMainRecovery, listedPiAgents, relocationFor, replaceActiveRequest, staleRecoveryMatches } from "./stale-main-recovery";
 
 export type Handover = {
   schema: "atdd-workflow/handover/v1";
@@ -314,20 +314,9 @@ function assertSinglePiWriter(raw: string) {
 type PiSource = Pick<HandoverReplacementRequest["source"], "pi_session" | "pi_session_path">;
 
 function assertCanonicalSourceNotLive(raw: string, canonical: PiSource) {
-  const value = JSON.parse(raw), agents = result(value)?.agents;
-  if (!Array.isArray(agents)) throw new Error("Consumed Path-A replacement requires complete global Herdr agent-list evidence.");
-  for (const entry of agents) {
-    const agent = object(entry);
-    if (!agent) throw new Error("Consumed Path-A replacement requires complete global Herdr agent-list evidence.");
-    if (text(agent.agent) !== "pi") continue;
-    const session = object(agent.agent_session);
-    const sessionPath = session?.kind === "path" ? text(session.value) : undefined;
-    if (!sessionPath) throw new Error("Consumed Path-A replacement requires complete global Herdr agent-list evidence.");
-    const sessionId = basename(sessionPath).match(/_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i)?.[1];
-    if (resolve(sessionPath) === resolve(canonical.pi_session_path) || sessionId === canonical.pi_session) {
-      throw new Error("Consumed Path-A replacement prior canonical source is still a live Pi agent.");
-    }
-  }
+  const live = listedPiAgents(raw, "Consumed Path-A replacement").some(({ path }) => path === resolve(canonical.pi_session_path)
+    || basename(path).match(/_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i)?.[1] === canonical.pi_session);
+  if (live) throw new Error("Consumed Path-A replacement prior canonical source is still a live Pi agent.");
 }
 
 async function verifyLegacySource(source: HandoverReplacementRequest["source"], target: HandoverReplacementRequest["target"], authorizationHash: string, dependencies: HandoverReplacementDependencies, canonical?: PiSource) {
@@ -387,7 +376,7 @@ function replacementTarget(args: string[], record: Seat, source: HandoverReplace
   const cwd = resolve(nonEmpty(words(args, "--target-cwd"), "--target-cwd"));
   if (cwd !== resolve(record.worktree)) throw new Error("Path-A replacement target CWD must be the exact canonical main worktree.");
   const target = { herdr_session: nonEmpty(words(args, "--herdr-session"), "--herdr-session"), pane: nonEmpty(words(args, "--target-pane"), "--target-pane"), cwd };
-  if (target.herdr_session !== source.herdr_session || target.pane !== source.pane) throw new Error("Path-A replacement target must be the exact released source pane.");
+  if (target.herdr_session !== source.herdr_session) throw new Error("Path-A replacement target must be the exact released source pane.");
   return target;
 }
 
@@ -402,9 +391,12 @@ async function prepareReplacement(root: string, resolved: string, args: string[]
   const handover = await currentReplacementHandover(root, resolved, args);
   const task = nonEmpty(words(args, "--takeover-task"), "--takeover-task");
   const { record } = await exactMainTakeoverTask(root, resolved, task);
-  const source = replacementSource(args), target = replacementTarget(args, record, source);
+  const source = replacementSource(args), file = handoverReplacementPath(root, resolved);
+  const target = replacementTarget(args, record, source);
+  const relocation = recover ? await relocationFor(record, source, target, file) : undefined;
+  if (!relocation && target.pane !== source.pane) throw new Error("Path-A replacement target must be the exact released source pane.");
   if (!supersede && !recover) assertReplacementSource(record, source, legacy);
-  return { legacy, supersede, recover, handover, task, record, source, target };
+  return { legacy, supersede, recover, handover, task, record, source, target, relocation };
 }
 
 function replacementRequest(resolved: string, intent: Awaited<ReturnType<typeof prepareReplacement>>, authorization: { id: string; hash: string }, legacySource: HandoverReplacementRequest["legacy_source"], dependencies: HandoverReplacementDependencies): HandoverReplacementRequest {
@@ -745,7 +737,9 @@ export async function requestHandoverReplacement(root: string, address: string,
     source: { herdr_session: intent.source.herdr_session, pane: intent.source.pane }, target: intent.target,
   });
   const legacySource = intent.legacy ? await verifyLegacySource(intent.source, intent.target, authorization.hash, dependencies) : undefined;
-  const recovery = intent.recover ? await buildStaleMainRecovery(root, resolved, intent, { file, isLive: (prior) => replacementMatchesRuntime(intent.record.runtime, prior) }, (canonical, once) => verifyLegacySource(intent.source, intent.target, authorization.hash, once(dependencies), canonical)) : undefined;
+  const recovery = intent.recover ? await buildStaleMainRecovery(root, resolved, intent, { file, isLive: (prior) => replacementMatchesRuntime(intent.record.runtime, prior) },
+    (canonical, once) => verifyLegacySource(intent.relocation ? { ...intent.source, ...intent.target } : intent.source, intent.target, authorization.hash, once(dependencies), canonical),
+    () => (dependencies.command ?? runOutput)(herdr(intent.target.herdr_session, "agent", "list"))) : undefined;
   const request = { ...replacementRequest(resolved, intent, authorization, legacySource, dependencies), ...(recovery ? { stale_main_recovery: recovery } : {}) };
   await (recovery?.prior_request ? replaceActiveRequest : dependencies.publish ?? publishCreateOnly)(file, yaml.print(request));
   console.log(`Recorded Path-A replacement request for ${resolved}.`);

package/src/pi-runtime-launch.ts

@@ -99,7 +99,7 @@ async function isExactNamedCoordinator(root: string, record: Seat, address: stri
   return Boolean(worktree && await hasUniqueCoordinatorPlacement(root, record, worktree));
 }
 
-async function launchEligibleTasks(root: string, record: Seat, address: string) {
+export async function launchEligibleTasks(root: string, record: Seat, address: string) {
   const coordinator = await isExactNamedCoordinator(root, record, address);
   const operator = await isExactOperatorSeat(root, record, address);
   const tasks = await seatTasks(root, record.project, record.address);

package/src/stale-main-recovery.ts

@@ -4,12 +4,13 @@
 // - test:atdd-flow:stale-main-recovery-resumed
 // - test:atdd-flow:stale-main-source-exited-path-a
 // - test:atdd-flow:stale-main-s1-exited-recovery
+// - test:atdd-flow:relocated-receipt-stale-main-recovery
 // Runtime: bun
 // Purpose: Evidence rules for operator-authorized stale-main Pi binding recovery.
 
 import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { type Runtime, type Seat, runOutput, yaml } from "./core";
 import type { HandoverReplacementRequest, LiveSourceProof } from "./handover";
 
@@ -24,15 +25,28 @@ export type StaleMainRecovery = {
   /** A superseded active request, preserved by hash; `live_source_exited` proves an active recovery request's own live source Pi was absent from every live Pi agent when a newer source replaced it. */
   prior_request?: { path: string; sha256: string; archive: string; source_exited?: SourceExited; live_source_exited?: SourceExited };
   live_source: LiveSourceProof;
+  /** Present only for a relocated main: the recorded receipt is an operator manual rebinding receipt for a retired placement. */
+  relocation?: Relocation;
 };
 
+export const MANUAL_REBINDING_SCHEMA = "atdd-flow/manual-pi-runtime-rebinding-receipt/v1";
+export const MANUAL_REBINDING_MODE = "operator-authorized-manual-in-place-adoption";
+
+/** The retired placement named by the manual rebinding receipt; lineage only, never a live source. */
+export type Relocation = { mode: string; retired: { herdr_session: string; pane: string } };
+
 /** Proof that a runtime-matching prior request's recorded source Pi was absent from every live Pi agent when it was replaced. */
 export type SourceExited = { pi_session: string; pi_session_path: string; herdr_session: string; pane: string; verified_at: string };
 
 type Run = (argv: string[]) => Promise<string>;
 type Source = HandoverReplacementRequest["source"];
 type Target = HandoverReplacementRequest["target"];
-type PriorReceipt = { schema?: string; seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string };
+type PriorReceipt = {
+  schema?: string; seat?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string;
+  mode?: string; authorized_by?: string; authorization?: string;
+  target?: { cwd?: string; pi_session?: string; pi_session_path?: string; herdr_session?: string; pane?: string };
+  backup?: { path?: string; bytes?: number; sha256?: string };
+};
 
 const sha256 = (content: string | Uint8Array) => createHash("sha256").update(content).digest("hex");
 
@@ -59,12 +73,22 @@ export function staleCanonicalSource(record: Seat, source: Source, target: Targe
 }
 
 /** The archived receipt must name exactly the recorded canonical seat, session, path and placement. */
-export function receiptProvesCanonical(receipt: PriorReceipt, seat: string, canonical: StaleMainRecovery["canonical_source"]) {
+export function receiptProvesCanonical(receipt: PriorReceipt, seat: string, canonical: StaleMainRecovery["canonical_source"], relocation?: Relocation) {
+  return relocation ? manualReceiptProvesCanonical(receipt, seat, canonical, relocation) : launchReceiptProvesCanonical(receipt, seat, canonical);
+}
+
+function launchReceiptProvesCanonical(receipt: PriorReceipt, seat: string, canonical: StaleMainRecovery["canonical_source"]) {
   return receipt.schema === "atdd-flow/pi-runtime-launch-receipt/v1" && receipt.seat === seat
     && receipt.pi_session === canonical.pi_session && receipt.pi_session_path === canonical.pi_session_path
     && receipt.herdr_session === canonical.herdr_session && receipt.pane === canonical.pane;
 }
 
+function manualReceiptProvesCanonical(receipt: PriorReceipt, seat: string, canonical: StaleMainRecovery["canonical_source"], relocation: Relocation) {
+  return receipt.schema === MANUAL_REBINDING_SCHEMA && receipt.seat === seat && receipt.mode === relocation.mode
+    && receipt.pi_session === canonical.pi_session && receipt.pi_session_path === canonical.pi_session_path
+    && receipt.herdr_session === relocation.retired.herdr_session && receipt.pane === relocation.retired.pane;
+}
+
 const archivePath = (root: string, folder: string, seat: string, hash: string) => join(root, ".atdd-flow", folder, encodeURIComponent(seat), `${hash}.yaml`);
 
 async function publishOrVerify(file: string, bytes: string) {
@@ -75,11 +99,11 @@ async function publishOrVerify(file: string, bytes: string) {
 }
 
 /** Preserve the stale receipt by content hash, create-only; an existing copy must be identical. */
-export async function archiveStaleReceipt(root: string, seat: string, canonical: StaleMainRecovery["canonical_source"]): Promise<StaleMainRecovery["prior_receipt"]> {
+export async function archiveStaleReceipt(root: string, seat: string, canonical: StaleMainRecovery["canonical_source"], relocation?: Relocation): Promise<StaleMainRecovery["prior_receipt"]> {
   let bytes: string;
   try { bytes = await readFile(canonical.launch_receipt, "utf8"); }
   catch { throw new Error("Stale main recovery requires its immutable recorded launch receipt."); }
-  if (!receiptProvesCanonical(yaml.parse<PriorReceipt>(bytes), seat, canonical)) {
+  if (!receiptProvesCanonical(yaml.parse<PriorReceipt>(bytes), seat, canonical, relocation)) {
     throw new Error("Stale main recovery recorded launch receipt does not prove the recorded canonical runtime.");
   }
   return { path: canonical.launch_receipt, ...await archiveBytes(root, "stale-main-receipt-archive", seat, bytes) };
@@ -153,7 +177,7 @@ export async function archivedReceiptMatches(request: HandoverReplacementRequest
   try {
     const bytes = await readFile(recovery.prior_receipt.archive, "utf8");
     const priorRequest = !recovery.prior_request || await archiveIntact(recovery.prior_request);
-    return priorRequest && await archiveIntact(recovery.prior_receipt) && receiptProvesCanonical(yaml.parse<PriorReceipt>(bytes), request.seat, recovery.canonical_source);
+    return priorRequest && await archiveIntact(recovery.prior_receipt) && receiptProvesCanonical(yaml.parse<PriorReceipt>(bytes), request.seat, recovery.canonical_source, recovery.relocation);
   } catch { return false; }
 }
 
@@ -169,15 +193,26 @@ function sessionMatches(runtime: Runtime | undefined, recovery: StaleMainRecover
     && runtime.launch_receipt === canonical.launch_receipt && recovery.prior_receipt.path === runtime.launch_receipt;
 }
 
-function targetMatches(request: HandoverReplacementRequest, canonical: StaleMainRecovery["canonical_source"]) {
+function targetMatches(request: HandoverReplacementRequest, canonical: StaleMainRecovery["canonical_source"], relocation?: Relocation) {
+  if (relocation) return relocatedTargetMatches(request, canonical, relocation);
   return canonical.cwd === request.target.cwd && canonical.herdr_session === request.target.herdr_session
     && canonical.pane === request.target.pane && canonical.pi_session !== request.source.pi_session;
 }
 
-function snapshotMatches(request: HandoverReplacementRequest, live: LiveSourceProof) {
+/** A relocated request names the exact recorded Pi at the retired pane, and moves to the current pane that Herdr observed it on. */
+function relocatedTargetMatches(request: HandoverReplacementRequest, canonical: StaleMainRecovery["canonical_source"], relocation: Relocation) {
+  return relocation.mode === MANUAL_REBINDING_MODE
+    && canonical.cwd === request.target.cwd && canonical.herdr_session === request.target.herdr_session && canonical.pane === request.target.pane
+    && request.source.pi_session === canonical.pi_session && request.source.pi_session_path === canonical.pi_session_path
+    && request.source.herdr_session === relocation.retired.herdr_session && request.source.pane === relocation.retired.pane
+    && (relocation.retired.herdr_session !== canonical.herdr_session || relocation.retired.pane !== canonical.pane);
+}
+
+function snapshotMatches(request: HandoverReplacementRequest, live: LiveSourceProof, relocation?: Relocation) {
+  const placement = relocation ? request.target : request.source;
   return live.authorization_hash === request.authorization.hash && live.pi_session === request.source.pi_session
-    && live.pi_session_path === request.source.pi_session_path && live.herdr_session === request.source.herdr_session
-    && live.pane === request.source.pane && live.cwd === request.target.cwd && Boolean(live.agent && live.verified_at);
+    && live.pi_session_path === request.source.pi_session_path && live.herdr_session === placement.herdr_session
+    && live.pane === placement.pane && live.cwd === request.target.cwd && Boolean(live.agent && live.verified_at);
 }
 
 function exitMatches(recovery: StaleMainRecovery) {
@@ -192,7 +227,7 @@ function archiveNamed(prior: { sha256: string; archive: string } | undefined) {
 
 /** Request, canonical source and live-source snapshot must describe one exact target tuple. */
 export function recoveryEvidenceMatches(request: HandoverReplacementRequest, recovery: StaleMainRecovery) {
-  return targetMatches(request, recovery.canonical_source) && snapshotMatches(request, recovery.live_source) && archiveNamed(recovery.prior_receipt) && archiveNamed(recovery.prior_request) && exitMatches(recovery);
+  return targetMatches(request, recovery.canonical_source, recovery.relocation) && snapshotMatches(request, recovery.live_source, recovery.relocation) && archiveNamed(recovery.prior_receipt) && archiveNamed(recovery.prior_request) && exitMatches(recovery);
 }
 
 /** The recorded runtime must still be the exact stale canonical source named by the recovery request. */
@@ -201,9 +236,137 @@ export function staleRecoveryMatches(runtime: Runtime | undefined, request: Hand
 }
 
 /** Build the recovery record: verify the live source (injected), then archive the stale receipt and any stale active request by hash. */
-export async function buildStaleMainRecovery(root: string, seat: string, intent: { record: Seat; source: Source; target: Target }, active: { file: string; isLive: (request: HandoverReplacementRequest) => boolean }, verify: (absent: Pick<Source, "pi_session" | "pi_session_path">, once: ReturnType<typeof agentListOnce>) => Promise<LiveSourceProof>): Promise<StaleMainRecovery> {
+export async function buildStaleMainRecovery(root: string, seat: string, intent: { record: Seat; source: Source; target: Target; relocation?: Relocation }, active: { file: string; isLive: (request: HandoverReplacementRequest) => boolean }, verify: (absent: Pick<Source, "pi_session" | "pi_session_path">, once: ReturnType<typeof agentListOnce>) => Promise<LiveSourceProof>, agentList: () => Promise<string>): Promise<StaleMainRecovery> {
+  if (intent.relocation) return buildRelocatedStaleMainRecovery(root, seat, intent, intent.relocation, active, { verify: () => verify(intent.source, agentListOnce()), agentList });
   const canonical = staleCanonicalSource(intent.record, intent.source, intent.target);
   const once = agentListOnce(), live_source = await verify(canonical, once);
   const prior_request = await archivePriorRequest(root, seat, active.file, active.isLive, { canonical, source: intent.source, verifiedAt: live_source.verified_at, assertAbsent: async (source) => { await verify(source, once); } });
   return { canonical_source: canonical, prior_receipt: await archiveStaleReceipt(root, seat, canonical), ...(prior_request ? { prior_request } : {}), live_source };
 }
+
+
+const refuse = (reason: string) => new Error(`Stale main relocation receipt recovery refused: ${reason}.`);
+
+/** True when the seat records a manual binding_mode or its launch receipt is a manual rebinding receipt, rather than a launcher receipt. */
+export async function isManualRebindingReceipt(record: Seat) {
+  const path = record.runtime?.launch_receipt;
+  if (!path) return false;
+  if (record.runtime?.binding_mode !== undefined) return true;
+  try { return yaml.parse<PriorReceipt>(await readFile(path, "utf8")).schema === MANUAL_REBINDING_SCHEMA; } catch { return false; }
+}
+
+/** A backup file must hash to its recorded digest (and size, when recorded) and be the exact byte prefix of the adopted session transcript. */
+export async function backupIsTranscriptPrefix(backup: { path?: string; sha256?: string; bytes?: number }, transcriptPath: string) {
+  try {
+    const [saved, transcript] = await Promise.all([readFile(backup.path!), readFile(transcriptPath)]);
+    return sha256(saved) === backup.sha256 && (backup.bytes === undefined || backup.bytes === saved.length)
+      && transcript.length >= saved.length && transcript.subarray(0, saved.length).equals(saved);
+  } catch { return false; }
+}
+
+/** An existing stale active request must retain exactly the retired placement of the recorded Pi. */
+async function priorRequestIsRetiredLineage(file: string, receipt: PriorReceipt) {
+  let bytes: string;
+  try { bytes = await readFile(file, "utf8"); } catch { return true; }
+  try {
+    const { source, target } = yaml.parse<HandoverReplacementRequest>(bytes);
+    return source.pi_session === receipt.pi_session && source.pi_session_path === receipt.pi_session_path
+      && [source, target].every((placement) => placement.herdr_session === receipt.herdr_session && placement.pane === receipt.pane);
+  } catch { return false; }
+}
+
+type Check = [boolean, string];
+const firstFailure = (checks: Check[]) => checks.find(([ok]) => !ok)?.[1];
+
+/** The recorded receipt is a complete operator-authorized manual rebinding receipt whose mode equals the seat binding_mode. */
+function authorityFailure(receipt: PriorReceipt, record: Seat) {
+  return firstFailure([
+    [receipt.schema === MANUAL_REBINDING_SCHEMA, "the recorded receipt is not a manual rebinding receipt"],
+    [receipt.seat === record.address, "the receipt names another seat"],
+    [receipt.mode === MANUAL_REBINDING_MODE && record.runtime?.binding_mode === receipt.mode, "the receipt mode must equal the seat binding_mode"],
+    [receipt.authorized_by === "operator@desk" && Boolean(receipt.authorization), "the receipt lacks operator@desk authorization"],
+  ]);
+}
+
+/** The receipt describes the exact recorded Pi, the canonical worktree and one retired placement. */
+function identityFailure(receipt: PriorReceipt, record: Seat, session: string, sessionPath: string) {
+  const placement = receipt.target;
+  return firstFailure([
+    [receipt.pi_session === session && receipt.pi_session_path === sessionPath, "the receipt does not name the exact recorded Pi session"],
+    [placement?.pi_session === session && placement.pi_session_path === sessionPath, "the receipt target does not name the exact recorded Pi session"],
+    [Boolean(placement?.cwd) && resolve(placement!.cwd!) === resolve(record.worktree), "the receipt cwd is not the canonical main worktree"],
+    [Boolean(receipt.pane) && placement?.herdr_session === receipt.herdr_session && placement.pane === receipt.pane, "the receipt placement is inconsistent"],
+  ]);
+}
+
+/** The request moves the exact recorded Pi from the retired placement to the seat's current locator. */
+function requestFailure(receipt: PriorReceipt, source: Source, target: Target, recorded: { session: string; sessionPath: string; locator: { session: string; pane: string } }) {
+  return firstFailure([
+    [source.pi_session === recorded.session && source.pi_session_path === recorded.sessionPath, "the request source is not the exact recorded Pi"],
+    [source.herdr_session === receipt.herdr_session && source.pane === receipt.pane, "the request source must be the receipt's retired placement"],
+    [target.herdr_session === recorded.locator.session && target.pane === recorded.locator.pane, "the request target must be the seat's current locator"],
+  ]);
+}
+
+/**
+ * Validate a relocated main before any authorization or Herdr evidence is consulted: the recorded receipt must be a
+ * complete operator manual rebinding receipt whose mode equals the seat binding_mode, for the exact recorded Pi, whose
+ * backup is a prefix of the adopted transcript, and whose retired placement is the request source and the stale request's
+ * placement while the request target is the seat's current locator. Returns the lineage to record.
+ */
+export async function assertRelocatedBinding(record: Seat, source: Source, target: Target, activeFile: string): Promise<Relocation> {
+  const { locator, session, sessionPath, receipt: path } = completeRuntime(record.runtime);
+  let receipt: PriorReceipt;
+  try { receipt = yaml.parse<PriorReceipt>(await readFile(path, "utf8")); } catch { throw refuse("the recorded relocation receipt is unreadable"); }
+  const failure = authorityFailure(receipt, record) ?? identityFailure(receipt, record, session, sessionPath)
+    ?? requestFailure(receipt, source, target, { session, sessionPath, locator })
+    ?? firstFailure([
+      [await backupIsTranscriptPrefix(receipt.backup ?? {}, receipt.pi_session_path!), "the receipt backup is missing, mismatched, or not a prefix of the adopted transcript"],
+      [await priorRequestIsRetiredLineage(activeFile, receipt), "the stale active request does not retain the receipt's retired placement"],
+    ]);
+  if (failure) throw refuse(failure);
+  return { mode: receipt.mode!, retired: { herdr_session: receipt.herdr_session!, pane: receipt.pane! } };
+}
+
+/** Build the relocated recovery record: the live source (injected) is the exact recorded Pi at the current locator. */
+export async function buildRelocatedStaleMainRecovery(root: string, seat: string, intent: { record: Seat; source: Source; target: Target }, relocation: Relocation, active: { file: string }, observe: { verify: () => Promise<LiveSourceProof>; agentList: () => Promise<string> }): Promise<StaleMainRecovery> {
+  const { locator, session, sessionPath, receipt } = completeRuntime(intent.record.runtime);
+  const canonical = { pi_session: session, pi_session_path: sessionPath, herdr_session: locator.session, pane: locator.pane, cwd: intent.target.cwd, launch_receipt: receipt };
+  let live_source: LiveSourceProof;
+  try {
+    live_source = await observe.verify();
+    assertRelocatedAgentList(await observe.agentList(), intent.source, intent.target, relocation.retired);
+  } catch (error) { throw refuse((error as Error).message.replace(/\.$/, "")); }
+  const prior_request = await archivePriorRequest(root, seat, active.file, () => false, { canonical, source: intent.source, verifiedAt: live_source.verified_at, assertAbsent: async () => {} });
+  const prior_receipt = await archiveStaleReceipt(root, seat, canonical, relocation);
+  return { canonical_source: canonical, prior_receipt, ...(prior_request ? { prior_request } : {}), live_source, relocation };
+}
+
+/** Pi agents from one complete global Herdr agent list, each with its pane and exact session path; `who` names the refusing operation. */
+export function listedPiAgents(raw: string, who: string) {
+  const incomplete = () => new Error(`${who} requires complete global Herdr agent-list evidence.`);
+  const parsed = JSON.parse(raw) as { result?: { agents?: unknown }; agents?: unknown };
+  const agents = (parsed.result ?? parsed).agents;
+  if (!Array.isArray(agents)) throw incomplete();
+  return agents.filter((entry) => {
+    if (!entry || typeof entry !== "object") throw incomplete();
+    return (entry as { agent?: unknown }).agent === "pi";
+  }).map((entry) => {
+    const { pane_id, agent_session } = entry as { pane_id?: string; agent_session?: { kind?: string; value?: string } };
+    if (agent_session?.kind !== "path" || !agent_session.value) throw incomplete();
+    return { pane: pane_id, path: resolve(agent_session.value) };
+  });
+}
+
+/** A relocated recovery requires the exact recorded Pi once, at the current pane, and no Pi at the retired pane. */
+export function assertRelocatedAgentList(raw: string, source: Pick<Source, "pi_session_path">, current: { pane: string }, retired: { pane: string }) {
+  const agents = listedPiAgents(raw, "Relocated recovery"), recorded = agents.filter((agent) => agent.path === resolve(source.pi_session_path));
+  if (agents.some((agent) => agent.pane === retired.pane)) throw new Error("A Pi is live at the retired relocation pane.");
+  if (recorded.some((agent) => agent.pane !== current.pane)) throw new Error("The recorded Pi is also live outside the current pane.");
+  if (recorded.length !== 1) throw new Error("The recorded Pi must be listed exactly once at the current pane.");
+}
+
+/** A target pane that differs from the source pane is a relocation only when the seat records a manual binding; otherwise undefined. */
+export async function relocationFor(record: Seat, source: Source, target: Target, activeFile: string): Promise<Relocation | undefined> {
+  return target.pane !== source.pane && await isManualRebindingReceipt(record) ? assertRelocatedBinding(record, source, target, activeFile) : undefined;
+}

package/src/task-supersede-authorization.ts

@@ -0,0 +1,113 @@
+// URN: component:flow:e022:task-supersede-authorization:backend:integration
+// Tested-By:
+// - test:atdd-flow:coordinator-stale-task-supersede-authorization
+// Runtime: bun
+// Purpose: Owner-authorized supersession of a stale coordinator task.
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicYaml, paths, readYaml, seat, yaml } from "./core";
+
+/** The one exact tuple an operator@desk message may carry to authorize `task supersede` by main. */
+export type SupersedeAuthorization = {
+  schema: "atdd-workflow/task-supersede-authorization/v1";
+  project: string;
+  task: string;
+  coordinator: string;
+  action: "supersede";
+  reason: string;
+  task_sha256: string;
+};
+
+const sha256 = (content: string) => createHash("sha256").update(content).digest("hex");
+
+/** Locate the one operator@desk message `reference`, addressed to main in a thread main joined, and return its typed payload. */
+export async function operatorAuthorizationPayload(root: string, reference: string, main: string): Promise<unknown> {
+  type Found = { schema?: string; id?: string; from?: string; to?: "all" | string[]; authorization?: unknown };
+  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<{ schema?: string; participants?: string[] }>(paths(root).threadFile(entry.name)),
+          readYaml<Found>(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.`);
+  }
+  const message = matches[0].message;
+  if (message.to !== "all" && !message.to?.includes(main)) throw new Error(`Authorization ${reference} is not applicable to ${main}.`);
+  return message.authorization;
+}
+
+/** Create-only evidence: an existing file must hold exactly the same bytes. */
+async function publishOrVerify(file: string, bytes: string) {
+  try { await writeFile(file, bytes, { encoding: "utf8", flag: "wx" }); }
+  catch (error) { if ((error as { code?: string }).code !== "EEXIST") throw error; }
+  if (await readFile(file, "utf8") !== bytes) throw new Error("Task supersede archive collides with different immutable evidence.");
+}
+
+/** Archive the pre-mutation task bytes and the authorization by task hash, create-only. */
+async function archiveEvidence(root: string, projectName: string, id: string, hash: string, taskBytes: string, evidence: Record<string, unknown>) {
+  const folder = join(root, ".atdd-flow", "task-supersede-archive", projectName, id, hash);
+  await mkdir(folder, { recursive: true });
+  await publishOrVerify(join(folder, "task.yaml"), taskBytes);
+  await publishOrVerify(join(folder, "authorization.yaml"), yaml.print(evidence));
+}
+
+/** Exact tuple equality: the same keys with the same values, and nothing more. */
+function sameTuple(actual: unknown, expected: SupersedeAuthorization) {
+  const record = actual && typeof actual === "object" ? actual as Record<string, unknown> : undefined;
+  const keys = Object.keys(expected) as (keyof SupersedeAuthorization)[];
+  return Boolean(record) && Object.keys(record!).length === keys.length && keys.every((key) => record![key] === expected[key]);
+}
+
+type Subject = { project: string; id: string; coordinator: string; reason: string; main: string; reference: string };
+
+async function assertStaleCoordinatorTask(root: string, subject: Subject) {
+  const owner = await seat(root, subject.coordinator).catch(() => undefined);
+  if (owner?.role !== "coordinator" || owner.project !== subject.project) {
+    throw new Error(`Task ${subject.id} is not owned by a named coordinator of ${subject.project}; the owner authorization applies only to coordinator tasks.`);
+  }
+  const { launchEligibleTasks } = await import("./pi-runtime-launch");
+  if ((await launchEligibleTasks(root, owner, subject.coordinator)).length) {
+    throw new Error(`${subject.coordinator} has a launch-eligible task and can supersede task ${subject.id} itself.`);
+  }
+}
+
+/**
+ * Validate every exact owner-authorization and staleness condition, then archive the evidence. Nothing is written until
+ * all checks pass; the caller records the terminal disposition afterwards. Returns the authorization reference.
+ */
+export async function authorizeSupersede(root: string, subject: Subject): Promise<string> {
+  const taskBytes = await readFile(paths(root).taskFile(subject.project, subject.id), "utf8");
+  const expected: SupersedeAuthorization = {
+    schema: "atdd-workflow/task-supersede-authorization/v1", project: subject.project, task: subject.id,
+    coordinator: subject.coordinator, action: "supersede", reason: subject.reason, task_sha256: sha256(taskBytes),
+  };
+  const authorization = await operatorAuthorizationPayload(root, subject.reference, subject.main);
+  if (!sameTuple(authorization, expected)) throw new Error(`Authorization ${subject.reference} is not an exact supersede authorization.`);
+  await assertStaleCoordinatorTask(root, subject);
+  await archiveEvidence(root, subject.project, subject.id, expected.task_sha256, taskBytes, { id: subject.reference, from: "operator@desk", authorization: expected });
+  return subject.reference;
+}
+
+/** Parse `post --task-supersede-authorization`: operator@desk only, one exact task-supersede-authorization/v1 tuple. */
+export function parseSupersedeAuthorization(encoded: string | undefined, from: string): SupersedeAuthorization | undefined {
+  if (!encoded) return undefined;
+  if (from !== "operator@desk") throw new Error("Only operator@desk may create a task supersede authorization.");
+  let value: Partial<SupersedeAuthorization> | undefined;
+  try { value = JSON.parse(encoded); } catch { throw new Error("--task-supersede-authorization must be valid JSON."); }
+  const fields = [value?.project, value?.task, value?.coordinator, value?.reason, value?.task_sha256];
+  if (value?.schema !== "atdd-workflow/task-supersede-authorization/v1" || value.action !== "supersede"
+    || !fields.every((entry) => typeof entry === "string" && entry.length) || !/^[a-f0-9]{64}$/i.test(value.task_sha256!)) {
+    throw new Error("--task-supersede-authorization must contain one exact task-supersede-authorization/v1 tuple.");
+  }
+  return value as SupersedeAuthorization;
+}

package/src/tasks.ts

@@ -3,6 +3,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import {
   type Checkpoint, type Seat, atomicYaml, canonicalAddress, exists, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
 } from "./core";
+import { operatorAuthorizationPayload } from "./task-supersede-authorization";
 import { branchCommit, currentCommit, isAncestor, vcsMode, type VcsMode } from "./vcs";
 
 export type TaskStatus = "todo" | "in_progress" | "review" | "done" | "superseded" | "rejected";
@@ -27,7 +28,7 @@ export type CoordinatorTransfer = {
   lineage_ref?: LineageRef;
   effective_at: string;
 };
-export type TerminalDisposition = { kind: "superseded" | "rejected"; by: string; at: string; reason: string };
+export type TerminalDisposition = { kind: "superseded" | "rejected"; by: string; at: string; reason: string; authorization?: 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. */
@@ -463,28 +464,7 @@ type TransferAuthorization = {
 };
 
 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;
+  const authorization = await operatorAuthorizationPayload(root, reference, main) as TransferAuthorization | undefined;
   if (!authorization || authorization.schema !== expected.schema
     || authorization.project !== expected.project || authorization.task !== expected.task
     || authorization.from !== expected.from || authorization.to !== expected.to
@@ -721,10 +701,14 @@ export async function block(root: string, projectName: string, id: string, args:
 export async function disposition(root: string, projectName: string, id: string, kind: TerminalDisposition["kind"], 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 ${kind} task ${id}.`);
+  const owner = kind === "superseded" && actor === `main@${projectName}` && actor !== task.coordinator && Boolean(words(args, "--authorization"));
+  if (actor !== task.coordinator && !owner) throw new Error(`Only ${task.coordinator} may ${kind} task ${id}.`);
   if (task.disposition || task.status === "done") throw new Error(`Task ${id} already has terminal history and cannot be ${kind}.`);
+  const reason = required(words(args, "--reason"), "--reason");
+  const reference = owner ? words(args, "--authorization") : undefined;
+  const authorization = reference ? await (await import("./task-supersede-authorization")).authorizeSupersede(root, { project: projectName, id, coordinator: task.coordinator, reason, main: actor, reference }) : undefined;
   task.status = kind;
-  task.disposition = { kind, by: actor, at: now(), reason: required(words(args, "--reason"), "--reason") };
+  task.disposition = { kind, by: actor, at: now(), reason, ...(authorization ? { authorization } : {}) };
   delete task.blocker;
   await writeTask(root, projectName, taskId(id), task);
   console.log(`${id}  ${kind}`);

package/src/threads.ts

@@ -2,6 +2,7 @@ import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { notify } from "./adapters";
 import { seatTasks, terminal } from "./tasks";
+import { type SupersedeAuthorization, parseSupersedeAuthorization } from "./task-supersede-authorization";
 import {
   atomicYaml, canonicalAddress, desk, has, id, now, paths, project, readYaml,
   required, runtimeAddress, seat, words,
@@ -29,7 +30,7 @@ export type Message = {
   created_at: string;
   body: string;
   /** Immutable owner authorization for one exact coordinator-transfer tuple. */
-  authorization?: TransferAuthorization;
+  authorization?: TransferAuthorization | SupersedeAuthorization;
 };
 
 async function thread(root: string, threadId: string) {
@@ -280,6 +281,11 @@ function transferAuthorization(args: string[], from: string) {
   return value as TransferAuthorization;
 }
 
+/** The one typed owner authorization a post may carry: a transfer tuple or a supersede tuple. */
+function typedAuthorization(args: string[], from: string) {
+  return transferAuthorization(args, from) ?? parseSupersedeAuthorization(words(args, "--task-supersede-authorization"), from);
+}
+
 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"));
@@ -289,7 +295,7 @@ 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);
+  const authorization = overrides.authorization ?? typedAuthorization(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 = {