Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

84.8 KB
Raw Blame
import { randomBytes, randomUUID } from "node:crypto";
import {
  existsSync,
  lstatSync,
  mkdirSync,
  readFileSync,
  readdirSync,
  realpathSync,
  rmSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { basename, dirname, join, resolve, sep } from "node:path";
import { type SpawnPlan, prehydrateCredentialsForSpawn } from "./auth/credentials/prehydrate.js";
import { ENV } from "./config.js";
import { writeFileAtomic } from "./fs-atomic.js";
import { UPSTREAM_ERROR_LOG_ENV } from "./handlers/shared/upstream-error-capture.js";
import type { HookEngine } from "./hooks/engine.js";
import { loadHooksOnce } from "./hooks/index.js";
import { createHookInbox } from "./hooks/injection/inbox.js";
import { HOOK_INBOX_ENV } from "./hooks/injection/sinks.js";
import type { SessionInfo as HookSessionInfo } from "./hooks/public.js";
import { HOOK_SESSION_ENV } from "./hooks/request-stage.js";
import {
  type SessionHookBinding,
  createSessionHookBinding,
  reportOwnerWithoutHooks,
  sessionHooksNeedBinding,
} from "./hooks/session/binding.js";
import { log } from "./logger.js";
import {
  type Accounting,
  type CaptureResult,
  type CaptureUnchanged,
  ContractErrorException,
  DEFAULT_PANE_COLS,
  DEFAULT_PANE_ROWS,
  type FailureReason,
  type FinalVerdict,
  MAX_LIVE_PANES,
  type PaneBlock,
  type PaneSession,
  type PaneSessionOptions,
  type PaneSnapshot,
  SLOT_STATES,
  type SettledTurn,
  type SlotRow,
  type SlotState,
  TERMINAL_STATES,
  type TeamCancelResult,
  type TeamListResult,
  type TeamResizeResult,
  type TeamRunRow,
  assertMagmuxAvailable,
  chainAnswerOf,
  checkChildFlags,
  contractMeta,
  deliveryRefusal,
  flagsRemoveRead,
  isTerminalState,
  livePaneCount,
  mergeAccounting,
  readTokenFileCached,
  reasonDetail,
  releasePaneReservations,
  reservePanes,
  resolveProvider,
  sockRootFor,
  startPaneSession,
  toSlotRow,
  upstreamRecordsFor,
} from "./pane/index.js";
import { redactSecrets } from "./redact.js";
import { projectsDir, transcriptPathFor } from "./session/session-discovery.js";
import { renderTeamStatsCompact, statsDir, tokenFileFor, writeStatusFile } from "./team-stats.js";

/*
 * Every team slot is an INTERACTIVE Claude Code session launched through claudish, in its
 * own headless magmux pane, driven by `PaneSession` (pane/). The transcript decides when a
 * turn settled and what its answer is; this file owns the TEAM policy on top of it:
 * `require_pattern` / `min_output_bytes` (`classifyRunOutput`), a slot that stops on a
 * question it cannot answer is FAILED `blocked` (D19), and the run registry the polling
 * verbs read. Rationale: ai-docs/architecture/team-lifecycle.md and team-capture.md.
 *
 * No claudish timer ends a slot after its prompt was accepted (D10). The only bounds are
 * the pane's boot (90 s) and the admission of the prompt (30 s), before any work exists.
 */

// ─── Types ───────────────────────────────────────────────────────────────────

export interface TeamManifest {
  created: string;
  models: Record<string, { model: string; assignedAt: string }>;
  shuffleOrder: string[];
}

export interface ModelError {
  /** Model ID that failed (anonymized id used in the report). */
  model: string;
  /** The command the slot ran (the pane child's claudish argv, for the reader). */
  command: string;
  /** Failure classification (the contract's closed set, pane/contract.ts). */
  reason: FailureReason;
  /** One-line human-readable explanation of `reason`. */
  detail: string;
  /** Redacted head and tail of the pane's final screen. */
  screenSnippet?: string;
  /** Redacted head and tail of the answer the slot produced. */
  answerSnippet?: string;
  /** Path to the full error log file. */
  errorLogPath: string;
  /**
   * Path to this slot's upstream-error records, when the child wrote any.
   *
   * The raw provider response body for every failed request — which is what
   * separates a retryable rate limit from a hard quota wall. Omitted when the
   * file does not exist, so this is never a dangling reference: an unwritten
   * file means the child never had an upstream failure to record.
   */
  upstreamErrorLogPath?: string;
  /** The team session directory. */
  workDir: string;
}

/**
 * One slot in `status.json`. `state` is the contract's closed nine-value set. The fields
 * after `error` are written by every pane run; they are optional in the TYPE because a
 * `status.json` written by a pre-contract claudish lacks them, and `getStatus` returns
 * whatever is on disk.
 */
export interface ModelStatus {
  state: SlotState;
  /** From the pane's exit event; null when claudish ended the pane (verdict, cancel). */
  exitCode: number | null;
  startedAt: string | null;
  completedAt: string | null;
  /** FINAL answer bytes, written once, when the slot turns terminal (team-lifecycle.md). */
  outputSize: number;
  /** Populated on FAILED / EMPTY / CANCELLED with details for the failure report. */
  error?: ModelError;
  model?: string;
  spawnModel?: string | null;
  provider?: string | null;
  sessionUuid?: string;
  transcriptPath?: string;
  pane?: string | null;
  captureSource?: "transcript" | "screen" | "none" | null;
  turnSource?: "transcript" | "screen";
  stopReason?: string | null;
  tokensIn?: number | null;
  tokensOut?: number | null;
  costUsd?: number | null;
  toolCalls?: number;
  turnsCompleted?: number;
  lastActivityAt?: string | null;
  /** The child's Claude Code version from its boot banner (R3-M4). */
  claudeCodeVersion?: string | null;
  /** Facts worth a reader's attention that are not failures (R3-M5, truncation). */
  anomalies?: string[];
}

export interface TeamStatus {
  startedAt: string;
  /** The run that wrote this file (CA-13); absent in a pre-contract file. */
  runId?: string;
  kind?: "run" | "judge";
  models: Record<string, ModelStatus>;
}

export interface TeamRunOptions {
  claudeFlags?: string[]; // extra flags passed to child claudish (checked by checkChildFlags)
  /**
   * Reasoning effort per model, keyed by the model string as the run's models give
   * it. A slot with an entry gets `--effort-override <level>` after `claudeFlags`, so
   * it wins over one there and its proxy pins that level on every request.
   */
  efforts?: Readonly<Record<string, string>>;
  onStatusChange?: (id: string, status: ModelStatus) => void;
  /**
   * Opt-in stub threshold: below this many answer bytes a settled slot is recorded
   * EMPTY. Default 0 (off) — see DEFAULT_MIN_OUTPUT_BYTES for why. Whitespace-only
   * output is caught regardless of this setting.
   */
  minOutputBytes?: number;
  /**
   * Opt-in SHAPE contract: a JS regex source string the answer must match, or the slot
   * is recorded EMPTY with reason `shape_mismatch`.
   *
   * Byte counts cannot separate a broken answer from a legitimately short one (a
   * measured 96 B reply is valid — see DEFAULT_MIN_OUTPUT_BYTES). A caller that
   * mandated an output shape, however, KNOWS what a complete answer looks like:
   * `team`'s prompts require a fenced ```vote block, so "```vote" is a precise oracle
   * where length is a guess.
   *
   * Matched with `new RegExp(pattern)` (no flags) against the FULL answer: every
   * assistant text block of the turn, joined with "\n\n", exactly as written to
   * `response-<id>.md`. For a prompt delivered as a file the answer starts with the
   * first text block AFTER the task file was fully read, so `^VERDICT:` matches an
   * answer that begins with its verdict even when the model narrated before reading.
   */
  requirePattern?: string;
  /**
   * Called on a timer with a rendered, colourless progress block, and once more
   * when the run settles. Used to push live status somewhere a human can see it
   * (MCP channel notification, terminal, log).
   *
   * `phase` MUST be honoured by consumers that model session lifecycle: without
   * a terminal `"settled"` frame, a watcher sees only "running" forever and
   * never observes the run close.
   */
  onProgress?: (update: {
    rendered: string;
    phase: "running" | "settled";
    /** True when no model produced usable output. */
    allFailed: boolean;
  }) => void;
  /**
   * Max seconds between `onProgress` calls when NOTHING has changed. Default 60.
   *
   * This is a heartbeat, not a poll rate. Each frame renders as its own new line
   * in the client, so a fixed 5s tick on a 15-minute run would print ~180 lines of
   * near-identical text. Frames are emitted when a model's STATE changes (finishes,
   * fails, produces output); this interval only bounds how long a quiet run can go
   * without proving it is still alive.
   *
   * `status.txt` is rewritten on every internal poll regardless — it is a file, so
   * frequency costs nothing there.
   */
  heartbeatSeconds?: number;
  /** Spawn-plan factory seam for hermetic call-site tests. */
  spawnPlanner?: (models: (string | undefined)[]) => Promise<SpawnPlan>;
  /**
   * Called exactly once, when the run SETTLES: after the last slot turned terminal
   * and the settled `status.txt` render, from inside `done`'s `finally`. Receives
   * the final status.
   *
   * Read inside `startModels`, so the hook exists before the first pane is
   * spawned and does not depend on anything the caller does after
   * `startModels` returns — a run that settles at once takes the same path as a
   * slow one. A throwing consumer cannot fail the run. NOT called when
   * `startModels` itself throws: no run started, and the caller settles that.
   */
  onSettled?: (status: TeamStatus) => void;
  /**
   * The environment every pane of this run is built from (X-M9). Default
   * `process.env`. The transcript path is derived with `projectsDir(parentEnv)`.
   */
  parentEnv?: Record<string, string | undefined>;
  /** "judge" for the judging/ sub-run of `judgeResponses`; default "run". */
  kind?: "run" | "judge";
  /** @internal test-only pane timing seams (X-M7); production never passes them */
  paneTimings?: PaneSessionOptions["timings"];
  /** @internal test-only boot bound; production uses the pane's 90 s */
  bootTimeoutMs?: number;
  /**
   * The hook engine slot bindings are built from. Default: the process engine
   * (`loadHooksOnce()`), awaited before the spawn loop. Tests pass their own.
   */
  hookEngine?: () => Promise<HookEngine | null>;
  /** @internal test seam (§11.5): the binding for one slot, instead of the real one */
  hookBinding?: (ctx: {
    session: HookSessionInfo;
    inboxPath: string | null;
    engine: HookEngine | null;
  }) => SessionHookBinding | null;
}

/**
 * A running team, handed back once every slot has LEFT STARTING (D9): its prompt was
 * accepted, or it failed to boot or to take the prompt.
 *
 * This is what makes a team run addressable without blocking on it. The caller
 * gets the ids it needs to ask questions later, and asks them through the polling
 * verbs (`teamRunRow`, `listTeamRuns`, `captureTeamSlot`, `getStatus`) rather than by
 * holding a tool call open for the length of the run.
 */
export interface TeamHandle {
  /**
   * Unique per start (CA-13): `<team_session_id>-<base36 start ms>-<6 hex>`. Distinct
   * even when a later run reuses `sessionPath`.
   */
  runId: string;
  /**
   * The session directory's basename. Already the id used for this run's channel
   * frames, so a caller correlating frames to a run needs no second identifier.
   */
  teamSessionId: string;
  /** Absolute session directory. `getStatus` and `judgeResponses` both take it. */
  sessionPath: string;
  /**
   * Display model → anonymised slot id, e.g. `{"grok-4.6": "02"}`.
   *
   * The slot id addresses everything on disk for that model: `response-<id>.md`,
   * `stats/<id>.json`, `errors/<id>.log`, and the per-model entry in
   * `getStatus().models`.
   */
  slots: Record<string, string>;
  /**
   * Settles when every slot is terminal. Nothing needs to await it — the run
   * completes and writes its files either way — and a caller that only polls
   * can ignore it entirely.
   */
  done: Promise<TeamStatus>;
}

export interface TeamJudgeOptions {
  judges?: string[]; // models to use as judges (default: same models as runners)
  claudeFlags?: string[];
  /** The environment the judge panes are built from; default `process.env`. */
  parentEnv?: Record<string, string | undefined>;
  /** @internal test-only pane timing seams */
  paneTimings?: PaneSessionOptions["timings"];
}

export interface VoteResult {
  judgeId: string;
  responseId: string;
  verdict: "APPROVE" | "REJECT" | "ABSTAIN";
  confidence: number;
  summary: string;
  keyIssues: string[];
}

export interface TeamVerdict {
  responses: Record<
    string,
    {
      approvals: number;
      rejections: number;
      abstentions: number;
      score: number; // approvals / (approvals + rejections)
    }
  >;
  ranking: string[]; // response IDs sorted by score descending
  votes: VoteResult[];
}

// ─── Run registry (architecture §3.2) ─────────────────────────────────────────

interface SlotEntry {
  id: string;
  model: string;
  spawnModel: string | null;
  tokenFile: string;
  /** null = the pane never spawned (its row is FAILED `pane_lost`, `pane: null`) */
  session: PaneSession | null;
  /** refreshed on the 2 s tick and on every read */
  acct: Accounting;
  /** what `response-<id>.md` holds once it was written (decide, onBlocked or terminal) */
  answer: string | null;
  stopReason: string | null;
  /** the slot's session-hook binding (§7.4); null = today's index formulas */
  binding?: SessionHookBinding | null;
  /** the owner-created hook inbox; removed at reap */
  inboxPath?: string | null;
}

interface LiveTeamRun {
  runId: string;
  /** resolved absolute session dir (was the basename: "judging" collided, F6) */
  path: string;
  kind: "run" | "judge";
  startedAt: string;
  finishedAt: string | null;
  /** the in-memory object `updateModelStatus` serialises to status.json */
  status: TeamStatus;
  slots: Map<string, SlotEntry>;
  /** resolves once `done` has ended the run's record (`onSettled`), whatever ended it */
  settled: Promise<void>;
}

/** A `startModels` still before its registry entry (credentials, the staggered spawn loop). */
interface StartFlight {
  /** set by shutdown: the loop starts no further pane and unwinds through its `catch` */
  aborted: boolean;
}

/** Every `startModels` in progress, to the promise it returns (§20.3 item 8). */
const startsInFlight = new Map<StartFlight, Promise<unknown>>();

/**
 * Runs this process started, keyed by run_id (CA-13). An ACTIVE run stays until it
 * settles; a SETTLED run stays listable and capturable for SETTLED_RUN_RETENTION_MS,
 * at most MAX_SETTLED_RUNS of them (oldest evicted first). After eviction `status` still
 * answers from `status.json` (newest run at a path only).
 */
const teamRuns = new Map<string, LiveTeamRun>();
/** resolved path → run_id of the newest run started there */
const newestRunByPath = new Map<string, string>();
export const SETTLED_RUN_RETENTION_MS = 30 * 60_000; // same as the MCP session manager's TERMINAL_RETENTION_MS
export const MAX_SETTLED_RUNS = 20;
/** Slots of one run spawn this far apart, so N REPLs do not write ~/.claude.json at once (X-L8). */
export const BOOT_STAGGER_MS = 300;

function slotTerminal(e: SlotEntry): boolean {
  if (!e.session) return true;
  return isTerminalState(e.session.snapshot().state);
}

function runSettled(run: LiveTeamRun): boolean {
  return [...run.slots.values()].every((e) => slotTerminal(e));
}

/** Set `finishedAt` the moment the last slot turned terminal. */
function markIfSettled(run: LiveTeamRun): void {
  if (run.finishedAt === null && runSettled(run)) run.finishedAt = new Date().toISOString();
}

function evictRun(run: LiveTeamRun): void {
  teamRuns.delete(run.runId);
  if (newestRunByPath.get(run.path) === run.runId) newestRunByPath.delete(run.path);
}

/** Apply the retention policy. Called on every registry read and on every new run. */
function pruneRuns(now: number = Date.now()): void {
  const settled = [...teamRuns.values()]
    .filter((r) => {
      markIfSettled(r);
      return r.finishedAt !== null;
    })
    .sort((a, b) => Date.parse(a.finishedAt as string) - Date.parse(b.finishedAt as string));
  const keep: LiveTeamRun[] = [];
  for (const r of settled) {
    if (now - Date.parse(r.finishedAt as string) > SETTLED_RUN_RETENTION_MS) evictRun(r);
    else keep.push(r);
  }
  while (keep.length > MAX_SETTLED_RUNS) evictRun(keep.shift() as LiveTeamRun);
}

/** The run a verb addresses: `run_id` while retained, else the newest run at `path`. */
function addressRun(path: string | undefined, runId?: string): LiveTeamRun | null {
  pruneRuns();
  if (runId) {
    const run = teamRuns.get(runId) ?? null;
    if (run && path !== undefined && resolve(path) !== run.path) return null;
    return run;
  }
  if (path === undefined) return null;
  const id = newestRunByPath.get(resolve(path));
  return id ? (teamRuns.get(id) ?? null) : null;
}

/** The newest run at `path` when it is still ACTIVE. */
export function activeRunAt(path: string): { runId: string } | null {
  const run = addressRun(path);
  return run && !runSettled(run) ? { runId: run.runId } : null;
}

/**
 * At most one ACTIVE run per path (§3.2). Thrown as `run`'s usual text error, never as
 * a ContractError: `run` is not a verb of the mod contract.
 */
function assertNoActiveRun(path: string): void {
  const active = activeRunAt(path);
  if (active)
    throw new Error(
      `invalid_args: a team run is already ACTIVE at ${path} (run_id ${active.runId}); cancel it or wait for it`
    );
}

function emptyAccounting(provider: string | null): Accounting {
  return { tokensIn: null, tokensOut: null, costUsd: null, toolCalls: 0, provider };
}

function refreshAccounting(e: SlotEntry, snap: PaneSnapshot): Accounting {
  e.acct = mergeAccounting(snap, readTokenFileCached(e.tokenFile), {
    model: e.model,
    spawnModel: e.spawnModel,
  });
  return e.acct;
}

/** The R3-M4 / R3-M5 anomalies a team reader must see beside the state. */
function notableAnomalies(snap: PaneSnapshot): string[] {
  return snap.anomalies.filter(
    (a) =>
      a.startsWith("background_shell_open") ||
      a.startsWith("turn_end_record_missing") ||
      a.startsWith("agent_count_mismatch") ||
      a.startsWith("prompt_not_read")
  );
}

/** `errors/<slot>-upstream.jsonl`: the child proxy's upstream-error capture for one slot. */
function upstreamLogPath(path: string, id: string): string {
  return join(path, "errors", `${id}-upstream.jsonl`);
}

function neverSpawnedRow(e: SlotEntry, m: ModelStatus | undefined): SlotRow {
  return {
    slot: e.id,
    model: e.model,
    provider: e.acct.provider,
    state: m?.state ?? "FAILED",
    reason: m?.error?.reason ?? "pane_lost",
    reason_detail: reasonDetail({
      state: m?.state ?? "FAILED",
      reason: m?.error?.reason ?? "pane_lost",
      detail: m?.error?.detail,
    }),
    tokens_in: null,
    tokens_out: null,
    cost_usd: null,
    tool_calls: 0,
    turns_completed: 0,
    last_activity_at: null,
    idle_seconds: null,
    activity: null,
    pane: null,
    recent: null,
  };
}

function liveSlotRow(run: LiveTeamRun, e: SlotEntry): SlotRow {
  if (!e.session) return neverSpawnedRow(e, run.status.models[e.id]);
  const snap = e.session.snapshot();
  return toSlotRow(
    { slot: e.id, model: e.model, spawnModel: e.spawnModel },
    snap,
    refreshAccounting(e, snap),
    Date.now(),
    upstreamRecordsFor(snap, upstreamLogPath(run.path, e.id))
  );
}

/** "ok" | "partial" | "all-failed" — the result card's words; CANCELLED counts as failed. */
function outcomeOf(states: SlotState[]): "ok" | "partial" | "all-failed" {
  const ok = states.filter((s) => s === "COMPLETED").length;
  if (ok === states.length) return "ok";
  return ok === 0 ? "all-failed" : "partial";
}

function runRow(run: LiveTeamRun): TeamRunRow {
  markIfSettled(run);
  const slots = [...run.slots.values()]
    .sort((a, b) => a.id.localeCompare(b.id))
    .map((e) => liveSlotRow(run, e));
  const settled = slots.every((s) => isTerminalState(s.state));
  return {
    run_id: run.runId,
    path: run.path,
    kind: run.kind,
    started_at: run.startedAt,
    finished_at: settled ? run.finishedAt : null,
    state: settled ? "SETTLED" : "ACTIVE",
    outcome: settled ? outcomeOf(slots.map((s) => s.state)) : null,
    slots,
  };
}

/** `run` from memory: the addressed run while retained, else null. */
export function teamRunRow(path: string | undefined, runId?: string): TeamRunRow | null {
  const run = addressRun(path, runId);
  return run ? runRow(run) : null;
}

/** True when `runId` is retained but a newer run now owns its path's status.json. */
export function isSupersededRun(runId: string): boolean {
  const run = teamRuns.get(runId);
  return !!run && newestRunByPath.get(run.path) !== runId;
}

/** A persisted state outside the closed set (e.g. `PENDING`) reads FAILED with reason null. */
function closedState(s: unknown): { state: SlotState; known: boolean } {
  return (SLOT_STATES as readonly unknown[]).includes(s)
    ? { state: s as SlotState, known: true }
    : { state: "FAILED", known: false };
}

/**
 * `run` built from `status.json`, for a run this server does not hold (§8 B): rows have
 * `idle_seconds:null` and `activity:null`, and `state` is whatever was last written.
 */
export function teamRunRowFromDisk(path: string, status: TeamStatus): TeamRunRow {
  const manifest = readManifestOrNull(path);
  const slots: SlotRow[] = Object.entries(status.models ?? {})
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([id, m]) => {
      const { state, known } = closedState(m?.state);
      const terminal = isTerminalState(state);
      const reason =
        !known || !terminal || state === "COMPLETED" ? null : (m?.error?.reason ?? null);
      const why = { state, reason, detail: m?.error?.detail };
      return {
        slot: id,
        model: m?.model ?? manifest?.models[id]?.model ?? "unknown",
        provider: m?.provider ?? null,
        state,
        reason,
        reason_detail: reasonDetail(why, upstreamRecordsFor(why, upstreamLogPath(path, id))),
        tokens_in: m?.tokensIn ?? null,
        tokens_out: m?.tokensOut ?? null,
        cost_usd: m?.costUsd ?? null,
        tool_calls: m?.toolCalls ?? 0,
        turns_completed: m?.turnsCompleted ?? 0,
        last_activity_at: m?.lastActivityAt ?? null,
        idle_seconds: null,
        activity: null,
        pane: m?.pane ?? null,
        recent: null,
      };
    });
  const settled = slots.length > 0 && slots.every((s) => isTerminalState(s.state));
  const completions = Object.values(status.models ?? {})
    .map((m) => (m?.completedAt ? Date.parse(m.completedAt) : Number.NaN))
    .filter(Number.isFinite);
  return {
    run_id: status.runId ?? basename(path),
    path,
    kind: status.kind ?? (basename(path) === "judging" ? "judge" : "run"),
    started_at: status.startedAt,
    // a SETTLED run always has finished_at (§8 A): pre-contract CANCELLED rows carry no
    // completedAt, so the file's own last write stands in, else the start
    finished_at: settled
      ? new Date(
          completions.length
            ? Math.max(...completions)
            : (statusMtimeMs(path) ?? Date.parse(status.startedAt))
        ).toISOString()
      : null,
    state: settled ? "SETTLED" : "ACTIVE",
    outcome: settled ? outcomeOf(slots.map((s) => s.state)) : null,
    slots,
  };
}

