@afokapu/atdd-flow 0.3.83 → 0.3.85

package/README.md

@@ -83,8 +83,13 @@ atdd-flow project init example-app
 atdd-flow project configure example-app --repository /Users/you/Github/example-app --worktree-root /Users/you/Github/worktrees/example-app
 ```
 
-`project configure` sets only `repository` and `worktree_root`. It fails closed, leaving the project
-unchanged, when `--repository` is not the top level of a Git repository or a flag is unknown, repeated,
+New projects default to Jujutsu: `project init` records `vcs: jj`, so `--repository` must be a JJ checkout
+(`jj git init --colocate` on an existing Git clone) and every spawned main, coordinator and driver worktree is a JJ
+workspace. Git is an explicit opt-out (`atdd-flow project init example-app --vcs git`); a legacy project record
+without a `vcs` field keeps reading as Git.
+
+`project configure` sets only `repository` and `worktree_root` (and `vcs` when asked). It fails closed, leaving the project
+unchanged, when `--repository` is not the top level of a repository of the project's VCS or a flag is unknown, repeated,
 or missing its value. It never changes seats, runtimes, tasks, branches, worktrees, or repository
 content; it lists each seat whose recorded placement violates the topology as `unprojected`.
 

package/extensions/pi/index.ts

@@ -629,5 +629,5 @@ export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = proc
       ? noticeActivation("inactive")
       : noticeActivation(current.active ? "active" : "inactive", error instanceof Error ? error.message : String(error)));
   });
-  pi.on("session_shutdown", () => { void runtime?.stop(); });
+  pi.on("session_shutdown", async () => { await runtime?.stop(); });
 }

package/package.json

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

package/src/cli.ts

@@ -7,6 +7,7 @@
 
 import { basename, resolve } from "node:path";
 import { init, initProject, configureProject, migrateNamedCoordinatorTopology, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
+import { formatMonitorRow, monitorContext } from "./context-monitor";
 import { formatWakeRow, wakePi } from "./pi-wake";
 import { createExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
@@ -33,7 +34,7 @@ Legacy coordination.yaml registries are read safely and can be migrated.
 Usage:
   atdd-flow init <desk-directory> [--git]
   atdd-flow desk migrate
-  atdd-flow project init <project>
+  atdd-flow project init <project> [--vcs <git|jj>]   (default: jj)
   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]
   atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>
@@ -116,11 +117,11 @@ async function main() {
       throw new Error("Use `atdd-flow desk migrate`.");
     },
     project: async () => {
-      if (rest[0] === "init") return initProject(root, required(rest[1], "project"));
+      if (rest[0] === "init") return initProject(root, required(rest[1], "project"), rest.slice(2));
       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 [--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>`.");
