@afokapu/atdd-flow 0.2.0

package/src/reviews.ts

@@ -0,0 +1,448 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { launchedAddress, launchCommand, notify } from "./adapters";
+import {
+  type Seat, atomicYaml, canonicalAddress, desk, exists, id, modelPortfolio, now, paths, project,
+  readYaml, required, runOutput, seat, values, words, yaml,
+} from "./core";
+import {
+  type JudgmentOptions, type ReviewRoutingResponse, routeBehavioralReview, selectModel,
+} from "./judgment";
+import { availableModelCandidates, bind, resolveExecutable, resolveModelCommand } from "./seats";
+import { type Task } from "./tasks";
+
+const conventionRule = "atdd-bun.review.behavioral-reconciliation";
+const conventionRelativePath = "conventions/atdd-bun.review/atdd-bun.review.behavioral-reconciliation.convention.yaml";
+
+export type BehavioralReviewDecision = "APPROVE" | "RETURN" | "ESCALATE";
+export type BehavioralReviewResult = {
+  intent: { sources: string[]; expected_behavior: string };
+  exercise: { boundary: string; evidence: string[] };
+  observed: { behavior: string };
+  reconciliation: {
+    intent_matches_runtime: boolean;
+    proof_matches_intent: boolean;
+    missing_behavior: string[];
+    unexpected_behavior: string[];
+    drift: string[];
+  };
+  decision: BehavioralReviewDecision;
+  rationale: string;
+  confidence: number;
+};
+
+export type BehavioralReviewAttempt = {
+  id: string;
+  status: "pending" | "complete";
+  created_at: string;
+  completed_at?: string;
+  delivery_head: string;
+  routing: {
+    classification: "LOCAL" | "ASSEMBLED" | "JOURNEY" | "SYSTEM";
+    confidence: number;
+    signals: {
+      behaviorEffect: "BEHAVIOR_AFFECTING" | "BEHAVIOR_PRESERVING";
+      proofBoundary: "LOCAL_ACCEPTANCE" | "ASSEMBLED_API_RUNTIME" | "INTERLOCKING_ROUTE" | "TRAIN" | "USER_JOURNEY";
+      crossesMultiplePaths: boolean;
+      consequence: "ORDINARY" | "HIGH_CONSEQUENCE";
+      reconciliation: "SINGLE_PATH" | "MULTI_PATH_SYSTEM";
+      runtimeObservation: "AVAILABLE" | "NOT_AVAILABLE";
+    };
+  };
+  reviewer: { address: string; model: string };
+  convention: { rule_id: string; path: string; package_version: string };
+  input: {
+    task: { title: string; body?: string; source?: string; done_when: Array<{ text: string; proof?: string }> };
+    plan_artifacts: string[];
+    deterministic_gates: string[];
+    executable_proof: string[];
+    runtime: { worktree: string; branch: string; head: string };
+    implementation: { changed_files: string[]; diff_command: string };
+  };
+  result?: BehavioralReviewResult;
+};
+
+export type BehavioralReviewHistory = {
+  schema: "atdd-workflow/behavioral-reviews/v1";
+  task: string;
+  attempts: BehavioralReviewAttempt[];
+};
+
+async function readTask(root: string, projectName: string, taskId: string) {
+  const task = await readYaml<Task>(paths(root).taskFile(projectName, taskId));
+  if (task.schema !== "atdd-workflow/task/v1") throw new Error(`Unsupported task schema: ${taskId}`);
+  return task;
+}
+
+export async function readBehavioralReviews(root: string, projectName: string, taskId: string): Promise<BehavioralReviewHistory | undefined> {
+  const file = paths(root).behavioralReviewFile(projectName, taskId);
+  if (!await exists(file)) return undefined;
+  const history = await readYaml<BehavioralReviewHistory>(file);
+  if (history.schema !== "atdd-workflow/behavioral-reviews/v1") throw new Error(`Unsupported behavioral review schema: ${taskId}`);
+  return history;
+}
+
+async function writeBehavioralReviews(root: string, projectName: string, taskId: string, history: BehavioralReviewHistory) {
+  await atomicYaml(paths(root).behavioralReviewFile(projectName, taskId), history);
+}
+
+async function ownerForTask(root: string, task: Task) {
+  return seat(root, required(task.assignee, "a task assignee for behavioral review"));
+}
+
+async function explicitWorkflowProfile(worktree: string) {
+  const file = join(worktree, "atdd-bun.yaml");
+  if (!await exists(file)) return false;
+  const config = await readYaml<{ profiles?: string[] }>(file);
+  return Array.isArray(config.profiles) && config.profiles.includes("workflow");
+}
+
+export async function behavioralReviewRequired(root: string, task: Task) {
+  if (!task.assignee) return false;
+  const owner = await ownerForTask(root, task);
+  const config = await project(root, owner.project);
+  const policyRoot = config.repository ?? (await seat(root, task.coordinator)).worktree;
+  return explicitWorkflowProfile(policyRoot);
+}
+
+async function currentHead(worktree: string) {
+  return runOutput(["git", "rev-parse", "HEAD"], worktree);
+}
+
+async function assertCleanDelivery(worktree: string) {
+  const dirty = await runOutput(["git", "status", "--porcelain"], worktree);
+  if (dirty) throw new Error("Final behavioral review requires a clean committed delivery worktree.");
+}
+
+async function changedFiles(worktree: string, base: string) {
+  const outputs = await Promise.allSettled([
+    runOutput(["git", "diff", "--name-only", `${base}...HEAD`], worktree),
+    runOutput(["git", "diff", "--name-only"], worktree),
+    runOutput(["git", "diff", "--name-only", "--cached"], worktree),
+    runOutput(["git", "ls-files", "--others", "--exclude-standard"], worktree),
+  ]);
+  return [...new Set(outputs.flatMap((output) => output.status === "fulfilled"
+    ? output.value.split("\n").map((entry) => entry.trim()).filter(Boolean)
+    : []
+  ))].slice(0, 200);
+}
+
+async function planArtifacts(worktree: string) {
+  try {
+    const output = await runOutput(["git", "ls-files", "plan"], worktree);
+    return output.split("\n").map((entry) => entry.trim()).filter((entry) => entry.endsWith(".yaml")).slice(0, 400);
+  } catch {
+    return [];
+  }
+}
+
+async function convention(worktree: string) {
+  const packageRoot = join(worktree, "node_modules", "@afokapu", "atdd-bun");
+  const file = join(packageRoot, conventionRelativePath);
+  if (!await exists(file)) {
+    throw new Error(`Installed ATDD Bun does not provide ${conventionRule}; upgrade @afokapu/atdd-bun before final behavioral review.`);
+  }
+  const packageJson = await readFile(join(packageRoot, "package.json"), "utf8");
+  const packageVersion = String(JSON.parse(packageJson).version ?? "unknown");
+  return { path: conventionRelativePath, absolutePath: file, packageVersion, text: await readFile(file, "utf8") };
+}
+
+function conservativeRouting(): Extract<ReviewRoutingResponse, { available: true }> {
+  return {
+    available: true,
+    classification: "SYSTEM",
+    confidence: 0,
+    signals: {
+      behaviorEffect: "BEHAVIOR_AFFECTING",
+      proofBoundary: "USER_JOURNEY",
+      crossesMultiplePaths: true,
+      consequence: "HIGH_CONSEQUENCE",
+      reconciliation: "MULTI_PATH_SYSTEM",
+      runtimeObservation: "NOT_AVAILABLE",
+    },
+  };
+}
+
+async function route(
+  root: string,
+  projectName: string,
+  taskId: string,
+  task: Task,
+  owner: Seat,
+  options: JudgmentOptions = {},
+) {
+  const config = await project(root, projectName);
+  const role = config.roles[owner.role];
+  const base = role?.base ?? config.roles.coordinator?.branch ?? "main";
+  const [files, plans] = await Promise.all([changedFiles(owner.worktree, base), planArtifacts(owner.worktree)]);
+  const judgment = await routeBehavioralReview({
+    title: task.title,
+    ...(task.body ? { body: task.body } : {}),
+    ...(task.source ? { source: task.source } : {}),
+    doneWhen: task.done_when,
+    changedFiles: files,
+    planArtifacts: plans,
+  }, options);
+  return {
+    routing: judgment.available ? judgment : conservativeRouting(),
+    files,
+    plans,
+    base,
+  };
+}
+
+function reviewAddress(projectName: string, taskId: string) {
+  return `reviewer.${taskId}@${projectName}`;
+}
+
+async function writeReviewerSeat(root: string, projectName: string, taskId: string, owner: Seat) {
+  const address = reviewAddress(projectName, taskId);
+  const file = paths(root).seatFile(address);
+  const previous = await exists(file) ? await readYaml<Seat>(file) : undefined;
+  const record: Seat = {
+    schema: "atdd-workflow/seat/v2",
+    address,
+    role: "reviewer",
+    project: projectName,
+    worktree: owner.worktree,
+    branch: owner.branch,
+    purpose: `Perform final behavioral reconciliation for ${projectName}/${taskId}; never mutate task state.`,
+    ...(previous?.runtime ? { runtime: previous.runtime } : {}),
+  };
+  await atomicYaml(file, record);
+  return record;
+}
+
+function reviewerNotice(projectName: string, taskId: string, attempt: BehavioralReviewAttempt, conventionText: string) {
+  const resultPath = `/tmp/atdd-workflow-${taskId}-behavioral-review.yaml`;
+  return [
+    `SYSTEM: you are ${attempt.reviewer.address}. You are the independent final behavioral reviewer for ${projectName}/${taskId}.`,
+    "Do not mutate task state, acceptance intent, or implementation. Perform only the final semantic reconciliation defined below.",
+    "",
+    "AUTHORITATIVE METHOD (ATDD Bun):",
+    conventionText,
+    "",
+    "READ INPUTS IN THIS ORDER:",
+    `1. Task criteria/source: atdd-flow task open ${projectName} ${taskId}`,
+    `2. Plan artifacts: ${attempt.input.plan_artifacts.join(", ") || "(none discovered)"}`,
+    `3. Deterministic gates: ${attempt.input.deterministic_gates.join("; ")}`,
+    `4. Executable proof: ${attempt.input.executable_proof.join("; ") || "(none)"}`,
+    `5. Runtime/worktree: ${attempt.input.runtime.worktree} @ ${attempt.input.runtime.head}`,
+    `6. Implementation only after reconstructing the behavioral oracle: ${attempt.input.implementation.diff_command}`,
+    "",
+    `Write the structured review result to ${resultPath} with intent, exercise, observed, reconciliation, decision, rationale, and confidence, then persist it with:`,
+    `atdd-flow behavioral-review record ${projectName} ${taskId} --by ${attempt.reviewer.address} --file ${resultPath}`,
+    "Allowed decisions: APPROVE, RETURN, ESCALATE. Do not directly return, block, or complete the task.",
+  ].join("\n");
+}
+
+export async function launchBehavioralReview(
+  root: string,
+  projectName: string,
+  taskId: string,
+  args: string[],
+  options: JudgmentOptions = {},
+) {
+  const task = await readTask(root, projectName, taskId);
+  if (task.status !== "review") throw new Error(`Task ${taskId} must be in review before behavioral review.`);
+  const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
+  if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may launch final behavioral review for ${taskId}.`);
+  if (!task.done_when.every((entry) => Boolean(entry.proof))) throw new Error(`Task ${taskId} is missing delivery proof.`);
+
+  const owner = await ownerForTask(root, task);
+  await assertCleanDelivery(owner.worktree);
+
+  let gateOutput: string;
+  try {
+    gateOutput = await runOutput(["atdd-bun"], owner.worktree);
+  } catch (error) {
+    throw new Error(`Deterministic ATDD Bun gates are red; do not invoke the semantic reviewer: ${(error as Error).message}`);
+  }
+
+  const conventionSource = await convention(owner.worktree);
+  const routed = await route(root, projectName, taskId, task, owner, options);
+  const config = await desk(root);
+  const portfolio = await modelPortfolio(root);
+  let modelId: string;
+  let agent: string;
+  let modelArgs: string[] = [];
+  if (portfolio) {
+    const candidates = availableModelCandidates(config, portfolio);
+    if (!candidates.length) throw new Error("No enabled model in models.yaml has an available executable for behavioral review.");
+    const selection = routed.routing.confidence < 0.75 ? undefined : await selectModel({
+      seat: { address: reviewAddress(projectName, taskId), role: "reviewer", purpose: "Final behavioral reconciliation" },
+      tasks: [{ id: taskId, title: task.title, status: task.status, ...(task.body ? { body: task.body } : {}), doneWhen: task.done_when.map((entry) => entry.text) }],
+      candidates,
+      reviewRouting: {
+        classification: routed.routing.classification,
+        confidence: routed.routing.confidence,
+        signals: routed.routing.signals,
+      },
+    }, options);
+    const selected = selection?.available
+      ? required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`)
+      : candidates[0]!;
+    const command = resolveModelCommand(config, selected);
+    modelId = selected.id;
+    agent = command.agent;
+    modelArgs = command.args;
+  } else {
+    const coordinator = await seat(root, task.coordinator);
+    const legacyAgent = required(coordinator.agent, "models.yaml or a legacy coordinator agent for behavioral review");
+    modelId = legacyAgent;
+    agent = resolveExecutable(config, legacyAgent);
+  }
+
+  const reviewer = await writeReviewerSeat(root, projectName, taskId, owner);
+  const head = await currentHead(owner.worktree);
+  const history = await readBehavioralReviews(root, projectName, taskId) ?? {
+    schema: "atdd-workflow/behavioral-reviews/v1" as const,
+    task: `${projectName}/${taskId}`,
+    attempts: [],
+  };
+  if (history.attempts.at(-1)?.status === "pending") throw new Error(`Task ${taskId} already has a pending behavioral review.`);
+
+  const attempt: BehavioralReviewAttempt = {
+    id: id("R"),
+    status: "pending",
+    created_at: now(),
+    delivery_head: head,
+    routing: {
+      classification: routed.routing.classification,
+      confidence: routed.routing.confidence,
+      signals: routed.routing.signals,
+    },
+    reviewer: { address: reviewer.address, model: modelId },
+    convention: { rule_id: conventionRule, path: conventionSource.path, package_version: conventionSource.packageVersion },
+    input: {
+      task: {
+        title: task.title,
+        ...(task.body ? { body: task.body } : {}),
+        ...(task.source ? { source: task.source } : {}),
+        done_when: task.done_when,
+      },
+      plan_artifacts: routed.plans,
+      deterministic_gates: [`atdd-bun: PASS${gateOutput ? ` — ${gateOutput.slice(0, 500)}` : ""}`, ...values(args, "--gate")],
+      executable_proof: task.done_when.flatMap((entry) => entry.proof ? [entry.proof] : []),
+      runtime: { worktree: owner.worktree, branch: owner.branch, head },
+      implementation: {
+        changed_files: routed.files,
+        diff_command: `git diff ${routed.base}...HEAD`,
+      },
+    },
+  };
+  history.attempts.push(attempt);
+  await writeBehavioralReviews(root, projectName, taskId, history);
+
+  const application = required(words(args, "--application"), "--application");
+  const placement = required(words(args, "--placement"), "--placement");
+  let output: string;
+  try {
+    output = await runOutput(launchCommand({
+      application,
+      placement,
+      name: reviewer.address,
+      worktree: reviewer.worktree,
+      agent,
+      args: modelArgs,
+      root,
+      seat: reviewer.address,
+      environment: {
+        ATDD_WORKFLOW_REVIEW_TASK: `${projectName}/${taskId}`,
+        ATDD_WORKFLOW_REVIEW_ID: attempt.id,
+      },
+    }));
+  } catch (error) {
+    history.attempts.pop();
+    await writeBehavioralReviews(root, projectName, taskId, history);
+    throw error;
+  }
+  const nativeAddress = launchedAddress(application, placement, output);
+  await bind(root, reviewer.address, ["--application", application, "--address", nativeAddress], modelId);
+  try {
+    await notify(application, nativeAddress, reviewerNotice(projectName, taskId, attempt, conventionSource.text));
+  } catch (error) {
+    console.warn(`Behavioral review notification for ${reviewer.address} was not delivered: ${(error as Error).message}`);
+  }
+  console.log(`${attempt.id}  ${routed.routing.classification}  ${modelId}`);
+}
+
+function stringArray(value: unknown, label: string) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(`${label} must be a string array.`);
+  return value as string[];
+}
+
+function stringValue(value: unknown, label: string) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is required.`);
+  return value;
+}
+
+function booleanValue(value: unknown, label: string) {
+  if (typeof value !== "boolean") throw new Error(`${label} must be boolean.`);
+  return value;
+}
+
+function validateResult(value: unknown): BehavioralReviewResult {
+  if (!value || typeof value !== "object") throw new Error("Behavioral review result must be a mapping.");
+  const result = value as Record<string, any>;
+  const decision = result.decision;
+  if (!["APPROVE", "RETURN", "ESCALATE"].includes(decision)) throw new Error("decision must be APPROVE, RETURN, or ESCALATE.");
+  const confidence = Number(result.confidence);
+  if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error("confidence must be between 0 and 1.");
+  return {
+    intent: {
+      sources: stringArray(result.intent?.sources, "intent.sources"),
+      expected_behavior: stringValue(result.intent?.expected_behavior, "intent.expected_behavior"),
+    },
+    exercise: {
+      boundary: stringValue(result.exercise?.boundary, "exercise.boundary"),
+      evidence: stringArray(result.exercise?.evidence, "exercise.evidence"),
+    },
+    observed: { behavior: stringValue(result.observed?.behavior, "observed.behavior") },
+    reconciliation: {
+      intent_matches_runtime: booleanValue(result.reconciliation?.intent_matches_runtime, "reconciliation.intent_matches_runtime"),
+      proof_matches_intent: booleanValue(result.reconciliation?.proof_matches_intent, "reconciliation.proof_matches_intent"),
+      missing_behavior: stringArray(result.reconciliation?.missing_behavior, "reconciliation.missing_behavior"),
+      unexpected_behavior: stringArray(result.reconciliation?.unexpected_behavior, "reconciliation.unexpected_behavior"),
+      drift: stringArray(result.reconciliation?.drift, "reconciliation.drift"),
+    },
+    decision,
+    rationale: stringValue(result.rationale, "rationale"),
+    confidence,
+  };
+}
+
+export async function recordBehavioralReview(root: string, projectName: string, taskId: string, args: string[]) {
+  const task = await readTask(root, projectName, taskId);
+  if (task.status !== "review") throw new Error(`Task ${taskId} must still be in review when the behavioral result is recorded.`);
+  const history = required(await readBehavioralReviews(root, projectName, taskId), `a pending behavioral review for ${taskId}`);
+  const attempt = required([...history.attempts].reverse().find((entry) => entry.status === "pending"), `a pending behavioral review for ${taskId}`);
+  const actor = required(words(args, "--by"), "--by");
+  if (actor !== attempt.reviewer.address) throw new Error(`Only ${attempt.reviewer.address} may record review ${attempt.id}.`);
+  const owner = await ownerForTask(root, task);
+  await assertCleanDelivery(owner.worktree);
+  if (await currentHead(owner.worktree) !== attempt.delivery_head) throw new Error("Delivery HEAD changed during behavioral review; launch a new review against the current delivery.");
+  const file = required(words(args, "--file"), "--file");
+  const result = validateResult(yaml.parse(await readFile(file, "utf8")));
+  attempt.status = "complete";
+  attempt.completed_at = now();
+  attempt.result = result;
+  await writeBehavioralReviews(root, projectName, taskId, history);
+  console.log(`${attempt.id}  ${result.decision}`);
+}
+
+export async function openBehavioralReview(root: string, projectName: string, taskId: string) {
+  const history = required(await readBehavioralReviews(root, projectName, taskId), `behavioral review history for ${taskId}`);
+  console.log(yaml.print(history));
+}
+
+export async function assertAcceptedBehavioralReview(root: string, projectName: string, taskId: string, task: Task) {
+  if (!await behavioralReviewRequired(root, task)) return;
+  const history = required(await readBehavioralReviews(root, projectName, taskId), `final behavioral review for ${taskId}`);
+  const latest = required(history.attempts.at(-1), `final behavioral review attempt for ${taskId}`);
+  if (latest.status !== "complete" || !latest.result) throw new Error(`Task ${taskId} has no completed final behavioral review.`);
+  if (latest.result.decision !== "APPROVE") throw new Error(`Task ${taskId} final behavioral review is ${latest.result.decision}, not APPROVE.`);
+  const owner = await ownerForTask(root, task);
+  await assertCleanDelivery(owner.worktree);
+  if (await currentHead(owner.worktree) !== latest.delivery_head) throw new Error(`Task ${taskId} changed after final behavioral review; review the current delivery before completion.`);
+}

package/src/seats.ts

@@ -0,0 +1,233 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { discoverAddress, launchedAddress, launchCommand, notify } from "./adapters";
+import {
+  type Checkpoint, type Desk, type ModelCandidate, type ModelPortfolio, type Project, type Role, type Seat,
+  atomicYaml, canonicalAddress, desk, exists, fill, migrateDesk, modelPortfolio, now, paths, project, readYaml,
+  required, run, runOutput, seat, words, yaml,
+} from "./core";
+import { selectModel } from "./judgment";
+import { seatTasks } from "./tasks";
+
+const defaultRoles = (dynamicModels = true): Record<string, Role> => ({
+  coordinator: {
+    address: "coordinator@{project}", branch: "main", worktree: "{repository}",
+    ...(dynamicModels ? {} : { agent: "claude" }),
+  },
+  driver: {
+    address: "driver.{name}@{project}", branch: "delivery/{name}", base: "main", worktree: "{worktree_root}/{name}",
+    ...(dynamicModels ? {} : { agent: "codex" }),
+  },
+});
+
+const defaultExecutables = () => ({ claude: "claude", codex: "codex", pi: "pi", kimi: "kimi", glm: "glm" });
+const defaultModels = (): ModelPortfolio => ({
+  schema: "atdd-workflow/models/v1",
+  models: [
+    { id: "claude", executable: "claude", description: "Default high-capability candidate; replace or refine this portfolio for the local environment." },
+    { id: "codex", executable: "codex", description: "Default lower-cost candidate." },
+  ],
+});
+
+/** Resolve the seat's named agent through the Desk-wide executable registry. */
+export function resolveExecutable(config: Desk, agent: string) {
+  return config.executables?.[agent] ?? agent;
+}
+
+export async function init(root: string, name: string, args: string[]) {
+  const config = { schema: "atdd-workflow/desk/v1" as const, desk: name, application: "tuios", executables: defaultExecutables() };
+  await Promise.all([mkdir(paths(root).work, { recursive: true }), mkdir(paths(root).threads, { recursive: true })]);
+  await Promise.all([atomicYaml(paths(root).desk, config), atomicYaml(paths(root).models, defaultModels())]);
+  if (args.includes("--git") && !await exists(join(root, ".git"))) await run(["git", "init", "--initial-branch=main", root]);
+  console.log(`Initialized Desk ${root}`);
+}
+
+export async function migrate(root: string) {
+  if (await migrateDesk(root)) console.log("Migrated legacy coordination registry to desk.yaml");
+  else console.log("Desk registry already exists");
+}
+
+export async function initProject(root: string, name: string) {
+  await desk(root);
+  const config: Project = { schema: "atdd-workflow/project/v1", project: name, roles: defaultRoles(Boolean(await modelPortfolio(root))) };
+  await mkdir(paths(root).seats(name), { recursive: true });
+  await atomicYaml(paths(root).projectFile(name), config);
+  console.log(`Initialized project ${name}`);
+}
+
+async function ensureWorktree(config: Project, role: Role, worktree: string, branch: string) {
+  if (!config.repository || worktree === resolve(config.repository) || await exists(worktree)) return;
+  await mkdir(dirname(worktree), { recursive: true });
+  const ref = `refs/heads/${branch}`;
+  const probe = Bun.spawn(["git", "-C", config.repository, "show-ref", "--verify", "--quiet", ref]);
+  const branchExists = await probe.exited === 0;
+  const command = branchExists
+    ? ["git", "-C", config.repository, "worktree", "add", worktree, branch]
+    : ["git", "-C", config.repository, "worktree", "add", "-b", branch, worktree, role.base ?? "HEAD"];
+  await run(command, true);
+}
+
+export async function spawn(root: string, projectName: string, roleName: string, name: string, args: string[]) {
+  const config = await project(root, projectName);
+  const role = required(config.roles[roleName], `role ${roleName}`);
+  const entries = { project: config.project, name, worktree_root: config.worktree_root ?? "" };
+  const address = fill(role.address, entries);
+  const configuredPath = role.worktree ? fill(role.worktree, { ...entries, repository: config.repository ?? "" }) : undefined;
+  const worktree = resolve(required(words(args, "--worktree") ?? configuredPath, "--worktree or role worktree template"));
+  const branch = words(args, "--branch") ?? fill(role.branch, { project: config.project, name });
+  await ensureWorktree(config, role, worktree, branch);
+  const purpose = words(args, "--purpose") ?? (role.purpose ? fill(role.purpose, entries) : undefined);
+  const portfolio = await modelPortfolio(root);
+  const requestedAgent = words(args, "--agent");
+  if (portfolio && requestedAgent) throw new Error("--agent is a legacy pin and cannot be used when models.yaml owns model allocation.");
+  const legacyAgent = portfolio ? undefined : requestedAgent ?? role.agent;
+  const record: Seat = {
+    schema: "atdd-workflow/seat/v2", address, role: roleName, project: config.project, worktree, branch,
+    ...(legacyAgent ? { agent: legacyAgent } : {}), ...(purpose ? { purpose } : {}),
+  };
+  await atomicYaml(paths(root).seatFile(address), record);
+  console.log(address);
+}
+
+export async function bind(root: string, address: string, args: string[], selectedModel?: string) {
+  const resolved = await canonicalAddress(root, address);
+  const record = await seat(root, resolved);
+  const config = await desk(root);
+  const application = words(args, "--application") ?? config.application;
+  if (!/^[a-z][a-z0-9_-]*$/.test(application)) throw new Error(`Application must use lowercase letters, numbers, underscores, or hyphens: ${application}`);
+  const nativeAddress = required(words(args, "--address"), "--address");
+  const addresses = record.runtime?.addresses ?? {};
+  record.runtime = {
+    ...record.runtime,
+    application,
+    addresses: { ...addresses, [application]: nativeAddress },
+    attached_at: now(),
+    ...(selectedModel ? { model: selectedModel } : {}),
+  };
+  await atomicYaml(paths(root).seatFile(resolved), record);
+  console.log(`Bound ${resolved} to ${application}:${nativeAddress}`);
+}
+
+export async function useApplication(root: string, address: string, application: string) {
+  const resolved = await canonicalAddress(root, address);
+  const record = await seat(root, resolved);
+  const runtime = required(record.runtime, `a runtime binding for ${resolved}`);
+  if (!runtime.addresses[application]) throw new Error(`${resolved} has no ${application} address. Bind it first.`);
+  record.runtime = { ...runtime, application, attached_at: now() };
+  await atomicYaml(paths(root).seatFile(resolved), record);
+  console.log(`Using ${application}:${record.runtime.addresses[application]} for ${resolved}`);
+}
+
+export async function attach(root: string, address: string, args: string[]) {
+  const application = words(args, "--application") ?? (await desk(root)).application;
+  const nativeAddress = discoverAddress(application);
+  await bind(root, address, ["--application", application, "--address", nativeAddress]);
+}
+
+export function availableModelCandidates(config: Desk, portfolio: ModelPortfolio) {
+  return portfolio.models.filter((candidate) => {
+    if (candidate.enabled === false) return false;
+    const executable = resolveExecutable(config, candidate.executable);
+    return executable.includes("/") ? existsSync(executable) : Boolean(Bun.which(executable));
+  });
+}
+
+export function resolveModelCommand(config: Desk, candidate: ModelCandidate) {
+  return { agent: resolveExecutable(config, candidate.executable), args: candidate.args ?? [] };
+}
+
+async function chooseLaunchModel(root: string, config: Desk, record: Seat, portfolio: ModelPortfolio) {
+  const candidates = availableModelCandidates(config, portfolio);
+  if (!candidates.length) throw new Error("No enabled model in models.yaml has an available executable.");
+  const work = (await seatTasks(root, record.project, record.address)).filter((entry) => entry.task.status !== "done");
+  const selection = await selectModel({
+    seat: { address: record.address, role: record.role, ...(record.purpose ? { purpose: record.purpose } : {}) },
+    tasks: work.map((entry) => ({
+      id: entry.id,
+      title: entry.task.title,
+      status: entry.task.status,
+      ...(entry.task.body ? { body: entry.task.body } : {}),
+      doneWhen: entry.task.done_when.map((item) => item.text),
+      ...(entry.task.blocker ? { blocker: entry.task.blocker } : {}),
+    })),
+    candidates,
+  });
+  if (!selection.available) {
+    console.warn(`Model selection for ${record.address} unavailable: ${selection.reason} Falling back to strongest available model.`);
+    return candidates[0]!;
+  }
+  return required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`);
+}
+
+export const launchNotice = (address: string) =>
+  `SYSTEM: you are ${address}. Read your durable seat and assigned task with: atdd-flow open ${address}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`;
+
+export async function launch(root: string, address: string, args: string[]) {
+  const resolved = await canonicalAddress(root, address);
+  const record = await seat(root, resolved);
+  const config = await desk(root);
+  const application = required(words(args, "--application"), "--application");
+  const placement = required(words(args, "--placement"), "--placement");
+  const portfolio = await modelPortfolio(root);
+  let agent: string;
+  let modelArgs: string[] = [];
+  let selectedModel: string;
+  if (portfolio) {
+    const selected = await chooseLaunchModel(root, config, record, portfolio);
+    const command = resolveModelCommand(config, selected);
+    agent = command.agent;
+    modelArgs = command.args;
+    selectedModel = selected.id;
+  } else {
+    const legacyAgent = required(record.agent, "models.yaml or a legacy seat agent");
+    agent = resolveExecutable(config, legacyAgent);
+    selectedModel = legacyAgent;
+  }
+  const output = await runOutput(launchCommand({
+    application, placement, name: resolved, worktree: record.worktree,
+    agent, args: modelArgs, root, seat: resolved,
+  }));
+  const nativeAddress = launchedAddress(application, placement, output);
+  await bind(root, resolved, ["--application", application, "--address", nativeAddress], selectedModel);
+  const notice = launchNotice(resolved);
+  try { await notify(application, nativeAddress, notice); }
+  catch (error) { console.warn(`Launch notification for ${resolved} was not delivered: ${(error as Error).message}`); }
+}
+
+export async function describe(root: string, address: string, args: string[]) {
+  const resolved = await canonicalAddress(root, address);
+  const record = await seat(root, resolved);
+  record.purpose = required(words(args, "--purpose"), "--purpose");
+  await atomicYaml(paths(root).seatFile(resolved), record);
+  console.log(`Described ${resolved}`);
+}
+
+export async function checkpoint(root: string, address: string, args: string[]) {
+  const resolved = await canonicalAddress(root, address);
+  await seat(root, resolved);
+  const references = words(args, "--references")?.split(",").filter(Boolean);
+  const record: Checkpoint = {
+    schema: "atdd-workflow/checkpoint/v1", seat: resolved,
+    status: (words(args, "--status") ?? "active") as Checkpoint["status"], updated_at: now(),
+    summary: required(words(args, "--summary"), "--summary"), next_action: required(words(args, "--next"), "--next"),
+    ...(references?.length ? { references } : {}),
+  };
+  await atomicYaml(paths(root).checkpointFile(resolved), record);
+  console.log(`Checkpointed ${resolved}`);
+}
+
+export async function openSeat(root: string, address: string) {
+  const resolved = await canonicalAddress(root, address);
+  const record = await seat(root, resolved);
+  console.log(yaml.print(record));
+  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);
+  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}`);
+  }
+}