function statusMtimeMs(path: string): number | null {
  try {
    return statSync(join(path, "status.json")).mtimeMs;
  } catch {
    return null;
  }
}

function readManifestOrNull(path: string): TeamManifest | null {
  try {
    return JSON.parse(readFileSync(join(path, "manifest.json"), "utf-8")) as TeamManifest;
  } catch {
    return null;
  }
}

/** Contract A: every retained run, ACTIVE first, then SETTLED by `finished_at` desc. */
export function listTeamRuns(): TeamListResult {
  pruneRuns();
  const rows = [...teamRuns.values()].map(runRow);
  const active = rows
    .filter((r) => r.state === "ACTIVE")
    .sort((a, b) => b.started_at.localeCompare(a.started_at));
  const settled = rows
    .filter((r) => r.state === "SETTLED")
    .sort((a, b) => (b.finished_at ?? "").localeCompare(a.finished_at ?? ""));
  return { ...contractMeta(), runs: [...active, ...settled] };
}

function unknownRun(path: string | undefined, runId?: string): ContractErrorException {
  return new ContractErrorException(
    "unknown_run",
    runId
      ? `no team run with run_id ${runId} is retained by this server`
      : `no team run at ${path} is held by this server`
  );
}

/**
 * Stop one slot, or every slot in a run, on the caller's instruction (contract C).
 *
 * The ONLY thing that ends a working team slot. The orchestrator used to do it on a
 * timer and got it wrong — three productive slots died in session team-20260827-0015
 * because silence during a long tool call was read as death. The decision belongs to
 * whoever set the task and can tell a slow build from a hang.
 *
 * Synchronous transition, asynchronous reap: the state is CANCELLED when this returns;
 * the pane close and the process-group reap finish in the background.
 */