+      throw new Error("Use `atdd-flow project init <project> [--vcs <git|jj>]`, `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)),
@@ -133,6 +134,12 @@ async function main() {
         if (rows.length !== 1) console.log(`pi wake: ${rows.length} seat(s) — ${["woke", "swapped+woke", "deferred", "refused", "skipped", "failed"].map((outcome) => [outcome, rows.filter((entry) => entry.outcome === outcome).length] as const).filter(([, count]) => count).map(([outcome, count]) => `${count} ${outcome}`).join(", ") || "none"}`);
         return;
       }
+      if (rest[0] === "context-monitor") {
+        const { rows, success } = await monitorContext(root, rest.slice(1), (entry) => console.log(formatMonitorRow(entry)));
+        if (!success) process.exitCode = 1;
+        if (rows.length !== 1) console.log(`pi context-monitor: ${rows.length} seat(s) — ${["prompted", "would-prompt", "below", "already", "deferred", "refused", "skipped", "failed"].map((outcome) => [outcome, rows.filter((entry) => entry.outcome === outcome).length] as const).filter(([, count]) => count).map(([outcome, count]) => `${count} ${outcome}`).join(", ") || "none"}`);
+        return;
+      }
       if (rest[0] === "runtime" && rest[1] === "authorize-adoption") return createExactSessionAdoptionAuthorization(root, required(rest[2], "authorization id"), rest.slice(3));
       if (rest[0] === "runtime" && rest[1] === "launch") {
         const plan = await launchPiRuntime(root, required(rest[2], "address"), rest.slice(3));
@@ -140,7 +147,7 @@ async function main() {
         else console.log(`Launched Pi runtime for ${required(rest[2], "address")} with ${plan.candidate}.`);
         return;
       }
-      throw new Error("Use `pi extension-path`, `pi wake <seat>|--scope project|desk [--model-profile <name>] --by <authorized-seat>`, `pi runtime authorize-adoption <id> ...`, or `pi runtime launch <address> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <record-id>]`.");
+      throw new Error("Use `pi extension-path`, `pi wake <seat>|--scope project|desk [--model-profile <name>] --by <authorized-seat>`, `pi context-monitor <seat>|--scope project|desk --by <authorized-seat> [--dry-run]`, `pi runtime authorize-adoption <id> ...`, or `pi runtime launch <address> [--pane <asserted-pane>] --herdr-session <session> [--resume] [--dry-run] [--adopt-session <exact-jsonl> --source-herdr-session <session> --source-pane <pane> --authorization <record-id>]`.");
     },
     application: async () => {
       if (rest[0] === "use") return useApplication(root, required(rest[1], "address"), required(rest[2], "application"));

package/src/context-monitor.ts

@@ -0,0 +1,103 @@
+// URN: component:flow:e025:context-monitor:backend:application
+// Tested-By:
+// - test:atdd-flow:server-side-context-monitor
+// Runtime: bun
+// Purpose: Prompt the context-threshold handover from Flow, using the exact Pi transcript.
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { canonicalAddress, modelPortfolio, now, piModel, type ModelPortfolio, yaml } from "./core";
+import { handoverThresholdInstruction } from "./collaboration-policy";
+import { contextHandoverThreshold } from "./handover";
+import { type Outcome, type Prepared, herdr, hold, message, parseWakeArguments, prepare, readBranch, targetAddresses } from "./pi-wake";
+import { recoveryFor } from "./recovery-bundle";
+import type { TranscriptEntry } from "./pi-wake-protocol";
+import { customEntries } from "./pi-wake-protocol";
+
+export const monitorUsage = "Use `atdd-flow pi context-monitor <seat>|--scope project|desk --by <authorized-seat> [--dry-run]`.";
+export type MonitorOutcome = Outcome | "prompted" | "would-prompt" | "below" | "already";
+export type MonitorRow = { seat: string; outcome: MonitorOutcome; detail?: string };
+
+/** The extension's own threshold prompt; the same custom type also carries successor prompts, so only the threshold detail counts. */
+const thresholdPromptType = "atdd-flow-context-handover-replacement";
+const object = (value: unknown): Record<string, unknown> | undefined => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const monitorRow = (seat: string, outcome: MonitorOutcome, detail?: string): MonitorRow => ({ seat, outcome, ...(detail ? { detail } : {}) });
+export const markerPath = (root: string, seat: string, piSession: string) => join(root, ".atdd-flow", "context-monitor", `${encodeURIComponent(seat)}__${piSession}.yaml`);
+
+/** The last assistant turn on the active branch: its exact model and the context it occupied. */
+export function lastAssistantUsage(branch: TranscriptEntry[]) {
+  for (const entry of [...branch].reverse()) {
+    const body = object((entry as Record<string, unknown>).message);
+    if (entry.type !== "message" || body?.role !== "assistant") continue;
+    const tokens = object(body.usage)?.totalTokens;
+    if (typeof tokens === "number" && tokens > 0 && typeof body.provider === "string" && typeof body.model === "string") return { tokens, provider: body.provider, model: body.model };
+  }
+  return undefined;
+}
+
+/** The window the Desk declares for exactly this provider/model; nothing is inferred. */
+function declaredWindow(portfolio: ModelPortfolio | undefined, provider: string, model: string) {
+  const windows = (portfolio?.models ?? []).flatMap((candidate) => {
+    const exact = piModel(candidate);
+    return exact?.provider === provider && exact.model === model && candidate.context_window ? [candidate.context_window] : [];
+  });
+  return windows.length === 1 ? windows[0] : undefined;
+}
+
+const format = (value: number) => `${Math.round(value * 10) / 10}%`;
+
+/** The reason a session needs no prompt yet (already prompted, no usage, no declared window), else its measured context. */
+async function measure(root: string, address: string, ready: { sessionPath: string; sessionId: string }, portfolio: ModelPortfolio | undefined) {
+  const branch = await readBranch(ready.sessionPath).catch((error) => error as Error);
+  if (branch instanceof Error) return monitorRow(address, "refused", `cannot read the Pi transcript: ${branch.message}`);
+  if (customEntries(branch, thresholdPromptType).some((entry) => entry.details?.threshold !== undefined)) return monitorRow(address, "already", "threshold prompt already in the transcript");
+  if (await Bun.file(markerPath(root, address, ready.sessionId)).exists()) return monitorRow(address, "already", "this Pi session was already prompted");
+  const usage = lastAssistantUsage(branch);
+  if (!usage) return monitorRow(address, "skipped", "no assistant usage recorded in the transcript");
+  const window = declaredWindow(portfolio, usage.provider, usage.model);
+  if (!window) return monitorRow(address, "skipped", `no context_window declared for ${usage.provider}/${usage.model}`);
+  return { percent: usage.tokens / window * 100, window };
+}
+
+/** Create-only marker first so a concurrent monitor cannot double-prompt; a failed prompt releases it. */
+async function prompt(root: string, address: string, ready: { session: string; pane: string; sessionId: string }, percent: number, threshold: number, summary: string) {
+  const marker = markerPath(root, address, ready.sessionId);
+  const bundle = await recoveryFor(root, address, "threshold", ready.sessionId).catch(() => undefined);
+  await mkdir(dirname(marker), { recursive: true });
+  try { await writeFile(marker, yaml.print({ schema: "atdd-flow/context-monitor-marker/v1", seat: address, pi_session: ready.sessionId, percent: Math.floor(percent), threshold, prompted_at: now() }), { encoding: "utf8", flag: "wx" }); }
+  catch { return monitorRow(address, "already", "this Pi session was already prompted"); }
+  try { await herdr(ready.session, "agent", "prompt", ready.pane, handoverThresholdInstruction(Math.floor(percent), threshold, bundle)); }
+  catch (error) { await rm(marker, { force: true }); return monitorRow(address, "failed", message(error)); }
+  return monitorRow(address, "prompted", summary);
+}
+
+async function monitorOne(root: string, address: string, prepared: Extract<Prepared, { record: unknown }>, threshold: number, portfolio: ModelPortfolio | undefined, dryRun: boolean): Promise<MonitorRow> {
+  const { ready } = prepared;
+  const measured = await measure(root, address, ready, portfolio);
+  if ("outcome" in measured) return measured;
+  const summary = `${format(measured.percent)} of ${measured.window} tokens`;
+  if (measured.percent < threshold) return monitorRow(address, "below", `${summary}; threshold ${threshold}%`);
+  if (dryRun) return monitorRow(address, "would-prompt", `${summary}; threshold ${threshold}%`);
+  return prompt(root, address, ready, measured.percent, threshold, summary);
+}
+
+/** Runs the closed `pi context-monitor` grammar; each seat's row is reported in lexical order as it completes. */
+export async function monitorContext(root: string, args: string[], report: (line: MonitorRow) => void = () => undefined) {
+  const dryRun = args.includes("--dry-run");
+  const options = (() => { try { return parseWakeArguments(args.filter((argument) => argument !== "--dry-run")); } catch { throw new Error(monitorUsage); } })();
+  if (options.profile) throw new Error(monitorUsage);
+  const actor = await canonicalAddress(root, options.by);
+  const addresses = (await targetAddresses(root, options, actor)).sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+  const threshold = await contextHandoverThreshold(root), portfolio = await modelPortfolio(root);
+  const rows: MonitorRow[] = [];
+  for (const address of addresses) {
+    const prepared: Prepared = await prepare(root, address, actor).catch((error) => hold(address, "failed", message(error)));
+    const outcome = "row" in prepared ? monitorRow(prepared.row.seat, prepared.row.outcome, prepared.row.detail)
+      : await monitorOne(root, address, prepared, threshold, portfolio, dryRun).catch((error) => monitorRow(address, "failed", message(error)));
+    rows.push(outcome);
+    report(outcome);
+  }
+  return { rows, success: rows.every((entry) => entry.outcome !== "refused" && entry.outcome !== "failed") };
+}
+
+export const formatMonitorRow = (entry: MonitorRow) => `${entry.seat}  ${entry.outcome}${entry.detail ? `  ${entry.detail}` : ""}`;

package/src/core.ts

@@ -34,6 +34,8 @@ export type ModelCandidate = {
   args?: string[];
   description?: string;
   enabled?: boolean;
+  /** Context window in tokens; the server-side context monitor never guesses one. */
+  context_window?: number;
 };
 export type ModelPortfolio = {
   schema: "atdd-workflow/models/v1";
@@ -300,6 +302,10 @@ function assertModelMigrations(value: unknown, models: ModelCandidate[]) {
   for (const [profile, migration] of Object.entries(value)) assertMigration(profile, migration, models);
 }
 
+function assertContextWindow(model: ModelCandidate) {
+  if (model.context_window !== undefined && !(Number.isInteger(model.context_window) && model.context_window > 0)) throw new Error(`context_window for ${model.id} must be a positive integer of tokens.`);
+}
+
 export async function modelPortfolio(root: string): Promise<ModelPortfolio | undefined> {
   const file = paths(root).models;
   if (!await exists(file)) return undefined;
@@ -311,6 +317,7 @@ export async function modelPortfolio(root: string): Promise<ModelPortfolio | und
     if (!model.id?.trim() || !model.executable?.trim()) throw new Error("Every model requires id and executable.");
     if (ids.has(model.id)) throw new Error(`Duplicate model id in models.yaml: ${model.id}`);
     ids.add(model.id);
+    assertContextWindow(model);
   }
   assertModelMigrations(value.model_migrations, value.models);
   return value;
@@ -322,21 +329,40 @@ export async function project(root: string, name: string) {
   return value;
 }
 
-export async function canonicalAddress(root: string, address: string) {
+/**
+ * Follows the Desk's alias chain without validating the result, so stored history written under a renamed seat's
+ * old address reads as its current address. One Desk read serves a whole batch; a cycle fails closed.
+ */
+export async function addressAliasResolver(root: string) {
   const aliases = (await desk(root)).aliases ?? {};
-  const visited = new Set<string>();
-  let resolved = address;
-  while (aliases[resolved]) {
-    if (visited.has(resolved)) throw new Error(`Address alias cycle: ${address}`);
-    visited.add(resolved);
-    resolved = aliases[resolved];
-  }
+  return (address: string) => {
+    const visited = new Set<string>();
+    let resolved = address;
+    while (aliases[resolved]) {
+      if (visited.has(resolved)) throw new Error(`Address alias cycle: ${address}`);
+      visited.add(resolved);
+      resolved = aliases[resolved];
+    }
+    return resolved;
+  };
+}
+
+export async function canonicalAddress(root: string, address: string) {
+  const resolved = (await addressAliasResolver(root))(address);
   addressParts(resolved);
   return resolved;
 }
 
+/** A Herdr pane id never carries its session; a binding typed as `<session>/<pane>` names that pane. */
+export function herdrPaneId(session: string, pane: string) {
+  return pane.startsWith(`${session}/`) ? pane.slice(session.length + 1) : pane;
+}
+
 export async function seat(root: string, address: string) {
-  return readYaml<Seat>(paths(root).seatFile(await canonicalAddress(root, address)));
+  const record = await readYaml<Seat>(paths(root).seatFile(await canonicalAddress(root, address)));
+  const locator = record.runtime?.addresses.herdr;
+  if (locator && typeof locator === "object") locator.pane = herdrPaneId(locator.session, locator.pane);
+  return record;
 }
 
 export function fill(template: string, entries: Record<string, string>) {

package/src/handover.ts

@@ -229,11 +229,35 @@ async function failedAdoptionTaskEligible(root: string, record: Seat, address: s
     && await isExactMainSeat(root, record, address);
 }
 
-export async function replacementForMainLaunch(root: string, record: Seat, address: string) {
+export type MainLaunchReplacement = { request?: HandoverReplacementRequest; taskId: string; task: Task; bootstrap?: { handover: string } };
+
+/**
+ * A brand-new exact main seat has no predecessor to name. It may launch once when it records no Pi identity, has no
+ * Path-A request file, has a recorded handover and exactly one ready self-assigned todo task; nothing is fabricated.
+ */
+/** A staged shell-pane binding is a Herdr locator only; any Pi session, path or receipt proves a Pi already ran. */
+function hasPiIdentity(runtime: Runtime | undefined) {
+  return Boolean(runtime?.pi_session || runtime?.pi_session_path || runtime?.launch_receipt);
+}
+
+async function bootstrapForMainLaunch(root: string, record: Seat, address: string): Promise<MainLaunchReplacement | undefined> {
+  if (hasPiIdentity(record.runtime) || await exists(handoverReplacementPath(root, address))) return undefined;
+  const handover = await recorded(root, address);
+  if (!handover) return undefined;
+  const ready = await readyMainTasks(root, record, address);
+  if (ready.length !== 1) return undefined;
+  const taskId = ready[0]!;
+  return { taskId, task: await readYaml<Task>(paths(root).taskFile(record.project, taskId)), bootstrap: { handover: handover.handover_id } };
+}
+
+export async function replacementForMainLaunch(root: string, record: Seat, address: string): Promise<MainLaunchReplacement | undefined> {
   if (!await isExactMainSeat(root, record, address)) return undefined;
-  const request = await readHandoverReplacement(root, address).catch(() => {
+  const request = await readHandoverReplacement(root, address).catch(async () => {
+    const bootstrap = await bootstrapForMainLaunch(root, record, address);
+    if (bootstrap) return bootstrap;
     throw new Error(`${address} requires one validated Path-A replacement request; refusing runtime launch.`);
   });
+  if ("taskId" in request) return request;
   const task = await readYaml<Task>(paths(root).taskFile(record.project, request.task));
   const failedAdoption = await exactFailedAdoptionProof(root, record, address, request,
     (task) => failedAdoptionTaskEligible(root, record, address, task));
@@ -245,7 +269,7 @@ export async function replacementForMainLaunch(root: string, record: Seat, addre
   if (!canonicalLaunch && !failedAdoptionRecovery) {
     throw new Error("Path-A replacement source tuple no longer matches the recorded runtime or ready main takeover task.");
   }
-  return { request, task };
+  return { request, taskId: request.task, task };
 }
 
 export function assertReplacementTarget(request: HandoverReplacementRequest, herdrSession: string, pane: string, worktree: string) {
@@ -254,15 +278,12 @@ export function assertReplacementTarget(request: HandoverReplacementRequest, her
   }
 }
 
-async function exactMainTakeoverTask(root: string, address: string, id: string) {
-  const record = await seat(root, address);
-  if (!await isExactMainSeat(root, record, address)) {
-    throw new Error(`Path-A replacement requires exact main@${record.project} primary-main topology.`);
-  }
+/** Ids of the todo tasks that main@project owns and could start now: unblocked, self-assigned, dependencies terminal. */
+async function readyMainTasks(root: string, record: Seat, address: string) {
   let files: string[];
   try { files = await readdir(paths(root).tasks(record.project)); }
-  catch { throw new Error(`Path-A replacement requires one ready self-assigned main takeover task for ${address}.`); }
-  const ready = (await Promise.all(files.filter((file) => file.endsWith(".yaml") && !file.endsWith(".reviews.yaml")).map(async (file) => {
+  catch { return []; }
+  return (await Promise.all(files.filter((file) => file.endsWith(".yaml") && !file.endsWith(".reviews.yaml")).map(async (file) => {
     const taskId = file.slice(0, -5);
     const task = await readYaml<Task>(paths(root).taskFile(record.project, taskId));
     if (task.schema !== "atdd-workflow/task/v1" || task.status !== "todo" || task.blocker || task.coordinator !== address || task.assignee !== address) return undefined;
@@ -272,6 +293,15 @@ async function exactMainTakeoverTask(root: string, address: string, id: string)
     }));
     return dependencies.every(Boolean) ? taskId : undefined;
   }))).filter((entry): entry is string => Boolean(entry));
+}
+
+async function exactMainTakeoverTask(root: string, address: string, id: string) {
+  const record = await seat(root, address);
+  if (!await isExactMainSeat(root, record, address)) {
+    throw new Error(`Path-A replacement requires exact main@${record.project} primary-main topology.`);
+  }
+  const ready = await readyMainTasks(root, record, address);
+  if (!ready.length && !await exists(paths(root).tasks(record.project))) throw new Error(`Path-A replacement requires one ready self-assigned main takeover task for ${address}.`);
   if (ready.length !== 1 || ready[0] !== id) throw new Error(`Path-A replacement requires exactly one ready self-assigned main takeover task; found: ${ready.join(", ") || "none"}.`);
   return { record };
 }
@@ -765,8 +795,30 @@ export async function resumedHandover(root: string, address: string) {
   return await isExactOperatorSeat(root, record, resolved) ? operatorResumed(root, record) : resumedHandoverReplacement(root, resolved);
 }
 
+/** A bootstrap successor has no Path-A request: reconcile it against its own launch receipt, Herdr binding and heartbeat. */
+async function resumedBootstrapLaunch(root: string, address: string) {
+  const record = await seat(root, address);
+  const runtime = record.runtime;
+  const locator = runtime?.addresses.herdr;
+  const receipt = runtime?.launch_receipt && await exists(runtime.launch_receipt) ? await readYaml<Record<string, any>>(runtime.launch_receipt) : undefined;
+  const bootstrap = receipt?.bootstrap_launch as { handover?: { id?: string }; task?: string } | undefined;
+  const handover = await recorded(root, address);
+  const runtimeState = await readRuntimeState(root, address);
+  const verified = [
+    Boolean(handover && bootstrap?.handover?.id === handover.handover_id && bootstrap.task && receipt?.seat === address && !receipt.handover_replacement),
+    runtime?.application === "herdr" && runtime.wake === "native",
+    Boolean(runtime?.pi_session && runtime.pi_session_path && receipt?.pi_session === runtime.pi_session && receipt.pi_session_path === runtime.pi_session_path),
+    typeof locator !== "string" && Boolean(locator) && locator?.session === receipt?.herdr_session && locator?.pane === receipt?.pane,
+    Boolean(runtimeState && runtimeState.seat === address),
+  ];
+  const discrepancies = ["bootstrap receipt", "native delivery", "fresh Pi session/JSONL path", "target tuple", "fresh heartbeat"].filter((_, index) => !verified[index]);
+  console.log(`RESUMED; verified ${verified.filter(Boolean).length}/${verified.length}; discrepancies: ${discrepancies.join(", ") || "none"}.`);
+  if (discrepancies.length) throw new Error("Bootstrap successor is not reconciled against the live Desk.");
+}
+
 export async function resumedHandoverReplacement(root: string, address: string) {
   const resolved = await canonicalAddress(root, address);
+  if (!await exists(handoverReplacementPath(root, resolved)) && await isExactMainSeat(root, await seat(root, resolved), resolved)) return resumedBootstrapLaunch(root, resolved);
   const [request, record] = await Promise.all([readHandoverReplacement(root, resolved), seat(root, resolved)]);
   const runtime = record.runtime;
   const locator = runtime?.addresses.herdr;

package/src/multiplexer.ts

@@ -240,11 +240,17 @@ function matchWorkspace(workspaces: Workspace[], target: Target) {
   return workspaces.find((entry) => checkoutOf(entry) === undefined && entry.label === target.project);
 }
 
-async function ensureWorkspace(session: string, target: Target, workspaces: Workspace[], command: HerdrCommand, primary?: WorkspaceState) {
+/**
+ * Workspaces and tabs Flow creates inherit the Desk root. Herdr 0.9.3 `worktree open` has no `--env`, so a linked
+ * worktree's reused root tab gets the root from `pi runtime launch`, which exports it into the pane before Pi starts.
+ */
+const deskEnv = (root: string) => ["--env", `ATDD_WORKFLOW_ROOT=${root}`];
+
+async function ensureWorkspace(root: string, session: string, target: Target, workspaces: Workspace[], command: HerdrCommand, primary?: WorkspaceState) {
   let current = matchWorkspace(workspaces, target);
   if (!current) {
     const args = target.workspaceLabel === target.project
-      ? ["workspace", "create", "--cwd", target.worktree, "--label", target.workspaceLabel, "--no-focus"]
+      ? ["workspace", "create", "--cwd", target.worktree, "--label", target.workspaceLabel, "--no-focus", ...deskEnv(root)]
       : ["worktree", "open", "--workspace", primary?.id ?? "", "--path", target.worktree, "--label", target.workspaceLabel, "--no-focus"];
     if (args.includes("")) throw new Error(`Project primary workspace is required to open linked worktree ${target.worktree}.`);
     const created = json(await command(["herdr", "--session", session, ...args]));
@@ -270,7 +276,7 @@ async function panes(session: string, workspace: string, command: HerdrCommand)
   return result.panes as Pane[];
 }
 
-async function ensureSeatTab(session: string, workspace: WorkspaceState, target: Target & { seat: Seat }, command: HerdrCommand): Promise<HerdrSeatProjection> {
+async function ensureSeatTab(root: string, session: string, workspace: WorkspaceState, target: Target & { seat: Seat }, command: HerdrCommand): Promise<HerdrSeatProjection> {
   let entries = await tabs(session, workspace.id, command);
   let tab = entries.find((entry) => entry.label === target.seat.address);
   let pane: string | undefined;
@@ -280,7 +286,7 @@ async function ensureSeatTab(session: string, workspace: WorkspaceState, target:
     tab.label = target.seat.address;
   }
   if (!tab) {
-    const created = json(await command(["herdr", "--session", session, "tab", "create", "--workspace", workspace.id, "--cwd", target.worktree, "--label", target.seat.address, "--no-focus"]));
+    const created = json(await command(["herdr", "--session", session, "tab", "create", "--workspace", workspace.id, "--cwd", target.worktree, "--label", target.seat.address, "--no-focus", ...deskEnv(root)]));
     const id = tabId(created);
     if (!id) throw new Error("Herdr did not return a tab id.");
     tab = { tab_id: id, workspace_id: workspace.id, label: target.seat.address };
@@ -295,9 +301,9 @@ async function ensureSeatTab(session: string, workspace: WorkspaceState, target:
   return { session, workspace: workspace.id, tab: tab.tab_id, pane: first, worktree: target.worktree, label: target.seat.address };
 }
 
-async function ensureTarget(session: string, target: Target, workspaces: Workspace[], command: HerdrCommand, primary: WorkspaceState) {
-  const workspace = target.workspaceLabel === target.project ? primary : await ensureWorkspace(session, target, workspaces, command, primary);
-  return target.seat ? ensureSeatTab(session, workspace, target as Target & { seat: Seat }, command) : undefined;
+async function ensureTarget(root: string, session: string, target: Target, workspaces: Workspace[], command: HerdrCommand, primary: WorkspaceState) {
+  const workspace = target.workspaceLabel === target.project ? primary : await ensureWorkspace(root, session, target, workspaces, command, primary);
+  return target.seat ? ensureSeatTab(root, session, workspace, target as Target & { seat: Seat }, command) : undefined;
 }
 
 /** Reconciles exactly one Desk seat into a labeled Herdr workspace/tab/pane. */
@@ -309,8 +315,8 @@ export async function projectHerdrSeat(root: string, address: string, session: s
   const primaryTarget = desired.find((entry) => entry.project === target.project && entry.workspaceLabel === target.project && !entry.seat);
   if (!primaryTarget) throw new Error(`Project ${target.project} has no declared primary workspace.`);
   const workspaces = await liveWorkspaces(session, command);
-  const primary = await ensureWorkspace(session, primaryTarget, workspaces, command);
-  return (await ensureTarget(session, target, workspaces, command, primary))!;
+  const primary = await ensureWorkspace(root, session, primaryTarget, workspaces, command);
+  return (await ensureTarget(root, session, target, workspaces, command, primary))!;
 }
 
 type StaleWorkspace = { workspace: Workspace; address: string; reason: "retired" | "no active task" };
@@ -453,10 +459,10 @@ export async function multiplexer(root: string, args: string[]) {
     if (!projectPrimary) {
       const primaryTarget = desired.find((entry) => entry.project === target.project && entry.workspaceLabel === target.project && !entry.seat);
       if (!primaryTarget) throw new Error(`Project ${target.project} has no declared primary workspace.`);
-      projectPrimary = await ensureWorkspace(session, primaryTarget, workspaces, command);
+      projectPrimary = await ensureWorkspace(root, session, primaryTarget, workspaces, command);
       primary.set(target.project, projectPrimary);
     }
-    await ensureTarget(session, target, workspaces, command, projectPrimary);
+    await ensureTarget(root, session, target, workspaces, command, projectPrimary);
   }
   for (const entry of unprojected) console.log(`unprojected  ${entry.address}: ${entry.reason}`);
   // Decided at close time with the same read-only rule `status` reports.

package/src/overview.ts

@@ -1,9 +1,9 @@
 import { readdir } from "node:fs/promises";
-import { canonicalAddress, desk, exists, paths, readYaml, type Checkpoint, type Seat } from "./core";
+import { addressAliasResolver, canonicalAddress, desk, exists, paths, readYaml, type Checkpoint, type Seat } from "./core";
 import { type Task, type TaskHandoff, type TaskStatus, terminal } from "./tasks";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { describeActivation, nativeMailInactive } from "./mail-activation-notice";
-import { type Message, type Thread } from "./threads";
+import { type Message, type Thread, canonicalMessage, canonicalThread } from "./threads";
 
 type ListedTask = { project: string; id: string; task: Task; waiting: string[] };
 type ListedSeat = { project: string; record: Seat; checkpoint?: Checkpoint };
@@ -62,13 +62,14 @@ async function tasks(root: string, project: string): Promise<ListedTask[]> {
 
 async function threads(root: string): Promise<ListedThread[]> {
   const ids = await names(paths(root).threads);
+  const resolve = await addressAliasResolver(root);
   return (await Promise.all(ids.map(async (id) => {
     const threadFile = paths(root).threadFile(id);
     if (!await exists(threadFile)) return undefined;
-    const record = await readYaml<Thread>(threadFile);
+    const record = canonicalThread(await readYaml<Thread>(threadFile), resolve);
     const messages = await Promise.all((await names(paths(root).thread(id)))
       .filter((file) => file.startsWith("M-") && file.endsWith(".yaml"))
-      .map((file) => readYaml<Message>(`${paths(root).thread(id)}/${file}`)));
+      .map(async (file) => canonicalMessage(await readYaml<Message>(`${paths(root).thread(id)}/${file}`), resolve)));
     const pending = messages.flatMap((message) => {
       if (!message.expects_result) return [];
       const recipients = message.to === "all" ? record.participants.filter((address) => address !== message.from) : message.to;

package/src/pi-runtime-launch.ts

@@ -287,7 +287,7 @@ async function prepareLaunch(root: string, address: string, args: string[], depe
   const resolved = await canonicalAddress(root, address), record = await seat(root, resolved), config = await desk(root);
   const options = parseLaunchOptions(args), existingPane = existingPaneForResume(record, options);
   const replacement = await replacementForMainLaunch(root, record, resolved);
-  const active = replacement ? [{ id: replacement.request.task, task: replacement.task }] : await launchEligibleTasks(root, record, resolved);
+  const active = replacement ? [{ id: replacement.taskId, task: replacement.task }] : await launchEligibleTasks(root, record, resolved);
   const operator = await isExactOperatorSeat(root, record, resolved);
   if (!active.length && !operator) throw new Error(`${resolved} has no launch-eligible task; refusing runtime launch.`);
   const selection = await chooseLaunchModel(root, config, record, required(await modelPortfolio(root), "models.yaml for Pi runtime launch"), dependencies.select);
@@ -306,7 +306,7 @@ function assertProjectedPane(launch: PreparedLaunch, pane: string) {
   const { options, existingPane, replacement, record } = launch;
   if (options.resume && pane !== existingPane) throw new Error("Resume cannot relocate a Pi session across a Herdr session or pane; use explicit exact-session adoption.");
   if (options.requestedPane && options.requestedPane !== pane) throw new Error("The asserted --pane does not match the seat-scoped Herdr projection.");
-  if (replacement) assertReplacementTarget(replacement.request, options.herdrSession, pane, record.worktree);
+  if (replacement?.request) assertReplacementTarget(replacement.request, options.herdrSession, pane, record.worktree);
 }
 
 const sameTerminalRefusal = "Run this from a different pane; the target pane must be an idle shell.";
@@ -446,7 +446,8 @@ async function persistLaunch(launch: PreparedLaunch, plan: LaunchPlan["plan"], s
   const receiptRecord = {
     schema: "atdd-flow/pi-runtime-launch-receipt/v1", seat: resolved, tasks: active.map((entry) => entry.id), candidate: selection.candidate.id,
     selection: receiptSelection(launch), pi_session: piSession, pi_session_path: sessionPath, herdr_session: options.herdrSession, pane: plan.pane,
-    ...(replacement ? { handover_replacement: { request: replacement.request, successor_session: piSession } } : {}),
+    ...(replacement?.request ? { handover_replacement: { request: replacement.request, successor_session: piSession } } : {}),
+    ...(replacement?.bootstrap ? { bootstrap_launch: { handover: { id: replacement.bootstrap.handover }, task: replacement.taskId } } : {}),
     ...(relocation ? { relocation: { source_herdr_session: options.sourceHerdrSession, source_pane: options.sourcePane, authorization: authorizationRecord, backup: relocation.backup, backup_sha256: relocation.sha256 } } : {}),
     created_at: dependencies.at?.() ?? now(),
   };

package/src/pi-wake.ts

@@ -16,7 +16,7 @@ import {
 
 export const wakeUsage = "Use `atdd-flow pi wake <seat>|--scope project|desk [--model-profile <name>] --by <authorized-seat>`.";
 
-type Outcome = "woke" | "swapped+woke" | "deferred" | "refused" | "skipped" | "failed";
+export type Outcome = "woke" | "swapped+woke" | "deferred" | "refused" | "skipped" | "failed";
 export type WakeRow = { seat: string; outcome: Outcome; detail?: string };
 type Options = { target?: string; scope?: "project" | "desk"; profile?: string; by: string };
 type Target = { provider: string; model: string };
@@ -24,7 +24,7 @@ type Target = { provider: string; model: string };
 type Pane = { agent?: string; status?: string; sessionPath?: string; pids: number[] };
 type Ready = { session: string; pane: string; sessionId: string; sessionPath: string };
 type Inspection = { row: WakeRow } | { ready: Ready };
-type Prepared = { row: WakeRow } | { record: Seat; ready: Ready; inspectedAt: number };
+export type Prepared = { row: WakeRow } | { record: Seat; ready: Ready; inspectedAt: number };
 
 const pollMs = 50;
 /** A runtime heartbeat older than this is not a live Pi (the extension beats every 15 s). */
@@ -40,11 +40,11 @@ const timeouts = () => {
   return { step: explicit ?? 30_000, idle: explicit ?? 300_000 };
 };
 const pause = (milliseconds: number) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-const row = (seat: string, outcome: Outcome, detail?: string): WakeRow => ({ seat, outcome, ...(detail ? { detail } : {}) });
-const hold = (seat: string, outcome: Outcome, detail: string): { row: WakeRow } => ({ row: row(seat, outcome, detail) });
+export const row = (seat: string, outcome: Outcome, detail?: string): WakeRow => ({ seat, outcome, ...(detail ? { detail } : {}) });
+export const hold = (seat: string, outcome: Outcome, detail: string): { row: WakeRow } => ({ row: row(seat, outcome, detail) });
 const object = (value: unknown): Record<string, unknown> | undefined => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
 const text = (value: unknown) => typeof value === "string" ? value : undefined;
-const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+export const message = (error: unknown) => error instanceof Error ? error.message : String(error);
 
 /** Polls until `read` yields a value or the bound elapses; one read always happens. */
 async function until<T>(read: () => Promise<T | undefined>, timeoutMs: number) {
@@ -77,7 +77,7 @@ export function parseWakeArguments(args: string[]): Options {
   return { ...(targets[0] ? { target: targets[0] } : {}), ...(scope ? { scope } : {}), ...(profile ? { profile } : {}), by };
 }
 
-async function herdr(session: string, ...args: string[]) {
+export async function herdr(session: string, ...args: string[]) {
   const child = Bun.spawn(["herdr", "--session", session, ...args], { stdout: "pipe", stderr: "pipe" });
   const [stdout, stderr, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
   if (code !== 0) throw new Error(`herdr ${args.slice(0, 2).join(" ")} failed: ${stderr.trim() || stdout.trim()}`);
@@ -100,7 +100,7 @@ async function observe(session: string, pane: string): Promise<Pane> {
 }
 
 /** The transcript's active branch: the chain from the newest entry, excluding abandoned siblings. */
-const readBranch = async (path: string) => activeBranch(parseTranscript(await readFile(path, "utf8")));
+export const readBranch = async (path: string) => activeBranch(parseTranscript(await readFile(path, "utf8")));
 
 /** Resolve a profile mapping for the seat's current model. `{}` means wake without a swap. */
 function resolveSwap(portfolio: ModelPortfolio, profile: string, branch: TranscriptEntry[]): { candidate?: string; target?: Target } | { refused: string } {
@@ -161,7 +161,7 @@ const capabilityOf = (branch: TranscriptEntry[], ready: Ready, address: string)
   customEntries(branch, wakeCapabilityType).filter((entry) => entry.data?.seat === address && entry.data.pi_session === ready.sessionId && entry.data.pane === ready.pane);
 
 /** Classify one seat without sending anything; every non-eligible seat resolves to its final row. */
-async function prepare(root: string, address: string, actor: string): Promise<Prepared> {
+export async function prepare(root: string, address: string, actor: string): Promise<Prepared> {
   if (address === actor) return hold(address, "skipped", "invoking seat");
   const record = await readYaml<Seat>(paths(root).seatFile(address)).catch(() => undefined);
   if (!record) return hold(address, "skipped", "no seat record");
@@ -248,7 +248,7 @@ async function seatAddresses(root: string, project: string) {
 }
 
 /** Authorization is by address: the operator may wake anything; a project main only its own project. */
-async function targetAddresses(root: string, options: Options, actor: string) {
+export async function targetAddresses(root: string, options: Options, actor: string) {
   const operator = actor === "operator@desk";
   if (options.target) {
     const target = await canonicalAddress(root, options.target), project = addressParts(target).project;

package/src/seats.ts

@@ -5,7 +5,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { discoverAddress, discoverHerdrLocator, notify } from "./adapters";
 import {
   type Checkpoint, type Desk, type ModelCandidate, type ModelPortfolio, type Project, type Role, type Runtime, type Seat,
-  atomicYaml, canonicalAddress, desk, exists, fill, has, migrateDesk, modelPortfolio, now, paths, project, readYaml,
+  addressAliasResolver, atomicYaml, canonicalAddress, desk, exists, fill, has, herdrPaneId, migrateDesk, modelPortfolio, now, paths, project, readYaml,
   required, run, runOutput, runtimeAddress, seat, taskId, words, yaml,
 } from "./core";
 import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
@@ -65,12 +65,16 @@ export async function migrate(root: string) {
   await projectCollaborationPolicy(root);
 }
 
-export async function initProject(root: string, name: string) {
+const initUsage = "Use `atdd-flow project init <project> [--vcs <git|jj>]`; new projects default to Jujutsu (jj).";
+
+/** New projects default to Jujutsu; Git is an explicit per-project opt-out. Legacy records without `vcs` keep reading as Git. */
+export async function initProject(root: string, name: string, args: string[] = []) {
+  if (args.length && (args.length !== 2 || args[0] !== "--vcs" || (args[1] !== "git" && args[1] !== "jj"))) throw new Error(initUsage);
   await desk(root);
-  const config: Project = { schema: "atdd-workflow/project/v1", project: name, roles: defaultRoles(Boolean(await modelPortfolio(root))) };
+  const config: Project = { schema: "atdd-workflow/project/v1", project: name, roles: defaultRoles(Boolean(await modelPortfolio(root))), vcs: (args[1] ?? "jj") as "git" | "jj" };
   await mkdir(paths(root).seats(name), { recursive: true });
   await atomicYaml(paths(root).projectFile(name), config);
-  console.log(`Initialized project ${name}`);
+  console.log(`Initialized project ${name} (vcs: ${config.vcs})`);
 }
 
 const configureUsage = "Use `atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]`.";
@@ -197,7 +201,7 @@ export async function configureProject(root: string, name: string, args: string[
   const repositoryPath = configuredRepository ? resolve(configuredRepository) : undefined;
   if (repositoryPath && (repository || selectedVcs)) {
     try { await assertRepository(mode, repositoryPath); }
-    catch (error) { throw new Error((error as Error).message); }
+    catch (error) { throw new Error(mode === "jj" && !selectedVcs ? `${(error as Error).message} Project ${name} uses Jujutsu by default; colocate the checkout with \`jj git init --colocate\` or opt out with \`--vcs git\`.` : (error as Error).message); }
     config.repository = repositoryPath;
   }
   if (selectedVcs) config.vcs = mode;
@@ -251,7 +255,7 @@ async function taskCoordinatorBase(root: string, config: Project, task: Task, re
     const head = await runOutput(["git", "-C", coordinator.worktree, "rev-parse", "HEAD"]);
     if (head !== branchHead) throw new Error(`Coordinator ${coordinator.address} head is stale relative to ${branch}.`);
   } else {
-    try { await assertBranchReady(mode, coordinator.worktree, branch); }
+    try { await assertBranchReady(mode, coordinator.worktree, branch, coordinator.role === "main"); }
     catch (error) { throw new Error(`Coordinator ${coordinator.address} is not ready: ${(error as Error).message}`); }
   }
   return { coordinator, branch, commit: branchHead };
@@ -327,7 +331,7 @@ async function spawnTaskDriver(root: string, config: Project, role: Role, name:
     const currentBranch = await branchCommit(mode, base.coordinator.worktree, coordinatorBase.branch);
     if (currentBranch !== coordinatorBase.commit) throw new Error(`Coordinator ${base.coordinator.address} advanced during driver provisioning.`);
     if (!baseArgument) {
-      const current = await assertBranchReady(mode, base.coordinator.worktree, coordinatorBase.branch);
+      const current = await assertBranchReady(mode, base.coordinator.worktree, coordinatorBase.branch, base.coordinator.role === "main");
       if (current !== coordinatorBase.commit) throw new Error(`Coordinator ${base.coordinator.address} advanced during driver provisioning.`);
     }
     await atomicYaml(paths(root).seatFile(address), record);
@@ -397,7 +401,7 @@ export async function bind(root: string, address: string, args: string[], select
   const nativeAddress = required(words(args, "--address"), "--address");
   const requestedSession = words(args, "--session");
   const addresses = record.runtime?.addresses ?? {};
-  const runtimeBinding = application === "herdr" && requestedSession ? { session: requestedSession, pane: nativeAddress } : nativeAddress;
+  const runtimeBinding = application === "herdr" && requestedSession ? { session: requestedSession, pane: herdrPaneId(requestedSession, nativeAddress) } : nativeAddress;
   record.runtime = {
     ...record.runtime,
     application,
@@ -493,11 +497,12 @@ export async function openSeat(root: string, address: string) {
   const checkpointFile = paths(root).checkpointFile(resolved);
   if (await exists(checkpointFile)) console.log(yaml.print(await readYaml<Checkpoint>(checkpointFile)));
   const threadIds = await readdir(paths(root).threads);
+  const resolve = await addressAliasResolver(root);
   for (const threadId of threadIds) {
     const file = paths(root).threadFile(threadId);
     if (!await exists(file)) continue;
     const entry = await readYaml<{ participants: string[]; state: string; subject: string }>(file);
-    if (entry.participants.includes(resolved)) console.log(`${threadId}  ${entry.state}  ${entry.subject}`);
+    if (entry.participants.map(resolve).includes(resolved)) console.log(`${threadId}  ${entry.state}  ${entry.subject}`);
   }
   console.log(`Convention: ${lifecycleConventionPath}`);
 }

package/src/task-supersede-authorization.ts

@@ -7,7 +7,7 @@
 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";
+import { addressAliasResolver, 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 = {
@@ -26,6 +26,7 @@ const sha256 = (content: string) => createHash("sha256").update(content).digest(
 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 resolve = await addressAliasResolver(root);
   const matches = (await Promise.all(folders.filter((entry) => entry.isDirectory() && entry.name.startsWith("T-"))
     .map(async (entry) => {
       try {
@@ -36,7 +37,7 @@ export async function operatorAuthorizationPayload(root: string, reference: stri
         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?.thread.schema === "atdd-workflow/thread/v1" && entry.thread.participants?.map(resolve).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.`);

package/src/threads.ts

@@ -4,7 +4,7 @@ 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,
+  addressAliasResolver, atomicYaml, canonicalAddress, desk, has, id, now, paths, project, readYaml,
   required, runtimeAddress, seat, words,
 } from "./core";
 
@@ -33,14 +33,27 @@ export type Message = {
   authorization?: TransferAuthorization | SupersedeAuthorization;
 };
 
-async function thread(root: string, threadId: string) {
-  return readYaml<Thread>(paths(root).threadFile(threadId));
+type Resolve = (address: string) => string;
+
+/** A thread as its current seats see it: addresses written before a seat rename read as the new address. The file is untouched. */
+export function canonicalThread(record: Thread, resolve: Resolve): Thread {
+  return { ...record, participants: [...new Set(record.participants.map(resolve))] };
+}
+
+export function canonicalMessage(message: Message, resolve: Resolve): Message {
+  return { ...message, from: resolve(message.from), to: message.to === "all" ? "all" : [...new Set(message.to.map(resolve))] };
+}
+
+async function thread(root: string, threadId: string, resolve?: Resolve) {
+  const record = await readYaml<Thread>(paths(root).threadFile(threadId));
+  return canonicalThread(record, resolve ?? await addressAliasResolver(root));
 }
 
-export async function messages(root: string, threadId: string) {
+export async function messages(root: string, threadId: string, resolve?: Resolve) {
   const folder = paths(root).thread(threadId);
   const files = (await readdir(folder)).filter((file) => file.startsWith("M-") && file.endsWith(".yaml")).sort();
-  return Promise.all(files.map((file) => readYaml<Message>(`${folder}/${file}`)));
+  const resolver = resolve ?? await addressAliasResolver(root);
+  return Promise.all(files.map(async (file) => canonicalMessage(await readYaml<Message>(`${folder}/${file}`), resolver)));
 }
 
 async function replyTarget(root: string, threadId: string, messageId: string, from: string, needsResult: boolean) {
@@ -384,9 +397,10 @@ export function pendingResponders(participants: string[], all: Message[], messag
 
 export async function status(root: string) {
   const threadIds = (await readdir(paths(root).threads)).sort();
+  const resolve = await addressAliasResolver(root);
   for (const threadId of threadIds) {
-    const record = await thread(root, threadId);
-    const all = await messages(root, threadId);
+    const record = await thread(root, threadId, resolve);
+    const all = await messages(root, threadId, resolve);
     const pending = all.flatMap((message) => message.expects_result
       ? pendingResponders(record.participants, all, message).map((address) => `${message.id}@${address}`) : []);
     console.log(`${threadId}  ${record.state}  ${record.subject}${pending.length ? `  waiting:${pending.join(",")}` : ""}`);
@@ -396,7 +410,8 @@ export async function status(root: string) {
 export async function threadsForSeat(root: string, address: string) {
   const resolved = await canonicalAddress(root, address);
   const threadIds = await readdir(paths(root).threads);
-  const records = await Promise.all(threadIds.map(async (threadId) => ({ threadId, record: await thread(root, threadId) })));
+  const resolve = await addressAliasResolver(root);
+  const records = await Promise.all(threadIds.map(async (threadId) => ({ threadId, record: await thread(root, threadId, resolve) })));
   return records.filter(({ record }) => record.participants.includes(resolved));
 }
 

package/src/vcs.ts

@@ -103,7 +103,11 @@ export async function isAncestor(cwd: string, ancestor: string, descendant: stri
   catch { return false; }
 }
 
-export async function assertBranchReady(mode: VcsMode, cwd: string, branch: string) {
+/**
+ * A branch is ready when its checkout is clean and at the branch tip. `allowDirtyParent` additionally accepts a Jujutsu working copy
+ * whose parent is exactly the branch tip with uncommitted changes (a migrated dirty primary); conflicts and any other lineage stay refused.
+ */
+export async function assertBranchReady(mode: VcsMode, cwd: string, branch: string, allowDirtyParent = false) {
   if (mode === "git") {
     if (await runOutput(["git", "-C", cwd, "status", "--porcelain"])) throw new Error(`Worktree ${cwd} is dirty.`);
     const checkedOut = await runOutput(["git", "-C", cwd, "branch", "--show-current"]);
@@ -120,7 +124,7 @@ export async function assertBranchReady(mode: VcsMode, cwd: string, branch: stri
       runOutput(["jj", "log", "-r", "@-", "--no-graph", "-T", "commit_id"], cwd),
       runOutput(["jj", "diff", "-r", "@", "--name-only"], cwd),
     ]);
-    if (parent === expected && !changed) return expected;
+    if (parent === expected && (!changed || allowDirtyParent)) return expected;
   }
   throw new Error(`Worktree ${cwd} is stale relative to ${branch}.`);
 }