@afokapu/atdd-flow 0.3.70 → 0.3.72

package/src/tasks.ts

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

package/src/threads.ts

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

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