export async function cancelTeamRun(
  path: string | undefined,
  slot?: string,
  runId?: string
): Promise<TeamCancelResult> {
  const run = addressRun(path, runId);
  if (!run) throw unknownRun(path, runId);
  const entries = [...run.slots.values()].sort((a, b) => a.id.localeCompare(b.id));
  const targets = slot === undefined ? entries : entries.filter((e) => e.id === slot);
  if (slot !== undefined && targets.length === 0)
    throw new ContractErrorException(
      "unknown_slot",
      `run ${run.runId} has no slot ${JSON.stringify(slot)}`
    );
  const results = targets.map((e) => {
    if (!e.session)
      return { slot: e.id, state: run.status.models[e.id]?.state ?? "FAILED", changed: false };
    const r = e.session.cancel();
    return { slot: e.id, state: r.state, changed: r.changed };
  });
  return { run_id: run.runId, path: run.path, results };
}

/** The screen of a slot whose pane never spawned (§8 D, amended r2). */
function neverSpawnedCapture(): CaptureResult {
  return {
    seq: 0,
    cols: DEFAULT_PANE_COLS,
    rows: DEFAULT_PANE_ROWS,
    cursor: { x: 0, y: 0 },
    lines: Array.from({ length: DEFAULT_PANE_ROWS }, () => ""),
    final: true,
  };
}

/** Contract D, memory only. Throws `ContractErrorException`. */
export function captureTeamSlot(
  path: string | undefined,
  slot: string,
  sinceSeq?: number,
  spans?: boolean,
  runId?: string
): CaptureResult | CaptureUnchanged {
  const run = addressRun(path, runId);
  if (!run) throw unknownRun(path, runId);
  const e = run.slots.get(slot);
  if (!e)
    throw new ContractErrorException(
      "unknown_slot",
      `run ${run.runId} has no slot ${JSON.stringify(slot)}`
    );
  if (!e.session) {
    const c = neverSpawnedCapture();
    return sinceSeq === 0 ? { unchanged: true, seq: 0, final: true } : c;
  }
  return e.session.capture(sinceSeq, { spans: spans === true });
}

/**
 * Contract F: set one slot's terminal size (clamped), in any state, mid-turn included.
 * A slot whose pane never spawned answers the default size with `changed:false`; a
 * terminal one its last size. Throws `ContractErrorException`: `unknown_run`,
 * `unknown_slot`, `resize_unsupported`, `delivery_unavailable`.
 */
export async function resizeTeamSlot(
  path: string | undefined,
  slot: string,
  cols: number,
  rows: number,
  runId?: string
): Promise<TeamResizeResult> {
  const run = addressRun(path, runId);
  if (!run) throw unknownRun(path, runId);
  const e = run.slots.get(slot);
  if (!e)
    throw new ContractErrorException(
      "unknown_slot",
      `run ${run.runId} has no slot ${JSON.stringify(slot)}`
    );
  const where = { run_id: run.runId, path: run.path, slot };
  if (!e.session)
    return { ...where, cols: DEFAULT_PANE_COLS, rows: DEFAULT_PANE_ROWS, changed: false, seq: 0 };
  return { ...where, ...(await e.session.resize(cols, rows)) };
}

/**
 * Per-slot maps the legacy `status` payload carries beside `run` (§4.1), derived from
 * the live rows: idle seconds and activity of every non-terminal slot, and the answer
 * bytes each has produced so far. Null for a run this server does not hold.
 */
export function teamLiveMaps(
  path: string | undefined,
  runId?: string
): {
  idle: Record<string, number>;
  activity: Record<string, string>;
  liveBytes: Record<string, number>;
  endRecordMissing: string[];
} | null {
  const run = addressRun(path, runId);
  if (!run) return null;
  const idle: Record<string, number> = {};
  const activity: Record<string, string> = {};
  const liveBytes: Record<string, number> = {};
  const endRecordMissing: string[] = [];
  for (const e of run.slots.values()) {
    if (!e.session) continue;
    const snap = e.session.snapshot();
    if (isTerminalState(snap.state)) continue;
    const row = toSlotRow({ slot: e.id, model: e.model, spawnModel: e.spawnModel }, snap, e.acct);
    if (row.idle_seconds !== null) idle[e.id] = row.idle_seconds;
    liveBytes[e.id] = snap.liveAnswerBytes;
    // the live condition, never the anomaly history: a slot that resumed work is not wedged
    if (snap.turnEndRecordMissing) endRecordMissing.push(e.id);
    if (row.activity !== null) activity[e.id] = row.activity;
  }
  return { idle, activity, liveBytes, endRecordMissing };
}

function cancelEverySlot(): void {
  for (const run of teamRuns.values()) for (const e of run.slots.values()) e.session?.cancel();
}

/**
 * Settle every team run CANCELLED and wait until each one's record has ENDED (§20.3
 * item 8). Process shutdown only; the pane registry's `reapAllPanes` does the killing.
 *
 * A run still in its spawn loop is not in `teamRuns` yet: it is told to stop spawning,
 * unwinds through its own `catch` (its handler writes `start-failed`), and is awaited. A
 * run whose loop finished meanwhile registers, so the cancel pass repeats until no start
 * is in flight. Then every run's `settled` — the end of `done`, after `onSettled` — is
 * awaited, so no record is left without its end on a clean shutdown.
 */
export async function shutdownAllTeamRuns(): Promise<void> {
  for (const f of startsInFlight.keys()) f.aborted = true;
  for (;;) {
    cancelEverySlot();
    if (startsInFlight.size === 0) break;
    await Promise.allSettled([...startsInFlight.values()]);
  }
  cancelEverySlot();
  await Promise.allSettled([...teamRuns.values()].map((r) => r.settled));
}

/** @internal tests: forget every retained run. */
export function resetTeamRegistryForTests(): void {
  teamRuns.clear();
  newestRunByPath.clear();
}

/** @internal tests: apply the retention policy as of `now` (the 30-minute rule). */
export function pruneTeamRunsForTests(now: number): void {
  pruneRuns(now);
}

// ─── Output Classification ────────────────────────────────────────────────────

/** How many trailing answer bytes a failed slot's error log keeps. */
export const STDOUT_TAIL_LIMIT = 4000;

/** Budget for the answer / screen snippets recorded in `status.json`. */
const SNIPPET_LIMIT = 2000;

/** Bytes of the snippet budget spent on the START of the text. */
const SNIPPET_HEAD = 600;

/**
 * Keep the snippet within budget WITHOUT discarding the beginning.
 *
 * A plain `.slice(-2000)` threw away the first half of a 4000-byte tail that was
 * already in hand, and the beginning is where a shape mismatch is usually
 * legible: a `require_pattern` near-miss like `**Verdict**: **FAIL**` against
 * `/\*\*Verdict\*\*: (PASS|CONDITIONAL|FAIL)/` is diagnosed the moment the
 * reader sees the model's actual wording. Ending a report at the tail can show
 * the reader the last 2000 bytes of prose and none of the line that explains it.
 *
 * Short text is returned whole, so the elision marker only ever appears when
 * something really was dropped.
 */
