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

package/src/pi/plan-checklist.ts

@@ -0,0 +1,305 @@
+/**
+ * The plan as a checklist: its steps parsed from the plan text, and each one
+ * done, current or pending from the worker runs so far. Pure.
+ */
+import type { AgentRun } from "../schemas/findings.ts";
+
+/** Upper bound on parsed plan steps so the checklist stays bounded. */
+export const MAX_PLAN_STEPS = 50;
+
+const PREFIX_CHARS = 32;
+const MIN_PREFIX = 8;
+const HEADER_LINE = /^\s*(?:#{1,6}\s+\S.*|\*\*[^*]+\*\*)\s*$/;
+const STEP_SECTION = /sequence|steps|order/i;
+const NUMBERED_STEP_LINE = /^(\s*)(\d+[.)])\s+(.*\S)\s*$/;
+const BULLET_LINE = /^(\s*)([*-])\s+(.*\S)\s*$/;
+const TOP_LEVEL_BULLET = /^()([*-])\s+(.*\S)\s*$/;
+/** `### Step 2: Wire the API`, `**Step 2 — Wire the API**`, `Phase 3) Tests`: one plan step per heading. */
+const STEP_HEADING = /^\s*(?:#{1,6}\s+)?(?:\*\*)?\s*(?:step|phase|stage)\s+#?\d+\s*(?:\*\*)?\s*[:.)\u2014\u2013-]\s*(?:\*\*)?\s*(.*?)\s*(?:\*\*)?\s*$/i;
+const MIN_STEP_HEADINGS = 2;
+
+export type PlanStepStatus = "done" | "current" | "pending";
+
+export interface PlanStep {
+  text: string;
+  status: PlanStepStatus;
+}
+
+interface ListItem {
+  indent: number;
+  /** Column where the item's text starts; deeper items are nested under it. */
+  content: number;
+  text: string;
+}
+
+type ItemMatcher = (line: string) => ListItem | undefined;
+
+function indentOf(line: string): number {
+  return /^\s*/.exec(line)![0].replace(/\t/g, "    ").length;
+}
+
+function itemMatcher(pattern: RegExp): ItemMatcher {
+  return (line) => {
+    const match = pattern.exec(line);
+    if (!match) return undefined;
+    const indent = indentOf(match[1]!);
+    return { indent, content: indent + match[2]!.length + 1, text: match[3]! };
+  };
+}
+
+const numberedItem = itemMatcher(NUMBERED_STEP_LINE);
+const bulletItem = itemMatcher(BULLET_LINE);
+const topBulletItem = itemMatcher(TOP_LEVEL_BULLET);
+
+/** Numbered `1.`/`1)` text, or a bullet inside a step section; undefined otherwise. */
+function sectionItem(line: string): ListItem | undefined {
+  return numberedItem(line) ?? bulletItem(line);
+}
+
+/**
+ * Top-level list items only. As in CommonMark, an item indented to its parent's
+ * text column is a sub-point of that step, so nested bullets or a nested `1.`
+ * list never inflate the checklist. Prose at a shallower indent ends the parent.
+ */
+function collectSteps(lines: readonly string[], accept: ItemMatcher): string[] {
+  const found: string[] = [];
+  let parent: number | undefined;
+  for (const line of lines) {
+    const item = accept(line);
+    if (!item) {
+      if (parent !== undefined && line.trim() && indentOf(line) < parent) parent = undefined;
+      continue;
+    }
+    if (parent !== undefined && item.indent >= parent) continue;
+    found.push(item.text);
+    parent = item.content;
+  }
+  return found;
+}
+
+/** Body of the first `sequence|steps|order` header, up to the next header; undefined when absent. */
+function stepSection(lines: readonly string[]): string[] | undefined {
+  const start = lines.findIndex((line) => HEADER_LINE.test(line) && STEP_SECTION.test(line));
+  if (start < 0) return undefined;
+  const body: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (HEADER_LINE.test(line)) break;
+    body.push(line);
+  }
+  return body;
+}
+
+/** `Step N` headings, when the plan is structured as one heading per step. */
+function headingSteps(lines: readonly string[]): string[] {
+  const found: string[] = [];
+  for (const line of lines) {
+    const match = STEP_HEADING.exec(line);
+    if (match) found.push(match[1] || line.replace(/[#*]/g, "").trim());
+  }
+  return found.length >= MIN_STEP_HEADINGS ? found : [];
+}
+
+/**
+ * Step texts from a free-form plan, capped. `Step N` headings win; then a
+ * `sequence|steps|order` section; then numbered lines; when none exists,
+ * top-level bullets are the last resort, so unrelated bullet lists under other
+ * headers never leak into the checklist. Only the shallowest items count.
+ */
+export function planSteps(plan: string): string[] {
+  const lines = plan.split("\n");
+  const headings = headingSteps(lines);
+  if (headings.length > 0) return headings.slice(0, MAX_PLAN_STEPS);
+  const section = stepSection(lines);
+  if (section) {
+    const sectioned = collectSteps(section, sectionItem);
+    if (sectioned.length > 0) return sectioned.slice(0, MAX_PLAN_STEPS);
+  }
+  const numbered = collectSteps(lines, numberedItem);
+  if (numbered.length > 0) return numbered.slice(0, MAX_PLAN_STEPS);
+  return collectSteps(lines, topBulletItem).slice(0, MAX_PLAN_STEPS);
+}
+
+/* -------------------------------------------------------------------------
+ * Step matching. A worker instruction names its step explicitly ("Step 3: ...")
+ * or is scored against every step by shared paths, a shared opening phrase and
+ * word overlap. Plans reuse file paths across steps, so near-ties go to the
+ * earliest step still open instead of the first step that ever mentioned the
+ * path -- otherwise every later instruction re-matches step 1 and the tracker
+ * never moves.
+ * ---------------------------------------------------------------------- */
+
+const STEP_REFERENCE = /\bsteps?\s*#?\s*(\d+)(?:\s*(?:-|\u2013|\u2014|to|through|thru|and|&)\s*#?\s*(\d+))?/gi;
+/** Text allowed before a step reference that labels the instruction itself ("Now implement step 3:"). */
+const LEADING_LABEL = /^[\s\W]*(?:(?:now|next|then|please|implement|do|complete|execute|start|begin|finish|work on|continue with|proceed with|plan)\s+)*(?:the\s+)?$/i;
+const MIN_SCORE = 0.5;
+const NEAR_TIE = 0.35;
+const PATH_WEIGHT = 0.75;
+const PREFIX_WEIGHT = 1;
+const WORD = /[a-z0-9_][a-z0-9_./-]*[a-z0-9_]/g;
+const MIN_WORD = 3;
+const STOP_WORDS = new Set([
+  "the", "and", "for", "with", "that", "this", "from", "into", "then", "when", "each", "use", "make",
+  "sure", "new", "all", "any", "its", "are", "not", "but", "now", "via", "per", "our", "your", "you",
+  "has", "have", "will", "should", "must", "also", "only", "step", "steps", "plan", "approved",
+  "implement", "please", "add", "update", "change", "changes", "file", "files", "code",
+]);
+
+function normalize(text: string): string {
+  return text.replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+function significantWords(text: string): Set<string> {
+  const words = new Set<string>();
+  for (const word of normalize(text).match(WORD) ?? []) {
+    if (word.length >= MIN_WORD && !STOP_WORDS.has(word)) words.add(word);
+  }
+  return words;
+}
+
+/** Scoring context for one instruction, built once per run and reused for every step. */
+interface InstructionIndex {
+  text: string;
+  words: Set<string>;
+}
+
+function indexInstruction(instruction: string): InstructionIndex {
+  return { text: normalize(instruction), words: significantWords(instruction) };
+}
+
+function prefixMatches(step: string, hay: string): boolean {
+  const tail = normalize(step.replace(/`[^`]+`/g, " ").replace(/^[\s:;,.\u2014\u2013-]+/, ""));
+  return tail.length >= MIN_PREFIX && hay.includes(tail.slice(0, PREFIX_CHARS));
+}
+
+function pathShare(step: string, hay: string): number {
+  const paths = [...step.matchAll(/`([^`]+)`/g)].map((match) => normalize(match[1]!)).filter((path) => path.length > 0);
+  if (paths.length === 0) return 0;
+  return paths.filter((path) => hay.includes(path)).length / paths.length;
+}
+
+function wordShare(step: string, words: ReadonlySet<string>): number {
+  const own = significantWords(step);
+  if (own.size === 0) return 0;
+  let shared = 0;
+  for (const word of own) if (words.has(word)) shared += 1;
+  return shared / own.size;
+}
+
+/** How strongly an instruction targets one step; 0 when it shares nothing. */
+function stepScore(step: string, instruction: InstructionIndex): number {
+  const prefix = prefixMatches(step, instruction.text) ? PREFIX_WEIGHT : 0;
+  return prefix + PATH_WEIGHT * pathShare(step, instruction.text) + wordShare(step, instruction.words);
+}
+
+/**
+ * Highest 0-based step an instruction labels itself with ("Step 3: ...", "steps 2-4"),
+ * or -1. A reference counts when it opens the instruction or is the only one
+ * named, so "building on step 1, now do step 3" does not jump back to step 1.
+ */
+export function explicitStepIndex(instruction: string, count: number): number {
+  const refs = [...instruction.matchAll(STEP_REFERENCE)];
+  if (refs.length === 0) return -1;
+  const first = refs[0]!;
+  const leading = LEADING_LABEL.test(instruction.slice(0, first.index ?? 0)) ? first : undefined;
+  const distinct = new Set(refs.map((ref) => ref[0].toLowerCase().replace(/\s+/g, "")));
+  const chosen = leading ?? (distinct.size === 1 ? refs[0] : undefined);
+  if (!chosen) return -1;
+  const last = Math.max(Number(chosen[1]), Number(chosen[2] ?? chosen[1]));
+  return last >= 1 && last <= count ? last - 1 : -1;
+}
+
+/**
+ * The step an instruction targets, given the steps already completed; -1 when
+ * nothing matches. Among near-tied candidates the earliest open step wins.
+ */
+export function targetStep(steps: readonly string[], instruction: string | undefined, completed: ReadonlySet<number> = new Set()): number {
+  if (!instruction || steps.length === 0) return -1;
+  const explicit = explicitStepIndex(instruction, steps.length);
+  if (explicit >= 0) return explicit;
+  const index = indexInstruction(instruction);
+  const scores = steps.map((step) => stepScore(step, index));
+  const best = Math.max(...scores);
+  if (best < MIN_SCORE) return -1;
+  const near = scores.findIndex((score, at) => score >= best - NEAR_TIE && score >= MIN_SCORE && !completed.has(at));
+  return near >= 0 ? near : scores.indexOf(best);
+}
+
+/** The latest worker run carrying an instruction; its step is the current one. */
+export function latestWorkerRun(runs: readonly AgentRun[]): AgentRun | undefined {
+  let latest: AgentRun | undefined;
+  for (const run of runs) {
+    if (run.role !== "worker" || !run.instruction) continue;
+    if (!latest || Date.parse(run.startedAt) >= Date.parse(latest.startedAt)) latest = run;
+  }
+  return latest;
+}
+
+function stepStatus(index: number, current: number): PlanStepStatus {
+  if (current < 0) return index === 0 ? "current" : "pending";
+  if (index < current) return "done";
+  return index === current ? "current" : "pending";
+}
+
+/** Lowest index not yet in `completed`, or -1 when every step is. */
+function nextOpenStep(steps: readonly string[], completed: ReadonlySet<number>): number {
+  return steps.findIndex((_text, index) => !completed.has(index));
+}
+
+/** Marks every step up to and including `index` as completed. */
+function markThrough(completed: Set<number>, index: number): void {
+  for (let step = 0; step <= index; step += 1) completed.add(step);
+}
+
+function byStart(runs: readonly AgentRun[]): AgentRun[] {
+  const time = (run: AgentRun) => {
+    const at = Date.parse(run.startedAt);
+    return Number.isFinite(at) ? at : 0;
+  };
+  return runs
+    .map((run, order) => ({ run, order }))
+    .sort((a, b) => time(a.run) - time(b.run) || a.order - b.order)
+    .map((entry) => entry.run);
+}
+
+/**
+ * Replays worker runs in start order. A successful run completes everything up
+ * to its target step; a run that matches nothing -- the common case for a
+ * reworded instruction -- completes the next still-open step, so the count only
+ * grows and a failure can never tick one off. The latest worker run's own target
+ * is reported separately so a running or failed step reads current.
+ */
+function replaySteps(steps: readonly string[], runs: readonly AgentRun[]): { completed: number; latest: number } {
+  const completed = new Set<number>();
+  const latestRun = latestWorkerRun(runs);
+  let latest = -1;
+  for (const run of byStart(runs)) {
+    if (run.role !== "worker") continue;
+    const matched = targetStep(steps, run.instruction, completed);
+    if (run === latestRun) latest = matched >= 0 && run.status === "success" ? matched + 1 : matched;
+    if (run.status !== "success") continue;
+    const target = matched >= 0 ? matched : nextOpenStep(steps, completed);
+    if (target >= 0) markThrough(completed, target);
+  }
+  return { completed: completed.size, latest };
+}
+
+/** One-entry memo: the panel asks for the same checklist several times per frame. */
+let checklistMemo: { plan: string; runs: readonly AgentRun[]; steps: PlanStep[] } | undefined;
+
+/**
+ * Done/current/pending per plan step. A succeeded run completes its step, so the
+ * next step becomes current (and the last step reads done); running, failed,
+ * cancelled and timeout runs keep it current. Progress is monotonic: steps
+ * already completed by successful worker runs stay done, and a later call that
+ * names an earlier step can never tick it back. Memoized on the exact plan text
+ * and runs array, so callers must not mutate either.
+ */
+export function planChecklist(plan: string, runs: readonly AgentRun[]): PlanStep[] {
+  if (checklistMemo && checklistMemo.plan === plan && checklistMemo.runs === runs) return checklistMemo.steps;
+  const texts = planSteps(plan);
+  const replay = replaySteps(texts, runs);
+  const current = Math.max(replay.completed, replay.latest);
+  const steps = texts.map((text, index) => ({ text, status: stepStatus(index, current) }));
+  checklistMemo = { plan, runs, steps };
+  return steps;
+}

package/src/pi/run-summary.ts

@@ -6,16 +6,25 @@
 import type { AgentRun } from "../schemas/findings.ts";
 import type { RunLogEntry } from "../schemas/task.ts";
 import { shortDuration } from "../text.ts";
-import { SLOT_LABELS, type SlotId } from "./mascot-art.ts";
 
-/** The zen column a run belongs to; a researcher reports under RESEARCH from any domain. */
+export type SlotId = "dev" | "design" | "research" | "qa";
+
+/** Uppercase agent names. */
+const SLOT_LABELS: Record<SlotId, string> = {
+  dev: "DEV",
+  design: "DESIGN",
+  research: "RESEARCH",
+  qa: "QA",
+};
+
+/** The agent slot a run belongs to; a researcher reports under RESEARCH from any domain. */
 export function slotOf(run: Pick<AgentRun, "domain" | "role">): SlotId {
   if (run.role === "researcher") return "research";
   if (run.domain === "backend") return "dev";
   return run.domain === "designer" ? "design" : "qa";
 }
 
-/** Upper-case agent name as the scene shows it (DEV, DESIGN, RESEARCH, QA). */
+/** Upper-case agent name (DEV, DESIGN, RESEARCH, QA). */
 export function agentName(run: Pick<AgentRun, "domain" | "role">): string {
   return SLOT_LABELS[slotOf(run)];
 }

package/src/pi/settings-ui.ts

@@ -40,11 +40,14 @@ interface EntryView {
   thinking?: string;
   instructions?: string;
   timeoutMs?: number;
+  /** The model this agent switches to when its own runs out of usage; unset = none. */
+  fallbackModel?: string;
+  fallbackThinking?: string;
 }
 
 function entryView(config: BotLobbyConfig, kind: SettingsKind): EntryView {
   if (kind === "master") return config.master;
-  if (kind === "scout") return { model: config.scout.model, timeoutMs: config.scout.timeoutMs };
+  if (kind === "scout") return { model: config.scout.model, timeoutMs: config.scout.timeoutMs, ...(config.scout.fallbackModel ? { fallbackModel: config.scout.fallbackModel } : {}) };
   if (kind === "researcher") return config.researcher;
   if (kind === "quickfix") return config.quickFix;
   if (kind === "planner") return config.planner;
@@ -56,21 +59,33 @@ interface EntryPatch {
   thinking?: string;
   instructions?: string;
   timeoutMs?: number;
+  /** `inherit` clears the fallback (its thinking level with it). */
+  fallbackModel?: string;
+  fallbackThinking?: string;
+}
+
+/** A settings entry with the fallback patch applied: `inherit` removes the fallback model and its thinking. */
+function withFallbackPatch<T extends { fallbackModel?: string; fallbackThinking?: string }>(entry: T): T {
+  if (entry.fallbackModel !== INHERIT_MODEL) return entry;
+  const { fallbackModel: _model, fallbackThinking: _thinking, ...rest } = entry;
+  return rest as T;
 }
 
 /** Apply a patch to one entry in a config copy; scouts ignore thinking and instructions. */
 export function patchEntry(config: BotLobbyConfig, kind: SettingsKind, patch: EntryPatch): BotLobbyConfig {
   const next: BotLobbyConfig = { ...config, agents: { ...config.agents } };
-  if (kind === "master") next.master = { ...config.master, ...patch } as AgentModelConfig;
+  if (kind === "master") next.master = withFallbackPatch({ ...config.master, ...patch } as AgentModelConfig);
   else if (kind === "scout") {
-    next.scout = {
+    const fallbackModel = patch.fallbackModel ?? config.scout.fallbackModel;
+    next.scout = withFallbackPatch({
       model: patch.model ?? config.scout.model,
       timeoutMs: patch.timeoutMs ?? config.scout.timeoutMs,
-    };
-  } else if (kind === "researcher") next.researcher = { ...config.researcher, ...patch } as AgentModelConfig;
-  else if (kind === "quickfix") next.quickFix = { ...config.quickFix, ...patch } as AgentModelConfig;
-  else if (kind === "planner") next.planner = { ...config.planner, ...patch } as AgentModelConfig;
-  else next.agents[kind] = { ...config.agents[kind], ...patch } as AgentModelConfig;
+      ...(fallbackModel ? { fallbackModel } : {}),
+    });
+  } else if (kind === "researcher") next.researcher = withFallbackPatch({ ...config.researcher, ...patch } as AgentModelConfig);
+  else if (kind === "quickfix") next.quickFix = withFallbackPatch({ ...config.quickFix, ...patch } as AgentModelConfig);
+  else if (kind === "planner") next.planner = withFallbackPatch({ ...config.planner, ...patch } as AgentModelConfig);
+  else next.agents[kind] = withFallbackPatch({ ...config.agents[kind], ...patch } as AgentModelConfig);
   return next;
 }
 
@@ -275,6 +290,37 @@ async function editThinking(pi: ExtensionAPI, ctx: ExtensionContext, kind: Setti
   await commit(pi, ctx, kind, { thinking: level }, `thinking → ${level}`);
 }
 
+/** The model an entry falls back to when its own runs out of usage; `none` removes it. */
+async function editFallbackModel(pi: ExtensionAPI, ctx: ExtensionContext, kind: SettingsKind): Promise<void> {
+  const view = entryView(loadConfig(), kind);
+  const current = view.fallbackModel ?? INHERIT_MODEL;
+  const none: SelectItem = { value: INHERIT_MODEL, label: current === INHERIT_MODEL ? "none ✓" : "none", description: "No fallback: when its model runs out of usage the run fails" };
+  const choice = await pick(ctx, `Fallback model — ${kindLabel(kind)}`, [none, ...modelItems(ctx, current, false)], { search: true });
+  if (choice === undefined) return;
+  const typed = choice === CUSTOM_MODEL ? (await ctx.ui.input("Model id", "provider/model"))?.trim() : choice;
+  if (!typed) return;
+  await commit(pi, ctx, kind, { fallbackModel: typed }, typed === INHERIT_MODEL ? "fallback removed" : `fallback model → ${typed}`);
+  if (typed === INHERIT_MODEL || kind === "scout") return;
+  // Keep the fallback's thinking level one its model can run.
+  const level = entryView(loadConfig(), kind).fallbackThinking;
+  const check = level ? checkThinking(modelLookup(ctx)(typed), level) : undefined;
+  if (check?.warning) {
+    updateEntry(kind, { fallbackThinking: check.level });
+    ctx.ui.notify(`bot-lobby: ${kindLabel(kind)} fallback — ${check.warning}.`, "warning");
+  }
+}
+
+/** The thinking level on the fallback model, limited to what that model supports. */
+async function editFallbackThinking(pi: ExtensionAPI, ctx: ExtensionContext, kind: SettingsKind): Promise<void> {
+  const view = entryView(loadConfig(), kind);
+  if (!view.fallbackModel) return;
+  const model = modelLookup(ctx)(view.fallbackModel);
+  const title = `Fallback thinking — ${kindLabel(kind)} (${view.fallbackModel})`;
+  const level = await pick(ctx, title, thinkingItems(supportedThinking(model), view.fallbackThinking ?? view.thinking));
+  if (!level || !isThinkingLevel(level)) return;
+  await commit(pi, ctx, kind, { fallbackThinking: level }, `fallback thinking → ${level}`);
+}
+
 async function editTimeout(pi: ExtensionAPI, ctx: ExtensionContext, kind: SettingsKind): Promise<void> {
   const current = entryView(loadConfig(), kind).timeoutMs ?? loadConfig().workflow.agentTimeoutMs;
   const typed = (await ctx.ui.input(`Time limit (minutes) — ${kindLabel(kind)}`, String(Math.round(current / 60_000))))?.trim();
@@ -303,6 +349,8 @@ export function entryItems(kind: SettingsKind, view: EntryView): SelectItem[] {
   const items: SelectItem[] = [{ value: "model", label: "Model", description: view.model }];
   if (kind === "scout") items.push({ value: "fixed", label: "Thinking", description: `${SCOUT_THINKING} (fixed for scouts)` });
   else items.push({ value: "thinking", label: "Thinking", description: view.thinking ?? "" });
+  items.push({ value: "fallback", label: "Fallback model", description: view.fallbackModel ?? "none · used when this model runs out of usage" });
+  if (kind !== "scout" && view.fallbackModel) items.push({ value: "fallbackThinking", label: "Fallback thinking", description: view.fallbackThinking ?? view.thinking ?? "" });
   if (kind !== "master") items.push({ value: "timeout", label: "Time limit", description: minutes(view.timeoutMs) });
   if (kind !== "scout" && kind !== "researcher") {
     items.push({ value: "instructions", label: "Instructions", description: view.instructions ? `${view.instructions.length} chars` : "(none)" });
@@ -317,6 +365,8 @@ async function editEntry(pi: ExtensionAPI, ctx: ExtensionContext, kind: Settings
     if (!action || action === "back") return;
     if (action === "model") await editModel(pi, ctx, kind);
     else if (action === "thinking") await editThinking(pi, ctx, kind);
+    else if (action === "fallback") await editFallbackModel(pi, ctx, kind);
+    else if (action === "fallbackThinking") await editFallbackThinking(pi, ctx, kind);
     else if (action === "timeout") await editTimeout(pi, ctx, kind);
     else if (action === "instructions") await editInstructions(pi, ctx, kind);
   }
@@ -352,23 +402,25 @@ function entryDescription(kind: SettingsKind, view: EntryView): string {
   const thinking = kind === "scout" ? SCOUT_THINKING : view.thinking;
   const custom = view.instructions ? " · custom" : "";
   const limit = kind === "master" ? "" : ` · ${minutes(view.timeoutMs)}`;
-  return `${view.model} · ${thinking}${limit}${custom}`;
+  const fallback = view.fallbackModel ? ` · fallback ${view.fallbackModel}` : "";
+  return `${view.model} · ${thinking}${limit}${custom}${fallback}`;
 }
 
 /** The lobby's on/off settings as the settings menu lists them; `panel:*` are the Lobby tab's panes. */
-export type LobbySwitch = "autoOpen" | "autoAsk" | "mouse" | "issues" | `panel:${LobbyPanel}`;
+export type LobbySwitch = "autoOpen" | "autoAsk" | "mouse" | "miniLine" | "issues" | `panel:${LobbyPanel}`;
 
-const PANEL_SWITCH_LABELS: Record<LobbyPanel, string> = { animations: "Animations in the lobby", conversation: "Conversation pane", activity: "Activity log pane", thinking: "Thinking pane" };
+const PANEL_SWITCH_LABELS: Record<LobbyPanel, string> = { conversation: "Conversation pane", activity: "Activity log pane", thinking: "Thinking pane" };
 
 export const LOBBY_SWITCHES: ReadonlyArray<{ id: LobbySwitch; label: string; help: string }> = [
   { id: "autoOpen", label: "Open with a task", help: "open the lobby when this session starts or resumes a task" },
   { id: "autoAsk", label: "Ask at once", help: "put the panel's questions to you as soon as a round ends, while the Plan tab is open" },
   { id: "mouse", label: "Mouse", help: "click tabs and draft lines, scroll with the wheel (shift+drag still selects text)" },
+  { id: "miniLine", label: "Status line when hidden", help: "one line under the editor while the lobby is hidden: task steps, the planning round, a quick fix, or idle" },
   { id: "issues", label: "Issues tab", help: "the GitHub Issues tab" },
   ...LOBBY_PANELS.map((panel) => ({
     id: `panel:${panel}` as const,
     label: PANEL_SWITCH_LABELS[panel],
-    help: panel === "animations" ? "the animated oracle and agents on the Lobby tab; off keeps only the task's status (they still show above pi's editor while the lobby is hidden); alt+z toggles it too" : "shown on the Lobby tab; its key in the lobby toggles it too",
+    help: "shown on the Lobby tab; its key in the lobby toggles it too",
   })),
 ];
 
@@ -419,6 +471,7 @@ function lobbySummary(config: BotLobbyConfig): string {
     config.lobby.autoOpen ? "opens with a task" : "opens on alt+l",
     config.lobby.autoAsk ? "asks at once" : "asks on enter",
     config.lobby.mouse ? "mouse" : "no mouse",
+    ...(config.lobby.miniLine ? [] : ["no status line"]),
     `planning: ${roundLimitLabel(config.lobby.maxPlanningRounds)}`,
     ...(config.lobby.issues ? ["issues tab"] : []),
     ...(hidden.length > 0 ? [`hidden: ${hidden.join(", ")}`] : []),

package/src/pi/tools.ts

@@ -29,17 +29,17 @@ const OrchestrateSchema = Type.Object({
   question: Type.Optional(Type.String({ description: "clarify: question for the user" })),
   options: Type.Optional(Type.Array(Type.String(), { description: "clarify: optional answer choices; put your recommended one first and mark it (Recommended)" })),
   domains: Type.Optional(Type.Array(Type.String(), { description: "scout: any of designer, backend, qa" })),
-  instruction: Type.Optional(Type.String({ description: "scout/research: what to investigate (for scout, also used to target-verify a claim)" })),
+  instruction: Type.Optional(Type.String({ description: "scout/research: a self-contained brief: the specific questions, where to look, the answer format you want (paths, names, versions, evidence) and what you will do with it. The agent may be a small model: assume nothing" })),
   proposal: Type.Optional(Type.String({ description: "propose: the user-facing proposal as a short `- ` bullet list, one line per change" })),
   concerns: Type.Optional(Type.Array(Type.String(), { description: "propose: concerns raised while challenging the request" })),
-  plan: Type.Optional(Type.String({ description: "plan: the detailed internal plan (while implementing or reviewing, the full revised plan that replaces it)" })),
+  plan: Type.Optional(Type.String({ description: "plan: the detailed internal plan (while implementing or reviewing, the full revised plan that replaces it). Every step names its files, its concrete actions and its done criteria, and the contracts between domains are written out; no decision is left to the workers" })),
   domain: Type.Optional(Type.String({ description: "implement/research: designer, backend, or qa" })),
-  task: Type.Optional(Type.String({ description: "implement: the concrete step for that domain's worker" })),
+  task: Type.Optional(Type.String({ description: "implement: a self-contained brief for that domain's worker (which may be a small, literal model): Goal, exact Files, numbered What to do with names/shapes/values, Contracts, Constraints, Done when (checkable criteria and commands), If stuck. Decide everything yourself; leave nothing to be assumed" })),
   assignments: Type.Optional(
     Type.Array(
       Type.Object({
         domain: Type.String({ description: "designer, backend, or qa" }),
-        task: Type.String({ description: "the concrete step(s) for that domain's worker" }),
+        task: Type.String({ description: "a self-contained brief for that domain's worker: Goal, exact Files, numbered What to do, Contracts (in full), Constraints, Done when, If stuck. No assumptions" }),
         minutes: Type.Optional(Type.Number({ description: "under a time budget: minutes for this worker, by its scope" })),
       }),
       { description: "implement: run several domains in parallel (distinct domains); workers share files through the file desk" },
@@ -77,6 +77,7 @@ const DESCRIPTION = [
   "pass), block/resume (escalate or continue), budget (under a time budget: where it stands, or ask the",
   "user for more minutes with a reason), track (the task's path and who takes part: show it, or correct it with",
   "track=fast|full, roster and a reason), status, cancel.",
+  "Every instruction you give an agent is read by a possibly smaller, cheaper model that cannot infer intent: write each one as a complete, explicit brief with the goal, files, actions, contracts, constraints and done criteria, then check the report against it.",
   "The engine validates every step against the task state machine, so a rejected action means the workflow is not at that step yet.",
 ].join(" ");