@a-t-h-i/bot-lobby 0.6.5 → 0.6.7

package/src/pi/ui.ts

@@ -1,32 +1,10 @@
-import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { Key, type Component, type TUI } from "@earendil-works/pi-tui";
-import { clip } from "../width.ts";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
 import type { AgentRun } from "../schemas/findings.ts";
-import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
+import type { Task } from "../schemas/task.ts";
 import { activeTask } from "../state/persistence.ts";
 import { detectProjectRoot } from "../state/project.ts";
-import {
-  advanceExpression,
-  anyPlaying,
-  createExpression,
-  expressionPhase,
-  FAST_TICK_MS,
-  ORACLE_GAP,
-  SLOT_GAP,
-  talkFrame,
-  triggerEmote,
-  WORKING_BLINK_CHANCE,
-  WORKING_GAP,
-  type ExpressionGap,
-  type ExpressionState,
-} from "./expressions.ts";
-import { ORACLE_THINKING } from "./activity.ts";
-import { SLOT_IDS, type SlotId } from "./mascot-art.ts";
-import { slotSituations } from "./zen-metrics.ts";
-import type { Situation } from "./kaomoji.ts";
-import { isQuiet, isSubagentProcess, toggleQuiet } from "./quiet.ts";
-import { panelLines, type ExpressionFrames, type OracleMotion } from "./zen.ts";
-import { budgetClock } from "../state/budget.ts";
+import { isSubagentProcess, isQuiet, toggleQuiet } from "./quiet.ts";
 
 export const STATUS_KEY = "bot-lobby";
 
@@ -44,44 +22,14 @@ export function statusText(task: Task | undefined, minimized = false): string {
   return `bot-lobby ${task.id} · ${task.paused ? `${task.state} (paused)` : task.state} · ${mode}`;
 }
 
-let zenOn = false;
-
 /**
- * Widget state. `live` holds the runs reported in this session; `runs` is what the
- * panel draws: the task's persisted worker records overlaid by the live copies,
- * so the checklist replays after a reload. `version` bumps on every change and
- * keys the widget's render cache.
+ * The session's task state. `live` holds the runs reported in this session;
+ * `runs` is the task's persisted worker records overlaid by the live copies,
+ * so the checklist replays after a reload.
  */
 let zenState: { task: Task | undefined; live: AgentRun[]; runs: AgentRun[] } = { task: undefined, live: [], runs: [] };
-/** Where the widget's task lives, so its time budget can be read. */
-let zenPaths: { root: string; configDir: string } | undefined;
-let zenVersion = 0;
-
-/** Latest master tool activity; the oracle's speech bubble shows it. */
-let oracleActivity: string | undefined;
-
-/** The mounted widget, so run and activity updates can repaint without waiting a tick. */
-let mountedWidget: { refresh(): void } | undefined;
-
-function touch(): void {
-  zenVersion += 1;
-  mountedWidget?.refresh();
-}
 
-/** Record the master's current activity word (see events.ts); undefined means it waits on the user. */
-export function setOracleActivity(activity: string | undefined, now = Date.now()): void {
-  if (activity === oracleActivity) return;
-  oracleActivity = activity;
-  // The oracle speaks when it names something new, including handing you the turn;
-  // quietly going back to "thinking" between tool calls is not worth a word.
-  if (activity !== ORACLE_THINKING) oracleSpokeAt = now;
-  touch();
-}
-
-/** When the oracle last said something new; its mouth lip-syncs for `TALK_MS` after. */
-let oracleSpokeAt: number | undefined;
-
-/** Upper bound on retained runs so a long task cannot grow the widget state without limit. */
+/** Upper bound on retained runs so a long task cannot grow the task state without limit. */
 export const MAX_RETAINED_RUNS = 128;
 
 /**
@@ -123,10 +71,9 @@ function slim(runs: readonly AgentRun[]): AgentRun[] {
 
 function setZenState(task: Task | undefined, live: AgentRun[]): void {
   zenState = { task, live, runs: mergeRuns(persistedRuns(task), live) };
-  touch();
 }
 
-/** Per-session standard-pi mode: the widget and Master prompt are hidden but ownership stays. */
+/** Per-session standard-pi mode: the Master prompt is hidden but ownership stays. */
 let minimized = false;
 
 export function isMinimized(): boolean {
@@ -153,206 +100,8 @@ export function toggleMinimized(ctx: ExtensionContext, configDir: string): void
   ctx.ui.notify(minimized ? "bot-lobby minimized — ctrl+shift+m or /bot-lobby restore to return" : "bot-lobby restored", "info");
 }
 