export function snippetHeadAndTail(text: string): string {
  if (text.length <= SNIPPET_LIMIT) return text;
  const head = text.slice(0, SNIPPET_HEAD);
  const tail = text.slice(-(SNIPPET_LIMIT - SNIPPET_HEAD));
  const omitted = text.length - head.length - tail.length;
  return `${head}\n\n… [${omitted} bytes omitted] …\n\n${tail}`;
}

/**
 * Stub threshold, OFF by default.
 *
 * An earlier default of 200 produced a 2/2 false-positive rate the first time it
 * met real short answers: two correct one-sentence replies (141 B and 96 B) were
 * both recorded EMPTY. Re-checking the three real failures that motivated the
 * threshold, none of them actually needs it — the 1-byte "\n" is whitespace-only,
 * and the 98-byte API error and 195-byte preamble are both caught by their
 * markers. So the byte threshold earned no unique detections while rejecting
 * valid output.
 *
 * Callers who KNOW their answers should be long (a multi-KB review) can opt in
 * via `minOutputBytes`. Whitespace-only output is always caught regardless.
 */
export const DEFAULT_MIN_OUTPUT_BYTES = 0;

/** Added to `detail` (or the COMPLETED slot's anomalies) when the turn ended on max_tokens. */
export const TRUNCATION_NOTE =
  "the turn ended on stop_reason max_tokens, so the answer may be truncated";

/**
 * Decide whether a settled turn produced a usable answer. Returns null when it did.
 *
 * Precedence: `api_error` (FAILED) → `prompt_not_read` (FAILED) → `refused` (EMPTY) →
 * whitespace-only `empty_output` → `min_output_bytes` → `shape_mismatch` LAST (all
 * EMPTY). The structural failures come first because they give better detail, and a
 * turn that hit one of them would fail the shape contract too — reporting "no ```vote
 * block" for what is really an API error would send the caller after the wrong problem.
 */
export function classifyRunOutput(input: {
  /** The full answer: text blocks joined with "\n\n", as written to response-<id>.md. */
  answer: string;
  /**
   * A hook-extended turn chain's answers, one per turn (§7.4): `requirePattern` passes
   * when it matches the joined `answer` OR any single element. Absent = the answer only.
   */
  chainAnswers?: string[];
  apiError: { status: number | null; text: string } | null;
  stopReason?: string | null;
  /** `complete === false` → prompt_not_read */
  promptRead?: SettledTurn["delivery"];
  minOutputBytes?: number;
  /** Caller's shape contract (regex source). See TeamRunOptions.requirePattern. */
  requirePattern?: string;
}): { state: "FAILED" | "EMPTY"; reason: FailureReason; detail: string } | null {
  const v = classifyAnswer(input);
  if (v && input.stopReason === "max_tokens") v.detail = `${v.detail} (${TRUNCATION_NOTE})`;
  return v;
}

type Verdict = { state: "FAILED" | "EMPTY"; reason: FailureReason; detail: string };

/** The turn's own failure signals: an API error, an unread task file, a refusal. */
function classifyTurnSignals(input: Parameters<typeof classifyRunOutput>[0]): Verdict | null {
  const { apiError, stopReason, promptRead } = input;
  if (apiError) {
    const status = apiError.status === null ? "" : ` (status ${apiError.status})`;
    return {
      state: "FAILED",
      reason: "api_error",
      detail: `The turn ended in an API error${status}: ${apiError.text.slice(0, 300) || "unknown"}`,
    };
  }
  if (promptRead?.complete === false) {
    const read = promptRead.linesRead ?? 0;
    return {
      state: "FAILED",
      reason: "prompt_not_read",
      detail:
        read === 0
          ? "the task file was never read, so the answer cannot be about the task"
          : `the child's Read calls returned ${read} of ${promptRead.linesTotal ?? "?"} lines of the task file`,
    };
  }
  if (stopReason === "refusal") {
    return {
      state: "EMPTY",
      reason: "refused",
      detail: "The model refused (stop_reason refusal).",
    };
  }
  return null;
}

/**
 * The caller's shape contract, matched against the full answer (no flags), or against any
 * single turn of a hook-extended chain, so a `^`-anchored pattern still matches a turn
 * that begins with it (§7.4).
 */
function classifyShape(
  answer: string,
  requirePattern: string | undefined,
  chainAnswers?: ReadonlyArray<string>
): Verdict | null {
  if (!requirePattern) return null;
  let re: RegExp | null = null;
  try {
    re = new RegExp(requirePattern);
  } catch {
    // An unusable pattern must never fail a run that may be perfectly good.
    // startModels validates up front so the caller hears about it before any
    // model is spawned; this branch only guards a direct call.
    return null;
  }
  if (re.test(answer)) return null;
  for (const turn of chainAnswers ?? []) if (re.test(turn)) return null;
  return {
    state: "EMPTY",
    reason: "shape_mismatch",
    detail:
      `The answer (${Buffer.byteLength(answer, "utf8")} B of assistant text after the task was ` +
      `read) does not match the required pattern /${requirePattern}/. Every assistant message ` +
      "of the turn was read from the transcript, so nothing was lost: the model did not " +
      "produce the shape. Re-prompt it, or relax the contract.",
  };
}

function classifyAnswer(input: Parameters<typeof classifyRunOutput>[0]): Verdict | null {
  const signal = classifyTurnSignals(input);
  if (signal) return signal;
  const { answer } = input;
  const minOutputBytes = input.minOutputBytes ?? DEFAULT_MIN_OUTPUT_BYTES;
  const outputSize = Buffer.byteLength(answer, "utf8");

  // Nothing but whitespace is never a real answer, at any threshold.
  if (answer.trim().length === 0) {
    return {
      state: "EMPTY",
      reason: "empty_output",
      detail: `The turn settled with no non-whitespace answer (${outputSize} B).`,
    };
  }

  // Opt-in stub threshold. Off by default — see DEFAULT_MIN_OUTPUT_BYTES.
  if (minOutputBytes > 0 && outputSize < minOutputBytes) {
    return {
      state: "EMPTY",
      reason: "empty_output",
      detail: `The answer is only ${outputSize} B (caller required at least ${minOutputBytes} B).`,
    };
  }

  return classifyShape(answer, input.requirePattern, input.chainAnswers);
}

/**
 * Write the full diagnostic log for a slot that did not complete.
 *
 * Always called on failure, so `errorLogPath` in the status report is never a
 * dangling reference.
 *
 * Credentials are stripped BEFORE the bytes hit disk. A screen or an answer can echo
 * key material, and the team result card names this path for the agent to read — so an
 * unredacted log is a credential handed straight into an agent's context. Redacting at
 * write time is the only point that covers every reader (the agent, a human,
 * `report_error`, a future consumer).
 */
function persistErrorLog(
  errorLogPath: string,
  header: string,
  sections: Array<[title: string, body: string]>
): void {
  const parts = [`=== ${redactSecrets(header)} ===`, ""];
  for (const [title, body] of sections) {
    parts.push(`--- ${title} ---`, body.trim() ? redactSecrets(body) : "(empty)", "");
  }
  try {
    writeFileSync(errorLogPath, parts.join("\n"), "utf-8");
  } catch {
    // Diagnostics are best-effort — never let logging failure mask the real error.
  }
}

// ─── Path Validation ──────────────────────────────────────────────────────────

/**
 * Validate that sessionPath is within cwd (prevents path traversal in MCP tools).
 *
 * Both sides are compared as realpaths, so symlinks are resolved: another
 * spelling of cwd (macOS `/var` vs `/private/var`) is accepted, and a symlink
 * inside cwd that points outside it — or dangles — is refused. The path may not
 * exist yet; its nearest existing ancestor is resolved and the rest re-appended.
 * Returns the resolved absolute path in the caller's spelling.
 */
export function validateSessionPath(sessionPath: string): string {
  const resolved = resolve(sessionPath);
  const outside = () => new Error(`Session path must be within current directory: ${sessionPath}`);

  // Walk up to the nearest ancestor that exists (lstat: a dangling link counts as existing).
  let existing = resolved;
  const tail: string[] = [];
  for (;;) {
    try {
      lstatSync(existing);
      break;
    } catch {
      const parent = dirname(existing);
      if (parent === existing) break;
      tail.unshift(basename(existing));
      existing = parent;
    }
  }

  let real: string;
  try {
    real = join(realpathSync(existing), ...tail);
  } catch {
    throw outside(); // a dangling symlink leads nowhere we can vouch for
  }

  const cwd = realpathSync(process.cwd());
  if (real !== cwd && !real.startsWith(cwd + sep)) {
    throw outside();
  }
  return resolved;
}

/**
 * Read a task prompt from a file on disk.
 *
 * Exists because a `team` prompt is typically hundreds of lines — a full review
 * brief with a required output shape. Passing that inline puts the entire text
 * into the tool-call record, where it is rendered verbatim in the caller's
 * terminal and buries every other argument. The prompt is already a file in
 * practice; this lets the caller say so.
 *
 * Contained to the working directory on the same terms as the session path.
 * `team` is reachable over MCP, so an unbounded path here would turn "run a
 * team" into "read any file on this machine and put it in a prompt".
 */
export function readTeamInputFile(inputPath: string): string {
  const resolved = resolve(inputPath);
  const cwd = process.cwd();
  if (!resolved.startsWith(`${cwd}/`) && resolved !== cwd) {
    throw new Error(`Input file must be within current directory: ${inputPath}`);
  }
  if (!existsSync(resolved)) {
    throw new Error(`Input file not found: ${resolved}`);
  }
  const text = readFileSync(resolved, "utf-8");
  // A silently-empty prompt would spawn N children to answer nothing, and every
  // one of them would bill for the attempt.
  if (text.trim().length === 0) {
    throw new Error(`Input file is empty: ${resolved}`);
  }
  return text;
}

// ─── Native Model Slots ──────────────────────────────────────────────────────

/*
 * A native-Anthropic name (`internal`, `default`, `opus`, `sonnet`, `haiku`,
 * `claude-*`) IS a runnable team slot. It spawns like any other child; the
 * proxy answers it through `nativeHandler` (proxy-server.ts, the `isNative`
 * branch) with no translation, because Claude Code already speaks the Anthropic
 * wire format, and it authenticates with the user's own subscription rather
 * than an API key (claude-runner.ts deletes ANTHROPIC_API_KEY for these).
 *
 * These names used to be REJECTED here. That guard (91ee9a8) was written
 * because they "failed with cryptic model not found errors" — but the cause was
 * `internal`/`default` reaching Claude Code as literal model names, which it
 * does not recognise. That is fixed at the source now: the `--model` boundary
 * normalizes a selector to its tier (normalizeNativeModelSpec), and the child
 * runs. Rejecting here as well would block a slot that demonstrably works, and
 * would keep the internal reviewer outside `requirePattern` — the one guard
 * that catches a voter which never voted.
 *
 * Pinning is already safe: `isRoutablyPinnable` (prehydrate.ts) excludes
 * native-anthropic specs, so the name stays BARE and the proxy's `isNative`
 * test (no "/" and no "@") still matches it.
 */

