@afokapu/atdd-flow 0.3.69 → 0.3.71

package/README.md

@@ -192,7 +192,7 @@ atdd-flow multiplexer apply herdr --session forge
 atdd-flow multiplexer apply herdr
 ```
 
-For each Desk project, apply reconciles the declared repository checkout as workspace `{project}` and gives every main/coordinator seat using it a tab and pane named `{seat.address}`. Linked coordinator worktrees and active drivers become linked-worktree workspaces named `{seat.address}`, with an equally named tab and pane. A driver is active only while it has an unblocked `in_progress` assigned task or a bound Herdr pane that still runs an agent; never-started, blocked, and finished drivers get no workspace. An explicit per-seat projection such as `pi runtime launch` still projects its own seat. A missing linked worktree is skipped and reported under `unprojected` instead of aborting the Desk. Unbound worktrees are ignored, and apply never focuses or guesses about other sessions.
+For each Desk project, apply reconciles the declared repository checkout as workspace `{project}` and gives every main, operator, and non-generic coordinator seat using it a tab and pane named `{seat.address}`. `main@{project}` is the single primary coordinator projection: when it uses the primary checkout, the preserved legacy generic `coordinator@{project}` sharing that checkout is not bulk-projected as a second tab (an explicit per-seat projection still projects it, and a project without a primary main keeps it). Linked coordinator worktrees and active drivers become linked-worktree workspaces named `{seat.address}`, with an equally named tab and pane. A driver is active only while it has an unblocked `in_progress` assigned task or a bound Herdr pane that still runs an agent; never-started, blocked, and finished drivers get no workspace. An explicit per-seat projection such as `pi runtime launch` still projects its own seat. A missing linked worktree is skipped and reported under `unprojected` instead of aborting the Desk. Unbound worktrees are ignored, and apply never focuses or guesses about other sessions.
 
 A workspace is stale when it is labelled with a Desk driver seat address, that driver is retired or inactive, and its checkout is a linked worktree of the seat's Desk project or no longer exists. `multiplexer status` reports the `stale` count and, read-only, lists each one under `stale_workspaces` with its `address`, `workspace_id`, `reason` (`retired` or `no active task`), current pane `agents` and `agent_status`, and the `outcome` apply would take (`close` or `keep`, with `because` for a kept workspace). Review that list before running apply. `multiplexer apply` closes stale workspaces only when `desk.yaml` enables it:
 

package/extensions/pi/index.ts

@@ -366,9 +366,9 @@ const sessionUnsetOrEqual = (runtime: Seat["runtime"], piSession?: string, piSes
 const recovery = (root: string, seat: string, mode: RecoveryMode, session?: string) => recoveryFor(root, seat, mode, session).catch(() => undefined);
 
 /** Desk mail is authoritative; the queue is a bounded delivery index and fs.watch only shortens latency. */
-export default function (pi: ExtensionAPI) {
-  const root = process.env.ATDD_WORKFLOW_ROOT;
-  const seat = process.env.ATDD_WORKFLOW_SEAT;
+export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = process.env) {
+  const root = environment.ATDD_WORKFLOW_ROOT;
+  const seat = environment.ATDD_WORKFLOW_SEAT;
   if (!root || !seat) return;
   let runtime: ReturnType<typeof createPiRuntime> | undefined;
   let handoverPrompted = false;
@@ -395,7 +395,7 @@ export default function (pi: ExtensionAPI) {
       const threshold = await contextHandoverThreshold(root);
       if (percent < threshold) return;
       handoverPrompted = true;
-      const bundle = await recovery(root, seat, "threshold", process.env.ATDD_FLOW_PI_SESSION);
+      const bundle = await recovery(root, seat, "threshold", environment.ATDD_FLOW_PI_SESSION);
       pi.sendMessage({
         customType: "atdd-flow-context-handover-replacement",
         content: handoverThresholdInstruction(percent, threshold, bundle),
@@ -404,7 +404,7 @@ export default function (pi: ExtensionAPI) {
     } catch { /* Desk policy is re-read on the next safe boundary. */ }
   });
   pi.on("turn_end", async (_event, ctx) => {
-    const sourceSession = process.env.ATDD_FLOW_PI_SESSION;
+    const sourceSession = environment.ATDD_FLOW_PI_SESSION;
     if (!sourceSession) return;
     try {
       const request = await readHandoverReplacement(root, seat);
@@ -419,13 +419,13 @@ export default function (pi: ExtensionAPI) {
   });
   pi.on("session_start", async (_event, ctx) => {
     const sessionManager = (ctx as { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string | undefined } }).sessionManager;
-    const liveSession = process.env.ATDD_FLOW_PI_SESSION ?? sessionManager?.getSessionId?.();
+    const liveSession = environment.ATDD_FLOW_PI_SESSION ?? sessionManager?.getSessionId?.();
     // One display-only notice per session: a refused, timed-out or failed activation must never be silent, and never wakes the agent.
     let noticed = false;
     const noticeActivation = async (transport: "active" | "inactive", error?: string) => {
       if (noticed) return;
       noticed = true;
-      const live = { pi_session: liveSession, herdr_session: process.env.ATDD_FLOW_HERDR_SESSION ?? process.env.HERDR_SESSION, pane: process.env.ATDD_FLOW_HERDR_PANE ?? process.env.HERDR_PANE_ID };
+      const live = { pi_session: liveSession, herdr_session: environment.ATDD_FLOW_HERDR_SESSION ?? environment.HERDR_SESSION, pane: environment.ATDD_FLOW_HERDR_PANE ?? environment.HERDR_PANE_ID };
       const activation = await diagnoseMailActivation(root, seat, live, transport, error).catch(() => undefined);
       if (!activation) return;
       if (runtime) await recordMailActivation(root, seat, runtime.ownerToken, activation).catch(() => undefined);
@@ -449,11 +449,11 @@ export default function (pi: ExtensionAPI) {
       });
     } });
     await runtime.start();
-    const piSession = process.env.ATDD_FLOW_PI_SESSION;
-    const herdrSession = process.env.ATDD_FLOW_HERDR_SESSION;
-    const pane = process.env.ATDD_FLOW_HERDR_PANE;
+    const piSession = environment.ATDD_FLOW_PI_SESSION;
+    const herdrSession = environment.ATDD_FLOW_HERDR_SESSION;
+    const pane = environment.ATDD_FLOW_HERDR_PANE;
     if (!piSession && !herdrSession && !pane) {
-      if (await hostAttachedActivation({ root, seat, herdrSession: process.env.HERDR_SESSION, pane: process.env.HERDR_PANE_ID, piSession: sessionManager?.getSessionId?.(), piSessionPath: sessionManager?.getSessionFile?.() })) {
+      if (await hostAttachedActivation({ root, seat, herdrSession: environment.HERDR_SESSION, pane: environment.HERDR_PANE_ID, piSession: sessionManager?.getSessionId?.(), piSessionPath: sessionManager?.getSessionFile?.() })) {
         hostActivatedAt = Date.now();
         if (await runtime.activate()) {
           const bundle = await recovery(root, seat, "start", sessionManager?.getSessionId?.());

package/package.json

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

package/src/address-book.ts

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

package/src/adoption-authorizations.ts

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

package/src/cli.ts

@@ -34,7 +34,7 @@ Usage:
   atdd-flow desk migrate
   atdd-flow project init <project>
   atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]
-  atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary] [--dry-run]
+  atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary [--retain-large-primary-file <path>:<sha256>:<bytes>:<mode> ...]] [--dry-run]
   atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>
   atdd-flow spawn <project> <role> <name> [--worktree <path>] [--branch <branch>] [--agent <legacy-executable>]
   atdd-flow bind <address> [--application <application>] --address <native-address> [--session <name>] [--agent <executable>] [--worktree <path>] [--wake host|native]
@@ -48,7 +48,7 @@ Usage:
   atdd-flow checkpoint <address> --summary <text> --next <text> [--status active|standby|blocked|complete|unverified]
   atdd-flow handover <address> --file <path> [--check]
   atdd-flow handover show <address>
-  atdd-flow handover replace <address> [--supersede-consumed] [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>
+  atdd-flow handover replace <address> [--supersede-consumed] [--recover-stale-main] [--legacy-source-bootstrap] --handover <id> --authorization <operator-record> --takeover-task <id> --source-pi-session <id> --source-pi-session-path <jsonl> --source-herdr-session <session> --source-pane <pane> --herdr-session <session> --target-pane <pane> --target-cwd <canonical-main-worktree>
   atdd-flow handover resumed <address>
   atdd-flow task add <project> <task-id> --title <text> --coordinator <address> [--assignee <address>] [--body <text>] [--source <reference>] [--depends-on <task-id,...>] --done-when <text> [--done-when <text> ...]
   atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address>
@@ -115,7 +115,7 @@ async function main() {
       if (rest[0] === "configure") return configureProject(root, required(rest[1], "project"), rest.slice(2));
       if (rest[0] === "migrate-vcs") return migrateProjectVcs(root, required(rest[1], "project"), rest.slice(2));
       if (rest[0] === "migrate-named-coordinator-topology") return migrateNamedCoordinatorTopology(root, required(rest[1], "project"), rest.slice(2));
-      throw new Error("Use `atdd-flow project init <project>`, `atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]`, `atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary] [--dry-run]`, or `atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>`.");
+      throw new Error("Use `atdd-flow project init <project>`, `atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]`, `atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary [--retain-large-primary-file <path>:<sha256>:<bytes>:<mode> ...]] [--dry-run]`, or `atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>`.");
     },
     spawn: () => spawn(root, required(rest[0], "project"), required(rest[1], "role"), required(rest[2], "name"), rest.slice(3)),
     bind: () => bind(root, required(rest[0], "address"), rest.slice(1)),

package/src/collaboration-policy.ts

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

package/src/exact-adoption-recovery.ts

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

package/src/handover.ts

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

package/src/multiplexer.ts

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

package/src/reconcile.ts

@@ -20,6 +20,7 @@ export type ReconcileOptions = {
   maxNudges?: number;
   inspect?: (locator: HerdrLocator, seat: string) => Promise<string>;
   wake?: (locator: HerdrLocator, notice: string) => Promise<void>;
+  warn?: (message: string) => void;
 };
 
 type Attempt = { schema: "atdd-flow/continuation-attempt/v1"; key: string; at: string; count: number };
@@ -46,13 +47,17 @@ async function inspectHerdr(locator: HerdrLocator, address: string) {
 /** Discover durable seat identity from the existing Desk directories.
  * No second fleet registry is created or synchronized.
  */
-async function seats(root: string): Promise<Seat[]> {
+async function seats(root: string, warn: (message: string) => void): Promise<Seat[]> {
   const found: Seat[] = [];
   for (const project of await readdir(paths(root).work, { withFileTypes: true })) {
     if (!project.isDirectory()) continue;
     for (const local of await readdir(paths(root).seats(project.name), { withFileTypes: true }).catch(() => [])) {
       if (!local.isDirectory()) continue;
-      found.push(await readYaml<Seat>(join(paths(root).seats(project.name), local.name, "seat.yaml")));
+      const folder = join(paths(root).seats(project.name), local.name);
+      // A completely empty directory (hidden entries included) is a ghost, not a seat: skip it once, never delete it.
+      // Any directory with content but no seat.yaml still fails closed in readYaml.
+      if ((await readdir(folder)).length === 0) { warn(`Skipping empty seat directory without a seat record: ${folder}`); continue; }
+      found.push(await readYaml<Seat>(join(folder, "seat.yaml")));
     }
   }
   return found;
@@ -143,7 +148,7 @@ async function reconcileSeat(root: string, owner: Seat, config: Settings): Promi
 export async function reconcileOnce(root: string, options: ReconcileOptions = {}): Promise<Reconciliation[]> {
   const config = settings(options);
   const results: Reconciliation[] = [];
-  for (const owner of await seats(root)) {
+  for (const owner of await seats(root, options.warn ?? ((message) => process.stderr.write(`warning: ${message}\n`)))) {
     const result = await reconcileSeat(root, owner, config);
     if (result) results.push(result);
   }

package/src/runtime-state.ts

@@ -1,3 +1,10 @@
+// URN: component:flow:e010:runtime-state:backend:application
+// Tested-By:
+// - test:flow:inactive-mail-notice-diagnosable
+// - test:flow:relaunched-seat-mail-activation
+// Runtime: bun
+// Purpose: Record and read advisory seat runtime state.
+
 import { mkdir, readFile, rm, stat, unlink } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";

package/src/stale-main-recovery.ts

@@ -0,0 +1,164 @@
+// URN: component:flow:e021:stale-main-recovery:backend:integration
+// Tested-By:
+// - test:atdd-flow:stale-main-binding-recovery
+// - test:atdd-flow:stale-main-recovery-resumed
+// 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 { type Runtime, type Seat, yaml } from "./core";
+import type { HandoverReplacementRequest, LiveSourceProof } from "./handover";
+
+/**
+ * Operator-authorized recovery of a main seat whose recorded Pi is stale while a
+ * newer Pi holds the exact canonical pane. The request names both sources and the
+ * stale launch receipt, archived by content hash.
+ */
+export type StaleMainRecovery = {
+  canonical_source: { pi_session: string; pi_session_path: string; herdr_session: string; pane: string; cwd: string; launch_receipt: string };
+  prior_receipt: { path: string; sha256: string; archive: string };
+  /** A superseded active request that no longer matches the recorded runtime, preserved by hash. */
+  prior_request?: { path: string; sha256: string; archive: string };
+  live_source: LiveSourceProof;
+};
+
+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 };
+
+const sha256 = (content: string | Uint8Array) => createHash("sha256").update(content).digest("hex");
+
+/** A complete recorded herdr runtime with a receipt, or no recovery is possible. */
+function completeRuntime(runtime: Runtime | undefined) {
+  const locator = runtime?.addresses.herdr;
+  if (runtime?.application !== "herdr" || typeof locator === "string" || !locator
+    || !runtime.pi_session || !runtime.pi_session_path || !runtime.launch_receipt) {
+    throw new Error("Stale main recovery requires a complete canonical main runtime receipt.");
+  }
+  return { locator, session: runtime.pi_session, sessionPath: runtime.pi_session_path, receipt: runtime.launch_receipt };
+}
+
+/** The stale source is the recorded runtime in the exact target pane; the live source must be a different Pi. */
+export function staleCanonicalSource(record: Seat, source: Source, target: Target): StaleMainRecovery["canonical_source"] {
+  const { locator, session, sessionPath, receipt } = completeRuntime(record.runtime);
+  if (locator.session !== target.herdr_session || locator.pane !== target.pane) {
+    throw new Error("Stale main recovery target must be the recorded canonical Herdr placement.");
+  }
+  if (session === source.pi_session || sessionPath === source.pi_session_path) {
+    throw new Error("Stale main recovery requires a live source that differs from the recorded runtime; use the ordinary Path-A replacement.");
+  }
+  return { pi_session: session, pi_session_path: sessionPath, herdr_session: locator.session, pane: locator.pane, cwd: target.cwd, launch_receipt: receipt };
+}
+
+/** 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"]) {
+  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;
+}
+
+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) {
+  await mkdir(dirname(file), { recursive: true });
+  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("Stale main recovery receipt archive collides with different immutable evidence.");
+}
+
+/** 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"]> {
+  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)) {
+    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) };
+}
+
+async function archiveBytes(root: string, folder: string, seat: string, bytes: string) {
+  const hash = sha256(bytes), archive = archivePath(root, folder, seat, hash);
+  await publishOrVerify(archive, bytes);
+  return { sha256: hash, archive };
+}
+
+/**
+ * An existing active request may be replaced only when it no longer matches the recorded runtime;
+ * a request that still matches is live and must go through the ordinary flow. The old bytes are archived by hash.
+ */
+async function archivePriorRequest(root: string, seat: string, file: string, isLive: (request: HandoverReplacementRequest) => boolean) {
+  let bytes: string;
+  try { bytes = await readFile(file, "utf8"); } catch { return undefined; }
+  const prior = yaml.parse<HandoverReplacementRequest>(bytes);
+  if (prior.seat !== seat || isLive(prior)) throw new Error("A live Path-A replacement request already exists; stale main recovery only replaces a request that no longer matches the recorded runtime.");
+  return { path: file, ...await archiveBytes(root, "stale-main-request-archive", seat, bytes) };
+}
+
+/** Swap the active request through a staged file so readers never observe a partial request. */
+export async function replaceActiveRequest(file: string, content: string) {
+  const staged = `${file}.${crypto.randomUUID()}.tmp`;
+  try { await writeFile(staged, content, { encoding: "utf8", flag: "wx" }); await rename(staged, file); }
+  finally { await rm(staged, { force: true }); }
+}
+
+/** An archive file must still hash to its recorded digest. */
+async function archiveIntact(prior: { sha256: string; archive: string }) {
+  try { return sha256(await readFile(prior.archive, "utf8")) === prior.sha256; } catch { return false; }
+}
+
+/** The archived receipt must prove the canonical source, and any archived prior request must be intact. */
+export async function archivedReceiptMatches(request: HandoverReplacementRequest, recovery: StaleMainRecovery) {
+  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);
+  } catch { return false; }
+}
+
+function placementMatches(runtime: Runtime | undefined, canonical: StaleMainRecovery["canonical_source"]) {
+  const locator = runtime?.addresses.herdr;
+  return runtime?.application === "herdr" && typeof locator !== "string"
+    && locator?.session === canonical.herdr_session && locator.pane === canonical.pane;
+}
+
+function sessionMatches(runtime: Runtime | undefined, recovery: StaleMainRecovery) {
+  const canonical = recovery.canonical_source;
+  return runtime?.pi_session === canonical.pi_session && runtime.pi_session_path === canonical.pi_session_path
+    && runtime.launch_receipt === canonical.launch_receipt && recovery.prior_receipt.path === runtime.launch_receipt;
+}
+
+function targetMatches(request: HandoverReplacementRequest, canonical: StaleMainRecovery["canonical_source"]) {
+  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) {
+  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);
+}
+
+function archiveNamed(prior: { sha256: string; archive: string } | undefined) {
+  return !prior || (/^[a-f0-9]{64}$/i.test(prior.sha256) && basename(prior.archive) === `${prior.sha256}.yaml`);
+}
+
+/** 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);
+}
+
+/** The recorded runtime must still be the exact stale canonical source named by the recovery request. */
+export function staleRecoveryMatches(runtime: Runtime | undefined, request: HandoverReplacementRequest, recovery: StaleMainRecovery) {
+  return placementMatches(runtime, recovery.canonical_source) && sessionMatches(runtime, recovery) && recoveryEvidenceMatches(request, recovery);
+}
+
+/** 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: (canonical: StaleMainRecovery["canonical_source"]) => Promise<LiveSourceProof>): Promise<StaleMainRecovery> {
+  const canonical = staleCanonicalSource(intent.record, intent.source, intent.target);
+  const live_source = await verify(canonical);
+  const prior_request = await archivePriorRequest(root, seat, active.file, active.isLive);
+  return { canonical_source: canonical, prior_receipt: await archiveStaleReceipt(root, seat, canonical), ...(prior_request ? { prior_request } : {}), live_source };
+}

package/src/vcs-migration.ts

@@ -2,6 +2,7 @@
 // Tested-By:
 // - test:flow:jj-vcs-migration:E013-UNIT-001
 // - test:flow:jj-vcs-migration:E014-UNIT-001
+// - test:flow:jj-vcs-migration:E017-UNIT-001
 // Runtime: bun
 // Purpose: Migrate one legacy Flow Git project to colocated JJ without losing lineage.
 //
@@ -21,7 +22,7 @@
 // state from a partial JJ conversion. The durable project VCS is written last.
 
 import { lstat, readFile, readdir, readlink, realpath, rename, rm, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, normalize, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import {
   type Project, type Seat, atomicYaml, exists, paths, project, readYaml, required, yaml,
@@ -37,12 +38,19 @@ type ReviewsLite = { attempts?: Array<{ delivery_head?: string }> };
 /** JJ silently skips new files above this size (snapshot.max-new-file-size default). */
 const SNAPSHOT_MAX_NEW_FILE_BYTES = 1048576;
 const DIRTY_PRIMARY_FLAG = "--allow-dirty-primary";
+const RETAIN_LARGE_FLAG = "--retain-large-primary-file";
+/** Plain literals (no interpolation): angle-bracket placeholders must never look like an HTML fragment. */
+const SPEC_FORMAT = "<path>:<sha256>:<bytes>:<mode>";
+const USAGE = "Use `atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary [--retain-large-primary-file <path>:<sha256>:<bytes>:<mode> ...]] [--dry-run]`.";
+
+/** One operator-authorized over-limit primary file, matched against disk exactly. */
+type LargeFile = { path: string; sha256: string; bytes: number; mode: string };
 
 type DiskState =
   | { kind: "absent" }
   | { kind: "file"; sha256: string; exec: boolean }
   | { kind: "symlink"; target: string };
-type DirtyEntry = { path: string; status: string; disk: DiskState };
+type DirtyEntry = { path: string; status: string; disk: DiskState; retained?: LargeFile };
 
 export type VcsMigrationPlan = {
   schema: "atdd-flow/vcs-migration-plan/v1";
@@ -53,6 +61,7 @@ export type VcsMigrationPlan = {
   workspaces: SeatState[];
   lineage: { tasks_checked: number; reviews_checked: number };
   dirty_primary?: { entries: Array<{ path: string; status: string }> };
+  large_primary?: LargeFile[];
 };
 
 type PreparedMigration = {
@@ -64,6 +73,31 @@ type PreparedMigration = {
   index: Buffer | null;
 };
 
+/** Parse `<path>:<sha256>:<bytes>:<mode>` from the right so the path alone may contain colons. */
+function parseLargeFile(spec: string): LargeFile {
+  const match = spec.match(/^(.+):([0-9a-f]{64}):(\d+):([0-7]{4})$/);
+  if (!match) throw new Error(`${RETAIN_LARGE_FLAG} expects ${SPEC_FORMAT} (lowercase 64-hex sha256, decimal bytes, four-digit octal mode); got ${spec}.`);
+  const [, path, sha256, bytes, mode] = match as unknown as [string, string, string, string, string];
+  if (isAbsolute(path) || path.split("/").includes("..") || normalize(path) !== path || path.endsWith("/")) {
+    throw new Error(`${RETAIN_LARGE_FLAG} path must be a normalized repository-relative path with no '..' (outside the primary checkout is refused): ${path}`);
+  }
+  return { path, sha256, bytes: Number(bytes), mode };
+}
+
+/** Every authorization must name a path that is actually dirty in the primary checkout. */
+function assertAuthorizationsDirty(authorized: LargeFile[], dirty: DirtyEntry[]) {
+  for (const auth of authorized) {
+    if (!dirty.some(entry => entry.path === auth.path)) throw new Error(`Authorized large file ${auth.path} is not a dirty primary path (it does not exist or is unchanged).`);
+  }
+}
+
+/** Compare one over-limit new file with its authorization; every field must match exactly. */
+function assertAuthorizedLarge(auth: LargeFile, size: number, mode: string, sha256: string) {
+  if (size !== auth.bytes) throw new Error(`Authorized large file ${auth.path} is ${size} bytes on disk, not the authorized ${auth.bytes} bytes.`);
+  if (sha256 !== auth.sha256) throw new Error(`Authorized large file ${auth.path} sha256 ${sha256} does not match the authorized sha256 ${auth.sha256}.`);
+  if (mode !== auth.mode) throw new Error(`Authorized large file ${auth.path} has mode ${mode} on disk, not the authorized mode ${auth.mode}.`);
+}
+
 /** Run one external VCS command without throwing so rollback can inspect failures. */
 async function command(cwd: string, executable: string, args: string[]): Promise<CommandResult> {
   const child = Bun.spawn([executable, ...args], { cwd, stdout: "pipe", stderr: "pipe" });
@@ -123,30 +157,48 @@ async function diskState(worktree: string, path: string): Promise<DiskState> {
   return { kind: "file", sha256, exec: (info.mode & 0o111) !== 0 };
 }
 
+/** Classify one dirty path: retained exactly, plain, or an unauthorized over-limit refusal. */
+async function classifyDirty(worktree: string, flags: string, path: string, authorized: LargeFile[]) {
+  const disk = await diskState(worktree, path);
+  const auth = authorized.find(item => item.path === path);
+  const info = disk.kind === "file" ? await lstat(join(worktree, path)) : null;
+  const isNew = flags.includes("?") || flags.includes("A");
+  const overLimit = isNew && info !== null && info.size > SNAPSHOT_MAX_NEW_FILE_BYTES;
+  const entry: DirtyEntry = { path, status: flags, disk };
+  if (auth) {
+    if (!overLimit || disk.kind !== "file" || !info) {
+      throw new Error(`Authorized file ${path} does not exceed the JJ snapshot size limit of ${SNAPSHOT_MAX_NEW_FILE_BYTES} bytes as a new regular file; the authorization is refused.`);
+    }
+    assertAuthorizedLarge(auth, info.size, (info.mode & 0o777).toString(8).padStart(4, "0"), disk.sha256);
+    entry.retained = auth;
+  }
+  const refusal = overLimit && !auth
+    ? `Dirty primary file ${path} (${info!.size} bytes) exceeds the JJ snapshot size limit of ${SNAPSHOT_MAX_NEW_FILE_BYTES} bytes and would not be retained; commit it, move it, ignore it, or authorize it exactly with ${RETAIN_LARGE_FLAG}.`
+    : undefined;
+  return { entry, refusal };
+}
+
 /** Capture the primary's uncommitted paths read-only, refusing anything JJ would drop. */
-async function captureDirtyPrimary(worktree: string): Promise<DirtyEntry[]> {
+async function captureDirtyPrimary(worktree: string, authorized: LargeFile[]): Promise<DirtyEntry[]> {
   // Raw, untrimmed: the first record's leading status space is significant.
   const status = await Bun.spawn(["git", "status", "--porcelain=v1", "-z", "--untracked-files=all", "--no-renames"], { cwd: worktree, stdout: "pipe", stderr: "pipe" });
   const [raw, failure, code] = await Promise.all([new Response(status.stdout).text(), new Response(status.stderr).text(), status.exited]);
   if (code !== 0) throw new Error(`git status failed: ${failure.trim()}`);
   const entries: DirtyEntry[] = [];
+  const refused: string[] = [];
   for (const record of raw.split("\0").filter(Boolean)) {
-    const flags = record.slice(0, 2), path = record.slice(3);
-    const disk = await diskState(worktree, path);
-    const isNew = flags.includes("?") || flags.includes("A");
-    if (isNew && disk.kind === "file") {
-      const size = (await lstat(join(worktree, path))).size;
-      if (size > SNAPSHOT_MAX_NEW_FILE_BYTES) {
-        throw new Error(`Dirty primary file ${path} (${size} bytes) exceeds the JJ snapshot size limit of ${SNAPSHOT_MAX_NEW_FILE_BYTES} bytes and would not be retained; commit it, move it, or ignore it first.`);
-      }
-    }
-    entries.push({ path, status: flags, disk });
+    const { entry, refusal } = await classifyDirty(worktree, record.slice(0, 2), record.slice(3), authorized);
+    entries.push(entry);
+    if (refusal) refused.push(refusal);
   }
+  // Report a stale authorization before an unauthorized file so the operator fixes the spec first.
+  assertAuthorizationsDirty(authorized, entries);
+  if (refused.length) throw new Error(refused[0]!);
   return entries;
 }
 
 /** Capture the exact clean Git tuple that migration must preserve or parent. */
-async function inspectSeat(repository: string, record: Seat, allowDirtyPrimary: boolean): Promise<{ state: SeatState; dirty: DirtyEntry[] }> {
+async function inspectSeat(repository: string, record: Seat, allowDirtyPrimary: boolean, authorized: LargeFile[]): Promise<{ state: SeatState; dirty: DirtyEntry[] }> {
   const worktree = await realpath(resolve(record.worktree)).catch(() => null);
   if (!worktree) throw new Error(`Seat ${record.address} worktree does not exist: ${record.worktree}`);
   const top = await realpath(await output(worktree, "git", ["rev-parse", "--show-toplevel"]));
@@ -156,7 +208,7 @@ async function inspectSeat(repository: string, record: Seat, allowDirtyPrimary:
   if (await output(worktree, "git", ["status", "--porcelain"])) {
     if (!primary) throw new Error(`Seat ${record.address} worktree is dirty: ${worktree}`);
     if (!allowDirtyPrimary) throw new Error(`Seat ${record.address} worktree is dirty: ${worktree}. Pass ${DIRTY_PRIMARY_FLAG} to retain the primary checkout's uncommitted changes as JJ working-copy state.`);