-export const LIVE_TICK_MS = 250;
-export const IDLE_TICK_MS = 1000;
-
-/** Fast frames while an agent works or the task is live; slow frames when it is quiet. */
-function isLive(): boolean {
-  if (zenState.runs.some((run) => run.status === "running")) return true;
-  const task = zenState.task;
-  return Boolean(task && !TERMINAL_STATES.includes(task.state) && !task.paused);
-}
-
-function liveTickDelay(): number {
-  return isLive() ? LIVE_TICK_MS : IDLE_TICK_MS;
-}
-
-/** Tick delay for the zen clock: fastest while an expression plays or the oracle talks, so no step is skipped. */
-export function expressionTickDelay(states: readonly ExpressionState[], now: number, live: boolean, talking = false): number {
-  if (talking || anyPlaying(states, now)) return FAST_TICK_MS;
-  return live ? LIVE_TICK_MS : IDLE_TICK_MS;
-}
-
-/** Every sprite with its own expression schedule. */
-type ExpressionKey = keyof ExpressionFrames;
-const EXPRESSION_KEYS: readonly ExpressionKey[] = [...SLOT_IDS, "oracle"];
-
-/** The oracle keeps its own schedule; working agents are livelier than idle ones. */
-function gapFor(key: ExpressionKey, situations?: Record<SlotId, Situation>): ExpressionGap {
-  if (key === "oracle") return ORACLE_GAP;
-  return situations?.[key].status === "working" ? WORKING_GAP : SLOT_GAP;
-}
-
-function blinkChanceFor(key: ExpressionKey, situations?: Record<SlotId, Situation>): number | undefined {
-  return key !== "oracle" && situations?.[key].status === "working" ? WORKING_BLINK_CHANCE : undefined;
-}
-
-/** A compact fingerprint of what a slot is going through; a change may earn a reaction. */
-export function situationKey(situation: Situation): string {
-  return [situation.status, situation.flag ?? "", situation.handover ? "handover" : "", situation.wrappedUp ? "wrapped" : ""].join("|");
-}
-
-/**
- * Whether a slot's change of situation deserves an immediate emote: it started
- * work, finished, failed, got flagged (waiting, quiet, retrying) or received a
- * file. Going idle, or a flag clearing, passes quietly.
- */
-export function isReaction(previous: string | undefined, next: Situation): boolean {
-  if (previous === undefined || previous === situationKey(next)) return false;
-  if (next.status === "idle") return false;
-  if (next.status !== "working") return true;
-  return !previous.startsWith("working|") || next.flag !== undefined || next.handover === true;
-}
-
-/**
- * The animated zen scene: the tick, each sprite's expression schedule and the
- * reactions to what the agents go through. The widget and the lobby's home tab
- * each own one and advance it from their own clock.
- */
-export class ZenScene {
-  tick = 0;
-  private readonly expressions: Record<ExpressionKey, ExpressionState>;
-  private readonly situations: Partial<Record<SlotId, string>> = {};
-  private readonly rng: () => number;
-  private cache: { key: string; theme: Theme | undefined; lines: string[] } | undefined;
-
-  constructor(rng: () => number = Math.random, now = Date.now()) {
-    this.rng = rng;
-    const entries = EXPRESSION_KEYS.map((key) => [key, createExpression(now, rng, gapFor(key))] as const);
-    this.expressions = Object.fromEntries(entries) as Record<ExpressionKey, ExpressionState>;
-  }
-
-  /** One clock step: expressions advance and agents react to their new situations. */
-  advance(now = Date.now()): void {
-    this.tick += 1;
-    const situations = slotSituations(zenState.runs, now);
-    for (const key of EXPRESSION_KEYS) {
-      this.expressions[key] = advanceExpression(this.expressions[key], now, this.rng, gapFor(key, situations), blinkChanceFor(key, situations));
-    }
-    for (const id of SLOT_IDS) {
-      const situation = situations[id];
-      if (isReaction(this.situations[id], situation)) this.expressions[id] = triggerEmote(now, this.rng, gapFor(id, situations));
-      this.situations[id] = situationKey(situation);
-    }
-  }
-
-  /** The delay until the next step: fast while an expression plays or the oracle talks. */
-  delay(now = Date.now()): number {
-    return expressionTickDelay(Object.values(this.expressions), now, isLive(), talkFrame(oracleSpokeAt, now) !== undefined);
-  }
-
-  private motion(now: number): OracleMotion {
-    return { phase: expressionPhase(this.expressions.oracle, now), talk: talkFrame(oracleSpokeAt, now) };
-  }
-
-  /**
-   * The scene lines for the current zen state. They only change with the tick,
-   * an expression frame, the widget state or the elapsed second, so any other
-   * repaint (typing, streaming output) reuses the last lines.
-   */
-  lines(width: number, rows: number, theme: Theme | undefined, now = Date.now(), still = false): string[] {
-    const expressions = Object.fromEntries(EXPRESSION_KEYS.map((key) => [key, this.expressions[key].frame])) as Partial<Record<ExpressionKey, number>>;
-    const variants = Object.fromEntries(SLOT_IDS.map((id) => [id, this.expressions[id].variant])) as Partial<Record<SlotId, number>>;
-    const quiet = isQuiet();
-    const frameKey = [...EXPRESSION_KEYS.map((key) => expressions[key] ?? 0), ...SLOT_IDS.map((id) => variants[id] ?? 0)].join(",");
-    const motion = this.motion(now);
-    const key = `${width}|${rows}|${this.tick}|${frameKey}|${motion.phase}|${motion.talk}|${zenVersion}|${Math.floor(now / 1000)}|${quiet}|${still}`;
-    if (this.cache && this.cache.key === key && this.cache.theme === theme) return this.cache.lines;
-    const time = zenState.task && zenPaths ? budgetClock(zenPaths.root, zenPaths.configDir, zenState.task.id, now) : undefined;
-    const opts = { width, rows, tick: this.tick, theme, expressions, variants, oracleActivity, oracleMotion: motion, still, ...(time ? { time } : {}) };
-    const lines = panelLines(zenState.task, zenState.runs, now, quiet, opts).map((line) => clip(line, width));
-    this.cache = { key, theme, lines };
-    return lines;
-  }
-
-  invalidate(): void {
-    this.cache = undefined;
-  }
-}
-
-/** The zen state as the lobby reads it: the session's active task and its runs. */
-export function zenSnapshot(): { task: Task | undefined; runs: readonly AgentRun[]; version: number; oracleActivity: string | undefined } {
-  return { task: zenState.task, runs: zenState.runs, version: zenVersion, oracleActivity };
-}
-
-/** Zen scene + plan checklist shown above the editor while a task is active and the lobby is closed. */
-class ZenWidget implements Component {
-  private readonly scene: ZenScene;
-  private delay = liveTickDelay();
-  private timer: ReturnType<typeof setInterval>;
-  private disposed = false;
-  private readonly tui: TUI;
-  private readonly theme: () => Theme;
-
-  constructor(tui: TUI, theme: () => Theme, rng: () => number = Math.random) {
-    this.tui = tui;
-    this.theme = theme;
-    this.scene = new ZenScene(rng);
-    this.timer = setInterval(() => this.advance(), this.delay);
-    mountedWidget = this;
-  }
-
-  /** Repaint now: state changed between ticks. */
-  refresh(): void {
-    if (!this.disposed) this.tui.requestRender();
-  }
-
-  private advance(): void {
-    if (this.disposed) return;
-    const now = Date.now();
-    this.scene.advance(now);
-    this.retime(now);
-    this.tui.requestRender();
-  }
-
-  /** One interval, retimed when work starts or stops or an expression plays. */
-  private retime(now: number): void {
-    const delay = this.scene.delay(now);
-    if (delay === this.delay) return;
-    this.delay = delay;
-    clearInterval(this.timer);
-    this.timer = setInterval(() => this.advance(), delay);
-  }
-
-  render(width: number): string[] {
-    return this.scene.lines(width, this.tui.terminal.rows, this.theme());
-  }
-
-  invalidate(): void {
-    this.scene.invalidate();
-  }
-
-  dispose(): void {
-    this.disposed = true;
-    clearInterval(this.timer);
-    if (mountedWidget === this) mountedWidget = undefined;
-  }
-}
-
-/** True while the full-screen lobby is showing; the small widget then stays unmounted. */
-let widgetSuppressed: () => boolean = () => false;
-let widgetMounted = false;
-
-/** The lobby registers how to tell whether it covers the screen. */
-export function setWidgetSuppressor(check: () => boolean): void {
-  widgetSuppressed = check;
-}
-
-function unmountWidget(ctx: ExtensionContext): void {
-  if (!widgetMounted) return;
-  widgetMounted = false;
-  ctx.ui.setWidget(STATUS_KEY, undefined);
-}
-
-function leaveZen(ctx: ExtensionContext): void {
-  if (!zenOn) return;
-  zenOn = false;
-  ctx.ui.setWorkingVisible(true);
-  ctx.ui.setWorkingIndicator();
-}
-
 /**
- * Refresh the footer + widget to match the task on disk. Runs are merged into the
+ * Refresh the footer to match the task on disk. Runs are merged into the
  * retained set for the same task because each `orchestrate` call reports only its
  * own agents: without retention the qa/reviewer call that follows the workers would
  * evict their successes and the checklist would reset. A new task starts clean.
@@ -360,28 +109,12 @@ function leaveZen(ctx: ExtensionContext): void {
 export function applyStatus(ctx: ExtensionContext, root: string, configDir: string, runs: AgentRun[] = []): void {
   const sessionId = ctx.sessionManager.getSessionId();
   const task = isSubagentProcess() || minimized ? undefined : activeTask(root, configDir, sessionId);
-  zenPaths = { root, configDir };
   const sameTask = zenState.task?.id === task?.id;
   setZenState(task, mergeRuns(sameTask ? zenState.live : [], slim(runs)));
   ctx.ui.setStatus(STATUS_KEY, statusText(task, minimized));
-  const active = Boolean(task && !TERMINAL_STATES.includes(task.state));
-  if (!active) {
-    leaveZen(ctx);
-    widgetMounted = false;
-    ctx.ui.setWidget(STATUS_KEY, undefined);
-    return;
-  }
-  zenOn = true;
-  ctx.ui.setWorkingVisible(false);
-  ctx.ui.setWorkingIndicator({ frames: [] });
-  if (widgetSuppressed()) return unmountWidget(ctx);
-  if (!widgetMounted) {
-    widgetMounted = true;
-    ctx.ui.setWidget(STATUS_KEY, (tui) => new ZenWidget(tui, () => ctx.ui.theme));
-  }
 }
 
-/** The session's active task as the widget last loaded it (undefined when none or minimized). */
+/** The session's active task as last loaded (undefined when none or minimized). */
 export function currentZenTask(): Task | undefined {
   return zenState.task;
 }