// ─── Core Functions ───────────────────────────────────────────────────────────

/**
 * Setup a new team session.
 * Creates directory structure, writes input.md, generates a shuffled manifest.
 */
export function setupSession(sessionPath: string, models: string[], input?: string): TeamManifest {
  if (models.length === 0) {
    throw new Error("At least one model is required");
  }

  // Reject re-use of existing session directory to prevent overwriting results
  if (existsSync(join(sessionPath, "manifest.json"))) {
    throw new Error(
      `Session already exists at ${sessionPath}. Use a new directory path or delete the existing session first.`
    );
  }

  // Create directories
  mkdirSync(join(sessionPath, "work"), { recursive: true });
  mkdirSync(join(sessionPath, "errors"), { recursive: true });

  // Write input.md if provided, otherwise require it to already exist
  if (input !== undefined) {
    writeFileSync(join(sessionPath, "input.md"), input, "utf-8");
  } else if (!existsSync(join(sessionPath, "input.md"))) {
    throw new Error(`No input.md found at ${sessionPath} and no input provided`);
  }

  // Generate zero-padded numeric IDs to support >26 models: 01, 02, ..., 99
  const ids = models.map((_, i) => String(i + 1).padStart(2, "0"));
  const shuffled = fisherYatesShuffle([...ids]);

  // Build manifest — shuffled[i] is the anonymous ID for models[i]
  const now = new Date().toISOString();
  const manifest: TeamManifest = {
    created: now,
    models: {},
    shuffleOrder: shuffled,
  };

  for (let i = 0; i < models.length; i++) {
    const anonId = shuffled[i];
    manifest.models[anonId] = {
      model: models[i],
      assignedAt: now,
    };
    mkdirSync(join(sessionPath, "work", anonId), { recursive: true });
  }

  writeFileSync(join(sessionPath, "manifest.json"), JSON.stringify(manifest, null, 2), "utf-8");

  // Initialize status.json with every model STARTING: the closed set has no "not yet
  // started" state, and a slot leaves STARTING within the boot + admission bounds.
  const status: TeamStatus = {
    startedAt: now,
    models: Object.fromEntries(
      Object.keys(manifest.models).map((id) => [
        id,
        {
          state: "STARTING" as const,
          exitCode: null,
          startedAt: null,
          completedAt: null,
          outputSize: 0,
          model: manifest.models[id]?.model,
        },
      ])
    ),
  };
  writeFileAtomic(join(sessionPath, "status.json"), JSON.stringify(status, null, 2));

  return manifest;
}

/**
 * Fail fast on an unusable shape contract. Deliberately called BEFORE the
 * manifest read and the spawn loop: a bad regex discovered after N children
 * have run would either waste the whole run or, worse, be swallowed and
 * silently enforce nothing — which is the exact class of quiet failure this
 * option exists to remove.
 */
function assertValidRequirePattern(pattern: string | undefined): void {
  if (pattern === undefined) return;
  try {
    new RegExp(pattern);
  } catch (err) {
    throw new Error(
      `Invalid requirePattern /${pattern}/: ${err instanceof Error ? err.message : String(err)}`
    );
  }
}

/**
 * The pre-spawn refusals of a team run, in the order the MCP `run` handler applies them
 * BEFORE `setupSession` writes anything (§4.1): the caller's flags (D18), a prompt that
 * cannot be delivered with those flags (§2.3 rule 4), magmux present (≥ `MIN_MAGMUX_VERSION`), no
 * ACTIVE run at the path, and room under the per-user pane limit. Each throws an Error
 * whose message starts with its code (`invalid_args:`, `magmux_unavailable:`,
 * `pane_limit:`). `startModels` repeats them, so the CLI gets the same checks.
 */
export async function preflightTeamRun(opts: {
  path: string;
  slots: number;
  claudeFlags?: string[];
  input?: string;
  requirePattern?: string;
  parentEnv?: Record<string, string | undefined>;
}): Promise<void> {
  // before setupSession and the run record, so a refused run leaves no record (§4.1)
  try {
    assertValidRequirePattern(opts.requirePattern);
  } catch (err) {
    throw new Error(`invalid_args: ${err instanceof Error ? err.message : String(err)}`);
  }
  const flags = opts.claudeFlags ?? [];
  const check = checkChildFlags(flags);
  if (!check.ok) throw new Error(`invalid_args: ${check.message}`);
  if (opts.input !== undefined) {
    const refusal = deliveryRefusal(opts.input, !flagsRemoveRead(flags));
    if (refusal) throw new Error(`invalid_args: ${refusal}`);
  }
  await assertMagmuxAvailable();
  assertNoActiveRun(resolve(opts.path));
  const root = sockRootFor(opts.parentEnv ?? process.env);
  const live = livePaneCount(root);
  if (live + opts.slots > MAX_LIVE_PANES)
    throw new Error(
      `pane_limit: ${live} live panes for this user, ${opts.slots} more would exceed ${MAX_LIVE_PANES}`
    );
}

function mintRunId(path: string, startMs: number): string {
  return `${basename(path)}-${startMs.toString(36)}-${randomBytes(3).toString("hex")}`;
}

const CANCELLED_DETAIL =
  'Stopped on the caller\'s instruction via team(mode:"cancel"). ' +
  "Whatever the child had written up to that point is in its response file.";

/**
 * Start every model as an interactive pane and RETURN once each has left STARTING
 * (D9): its prompt was accepted, or it failed to boot or to take the prompt. Bounded
 * by the boot (90 s) and admission (30 s) limits, about 12–20 s typical.
 *
 * Why this is the primitive rather than a blocking call. A team slot is a full
 * Claude Code session and can legitimately work for a very long time; the
 * previous blocking shape forced a deadline on it, and enforcing that deadline
 * killed three productive slots in session team-20260827-0015. Nothing here
 * imposes a deadline after a prompt is accepted. The caller polls, reads how long
 * each slot has been quiet and what it is doing, and decides for itself whether to
 * keep waiting.
 *
 * Each slot receives input.md (typed when it is one plain line, else as a task file it
 * is told to Read) and its answer is written to response-{ID}.md.
 */
export function startModels(sessionPath: string, opts: TeamRunOptions = {}): Promise<TeamHandle> {
  const flight: StartFlight = { aborted: false };
  const p = startModelsIn(flight, sessionPath, opts);
  startsInFlight.set(flight, p);
  const forget = () => {
    startsInFlight.delete(flight);
  };
  p.then(forget, forget);
  return p;
}

/** The stagger before slot `i` (X-L8), then the shutdown check: no pane starts after it. */
async function beforeSpawn(i: number, flight: StartFlight): Promise<void> {
  if (i > 0) await new Promise((r) => setTimeout(r, BOOT_STAGGER_MS));
  if (flight.aborted) throw new Error("cancelled: the server is shutting down");
}