-    dirty = await captureDirtyPrimary(worktree);
+    dirty = await captureDirtyPrimary(worktree, authorized);
   }
   const branch = await output(worktree, "git", ["branch", "--show-current"]);
   if (branch !== record.branch) throw new Error(`Seat ${record.address} is checked out at ${branch || "detached HEAD"}, not ${record.branch}.`);
@@ -249,7 +301,7 @@ async function assertLineage(root: string, name: string, repository: string, sta
 }
 
 /** Build the complete deterministic migration plan before creating .jj metadata. */
-async function prepare(root: string, name: string, allowDirtyPrimary: boolean): Promise<PreparedMigration> {
+async function prepare(root: string, name: string, allowDirtyPrimary: boolean, authorized: LargeFile[]): Promise<PreparedMigration> {
   const config = await project(root, name);
   if (vcsMode(config) !== "git") throw new Error(`Project ${name} is not a Git project.`);
   const repository = await realpath(resolve(required(config.repository, `project ${name} repository`))).catch(() => null);
@@ -259,9 +311,10 @@ async function prepare(root: string, name: string, allowDirtyPrimary: boolean):
   await assertToolVersions(repository);
   const records = await activeSeats(root, name);
   if (!records.length) throw new Error("Project has no active seats; configure vcs: jj directly before creating seats.");
-  const inspected = await Promise.all(records.map(record => inspectSeat(repository, record, allowDirtyPrimary)));
+  const inspected = await Promise.all(records.map(record => inspectSeat(repository, record, allowDirtyPrimary, authorized)));
   const states = inspected.map(entry => entry.state);
   const dirty = inspected.flatMap(entry => entry.dirty);
+  assertAuthorizationsDirty(authorized, dirty);
   const primary = states.filter(state => state.primary);
   if (primary.length !== 1) throw new Error(`Migration requires exactly one active seat in the primary checkout; found ${primary.length}.`);
   if (new Set(states.map(state => state.worktree)).size !== states.length) throw new Error("Active Flow seats must have distinct worktree paths before migration.");
@@ -272,6 +325,8 @@ async function prepare(root: string, name: string, allowDirtyPrimary: boolean):
   const index = await readIndex(repository);
   const plan: VcsMigrationPlan = { schema: "atdd-flow/vcs-migration-plan/v1", project: name, from: "git", to: "jj", primary: primary[0]!, workspaces, lineage };
   if (dirty.length) plan.dirty_primary = { entries: dirty.map(({ path, status }) => ({ path, status })) };
+  const large = dirty.flatMap(entry => entry.retained ? [entry.retained] : []);
+  if (large.length) plan.large_primary = large;
   return { config, repository, states, plan, dirty, index };
 }
 
@@ -309,6 +364,17 @@ async function verifyDirtyPath(state: SeatState, head: string, entry: DirtyEntry
   const found = await treeEntry(state, head, entry.path);
   const retained = entry.disk.kind === "absent" ? found === null : found !== null && await entryMatches(state, entry, found);
   if (!retained) throw new Error(`Primary path ${entry.path} was not retained exactly in the JJ working copy.`);
+  if (entry.retained) await verifyLargeBlob(state, head, entry.retained);
+}
+
+/** Hash-preservation: the bytes stored in the JJ working-copy commit equal the authorization. */
+async function verifyLargeBlob(state: SeatState, head: string, auth: LargeFile) {
+  const child = Bun.spawn(["git", "cat-file", "blob", `${head}:${auth.path}`], { cwd: state.worktree, stdout: "pipe", stderr: "pipe" });
+  const [bytes, code] = await Promise.all([new Response(child.stdout).arrayBuffer(), child.exited]);
+  const digest = createHash("sha256").update(new Uint8Array(bytes)).digest("hex");
+  if (code !== 0 || bytes.byteLength !== auth.bytes || digest !== auth.sha256) {
+    throw new Error(`Authorized large file ${auth.path} in the JJ working copy does not match the authorized sha256 ${auth.sha256} and ${auth.bytes} bytes.`);
+  }
 }
 
 /** A dirty primary must be exactly `main` plus the captured manifest, nothing more. */
@@ -399,35 +465,63 @@ async function rollback(repository: string, primary: SeatState, displaced: SeatS
   for (const state of [...displaced].reverse()) await removePartialWorkspace(repository, state);
   await rm(join(repository, ".jj"), { recursive: true, force: true }).catch(error => errors.push(String(error)));
   await removeJjRefs(repository).catch(error => errors.push(String(error)));
-  const switched = await command(repository, "git", ["switch", primary.branch]);
-  if (switched.code) errors.push(switched.err || switched.out);
+  // Skip the switch when HEAD already names the branch so rollback adds no HEAD reflog entry.
+  const onBranch = await command(repository, "git", ["symbolic-ref", "-q", "HEAD"]);
+  if (onBranch.out !== `refs/heads/${primary.branch}`) {
+    const switched = await command(repository, "git", ["switch", primary.branch]);
+    if (switched.code) errors.push(switched.err || switched.out);
+  }
   for (const state of displaced) errors.push(...await restoreGitWorkspace(repository, state));
   await restoreIndex(repository, index).catch(error => errors.push(String(error)));
   return errors;
 }
 
-/** Accept exactly `--to jj` plus at most one each of the known flags. */
+/** Require exactly one `--to jj` pair and return the remaining arguments. */
+function withoutTarget(args: string[]) {
+  const toIndex = args.indexOf("--to");
+  const valid = toIndex >= 0 && args[toIndex + 1] === "jj" && args.filter(arg => arg === "--to").length === 1;
+  if (!valid) throw new Error(USAGE);
+  return args.filter((_arg, index) => index !== toIndex && index !== toIndex + 1);
+}
+
+/** Parse the value after one `--retain-large-primary-file`, refusing duplicates. */
+function parseRetainValue(value: string | undefined, authorized: LargeFile[]) {
+  if (value === undefined || value.startsWith("--")) throw new Error(USAGE);
+  const file = parseLargeFile(value);
+  if (authorized.some(item => item.path === file.path)) throw new Error(`${RETAIN_LARGE_FLAG} names ${file.path} more than once (duplicate authorization).`);
+  return file;
+}
+
+/** Accept exactly `--to jj`, at most one each of the known flags, and any number of distinct file authorizations. */
 function parseMigrationArgs(args: string[]) {
-  const toIndex = args.indexOf("--to"), to = toIndex < 0 ? undefined : args[toIndex + 1];
-  const flags = ["--dry-run", DIRTY_PRIMARY_FLAG];
-  const rest = args.filter((_arg, index) => index !== toIndex && index !== toIndex + 1);
-  const valid = toIndex >= 0 && to === "jj"
-    && args.filter(arg => arg === "--to").length === 1
-    && rest.every(arg => flags.includes(arg))
-    && new Set(rest).size === rest.length;
-  if (!valid) throw new Error("Use `atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary] [--dry-run]`.");
-  return { dryRun: rest.includes("--dry-run"), allowDirtyPrimary: rest.includes(DIRTY_PRIMARY_FLAG) };
+  const rest = withoutTarget(args);
+  const flags = new Set<string>();
+  const authorized: LargeFile[] = [];
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index]!;
+    if (arg === RETAIN_LARGE_FLAG) {
+      authorized.push(parseRetainValue(rest[index + 1], authorized));
+      index += 1;
+    } else if (["--dry-run", DIRTY_PRIMARY_FLAG].includes(arg) && !flags.has(arg)) flags.add(arg);
+    else throw new Error(USAGE);
+  }
+  if (authorized.length && !flags.has(DIRTY_PRIMARY_FLAG)) throw new Error(`${RETAIN_LARGE_FLAG} requires ${DIRTY_PRIMARY_FLAG}.`);
+  return { dryRun: flags.has("--dry-run"), allowDirtyPrimary: flags.has(DIRTY_PRIMARY_FLAG), authorized };
 }
 
 /** Execute the only supported legacy conversion: Git project to colocated JJ. */
 export async function migrateProjectVcs(root: string, name: string, args: string[]) {
-  const { dryRun, allowDirtyPrimary } = parseMigrationArgs(args);
-  const prepared = await prepare(root, name, allowDirtyPrimary);
+  const { dryRun, allowDirtyPrimary, authorized } = parseMigrationArgs(args);
+  const prepared = await prepare(root, name, allowDirtyPrimary, authorized);
   if (dryRun) { process.stdout.write(yaml.print(prepared.plan)); return; }
 
   const displaced: SeatState[] = [];
   try {
-    await output(prepared.repository, "jj", ["git", "init", "--colocate"]);
+    // The raised snapshot limit is scoped to this one command and equals the largest authorized file;
+    // preflight proved every over-limit new file is authorized and verification rejects any extra path.
+    const limit = Math.max(0, ...(prepared.plan.large_primary ?? []).map(file => file.bytes));
+    const config = limit > SNAPSHOT_MAX_NEW_FILE_BYTES ? [`--config=snapshot.max-new-file-size=${limit}`] : [];
+    await output(prepared.repository, "jj", [...config, "git", "init", "--colocate"]);
     await assertRepository("jj", prepared.repository);
     await verifyPrimary(prepared.plan.primary, prepared.dirty);
     for (const state of prepared.plan.workspaces) {