@@ -397,7 +130,7 @@ export function onRunUpdates(listener: ((runs: readonly AgentRun[]) => void) | u
  * Streamed run updates (start, every activity change, finish) from an in-flight
  * `orchestrate` call. The task on disk does not change mid-call, so this only
  * merges the runs and repaints; `applyStatus` rereads the task once the call ends.
- * Before any task is loaded it falls back to `applyStatus` so the widget appears.
+ * Before any task is loaded it falls back to `applyStatus` so the status appears.
  */
 export function reportRuns(ctx: ExtensionContext, root: string, configDir: string, runs: AgentRun[]): void {
   runListener?.(runs);
@@ -409,12 +142,8 @@ export function reportRuns(ctx: ExtensionContext, root: string, configDir: strin
 }
 
 export function clearStatus(ctx: ExtensionContext): void {
-  leaveZen(ctx);
-  widgetMounted = false;
-  oracleActivity = undefined;
   zenState = { task: undefined, live: [], runs: [] };
   ctx.ui.setStatus(STATUS_KEY, undefined);
-  ctx.ui.setWidget(STATUS_KEY, undefined);
 }
 
 /** Register `alt+t`, the reveal-on-demand toggle for built-in tool rows. */
@@ -425,7 +154,7 @@ export function registerRevealShortcut(pi: ExtensionAPI, configDir: string): voi
     handler: (ctx) => revealTools(ctx, configDir),
   });
   pi.registerShortcut(Key.ctrlShift("m"), {
-    description: "bot-lobby: minimize or restore the widget for this session",
+    description: "bot-lobby: minimize or restore bot-lobby for this session",
     handler: (ctx) => toggleMinimized(ctx, configDir),
   });
 }