async function startModelsIn(
  flight: StartFlight,
  sessionPath: string,
  opts: TeamRunOptions
): Promise<TeamHandle> {
  assertValidRequirePattern(opts.requirePattern);
  const claudeFlags = opts.claudeFlags ?? [];
  const flagCheck = checkChildFlags(claudeFlags);
  if (!flagCheck.ok) throw new Error(`invalid_args: ${flagCheck.message}`);

  const path = resolve(sessionPath);
  const manifest: TeamManifest = JSON.parse(readFileSync(join(path, "manifest.json"), "utf-8"));
  const statusPath = join(path, "status.json");
  const inputContent = readFileSync(join(path, "input.md"), "utf-8");
  const readAvailable = !flagsRemoveRead(claudeFlags);
  const refusal = deliveryRefusal(inputContent, readAvailable);
  if (refusal) throw new Error(`invalid_args: ${refusal}`);
  assertNoActiveRun(path);
  const parentEnv = opts.parentEnv ?? process.env;
  const kind = opts.kind ?? "run";
  // The hook engine slot bindings are built from (§2.2), loaded before any spawn.
  const hookEngine = await (opts.hookEngine ?? (() => loadHooksOnce()))().catch(() => null);

  // Resolve every model's credential AND its route HERE, before the spawn loop
  // below starts N children. Each child would otherwise open its own 1Password SDK
  // client, and the desktop app authorizes exactly one of them and denies the rest
  // ("Denied authorization for SDK client") — silently losing whichever models
  // depend on 1Password rather than a shell env var. Resolving in the parent
  // write-throughs the keys into process.env, which the pane snapshot carries to the
  // children, and the returned plan pins each bare name to an explicit
  // "provider@model" spec so the child never re-walks the chain. See
  // auth/credentials/prehydrate.ts for the measured repro.
  const spawnPlan = await (opts.spawnPlanner ?? prehydrateCredentialsForSpawn)(
    Object.values(manifest.models).map((m) => m.model)
  );
  await assertMagmuxAvailable();

  // In-memory status cache to eliminate read-modify-write races
  const statusCache: TeamStatus = JSON.parse(readFileSync(statusPath, "utf-8"));
  const startMs = Date.now();
  const runId = mintRunId(path, startMs);
  statusCache.runId = runId;
  statusCache.kind = kind;

  /**
   * Set while the spawn loop is being unwound (§6.1 step 7): the cancels it issues are
   * not the caller's, so nothing they do reaches status.json — the started slots stay
   * STARTING there and `summarise` counts them as failed.
   */
  let aborting = false;

  function patchModelStatus(id: string, update: Partial<ModelStatus>): void {
    statusCache.models[id] = { ...statusCache.models[id], ...update } as ModelStatus;
  }
  function flushStatus(): void {
    writeFileAtomic(statusPath, JSON.stringify(statusCache, null, 2));
  }
  function updateModelStatus(id: string, update: Partial<ModelStatus>): void {
    if (aborting) return;
    patchModelStatus(id, update);
    flushStatus();
  }
  function notifyStatus(id: string): void {
    try {
      opts.onStatusChange?.(id, statusCache.models[id] as ModelStatus);
    } catch {
      // A status consumer must never be able to fail the run.
    }
  }

  const minOutputBytes = opts.minOutputBytes ?? DEFAULT_MIN_OUTPUT_BYTES;
  const requirePattern = opts.requirePattern;

  // Each child writes its token/cost stats here (one file per model).
  mkdirSync(statsDir(path), { recursive: true });

  const entries = new Map<string, SlotEntry>();
  let run: LiveTeamRun | null = null;
  const errorLogPathOf = (id: string) => join(path, "errors", `${id}.log`);
  const upstreamLogOf = (id: string) => upstreamLogPath(path, id);
  const flagsOf = (e: SlotEntry): string[] => {
    const effort = opts.efforts?.[e.model];
    return effort ? [...claudeFlags, "--effort-override", effort] : claudeFlags;
  };
  const commandOf = (e: SlotEntry) =>
    ["claudish", "-i", "--model", e.spawnModel ?? e.model, "-y", "--quiet", ...flagsOf(e)].join(
      " "
    );

  /** `response-<id>.md` in one write, byte-exact; remembered so it is written once. */
  /**
   * The slot's response file. A failed write (disk full, the directory removed mid-run)
   * must not throw out of the verdict or the terminal patch: the slot's terminal row is
   * still written, and the failure goes to the slot's error log instead.
   */
  function writeResponse(e: SlotEntry, text: string): string {
    e.answer = text;
    try {
      writeFileSync(join(path, `response-${e.id}.md`), text, "utf-8");
    } catch (err) {
      persistErrorLog(errorLogPathOf(e.id), `response file not written: ${String(err)}`, []);
    }
    return text;
  }

  /**
   * `onTurnRecorded` (binding present): the response file holds the chain so far, so no
   * terminal path can lose a settled turn. Not final: `e.answer` stays unset (§7.4).
   */
  function writeChainSoFar(e: SlotEntry): void {
    if (e.answer !== null || !e.session) return;
    try {
      writeFileSync(join(path, `response-${e.id}.md`), e.session.chainText(), "utf-8");
    } catch (err) {
      persistErrorLog(errorLogPathOf(e.id), `response file not written: ${String(err)}`, []);
    }
  }

  /** The answer of a slot that ended without a verdict: the chain with a binding (§7.4). */
  function unsettledAnswer(e: SlotEntry, index: number): string {
    if (e.binding && e.session) return e.session.chainText();
    return e.session?.turnAnswer(index) ?? "";
  }

  /** Team policy for a settled turn (D8): the verdict, after the response file exists. */
  function teamDecide(e: SlotEntry, turn: SettledTurn): FinalVerdict {
    e.stopReason = turn.stopReason;
    // A hook-extended chain is the slot's answer: every turn joined, classified with the
    // chain head's prompt-read result. Without hooks both are the turn's own (§7.4).
    const answer = chainAnswerOf(turn);
    writeResponse(e, answer);
    const v = classifyRunOutput({
      answer,
      chainAnswers: [...turn.chainAnswers, turn.answer],
      apiError: turn.apiError,
      stopReason: turn.stopReason,
      promptRead: turn.chainDelivery,
      minOutputBytes,
      requirePattern,
    });
    // R3-M5: an open background shell goes into the slot's detail, not only the anomalies.
    const shells = (e.session?.snapshot().anomalies ?? []).filter((a) =>
      a.startsWith("background_shell_open")
    );
    if (!v) {
      const notes = [...shells, ...(turn.stopReason === "max_tokens" ? [TRUNCATION_NOTE] : [])];
      return notes.length
        ? { state: "COMPLETED", detail: notes.join(" · ") }
        : { state: "COMPLETED" };
    }
    return { state: v.state, reason: v.reason, detail: [v.detail, ...shells].join(" · ") };
  }

  /** D19: team has no answering verb, so a slot blocked on a question can never finish. */
  function teamOnBlocked(e: SlotEntry, b: PaneBlock): FinalVerdict {
    const index = (e.session?.snapshot().turnsCompleted ?? 0) + 1;
    if (e.answer === null) writeResponse(e, unsettledAnswer(e, index));
    return { state: "FAILED", reason: "blocked", detail: b.text };
  }

  function accountingFields(a: Accounting): Partial<ModelStatus> {
    return {
      provider: a.provider,
      tokensIn: a.tokensIn,
      tokensOut: a.tokensOut,
      costUsd: a.costUsd,
      toolCalls: a.toolCalls,
    };
  }

  function liveFields(e: SlotEntry, snap: PaneSnapshot): Partial<ModelStatus> {
    return {
      state: snap.state,
      pane: snap.paneId || null,
      captureSource: snap.captureSource,
      turnSource: snap.turnSource,
      lastActivityAt: snap.lastActivityAt,
      turnsCompleted: snap.turnsCompleted,
      claudeCodeVersion: snap.claudeCodeVersion,
      anomalies: notableAnomalies(snap),
      ...accountingFields(refreshAccounting(e, snap)),
    };
  }

  /** The fields a slot gets once, when it turns terminal (and its error log on failure). */
  function terminalFields(e: SlotEntry, snap: PaneSnapshot): Partial<ModelStatus> {
    const index = Math.max(1, snap.turnsCompleted);
    const answer = e.answer ?? writeResponse(e, unsettledAnswer(e, index));
    const anomalies = [
      ...notableAnomalies(snap),
      ...(snap.state === "COMPLETED" && e.stopReason === "max_tokens" ? [TRUNCATION_NOTE] : []),
    ];
    const base: Partial<ModelStatus> = {
      completedAt: snap.endedAt ?? new Date().toISOString(),
      exitCode: snap.exitCode,
      outputSize: Buffer.byteLength(answer, "utf8"),
      stopReason: e.stopReason,
      anomalies,
    };
    if (snap.state === "COMPLETED") return { ...base, error: undefined };
    return { ...base, error: slotError(e, snap, answer) };
  }

  /** The `ModelError` of a slot that did not complete; writes its error log first. */
  function slotError(e: SlotEntry, snap: PaneSnapshot, answer: string): ModelError {
    const reason: FailureReason =
      snap.reason ?? (snap.state === "CANCELLED" ? "cancelled" : "child_exited");
    const detail = reason === "cancelled" ? CANCELLED_DETAIL : (snap.detail ?? reason);
    const errorLogPath = errorLogPathOf(e.id);
    persistErrorLog(errorLogPath, `${snap.state}: ${reason}: ${detail}`, [
      ["final screen", snap.screenTail],
      [
        "exit code",
        snap.exitCode === null ? "(none: claudish ended the pane)" : String(snap.exitCode),
      ],
      ["anomalies", snap.anomalies.join("\n")],
      ["answer (tail)", answer.slice(-STDOUT_TAIL_LIMIT)],
    ]);
    const upstream = upstreamLogOf(e.id);
    return {
      model: e.id,
      command: commandOf(e),
      reason,
      detail,
      screenSnippet: snap.screenTail
        ? snippetHeadAndTail(redactSecrets(snap.screenTail))
        : undefined,
      answerSnippet: answer ? snippetHeadAndTail(redactSecrets(answer)) : undefined,
      errorLogPath,
      // Only when the child actually wrote one. Naming a file that does not exist
      // sends a reader after evidence that was never captured.
      upstreamErrorLogPath: existsSync(upstream) ? upstream : undefined,
      workDir: path,
    };
  }

  /** `onTransition`: every wire-state change, synchronously, before any frame. */
  function onSlotTransition(e: SlotEntry, snap: PaneSnapshot): void {
    if (aborting) return;
    const update = liveFields(e, snap);
    if (isTerminalState(snap.state)) Object.assign(update, terminalFields(e, snap));
    updateModelStatus(e.id, update);
    notifyStatus(e.id);
    if (run) markIfSettled(run);
  }

  /** A slot whose pane never spawned: FAILED `pane_lost` with the message; siblings continue. */
  function failNeverSpawned(e: SlotEntry, err: unknown): void {
    const msg = err instanceof Error ? err.message : String(err);
    const errorLogPath = errorLogPathOf(e.id);
    writeResponse(e, "");
    persistErrorLog(errorLogPath, `FAILED: pane_lost: ${msg}`, [["start", msg]]);
    updateModelStatus(e.id, {
      state: "FAILED",
      completedAt: new Date().toISOString(),
      outputSize: 0,
      pane: null,
      error: {
        model: e.id,
        command: commandOf(e),
        reason: "pane_lost",
        detail: `the pane never started: ${msg}`,
        errorLogPath,
        workDir: path,
      },
    });
    notifyStatus(e.id);
  }

  const cwd = process.cwd();
  const projects = projectsDir(parentEnv);

  /** The slot's hook binding: a test's, or the real one when the engine has session hooks. */
  function bindingFor(e: SlotEntry, uuid: string): SessionHookBinding | null {
    const session: HookSessionInfo = {
      kind: "team",
      role: kind === "judge" ? "judge" : "slot",
      id: `${runId}:${e.id}`,
      claudeSessionId: uuid,
      model: e.model,
      cwd,
      shape: "one-shot",
      injection: "available",
    };
    if (opts.hookBinding)
      return opts.hookBinding({ session, inboxPath: e.inboxPath ?? null, engine: hookEngine });
    if (!hookEngine || !sessionHooksNeedBinding(hookEngine)) return null;
    return createSessionHookBinding(hookEngine, session, e.inboxPath ?? null);
  }

  async function startSlot(e: SlotEntry, uuid: string, transcriptPath: string): Promise<void> {
    let session: PaneSession;
    e.inboxPath = createHookInbox(join(path, "work"), `${e.id}.hook-inbox.jsonl`);
    const binding = bindingFor(e, uuid);
    e.binding = binding;
    try {
      session = await startPaneSession({
        kind: "t",
        label: e.id,
        callerFlags: flagsOf(e),
        spawnModel: e.spawnModel ?? e.model,
        cwd,
        sessionUuid: uuid,
        transcriptPath,
        slotEnv: {
          // Point this child's token tracker at a path WE choose, so its tokens/cost
          // can be attributed back to this model.
          [ENV.CLAUDISH_TOKEN_FILE]: e.tokenFile,
          // Per SLOT, unconditionally: the records carry no slot id, so one shared
          // path would interleave every model in the run into an unattributable file.
          [UPSTREAM_ERROR_LOG_ENV]: upstreamLogOf(e.id),
          // Every slot and judge, unconditionally (§2.3 step 1).
          ...(e.inboxPath ? { [HOOK_INBOX_ENV]: e.inboxPath } : {}),
          [HOOK_SESSION_ENV]: JSON.stringify({
            kind: "team",
            id: `${runId}:${e.id}`,
            role: kind === "judge" ? "judge" : "slot",
          }),
        },
        shape: "one-shot",
        initialPrompt: inputContent,
        readAvailable,
        decide: (turn) => teamDecide(e, turn),
        onBlocked: (b) => teamOnBlocked(e, b),
        onTransition: (t) => onSlotTransition(e, t.snap),
        parentEnv,
        ...(opts.bootTimeoutMs !== undefined ? { bootTimeoutMs: opts.bootTimeoutMs } : {}),
        ...(opts.paneTimings ? { timings: opts.paneTimings } : {}),
        ...(binding ? { hooks: binding, onTurnRecorded: () => writeChainSoFar(e) } : {}),
      });
    } catch (err) {
      removeInbox(e);
      failNeverSpawned(e, err);
      return;
    }
    e.session = session;
    // At reap: an owner without a binding checks the inbox once, then the file goes.
    void session.reaped().then(() => {
      if (!binding && e.inboxPath)
        reportOwnerWithoutHooks(e.inboxPath, hookEngine, { model: e.model, sessionId: uuid });
      // with a binding, what no settle took is journaled before the file goes
      binding?.sweepInbox?.();
      removeInbox(e);
    });
    updateModelStatus(e.id, { pane: session.paneId });
  }

  function removeInbox(e: SlotEntry): void {
    if (!e.inboxPath) return;
    try {
      rmSync(e.inboxPath, { force: true });
    } catch {
      // nothing reads it after the reap
    }
  }

  const slotIds = Object.keys(manifest.models);
  reservePanes(slotIds.length, sockRootFor(parentEnv));
  // Each startSlot call consumes exactly one reservation, whether its pane starts or not.
  let reservationsLeft = slotIds.length;
  const starts: Promise<void>[] = [];

  // The spawn loop has its own catch because NOTHING after it exists yet when it
  // throws: the ticker, the registry entry and `done` are all built below. A failed
  // status.json write for slot N would otherwise leave slots 1..N-1 running and billing
  // with no `done` and no registry entry to cancel them through. A slot's own
  // startPaneSession throw is NOT such a throw: it is that slot's FAILED pane_lost.
  try {
    let i = 0;
    for (const [id, entry] of Object.entries(manifest.models)) {
      await beforeSpawn(i++, flight);
      // Spawn with the parent-resolved explicit spec when there is one, so the child
      // skips routing entirely and finds its key in the inherited env. ABSENT from the
      // map means "spawn it bare". The manifest keeps `entry.model` (the user's string)
      // as the run's identity; only argv changes.
      const spawnModel = spawnPlan.pinned.get(entry.model) ?? entry.model;
      const tokenFile = tokenFileFor(path, id);
      const provider = resolveProvider({ model: entry.model, spawnModel, tokenFile: null });
      const e: SlotEntry = {
        id,
        model: entry.model,
        spawnModel,
        tokenFile,
        session: null,
        acct: emptyAccounting(provider),
        answer: null,
        stopReason: null,
      };
      entries.set(id, e);
      const uuid = randomUUID();
      // Team children run in the server's cwd, as before; the launcher `cd`s there.
      const transcriptPath = transcriptPathFor(cwd, uuid, projects);
      updateModelStatus(id, {
        state: "STARTING",
        startedAt: new Date().toISOString(),
        completedAt: null,
        exitCode: null,
        outputSize: 0,
        model: entry.model,
        spawnModel,
        provider,
        sessionUuid: uuid,
        transcriptPath,
        pane: null,
        captureSource: null,
        turnSource: "transcript",
        stopReason: null,
        tokensIn: null,
        tokensOut: null,
        costUsd: null,
        toolCalls: 0,
        turnsCompleted: 0,
        lastActivityAt: null,
      });
      const start = startSlot(e, uuid, transcriptPath);
      // Observed by the Promise.all below; until then a rejection must not count as
      // unhandled while the loop is still staggering.
      start.catch(() => undefined);
      starts.push(start);
      reservationsLeft--;
    }
    await Promise.all(starts);
  } catch (err) {
    // Nothing reported as failed to start may keep running or billing: stop every pane
    // already started (§2.10: close_pane, magmux, then SIGTERM and SIGKILL on the
    // verified group) and only then let the ORIGINAL error out, so the caller's
    // `start-failed` record is true when it is written. `onSettled` is NOT called — no
    // run started; the caller records the failure.
    aborting = true;
    await Promise.allSettled(starts);
    const started = [...entries.values()]
      .map((e) => e.session)
      .filter((s): s is PaneSession => s !== null);
    for (const s of started) s.cancel();
    await Promise.all(started.map((s) => s.reaped().catch(() => undefined)));
    releasePaneReservations(reservationsLeft);
    throw err;
  }

  // ── Live progress ─────────────────────────────────────────────────────────
  // Two different cadences, deliberately:
  //   · status.json / status.txt — rewritten every poll. Files; frequency is free.
  //   · onProgress — only when the run's state actually CHANGES, plus a slow
  //                  heartbeat. Each frame renders as its own new line in the
  //                  client, so a fixed short tick would bury the transcript in
  //                  near-identical rows (a 15-min run at 5s = ~180 lines).
  const POLL_MS = 2000;
  const heartbeatMs = (opts.heartbeatSeconds ?? 60) * 1000;

  let lastSignature = "";
  let lastEmitMs = 0;

  /**
   * What "changed" means for emission purposes. EXCLUDES elapsed time and raw token
   * counts: both tick continuously, and keying on them re-creates the spam this dedupe
   * exists to stop. Token totals still ride along on whatever frame does get emitted.
   */
  const stateSignature = (): string =>
    Object.entries(statusCache.models)
      .sort(([a], [b]) => a.localeCompare(b))
      .map(([id, m]) => `${id}:${m.state}:${m.outputSize}`)
      .join("|");

  const emitProgress = (phase: "running" | "settled" = "running"): void => {
    const elapsedSeconds = (Date.now() - startMs) / 1000;
    writeStatusFile(path, manifest, statusCache, { elapsedSeconds });
    if (!opts.onProgress) return;

    const signature = stateSignature();
    const changed = signature !== lastSignature;
    const heartbeatDue = Date.now() - lastEmitMs >= heartbeatMs;
    // A settled run must always emit — it is the terminal frame.
    if (phase !== "settled" && !changed && !heartbeatDue) return;

    lastSignature = signature;
    lastEmitMs = Date.now();

    try {
      const models = Object.values(statusCache.models);
      opts.onProgress({
        rendered: renderTeamStatsCompact(path, manifest, statusCache, { elapsedSeconds }),
        phase,
        allFailed: models.length > 0 && models.every((m) => m.state !== "COMPLETED"),
      });
    } catch {
      // A progress consumer must never be able to fail the run.
    }
  };

  /** Fresh accounting for disk readers (§3.1): every non-terminal slot, one write. */
  const refreshLiveSlots = (): void => {
    let dirty = false;
    for (const e of entries.values()) {
      if (!e.session) continue;
      const snap = e.session.snapshot();
      if (isTerminalState(snap.state)) continue;
      patchModelStatus(e.id, liveFields(e, snap));
      dirty = true;
    }
    if (dirty) {
      try {
        flushStatus();
      } catch {
        // the next tick retries; a state change writes on its own
      }
    }
  };

  // The registry entry exists from here, before the D9 `ready` await, so a run is
  // listable and cancellable once all of its panes exist (§3.2, §20.3).
  let resolveSettled: () => void = () => {};
  const settled = new Promise<void>((r) => {
    resolveSettled = r;
  });
  run = {
    runId,
    path,
    kind,
    startedAt: new Date(startMs).toISOString(),
    finishedAt: null,
    status: statusCache,
    slots: entries,
    settled,
  };
  teamRuns.set(runId, run);
  newestRunByPath.set(path, runId);
  pruneRuns();
  markIfSettled(run);

  emitProgress(); // one immediately, so status.txt exists from the start
  const progressHandle = setInterval(() => {
    refreshLiveSlots();
    emitProgress("running");
  }, POLL_MS);
  // Don't hold the event loop open on the ticker alone.
  progressHandle.unref?.();

  // D9: return once every slot has left STARTING. `ready` never rejects: it resolves on
  // any exit from STARTING, terminal included.
  await Promise.all([...entries.values()].map((e) => e.session?.ready ?? Promise.resolve()));

  const liveRun = run;
  // Built last, immediately before the return, and nothing after it can throw: the
  // record's one end (`onSettled`) can therefore never race the handler's start-failed
  // `catch` (§20.3 item 1).
  const done = (async (): Promise<TeamStatus> => {
    // The caller resumes from `await startModels(...)` before this body runs on, even
    // for a run whose every slot already ended.
    await new Promise((r) => setImmediate(r));
    try {
      await Promise.all([...entries.values()].map((e) => e.session?.terminal ?? Promise.resolve()));
    } finally {
      clearInterval(progressHandle);
      markIfSettled(liveRun);
      if (liveRun.finishedAt === null) liveRun.finishedAt = new Date().toISOString();
      // Terminal frame. Without this a status-tracking consumer never sees the run
      // close — every frame would read "running", including the last one.
      emitProgress("settled");
      // The caller's settle hook, exactly once, after the settled render. Its own try,
      // the `onProgress` convention: a consumer can never fail the run.
      try {
        opts.onSettled?.(statusCache);
      } catch (err) {
        // A settle consumer must never be able to fail the run, but its failure
        // leaves the run record unended, so it is logged.
        log(
          `[team] onSettled failed for ${path}: ${err instanceof Error ? err.message : String(err)}`
        );
      }
      resolveSettled();
    }
    return statusCache;
  })();
  // A caller that only polls never touches `done`. Without this an unobserved rejection
  // would take down the MCP server, which hosts every other session too.
  done.catch((err: unknown) =>
    log(`[team] run failed at ${path}: ${err instanceof Error ? err.message : String(err)}`)
  );

  return {
    runId,
    teamSessionId: basename(path),
    sessionPath: path,
    // Display model → anonymised slot. The manifest is shuffled for blind JUDGING,
    // which protects the judge children reading response-<id>.md without a manifest.
    // It was never hidden from the orchestrating caller.
    slots: Object.fromEntries(
      Object.entries(manifest.models).map(([anonId, entry]) => [entry.model, anonId])
    ),
    done,
  };
}

