@afokapu/atdd-flow 0.3.77 → 0.3.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.77",
+  "version": "0.3.79",
   "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/handover.ts

@@ -739,7 +739,8 @@ export async function requestHandoverReplacement(root: string, address: string,
   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.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;
+    () => (dependencies.command ?? runOutput)(herdr(intent.target.herdr_session, "agent", "list")),
+    { paneList: () => (dependencies.command ?? runOutput)(herdr(intent.target.herdr_session, "pane", "list")), authorizationHash: authorization.hash, at: () => dependencies.at?.() ?? now() }) : 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

@@ -24,21 +24,26 @@ export type StaleMainRecovery = {
   prior_receipt: { path: string; sha256: string; archive: string };
   /** 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. */
+  /** Absent only for a pane-gone relocation, whose source is proven absent rather than live. */
+  live_source?: LiveSourceProof;
+  /** Present only for a relocated main: an operator manual rebinding receipt, or a launcher receipt whose retired pane is gone. */
   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 } };
+/** Relocation mode of a launcher-generated receipt whose canonical pane and exact Pi are both absent from Herdr. */
+export const PANE_GONE_MODE = "launcher-receipt-pane-gone";
+
+/** The retired placement named by the receipt; lineage only, never a live source. A pane-gone relocation also records the global absence proof. */
+export type Relocation = { mode: string; retired: { herdr_session: string; pane: string }; absence?: { authorization_hash: string; verified_at: 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 Recorded = { session: string; sessionPath: string; locator: { session: string; pane: string } };
 type Source = HandoverReplacementRequest["source"];
 type Target = HandoverReplacementRequest["target"];
 type PriorReceipt = {
@@ -74,6 +79,7 @@ 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"], relocation?: Relocation) {
+  if (relocation?.mode === PANE_GONE_MODE) return launchReceiptProvesCanonical(receipt, seat, { ...canonical, ...relocation.retired });
   return relocation ? manualReceiptProvesCanonical(receipt, seat, canonical, relocation) : launchReceiptProvesCanonical(receipt, seat, canonical);
 }
 
@@ -201,14 +207,24 @@ function targetMatches(request: HandoverReplacementRequest, canonical: StaleMain
 
 /** 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
+  return [MANUAL_REBINDING_MODE, PANE_GONE_MODE].includes(relocation.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) {
+/** A pane-gone relocation has no live source: its absence proof must be bound to this request's authorization. */
+function absenceMatches(request: HandoverReplacementRequest, relocation: Relocation) {
+  return relocation.absence?.authorization_hash === request.authorization.hash && Boolean(relocation.absence.verified_at);
+}
+
+function snapshotMatches(request: HandoverReplacementRequest, live: LiveSourceProof | undefined, relocation?: Relocation) {
+  if (relocation?.mode === PANE_GONE_MODE) return !live && absenceMatches(request, relocation);
+  return live !== undefined && liveSnapshotMatches(request, live, relocation);
+}
+
+function liveSnapshotMatches(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 === placement.herdr_session
@@ -218,7 +234,7 @@ function snapshotMatches(request: HandoverReplacementRequest, live: LiveSourcePr
 function exitMatches(recovery: StaleMainRecovery) {
   const exited = recovery.prior_request?.source_exited, replaced = recovery.prior_request?.live_source_exited;
   return (!exited || (sourceIsCanonical({ ...exited }, recovery.canonical_source) && Boolean(exited.verified_at)))
-    && (!replaced || (!sameSource(replaced, recovery.live_source) && !sourceIsCanonical({ ...replaced }, recovery.canonical_source) && Boolean(replaced.verified_at)));
+    && (!replaced || (!(recovery.live_source && sameSource(replaced, recovery.live_source)) && !sourceIsCanonical({ ...replaced }, recovery.canonical_source) && Boolean(replaced.verified_at)));
 }
 
 function archiveNamed(prior: { sha256: string; archive: string } | undefined) {
@@ -236,7 +252,8 @@ 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; 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> {
+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>, gone: PaneGoneObservation): Promise<StaleMainRecovery> {
+  if (intent.relocation?.mode === PANE_GONE_MODE) return buildPaneGoneStaleMainRecovery(root, seat, intent, intent.relocation, active, { agentList, ...gone });
   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);
@@ -366,7 +383,72 @@ export function assertRelocatedAgentList(raw: string, source: Pick<Source, "pi_s
   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. */
+/** A target pane that differs from the source pane is a relocation only for a manual binding or an exact pane-gone launcher receipt; 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;
+  if (target.pane === source.pane) return undefined;
+  return await isManualRebindingReceipt(record) ? assertRelocatedBinding(record, source, target, activeFile) : assertPaneGoneBinding(record, source, target, activeFile);
+}
+
+async function readLauncherReceipt(path: string) {
+  try {
+    const receipt = yaml.parse<PriorReceipt>(await readFile(path, "utf8"));
+    return receipt.schema === "atdd-flow/pi-runtime-launch-receipt/v1" ? receipt : undefined;
+  } catch { return undefined; }
+}
+
+/** The launcher receipt names this seat's exact recorded Pi at a pane other than the seat's current locator. */
+function receiptNamesRetiredPane(receipt: PriorReceipt, record: Seat, recorded: Recorded) {
+  return receipt.seat === record.address && receipt.pi_session === recorded.session && receipt.pi_session_path === recorded.sessionPath
+    && Boolean(receipt.herdr_session && receipt.pane) && (receipt.herdr_session !== recorded.locator.session || receipt.pane !== recorded.locator.pane);
+}
+
+/** The request moves the exact recorded Pi from the receipt's retired pane to the seat's current locator. */
+function requestMovesRetiredPi(receipt: PriorReceipt, source: Source, target: Target, recorded: Recorded) {
+  return source.pi_session === recorded.session && source.pi_session_path === recorded.sessionPath
+    && source.herdr_session === receipt.herdr_session && source.pane === receipt.pane
+    && target.herdr_session === recorded.locator.session && target.pane === recorded.locator.pane;
+}
+
+/** A launcher-generated receipt whose retired canonical pane is the request source while the request target is the seat's current locator; otherwise undefined, so the ordinary released-source-pane guard refuses. */
+async function assertPaneGoneBinding(record: Seat, source: Source, target: Target, activeFile: string): Promise<Relocation | undefined> {
+  const runtime = record.runtime, locator = runtime?.addresses.herdr;
+  if (!runtime?.launch_receipt || typeof locator === "string" || !locator) return undefined;
+  const receipt = await readLauncherReceipt(runtime.launch_receipt);
+  if (!receipt || !runtime.pi_session || !runtime.pi_session_path) return undefined;
+  const recorded = { session: runtime.pi_session, sessionPath: runtime.pi_session_path, locator };
+  if (!receiptNamesRetiredPane(receipt, record, recorded) || !requestMovesRetiredPi(receipt, source, target, recorded) || !await priorRequestIsRetiredLineage(activeFile, receipt)) return undefined;
+  return { mode: PANE_GONE_MODE, retired: { herdr_session: receipt.herdr_session!, pane: receipt.pane! } };
+}
+
+/** Pane ids from one complete global Herdr pane list. */
+function listedPaneIds(raw: string) {
+  const parsed = JSON.parse(raw) as { result?: { panes?: unknown }; panes?: unknown };
+  const panes = (parsed.result ?? parsed).panes;
+  const ids = Array.isArray(panes) ? panes.map((pane) => (pane as { pane_id?: unknown } | null)?.pane_id) : undefined;
+  if (!ids || ids.some((id) => typeof id !== "string")) throw new Error("Pane-gone recovery requires complete global Herdr pane-list evidence.");
+  return ids as string[];
+}
+
+const piSessionId = (path: string) => 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];
+
+/** Pane-gone recovery requires the retired pane and the exact recorded Pi to be absent from one complete global pane list and agent list. */
+export function assertPaneGone(agentsRaw: string, panesRaw: string, source: Pick<Source, "pi_session" | "pi_session_path">, retired: { pane: string }) {
+  if (listedPaneIds(panesRaw).includes(retired.pane)) throw new Error("The retired canonical pane is still listed by Herdr.");
+  const agents = listedPiAgents(agentsRaw, "Pane-gone recovery");
+  if (agents.some((agent) => agent.pane === retired.pane)) throw new Error("A Pi is live at the retired canonical pane.");
+  if (agents.some(({ path }) => path === resolve(source.pi_session_path) || piSessionId(path) === source.pi_session)) throw new Error("The exact recorded Pi is still a live Pi agent.");
+}
+
+/** Herdr pane-list evidence plus the authorization and clock that bind the absence proof to one request. */
+export type PaneGoneObservation = { paneList: () => Promise<string>; authorizationHash: string; at: () => string };
+
+async function buildPaneGoneStaleMainRecovery(root: string, seat: string, intent: { record: Seat; source: Source; target: Target }, pane: Relocation, active: { file: string }, observe: { agentList: () => Promise<string> } & PaneGoneObservation): 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 };
+  try { assertPaneGone(await observe.agentList(), await observe.paneList(), intent.source, pane.retired); }
+  catch (error) { throw new Error(`Path-A replacement target must be the exact released source pane; pane-gone recovery refused: ${(error as Error).message}`); }
+  const verified_at = observe.at(), relocation: Relocation = { ...pane, absence: { authorization_hash: observe.authorizationHash, verified_at } };
+  const prior_request = await archivePriorRequest(root, seat, active.file, () => false, { canonical, source: intent.source, verifiedAt: verified_at, assertAbsent: async () => {} });
+  const prior_receipt = await archiveStaleReceipt(root, seat, canonical, relocation);
+  return { canonical_source: canonical, prior_receipt, ...(prior_request ? { prior_request } : {}), relocation };
 }

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 = {