@@ -443,3 +172,8 @@ function revealTools(ctx: ExtensionContext, configDir: string): void {
     "info",
   );
 }
+
+/** The session's active task and its runs, as the lobby reads them. */
+export function taskSnapshot(): { task: Task | undefined; runs: readonly AgentRun[] } {
+  return { task: zenState.task, runs: zenState.runs };
+}

package/src/roles/worker.ts

@@ -16,7 +16,7 @@ export const workerSpec: RoleSpec = {
   contract: [
     "### Output contract",
     "Respond with exactly these sections and nothing else: `## Completed`, `## Files Changed`,",
-    "`## Verification`, `## Notes`, `## Blockers`, `## Dependencies Needed`, `## Architecture Changes`,",
+    "`## Verification`, `## Brief Check` (one `- criterion — met|not met — evidence` line per \"Done when\" item of your brief), `## Notes`, `## Blockers`, `## Dependencies Needed`, `## Architecture Changes`,",
     "`## Knowledge Proposals` (`- knowledge: ...`, `- standard: ...`, or `- decision: ...`).",
     "`## Files Changed` entries are `- \\`path\\` — change`.",
     "`## Verification` entries are `- command — result`.",

package/src/schemas/configuration.ts

@@ -31,12 +31,18 @@ export interface AgentModelConfig {
   instructions?: string;
   /** Time limit per run; falls back to `workflow.agentTimeoutMs`. */
   timeoutMs?: number;
+  /** Model this agent switches to when its own model runs out of usage or is unavailable; unset or `inherit` = none. */
+  fallbackModel?: ModelRef;
+  /** Thinking level on the fallback model; unset uses this agent's own `thinking`. */
+  fallbackThinking?: string;
 }
 
 /** Scouts pick a model and a time limit only; their thinking is fixed at `SCOUT_THINKING`. */
 export interface ScoutConfig {
   model: ModelRef;
   timeoutMs: number;
+  /** Model scouts switch to when theirs runs out of usage or is unavailable (they think at `SCOUT_THINKING` on it too). */
+  fallbackModel?: ModelRef;
 }
 
 /** Subagent kinds with their own settings entry. */
@@ -72,6 +78,8 @@ export interface WorkflowConfig {
   taskBudgetMinutes: number;
   /** Small, clear, low-risk requests take the fast track (no scouts, proposal or plan; QA only when tests are needed); false puts every task on the full workflow. */
   fastTrack: boolean;
+  /** A delegation that names nothing concrete, or is long without done criteria, is sent back to the oracle once for a fuller brief (sending it again unchanged goes through). */
+  briefCheck: boolean;
   /** A new request that one agent can do alone goes to the quick-fix agent once the oracle confirms; false makes every request a task. */
   routeQuickFixes: boolean;
 }
@@ -92,12 +100,10 @@ export function isPanelMember(value: string): value is PanelMember {
 }
 
 /**
- * Lobby panes that can be shown or hidden: the Lobby tab's animated oracle and
- * agents (off by default: the lobby keeps only the task's status, and the
- * animations show above pi's editor while the lobby is hidden), the
- * conversation, the activity log and thinking.
+ * Lobby panes that can be shown or hidden: the conversation, the activity log
+ * and thinking.
  */
-export const LOBBY_PANELS = ["animations", "conversation", "activity", "thinking"] as const;
+export const LOBBY_PANELS = ["conversation", "activity", "thinking"] as const;
 export type LobbyPanel = (typeof LOBBY_PANELS)[number];
 
 /** The full-screen lobby. */
@@ -114,6 +120,8 @@ export interface LobbyConfig {
   panels: Record<LobbyPanel, boolean>;
   /** Key overrides by action name, e.g. `{ "toggleThinking": "alt+t" }`. */
   keys: Record<string, string>;
+  /** A one-line status (task steps, planning round, quick fix, or idle) under the editor while the lobby is hidden. */
+  miniLine: boolean;
   /** Clicks and the wheel work in the lobby (click a draft line to comment on it); shift+drag still selects text. */
   mouse: boolean;
   /**
@@ -214,6 +222,7 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     freshContext: true,
     taskBudgetMinutes: 0,
     fastTrack: true,
+    briefCheck: true,
     routeQuickFixes: true,
   },
   knowledge: {
@@ -227,9 +236,10 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     planningPanel: [...PANEL_MEMBERS],
     autoAsk: true,
     issues: false,
-    panels: { animations: false, conversation: true, activity: true, thinking: true },
+    panels: { conversation: true, activity: true, thinking: true },
     keys: {},
     mouse: true,
+    miniLine: true,
     maxPlanningRounds: 5,
   },
   classifier: {
@@ -265,18 +275,22 @@ function positive(value: unknown): number | undefined {
 
 /** Merge one agent's override over its default; legacy `inherit` or unknown thinking falls back to the default level. */
 function normalizeAgent(base: AgentModelConfig, override: Partial<AgentModelConfig> | undefined): AgentModelConfig {
-  const merged = { ...base, ...(override ?? {}) };
+  const { fallbackModel: rawModel, fallbackThinking: rawThinking, ...merged } = { ...base, ...(override ?? {}) };
   const thinking = isThinkingLevel(merged.thinking) ? merged.thinking : base.thinking;
   const timeoutMs = positive(merged.timeoutMs) ?? base.timeoutMs;
-  return { ...merged, thinking, ...(timeoutMs ? { timeoutMs } : {}) };
+  const fallbackModel = typeof rawModel === "string" && rawModel.trim() && rawModel !== INHERIT_MODEL ? rawModel.trim() : undefined;
+  const fallbackThinking = typeof rawThinking === "string" && isThinkingLevel(rawThinking) ? rawThinking : undefined;
+  return { ...merged, thinking, ...(timeoutMs ? { timeoutMs } : {}), ...(fallbackModel ? { fallbackModel, ...(fallbackThinking ? { fallbackThinking } : {}) } : {}) };
 }
 
 /** Scouts keep a model and a time limit; any thinking value in the file is dropped. */
 function normalizeScout(override: Partial<ScoutConfig> | undefined): ScoutConfig {
   const base = DEFAULT_CONFIG.scout;
+  const fallback = override?.fallbackModel;
   return {
     model: typeof override?.model === "string" && override.model.trim() ? override.model : base.model,
     timeoutMs: positive(override?.timeoutMs) ?? base.timeoutMs,
+    ...(typeof fallback === "string" && fallback.trim() && fallback !== INHERIT_MODEL ? { fallbackModel: fallback.trim() } : {}),
   };
 }
 
@@ -285,7 +299,7 @@ function flag(value: unknown, fallback: boolean): boolean {
 }
 
 function normalizeLobby(value: unknown): LobbyConfig {
-  const source = value as { autoOpen?: unknown; planningPanel?: unknown; autoAsk?: unknown; issues?: unknown; panels?: unknown; keys?: unknown; mouse?: unknown; maxPlanningRounds?: unknown } | undefined;
+  const source = value as { autoOpen?: unknown; planningPanel?: unknown; autoAsk?: unknown; issues?: unknown; panels?: unknown; keys?: unknown; mouse?: unknown; miniLine?: unknown; maxPlanningRounds?: unknown } | undefined;
   const defaults = DEFAULT_CONFIG.lobby;
   const panel = Array.isArray(source?.planningPanel)
     ? [...new Set(source.planningPanel.filter((entry): entry is PanelMember => typeof entry === "string" && isPanelMember(entry)))]
@@ -300,6 +314,7 @@ function normalizeLobby(value: unknown): LobbyConfig {
     panels: Object.fromEntries(LOBBY_PANELS.map((name) => [name, flag(panels[name], defaults.panels[name])])) as Record<LobbyPanel, boolean>,
     keys: Object.fromEntries(Object.entries(keys).filter((entry): entry is [string, string] => typeof entry[1] === "string" && entry[1].trim().length > 0)),
     mouse: flag(source?.mouse, defaults.mouse),
+    miniLine: flag(source?.miniLine, defaults.miniLine),
     maxPlanningRounds: roundLimit(source?.maxPlanningRounds, defaults.maxPlanningRounds),
   };
 }
@@ -353,6 +368,7 @@ export function resolveConfig(partial: unknown): BotLobbyConfig {
   const workflow = { ...DEFAULT_CONFIG.workflow, ...(src.workflow as Partial<WorkflowConfig> | undefined) };
   workflow.freshContext = workflow.freshContext !== false;
   workflow.fastTrack = workflow.fastTrack !== false;
+  workflow.briefCheck = workflow.briefCheck !== false;
   workflow.routeQuickFixes = workflow.routeQuickFixes !== false;
   workflow.taskBudgetMinutes = typeof workflow.taskBudgetMinutes === "number" && workflow.taskBudgetMinutes > 0 ? Math.min(24 * 60, Math.round(workflow.taskBudgetMinutes)) : 0;
   const knowledge = { ...DEFAULT_CONFIG.knowledge, ...(src.knowledge as Partial<KnowledgeConfig> | undefined) };
@@ -388,6 +404,22 @@ export interface AgentProfile {
   thinking: string;
   timeoutMs: number;
   instructions?: string;
+  /** Where the run goes when its model runs out of usage or is unavailable; absent = it just fails. */
+  fallback?: FallbackProfile;
+}
+
+/** The fallback model and the thinking level to run it at. */
+export interface FallbackProfile {
+  model: string;
+  thinking: string;
+}
+
+/** The fallback of a settings entry: its model and thinking (the entry's own level when none is set). */
+export function fallbackOf(entry: { fallbackModel?: string; fallbackThinking?: string; thinking?: string }): FallbackProfile | undefined {
+  const model = modelOf(entry.fallbackModel ?? INHERIT_MODEL);
+  if (!model) return undefined;
+  const own = entry.thinking && isThinkingLevel(entry.thinking) ? entry.thinking : DEFAULT_THINKING;
+  return { model, thinking: entry.fallbackThinking && isThinkingLevel(entry.fallbackThinking) ? entry.fallbackThinking : own };
 }
 
 /** The settings entry a domain/role run draws from. */
@@ -412,10 +444,12 @@ export function agentProfile(config: BotLobbyConfig, domain: Domain, role: Role)
   const instructions = config.agents[domain].instructions;
   const fallback = config.workflow.agentTimeoutMs;
   if (kind === "scout") {
-    return { kind, model: modelOf(config.scout.model), thinking: SCOUT_THINKING, timeoutMs: config.scout.timeoutMs || fallback, instructions };
+    const scoutFallback = fallbackOf({ fallbackModel: config.scout.fallbackModel, thinking: SCOUT_THINKING });
+    return { kind, model: modelOf(config.scout.model), thinking: SCOUT_THINKING, timeoutMs: config.scout.timeoutMs || fallback, instructions, ...(scoutFallback ? { fallback: scoutFallback } : {}) };
   }
   const entry = kind === "researcher" ? config.researcher : config.agents[kind];
-  return { kind, model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? fallback, instructions };
+  const entryFallback = fallbackOf(entry);
+  return { kind, model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? fallback, instructions, ...(entryFallback ? { fallback: entryFallback } : {}) };
 }
 
 /** The settings entry of a lobby agent (quick fix or planner). */
@@ -424,19 +458,21 @@ export function lobbyAgentConfig(config: BotLobbyConfig, kind: LobbyAgentKind):
 }
 
 /** Profile for a lobby agent run, from settings alone; `model` is undefined while unset. */
-export function lobbyAgentProfile(config: BotLobbyConfig, kind: LobbyAgentKind): { model?: string; thinking: string; timeoutMs: number; instructions?: string } {
+export function lobbyAgentProfile(config: BotLobbyConfig, kind: LobbyAgentKind): { model?: string; thinking: string; timeoutMs: number; instructions?: string; fallback?: FallbackProfile } {
   const entry = lobbyAgentConfig(config, kind);
-  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? config.workflow.agentTimeoutMs, instructions: entry.instructions };
+  const fallback = fallbackOf(entry);
+  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? config.workflow.agentTimeoutMs, instructions: entry.instructions, ...(fallback ? { fallback } : {}) };
 }
 
 /**
  * A planning panel seat's profile: the domain's (or the researcher's) model,
  * thinking and custom instructions, bounded by the planner's per-turn limit.
  */
-export function panelMemberProfile(config: BotLobbyConfig, member: PanelMember): { model?: string; thinking: string; timeoutMs: number; instructions?: string } {
+export function panelMemberProfile(config: BotLobbyConfig, member: PanelMember): { model?: string; thinking: string; timeoutMs: number; instructions?: string; fallback?: FallbackProfile } {
   const entry = member === "researcher" ? config.researcher : config.agents[member];
   const timeoutMs = config.planner.timeoutMs ?? config.workflow.agentTimeoutMs;
-  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs, instructions: entry.instructions };
+  const fallback = fallbackOf(entry);
+  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs, instructions: entry.instructions, ...(fallback ? { fallback } : {}) };
 }
 
 /** Resolves the model, thinking and time limit one subagent run uses. */