/**
 * Start every model and wait for all of them.
 *
 * The blocking form of `startModels`, kept for the pipeline modes that are
 * inherently sequential: `run-and-judge` cannot judge answers that do not exist
 * yet. Prefer `startModels` anywhere the caller can poll instead, because this
 * form makes the run's duration the CALLER's problem — and an MCP client aborts
 * a tool call that stays silent too long.
 */
export async function runModels(
  sessionPath: string,
  opts: TeamRunOptions = {}
): Promise<TeamStatus> {
  const handle = await startModels(sessionPath, opts);
  return handle.done;
}

/**
 * Judge existing responses blindly.
 * Reads response-*.md files, sends to judge models, collects votes, aggregates verdict.
 */
export async function judgeResponses(
  sessionPath: string,
  opts: TeamJudgeOptions = {}
): Promise<TeamVerdict> {
  // Response files are written only at a slot's terminal transition: judging a run that
  // is still ACTIVE would silently vote on the subset that happens to have finished.
  const active = activeRunAt(resolve(sessionPath));
  if (active)
    throw new Error(
      `invalid_args: the team run at ${resolve(sessionPath)} is still ACTIVE (run_id ${active.runId}); judge it once it has settled`
    );
  // Collect all response files in sorted order
  const responseFiles = readdirSync(sessionPath)
    .filter((f) => f.startsWith("response-") && f.endsWith(".md"))
    .sort();

  if (responseFiles.length < 2) {
    throw new Error(`Need at least 2 responses to judge, found ${responseFiles.length}`);
  }

  const responses: Record<string, string> = {};
  for (const file of responseFiles) {
    const id = file.replace(/^response-/, "").replace(/\.md$/, "");
    responses[id] = readFileSync(join(sessionPath, file), "utf-8");
  }

  // Build and save judge prompt
  const input = readFileSync(join(sessionPath, "input.md"), "utf-8");
  const judgePrompt = buildJudgePrompt(input, responses);
  writeFileSync(join(sessionPath, "judge-prompt.md"), judgePrompt, "utf-8");

  // Determine judge models (default: same models that produced responses)
  const judgeModels = opts.judges ?? getDefaultJudgeModels(sessionPath);

  // Run judges in a sub-session under sessionPath/judging/
  const judgePath = join(sessionPath, "judging");
  mkdirSync(judgePath, { recursive: true });

  setupSession(judgePath, judgeModels, judgePrompt);
  // The judge prompt (rubric + every response) is not a plain line, so it reaches each
  // judge as a task file it Reads; an incomplete read is FAILED prompt_not_read, never a
  // verdict on part of the input.
  await runModels(judgePath, {
    claudeFlags: opts.claudeFlags,
    kind: "judge",
    ...(opts.parentEnv ? { parentEnv: opts.parentEnv } : {}),
    ...(opts.paneTimings ? { paneTimings: opts.paneTimings } : {}),
  });

  // Parse votes from judge outputs
  const votes = parseJudgeVotes(judgePath, Object.keys(responses));

  // Aggregate votes into a verdict
  const verdict = aggregateVerdict(votes, Object.keys(responses));

  // Write verdict.md (reveals model names since judging is complete)
  writeFileSync(join(sessionPath, "verdict.md"), formatVerdict(verdict, sessionPath), "utf-8");

  return verdict;
}