package/src/schemas/findings.ts

@@ -139,6 +139,8 @@ export interface AgentRun {
   wrappedUp?: boolean;
   /** File this worker is queued for at the file desk. */
   waitingFor?: string;
+  /** The run switched to its fallback model because this one ran out of usage or was unavailable. */
+  fellBackFrom?: string;
   /** The classifier routed this run down: the configured profile it came from (`p/big · medium`). */
   routedFrom?: string;
   /** Why and where it was routed (`trivial 0.88: p/big · medium → p/cheap · low`). */

package/src/workflow/brief.ts

@@ -0,0 +1,59 @@
+/**
+ * A cheap check that a delegation is a brief a small model can act on: it
+ * points at something concrete, and a longer one says when it is done. It only
+ * ever asks the master to add detail once: repeating the same instruction
+ * unchanged is accepted, so a short task that really is complete never gets
+ * stuck behind it. Pure apart from that one-entry-per-step memory.
+ */
+
+/** Longest instruction that only has to point at something concrete. */
+export const SHORT_BRIEF_CHARS = 200;
+
+/** A path, a file name with an extension, a `code` span, a quoted string or a "Files" label. */
+const ANCHOR = /(?:[\w.-]+\/[\w./-]+)|(?:\b[\w-]+\.[a-z]{1,5}\b)|`[^`\n]+`|"[^"\n]{2,}"|\*\*files?\*\*|\bfiles?:/i;
+/** An identifier in camelCase, PascalCase or snake_case (case matters, so it is kept apart). */
+const IDENTIFIER = /\b[a-z]+[A-Z]\w*\b|\b[A-Z][a-z]+[A-Z]\w*\b|\b[a-z]+_[a-z_]+\b/;
+/** Wording that states when the step is finished or how it is checked. */
+const CRITERIA = /done when|definition of done|acceptance|success criteri|verif|must (?:pass|print|return|show|exist|render|display|work)|should (?:pass|print|return|show|exist|render|display|work)|expect|check that|ensure/i;
+
+/** What a delegation is missing, one sentence each; empty when it is fine. */
+export function briefProblems(instruction: string): string[] {
+  const text = instruction.replace(/\s+/g, " ").trim();
+  const problems: string[] = [];
+  if (!ANCHOR.test(text) && !IDENTIFIER.test(text)) problems.push("it names no file, path, function, identifier or exact string, so the agent must guess where and what to change");
+  if (text.length > SHORT_BRIEF_CHARS && !CRITERIA.test(text)) problems.push("it has no \"Done when\" criteria (observable checks, or commands and what they should show), so the agent cannot tell when it has finished");
+  return problems;
+}
+
+const lastRejected = new Map<string, string>();
+
+const normalize = (text: string) => text.replace(/\s+/g, " ").trim().toLowerCase();
+
+/**
+ * The error to answer a delegation with, or undefined to let it through. The
+ * first time a step's brief falls short it is sent back; sending the same
+ * text again means the master has judged it complete.
+ */
+export function briefRejection(taskId: string, domain: string, instruction: string): string | undefined {
+  const key = `${taskId}:${domain}`;
+  const problems = briefProblems(instruction);
+  if (problems.length === 0) {
+    lastRejected.delete(key);
+    return undefined;
+  }
+  if (lastRejected.get(key) === normalize(instruction)) {
+    lastRejected.delete(key);
+    return undefined;
+  }
+  lastRejected.set(key, normalize(instruction));
+  return [
+    `The ${domain} brief was not sent: ${problems.join("; ")}.`,
+    "The agent may be a smaller, literal model that assumes nothing. Rewrite the brief as: Goal, Files, numbered What to do (exact names, shapes, values), Contracts, Constraints, Done when, If stuck.",
+    "If it really is complete as written, send the same instruction again and it goes through.",
+  ].join(" ");
+}
+
+/** Forget what was rejected (tests). */
+export function resetBriefs(): void {
+  lastRejected.clear();
+}