/**
 * Get current status of a team session.
 */
export function getStatus(sessionPath: string): TeamStatus {
  return JSON.parse(readFileSync(join(sessionPath, "status.json"), "utf-8"));
}

/**
 * `<sessionPath>/status.json`, or a status with an EMPTY `models` map when it
 * cannot be read. Never throws: it feeds the start-failure record, which must
 * be written whatever state the run's directory is in.
 */
export function readTeamStatus(sessionPath: string): TeamStatus {
  try {
    const parsed = getStatus(sessionPath);
    if (
      parsed &&
      typeof parsed === "object" &&
      parsed.models &&
      typeof parsed.models === "object"
    ) {
      return parsed;
    }
  } catch (err) {
    // status.json is written atomically, so anything but its absence is a fault.
    if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
      log(
        `[team] unreadable status.json at ${sessionPath}: ${err instanceof Error ? err.message : String(err)}`
      );
    }
  }
  return { startedAt: new Date().toISOString(), models: {} };
}

/**
 * How one `team(mode:"run")` ended, as its session-directory record states it
 * (`<sessionsDir>/team-<8 hex>/meta.json`, written by `finishTeamRun`).
 */
export interface TeamRunOutcome {
  status: "completed" | "failed" | "cancelled";
  slots: number;
  ok: number;
  failed: number;
  cancelled: number;
  /** Present only when the run never started: `startModels` threw. */
  reason?: "start-failed";
}

/**
 * Counts and verdict for ANY `TeamStatus`, settled or not, so a run that failed
 * partway still yields counts.
 *
 * - `COMPLETED` → ok.
 * - a terminal row whose `error.reason` is `cancelled` → cancelled (a CANCELLED row
 *   always carries it); with any other reason → failed.
 * - every non-terminal row (STARTING, RUNNING, AWAITING_*) → failed. A settled run has
 *   none; in a run that failed to start they are the slots never started and the slots
 *   just stopped. The magus monitor's heartbeat applies the same rule.
 *
 * `slots` is the number of entries. `status` is `completed` when at least one
 * slot is ok (the channel frame's rule), `cancelled` when every slot was
 * cancelled, otherwise `failed`.
 */
export function summarise(status: TeamStatus): TeamRunOutcome {
  const models = Object.values(status?.models ?? {});
  let ok = 0;
  let failed = 0;
  let cancelled = 0;
  for (const model of models) {
    if (model?.state === "COMPLETED") ok++;
    else if (model?.error?.reason === "cancelled" && TERMINAL_STATES.includes(model.state)) {
      cancelled++;
    } else failed++;
  }
  const slots = models.length;
  const verdict: TeamRunOutcome["status"] =
    ok >= 1 ? "completed" : slots > 0 && cancelled === slots ? "cancelled" : "failed";
  return { status: verdict, slots, ok, failed, cancelled };
}

// ─── Internal Helpers ─────────────────────────────────────────────────────────

export function fisherYatesShuffle<T>(arr: T[]): T[] {
  for (let i = arr.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [arr[i], arr[j]] = [arr[j], arr[i]];
  }
  return arr;
}

function getDefaultJudgeModels(sessionPath: string): string[] {
  const manifest: TeamManifest = JSON.parse(
    readFileSync(join(sessionPath, "manifest.json"), "utf-8")
  );
  return Object.values(manifest.models).map((e) => e.model);
}

export function buildJudgePrompt(input: string, responses: Record<string, string>): string {
  const ids = Object.keys(responses).sort();
  let prompt = "## Blind Evaluation Task\n\n";
  prompt += "### Original Task\n\n";
  prompt += `${input}\n\n`;
  prompt += "---\n\n";
  prompt += "### Responses to Evaluate\n\n";
  prompt +=
    "Evaluate each response independently. You do not know which model produced which response.\n\n";

  for (const id of ids) {
    prompt += `#### Response ${id}\n\n`;
    prompt += `${responses[id]}\n\n`;
    prompt += "---\n\n";
  }

  prompt += "### Your Assignment\n\n";
  prompt += `For EACH of the ${ids.length} responses above, provide a vote block in this exact format:\n\n`;
  prompt += "```vote\n";
  prompt += "RESPONSE: [ID]\n";
  prompt += "VERDICT: [APPROVE|REJECT|ABSTAIN]\n";
  prompt += "CONFIDENCE: [1-10]\n";
  prompt += "SUMMARY: [One sentence]\n";
  prompt += "KEY_ISSUES: [Comma-separated issues, or None]\n";
  prompt += "```\n\n";
  prompt += `Provide exactly ${ids.length} vote blocks, one per response. Be decisive and analytical.\n`;

  return prompt;
}

export function parseJudgeVotes(judgePath: string, responseIds: string[]): VoteResult[] {
  const votes: VoteResult[] = [];
  const responseFiles = readdirSync(judgePath)
    .filter((f) => f.startsWith("response-") && f.endsWith(".md"))
    .sort();

  for (const file of responseFiles) {
    const judgeId = file.replace(/^response-/, "").replace(/\.md$/, "");
    let content: string;
    try {
      content = readFileSync(join(judgePath, file), "utf-8");
    } catch (err) {
      // This judge's votes are dropped from the verdict; say so.
      log(
        `[team] judge answer ${file} unreadable: ${err instanceof Error ? err.message : String(err)}`
      );
      continue;
    }

    // Parse ```vote ... ``` blocks
    const votePattern = /```vote\s*\n([\s\S]*?)\n\s*```/g;
    let match: RegExpExecArray | null;
    // biome-ignore lint/suspicious/noAssignInExpressions: canonical RegExp.exec() iteration idiom
    while ((match = votePattern.exec(content)) !== null) {
      const block = match[1];
      const responseMatch = block.match(/RESPONSE:\s*(\S+)/);
      const verdictMatch = block.match(/VERDICT:\s*(APPROVE|REJECT|ABSTAIN)/);
      const confidenceMatch = block.match(/CONFIDENCE:\s*(\d+)/);
      const summaryMatch = block.match(/SUMMARY:\s*(.+)/);
      const keyIssuesMatch = block.match(/KEY_ISSUES:\s*(.+)/);

      const responseId = responseMatch?.[1];
      const verdict = verdictMatch?.[1];

      if (!responseId || !verdict) continue;
      // Only record votes for IDs we expect
      if (!responseIds.includes(responseId)) continue;

      votes.push({
        judgeId,
        responseId,
        verdict: verdict as "APPROVE" | "REJECT" | "ABSTAIN",
        confidence: Number.parseInt(confidenceMatch?.[1] ?? "5", 10),
        summary: summaryMatch?.[1]?.trim() ?? "",
        keyIssues:
          keyIssuesMatch?.[1]
            ?.split(",")
            .map((s) => s.trim())
            .filter((s) => s.toLowerCase() !== "none" && s.length > 0) ?? [],
      });
    }
  }

  return votes;
}

export function aggregateVerdict(votes: VoteResult[], responseIds: string[]): TeamVerdict {
  const responses: TeamVerdict["responses"] = {};

  for (const id of responseIds) {
    const votesForResponse = votes.filter((v) => v.responseId === id);
    const approvals = votesForResponse.filter((v) => v.verdict === "APPROVE").length;
    const rejections = votesForResponse.filter((v) => v.verdict === "REJECT").length;
    const abstentions = votesForResponse.filter((v) => v.verdict === "ABSTAIN").length;
    const total = approvals + rejections;

    responses[id] = {
      approvals,
      rejections,
      abstentions,
      score: total > 0 ? approvals / total : 0,
    };
  }

  const ranking = Object.entries(responses)
    .sort(([, a], [, b]) => b.score - a.score)
    .map(([id]) => id);

  return { responses, ranking, votes };
}

function formatVerdict(verdict: TeamVerdict, sessionPath: string): string {
  let manifest: TeamManifest | null = null;
  try {
    manifest = JSON.parse(readFileSync(join(sessionPath, "manifest.json"), "utf-8"));
  } catch {
    // If manifest is missing we just won't show model names
  }

  let output = "# Team Verdict\n\n";
  output += "## Ranking\n\n";
  output += "| Rank | Response | Model | Score | Approvals | Rejections | Abstentions |\n";
  output += "|------|----------|-------|-------|-----------|------------|-------------|\n";

  for (let i = 0; i < verdict.ranking.length; i++) {
    const id = verdict.ranking[i];
    const r = verdict.responses[id];
    const modelName = manifest?.models[id]?.model ?? "unknown";
    const scoreStr = `${(r.score * 100).toFixed(0)}%`;
    output += `| ${i + 1} | ${id} | ${modelName} | ${scoreStr} | ${r.approvals} | ${r.rejections} | ${r.abstentions} |\n`;
  }

  output += "\n## Individual Votes\n\n";
  for (const vote of verdict.votes) {
    const issueStr = vote.keyIssues.length > 0 ? ` Issues: ${vote.keyIssues.join(", ")}.` : "";
    output += `- **Judge ${vote.judgeId}** -> Response ${vote.responseId}: **${vote.verdict}** (${vote.confidence}/10) — ${vote.summary}${issueStr}\n`;
  }

  return output;
}