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

package/src/pi/route.ts

@@ -0,0 +1,180 @@
+/**
+ * Where a new request goes before any task exists. The classifier (Jev, or
+ * the rules while it is off) reads whether one agent can do it alone, right
+ * away. When it can, the oracle confirms with `route_request`: the lobby hands
+ * the request to the quick-fix agent and shows the Quick fix tab. Otherwise,
+ * or when the oracle says it needs the team, the task starts as before.
+ *
+ * Nothing is routed without the lobby (it runs quick fixes), when routing is
+ * off (`workflow.routeQuickFixes`), or for a request the user already placed
+ * (`--task`, `--fast`, `--full`) or a planned task.
+ */
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { Domain } from "../schemas/agent.ts";
+import type { TaskTriage } from "../schemas/task.ts";
+import { chooseRoute, type RequestRoute } from "../workflow/track.ts";
+import { triageFor } from "../classifier/instance.ts";
+import { ownedTask } from "../state/persistence.ts";
+import { detectProjectRoot, loadConfig } from "../state/project.ts";
+import { lobbyFeed } from "../lobby/feed.ts";
+import { startTask, type StartOptions } from "./start-task.ts";
+import { isQuiet, isSubagentProcess } from "./quiet.ts";
+
+export const ROUTE_TOOL = "route_request";
+
+/**
+ * Hands a request to the lobby's quick-fix agent and shows the Quick fix tab;
+ * the job's id, or undefined without a lobby. `builder` is set for a quick
+ * feature: it runs on that domain's model, thinking and time limit.
+ */
+export type QuickFixHandoff = (request: string, builder: Domain | undefined, reason: string) => string | undefined;
+
+let handoff: QuickFixHandoff | undefined;
+
+/** The lobby registers its quick-fix hand-off while it runs. */
+export function setQuickFixHandoff(next: QuickFixHandoff | undefined): void {
+  handoff = next;
+}
+
+interface Pending {
+  request: string;
+  options: StartOptions;
+  route: RequestRoute;
+  at: number;
+}
+
+let pending: Pending | undefined;
+
+/** A request the oracle has not routed in this long is forgotten: the next one starts afresh. */
+const STALE_MS = 30 * 60_000;
+
+/** The request waiting for the oracle to route it, if any. */
+export function pendingRequest(now = Date.now()): { request: string; route: RequestRoute } | undefined {
+  if (pending && now - pending.at >= STALE_MS) pending = undefined;
+  return pending ? { request: pending.request, route: pending.route } : undefined;
+}
+
+/** A quick feature (bigger than a small change, but self-contained) runs with its builder's settings; a quick fix with the quick-fix agent's. */
+function builderFor(route: RequestRoute): Domain | undefined {
+  return route.size === "medium" || route.size === "large" ? route.builder : undefined;
+}
+
+/** What the oracle is asked: one step, from the request alone. */
+export function routeMessage(request: string, route: RequestRoute): string {
+  return [
+    "bot-lobby: a new request, not a task yet.",
+    `Request: ${request}`,
+    `Read: a ${builderFor(route) ? "quick feature" : "quick fix"} — ${route.reasons.join("; ")} (${route.source}).`,
+    "",
+    "Confirm where it goes with route_request, in one step and from the request alone: do not read files, plan or ask.",
+    "- to=quickfix: one agent does it now and the lobby shows it on the Quick fix tab. Right for anything one person can just do, even a rich piece of work in one file.",
+    "- to=task: the team (bot-lobby's workflow), when it needs several areas agreeing on a contract, a survey of an unfamiliar codebase, a risky change, or decisions the user must make first.",
+    "Then tell the user in one line where it went.",
+  ].join("\n");
+}
+
+export interface RequestOptions extends StartOptions {
+  /** `--task`: always a task. */
+  task?: boolean;
+}
+
+/**
+ * A new request from the lobby or `/bot-lobby <request>`: a task at once, or
+ * (when it reads as one agent's work) a question to the oracle first.
+ * Resolves with what happened.
+ */
+export async function startRequest(pi: ExtensionAPI, ctx: ExtensionContext, configDir: string, request: string, options: RequestOptions = {}): Promise<"task" | "routing" | undefined> {
+  const { task: asTask, ...start } = options;
+  const config = loadConfig();
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const placed = asTask || start.track || start.approvedPlan || !config.workflow.routeQuickFixes || !handoff;
+  // A session that already drives a task gets startTask's own warning.
+  if (placed || ownedTask(root, configDir, ctx.sessionManager.getSessionId())) {
+    return (await startTask(pi, ctx, configDir, request, start)) ? "task" : undefined;
+  }
+  const triage = await triageFor({ cwd: ctx.cwd, root, configDir }, request);
+  const route = chooseRoute(request, triage, config.classifier.thresholds.quickFixAt);
+  const read: StartOptions = { ...start, triaged: true, ...(triage ? { triage } : {}) };
+  if (route.to === "task") return (await startTask(pi, ctx, configDir, request, read)) ? "task" : undefined;
+  pending = { request, options: read, route, at: Date.now() };
+  lobbyFeed.log("LOBBY", `reads as a ${builderFor(route) ? "quick feature" : "quick fix"} (${route.source}): ${route.reasons[0]} — the oracle confirms`, "info");
+  pi.sendUserMessage(routeMessage(request, route), ctx.isIdle() ? undefined : { deliverAs: "followUp" });
+  return "routing";
+}
+
+const RouteSchema = Type.Object({
+  to: StringEnum(["quickfix", "task"] as const, { description: "quickfix: one agent does it now, on the lobby's Quick fix tab; task: the team (bot-lobby's workflow)" }),
+  reason: Type.Optional(Type.String({ description: "one line: why it goes there" })),
+  request: Type.Optional(Type.String({ description: "the request as it should be done, when the user refined it since; their words otherwise" })),
+});
+
+/** The oracle's answer to a routing question: the quick-fix agent, or a task. */
+export async function routeRequest(pi: ExtensionAPI, ctx: ExtensionContext, configDir: string, params: { to: "quickfix" | "task"; reason?: string; request?: string }): Promise<{ ok: boolean; text: string }> {
+  const waiting = pendingRequest();
+  if (!waiting || !pending) return { ok: false, text: "No request is waiting to be routed. Start a task with /bot-lobby <request>." };
+  const { options, route } = pending;
+  const request = params.request?.trim() || pending.request;
+  pending = undefined;
+  const why = params.reason?.trim();
+  if (params.to === "quickfix") {
+    const id = handoff?.(request, builderFor(route), why || route.reasons[0] || "one agent can do it alone");
+    if (id) {
+      lobbyFeed.log("LOBBY", `the oracle sent it to the quick-fix agent: ${id}${why ? ` — ${why}` : ""}`, "success");
+      return { ok: true, text: `${id} is running on the lobby's Quick fix tab, which is now open. Tell the user in one line that this looks like a ${builderFor(route) ? "quick feature" : "quick fix"} and the quick-fix agent is on it; nothing else to do.` };
+    }
+    // No lobby to run it any more: it becomes a task.
+  }
+  lobbyFeed.log("LOBBY", `the oracle sent it to the team${why ? ` — ${why}` : ""}`, "info");
+  const task = await startTask(pi, ctx, configDir, request, { ...options, routed: true });
+  return task
+    ? { ok: true, text: `Started ${task.id} as a task; its kickoff follows as the next message. Say nothing more now.` }
+    : { ok: false, text: "Could not start a task: this session already drives one (finish or cancel it first)." };
+}
+
+/**
+ * `route_request`, active only while a request waits for the oracle, so it
+ * never sits in the tool list of plain pi or of a running task.
+ */
+export function registerRouteTool(pi: ExtensionAPI, configDir: string): void {
+  if (isSubagentProcess()) return;
+  pi.on("session_start", () => {
+    pending = undefined;
+  });
+  pi.on("before_agent_start", () => {
+    const active = pi.getActiveTools();
+    const want = Boolean(pendingRequest());
+    if (want === active.includes(ROUTE_TOOL)) return;
+    pi.setActiveTools(want ? [...active, ROUTE_TOOL] : active.filter((name) => name !== ROUTE_TOOL));
+  });
+  pi.registerTool({
+    name: ROUTE_TOOL,
+    label: "Route request",
+    description: "Send a new bot-lobby request to the quick-fix agent (to=quickfix: one agent does it now, shown on the lobby's Quick fix tab) or to the team (to=task: bot-lobby's workflow). Only while a request waits to be routed.",
+    promptSnippet: "Route a new bot-lobby request: quickfix (one agent now) or task (the team)",
+    parameters: RouteSchema,
+    renderShell: "self",
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const result = await routeRequest(pi, ctx, configDir, params as { to: "quickfix" | "task"; reason?: string; request?: string });
+      return { content: [{ type: "text", text: result.text }], details: { ok: result.ok, to: (params as { to: string }).to } };
+    },
+    renderCall(args, theme) {
+      if (isQuiet()) return new Container();
+      const call = args as { to?: string };
+      return new Text(`${theme.fg("toolTitle", theme.bold("route_request"))} ${theme.fg("accent", call.to ?? "")}`, 0, 0);
+    },
+    renderResult(result, _options, theme) {
+      if (isQuiet()) return new Container();
+      const details = result.details as { ok?: boolean; to?: string } | undefined;
+      const icon = details?.ok ? theme.fg("success", "✓") : theme.fg("warning", "!");
+      return new Text(`${icon} ${theme.fg("toolTitle", theme.bold("route_request"))} ${theme.fg("muted", `→ ${details?.to === "quickfix" ? "Quick fix tab" : "a task"}`)}`, 0, 0);
+    },
+  });
+}
+
+/** Tests: forget any request waiting for the oracle. */
+export function clearPendingRequest(): void {
+  pending = undefined;
+}

package/src/pi/start-task.ts

@@ -5,7 +5,10 @@
  */
 import { existsSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { createTask, taskRequest, type Task } from "../schemas/task.ts";
+import { createTask, taskRequest, type Task, type TaskTrack, type TaskTriage, type TrackPath } from "../schemas/task.ts";
+import type { Domain } from "../schemas/agent.ts";
+import { chooseTrack, trackLine, trackSummary } from "../workflow/track.ts";
+import { lobbyFeed } from "../lobby/feed.ts";
 import { createTaskDir, ensureProjectStructure, nextTaskId, ownedTask, saveTask, taskDirFor } from "../state/persistence.ts";
 import { detectProjectRoot, loadConfig } from "../state/project.ts";
 import { transition } from "../state/task-state.ts";
@@ -16,6 +19,7 @@ import { setAutoMode } from "../state/auto.ts";
 import { loadPlannedTask, markPlannedTaskStarted, plannedTaskRequest } from "../state/backlog.ts";
 import { triageFor } from "../classifier/instance.ts";
 import { freshContextOn, markContext } from "./fresh-context.ts";
+import { setBudget } from "../state/budget.ts";
 
 function uniqueTaskId(root: string, configDir: string, request: string): string {
   const base = nextTaskId(request);
@@ -25,18 +29,51 @@ function uniqueTaskId(root: string, configDir: string, request: string): string
   return id;
 }
 
-export function kickoff(task: Task): string {
+/** In a kickoff after the oracle routed the request to the team (the lobby then shows the request once). */
+export const ROUTED_LINE = "Routed: you sent this request to the team.";
+
+/** The fast track's steps: straight to the agents the request needs, QA only for tests, then complete. */
+function fastSteps(track: TaskTrack): string[] {
+  const building = track.roster.filter((member): member is Domain => member === "designer" || member === "backend");
+  const builders = building.length > 1
+    ? `one call with assignments for ${building.join(" and ")}, each task stating the contract between them`
+    : building.length === 1 ? `domain ${building[0]}` : track.roster.includes("qa") ? "domain qa (the change is its tests)" : "the one domain that owns the files";
+  const steps = [
+    ...(track.roster.includes("researcher") ? ["First summon the researcher for the outside facts it needs: orchestrate action=research with a domain and the question."] : []),
+    `Delegate now with orchestrate action=implement: ${builders}; open each task with "Step 1:" (the engine keeps the plan).`,
+    ...(track.roster.includes("qa") && building.length > 0 ? ["QA takes part (tests): once the change is in, give qa the tests as the last step (action=implement domain=qa), or run action=qa."] : []),
+    "Check `git diff --stat` and the report, then orchestrate action=complete with a one-line summary.",
+  ];
   return [
+    "Fast track: the request reads small and clear, so skip the ceremony: no scouts, no proposal, no plan document.",
+    ...steps.map((step, index) => `${index + 1}. ${step}`),
+    track.roster.includes("qa") ? "" : "No QA gate on this track: nothing here needs tests.",
+    "If the request is bigger, riskier or less clear than it reads, switch before delegating: orchestrate action=track track=full with a reason. Otherwise do not deliberate over the track.",
+  ].filter(Boolean);
+}
+
+export function kickoff(task: Task, budgetMinutes = 0, options: { fastTrack?: boolean; routed?: boolean } = {}): string {
+  const track = task.track;
+  const head = [
     `A bot-lobby task is active: ${task.id}`,
     `Title: ${task.title}`,
     `Request: ${taskRequest(task)}`,
     `State: ${task.state}`,
+    ...(options.routed ? [ROUTED_LINE] : []),
+    ...(track ? [trackSummary(track)] : []),
+    ...(budgetMinutes > 0 ? [`Time budget: ${budgetMinutes} minutes of work, for you and every agent. Size the plan to fit it and divide it by scope (see Time budget in your prompt).`] : []),
     "",
+  ];
+  if (track?.path === "fast") return [...head, ...fastSteps(track)].join("\n");
+  const fastAllowed = Boolean(track) && options.fastTrack !== false && track?.userChoice !== "full" && track?.source !== "plan";
+  return [
+    ...head,
     "Drive it with the orchestrate tool:",
     "1. clarify if the request is genuinely ambiguous,",
     "2. scout the domains the request touches,",
     "3. synthesize the findings and propose a short `- ` bullet list for approval.",
     "Do not implement anything before the user approves the proposal.",
+    ...(fastAllowed ? ["If it is in fact a small, clear, low-risk change, take the fast track instead: orchestrate action=track track=fast with a reason."] : []),
   ].join("\n");
 }
 
@@ -52,6 +89,15 @@ export interface StartOptions {
   auto?: boolean;
   /** The task's short title (a planned task's own title); derived from the request otherwise. */
   title?: string;
+  /** Minutes of work time the task gets; `workflow.taskBudgetMinutes` when absent. */
+  budget?: number;
+  /** The user's `--fast` or `--full`: the path the task takes, whatever its request reads as. */
+  track?: TrackPath;
+  /** The classifier already read the request (routing did): `triage` is its read, or absent when it was off. */
+  triaged?: boolean;
+  triage?: TaskTriage;
+  /** The oracle sent this request to the team after the classifier read it as a quick fix. */
+  routed?: boolean;
 }
 
 export async function startTask(pi: ExtensionAPI, ctx: ExtensionContext, configDir: string, request: string, options: StartOptions = {}): Promise<Task | undefined> {
@@ -68,9 +114,15 @@ export async function startTask(pi: ExtensionAPI, ctx: ExtensionContext, configD
   createTaskDir(root, configDir, task);
   transition(task, "clarifying");
   // The classifier's read of the request (when it is on) reaches the Master's very first turn.
-  const triage = await triageFor({ cwd: ctx.cwd, root, configDir }, request);
+  const triage = options.triaged ? options.triage : await triageFor({ cwd: ctx.cwd, root, configDir }, request);
   if (triage) task.triage = triage;
+  // How serious the request reads: who takes part, and whether it takes the fast track or the full workflow.
+  const config = loadConfig();
+  task.track = chooseTrack(request, triage, { fastTrack: config.workflow.fastTrack, ...(options.track ? { forced: options.track } : {}), ...(options.approvedPlan ? { approvedPlan: true } : {}) });
+  lobbyFeed.log("LOBBY", trackLine(task.track), "info");
   saveTask(root, configDir, task);
+  const budgetMinutes = options.budget ?? config.workflow.taskBudgetMinutes;
+  if (budgetMinutes > 0) setBudget(root, configDir, task.id, budgetMinutes);
   if (options.auto) setAutoMode(root, configDir, task.id, true, sessionId);
   // A session that starts a task is named after it, so /resume and the lobby list it by name.
   if (!pi.getSessionName()) pi.setSessionName(task.title);
@@ -80,7 +132,7 @@ export async function startTask(pi: ExtensionAPI, ctx: ExtensionContext, configD
   // The oracle takes the task on with a clean context: nothing said before the kickoff is sent to its model.
   if (freshContextOn()) markContext(pi, { kind: "start", taskId: task.id, at: Date.now() });
   // A kickoff while pi is still busy (another turn) queues behind it instead of throwing.
-  pi.sendUserMessage(kickoff(task), ctx.isIdle() ? undefined : { deliverAs: "followUp" });
+  pi.sendUserMessage(kickoff(task, budgetMinutes, { fastTrack: config.workflow.fastTrack, ...(options.routed ? { routed: true } : {}) }), ctx.isIdle() ? undefined : { deliverAs: "followUp" });
   return task;
 }
 

package/src/pi/tools.ts

@@ -1,6 +1,6 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Container, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, type AgentToolUpdateCallback, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import type { AgentRun } from "../schemas/findings.ts";
 import type { ProcessRunner } from "../execution/pi-runner.ts";
@@ -8,6 +8,10 @@ import { detectProjectRoot, loadConfig } from "../state/project.ts";
 import { classifier, effortFor, hintsFor, triageFor } from "../classifier/instance.ts";
 import { truncate } from "../text.ts";
 import { applyStatus, reportRuns, summarizeRun } from "./ui.ts";
+import { whileAsking } from "../state/budget.ts";
+import { askUser } from "../ask/dialog.ts";
+import type { AskQuestion } from "../ask/types.ts";
+import { unescapeBreaks } from "../lobby/markdown.ts";
 import { isQuiet } from "./quiet.ts";
 import { checkThinking, createProfileResolver, modelRef, type ModelLookup } from "./model-support.ts";
 import { agentName, describeRun } from "./run-summary.ts";
@@ -36,16 +40,22 @@ const OrchestrateSchema = Type.Object({
       Type.Object({
         domain: Type.String({ description: "designer, backend, or qa" }),
         task: Type.String({ description: "the concrete step(s) for that domain's worker" }),
+        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" },
     ),
   ),
+  minutes: Type.Optional(Type.Number({ description: "implement (under a time budget): minutes for this step, by its scope; budget: more minutes to ask the user for" })),
   approvalId: Type.Optional(Type.String({ description: "resolve_approval: the approval id from a worker result" })),
   decision: Type.Optional(
     StringEnum(["approved", "rejected"] as const, { description: "resolve_approval: approve or reject the request" }),
   ),
   note: Type.Optional(Type.String({ description: "resolve_approval: rationale, or what to do instead when rejected" })),
-  reason: Type.Optional(Type.String({ description: "block: why the task cannot continue" })),
+  reason: Type.Optional(Type.String({ description: "block: why the task cannot continue; budget: why the task needs more time; track: why the task takes that path or needs those members" })),
+  track: Type.Optional(
+    StringEnum(["fast", "full"] as const, { description: "track: fast (straight to the roster's agents, no scouts, proposal or plan; QA only for tests) or full (the whole workflow)" }),
+  ),
+  roster: Type.Optional(Type.Array(Type.String(), { description: "track: who takes part — any of designer, backend, qa, researcher" })),
   text: Type.Optional(Type.String({ description: "decide/complete/knowledge: the decision, completion summary, or knowledge text" })),
   file: Type.Optional(Type.String({ description: "compact: the knowledge file to rewrite, e.g. knowledge.md" })),
   kind: Type.Optional(
@@ -64,7 +74,9 @@ const DESCRIPTION = [
   "review), knowledge (record approved knowledge or a decision),",
   "compact (replace a knowledge file with a rewritten version, archiving the old one),",
   "resolve_approval (approve or reject a request), complete (declare the task done after the gates",
-  "pass), block/resume (escalate or continue), status, cancel.",
+  "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.",
   "The engine validates every step against the task state machine, so a rejected action means the workflow is not at that step yet.",
 ].join(" ");
 
@@ -109,8 +121,11 @@ export function workflowDeps(
     classifier: classifier(),
     triage: (request, triageSignal) => triageFor({ cwd: ctx.cwd, root, configDir }, request, triageSignal),
     effort: effortFor((model, thinking) => checkThinking(modelLookup(ctx)(model), thinking).level),
-    ask: async (question) => (hasUI ? ctx.ui.input(question) : undefined),
-    choose: async (title, options) => (hasUI ? ctx.ui.select(title, options) : undefined),
+    // Time spent waiting on the user is not the task's: its budget clock waits too.
+    ask: async (question) => (hasUI ? whileAsking(() => ctx.ui.input(question)) : undefined),
+    choose: async (title, options) => (hasUI ? whileAsking(() => ctx.ui.select(title, options)) : undefined),
+    // An agent's own questions (the designer's), relayed as the questionnaire.
+    ...(hasUI ? { askQuestions: (questions: AskQuestion[], from: string, askSignal?: AbortSignal) => whileAsking(() => askUser(questions, ctx, askSignal, from)) } : {}),
     notify: (message, level = "info") => {
       if (hasUI) ctx.ui.notify(message, level);
     },
@@ -135,6 +150,14 @@ function runReporter(
   };
 }
 
+/** A header line over Markdown, rendered as pi renders its own messages (a proposal's bullets, a report's code spans). */
+function headedMarkdown(header: string, body: string, color: (text: string) => string): Container {
+  const box = new Container();
+  box.addChild(new Text(header, 0, 0));
+  if (body.trim()) box.addChild(new Markdown(unescapeBreaks(body), 0, 0, getMarkdownTheme(), { color }));
+  return box;
+}
+
 /** TUI-only transcript entries; these never enter the model's context. */
 function registerBotLobbyEntries(pi: ExtensionAPI): void {
   pi.registerEntryRenderer("bot-lobby", (entry, { expanded }, theme) => {
@@ -145,7 +168,7 @@ function registerBotLobbyEntries(pi: ExtensionAPI): void {
     }
     const header = `bot-lobby ${data?.taskId ?? ""} — ${data?.kind ?? "note"}`.trim();
     const body = data?.text ?? "";
-    return new Text(`${theme.fg("accent", theme.bold(header))}\n${theme.fg("toolOutput", expanded ? body : truncate(body, 600))}`, 0, 0);
+    return headedMarkdown(theme.fg("accent", theme.bold(header)), expanded ? body : truncate(body, 600), (text) => theme.fg("toolOutput", text));
   });
 }
 
@@ -166,7 +189,7 @@ export function registerOrchestrateTool(pi: ExtensionAPI, configDir: string, run
     name: "orchestrate",
     label: "Orchestrate",
     description: DESCRIPTION,
-    promptSnippet: "Run a bot-lobby workflow step (clarify, scout, propose, plan, decide, status, cancel)",
+    promptSnippet: "Run a bot-lobby workflow step (clarify, scout, propose, plan, implement, track, decide, status, cancel)",
     promptGuidelines: [
       "Use orchestrate for every bot-lobby workflow step; it enforces the task state machine and records results.",
     ],
@@ -200,7 +223,7 @@ export function registerOrchestrateTool(pi: ExtensionAPI, configDir: string, run
       const body = result.content[0]?.type === "text" ? result.content[0].text : "";
       const icon = details?.ok ? theme.fg("success", "✓") : theme.fg("warning", "!");
       const header = `${icon} ${theme.fg("toolTitle", theme.bold("orchestrate"))} ${theme.fg("accent", details?.taskId ?? "")} ${theme.fg("muted", `→ ${details?.state ?? "?"}`)}`;
-      return new Text(expanded && body ? `${header}\n${theme.fg("dim", truncate(body, 2000))}` : header, 0, 0);
+      return expanded && body ? headedMarkdown(header, truncate(body, 2000), (text) => theme.fg("dim", text)) : new Text(header, 0, 0);
     },
   });
 }

package/src/pi/ui.ts

@@ -26,6 +26,7 @@ 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";
 
 export const STATUS_KEY = "bot-lobby";
 
@@ -52,6 +53,8 @@ let zenOn = false;
  * keys the widget's render cache.
  */
 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. */
@@ -255,7 +258,8 @@ export class ZenScene {
     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 opts = { width, rows, tick: this.tick, theme, expressions, variants, oracleActivity, oracleMotion: motion, still };
+    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;
@@ -356,6 +360,7 @@ 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));

package/src/pi/zen-metrics.ts

@@ -11,6 +11,13 @@ import { SLOT_IDS, SLOT_LABELS, type SlotId, type SlotState } from "./mascot-art
 import { formatDuration, planChecklist } from "./zen.ts";
 import { QUIET_MS, quietFor, slotOf } from "./run-summary.ts";
 import type { Situation } from "./kaomoji.ts";
+import { formatMinutes } from "../state/budget.ts";
+
+/** A task's time budget as the scene shows it: work time spent of the whole. */
+export interface SceneTime {
+  usedMs: number;
+  totalMs: number;
+}
 
 export type { SlotId, SlotState };
 
@@ -70,7 +77,10 @@ function latestRunFor(runs: AgentRun[], id: SlotId): AgentRun | undefined {
 function runElapsedLabel(run: AgentRun | undefined, now: number): string {
   if (!run) return "—";
   const end = run.finishedAt ? Date.parse(run.finishedAt) : now;
-  return formatDuration(end - Date.parse(run.startedAt));
+  const elapsed = end - Date.parse(run.startedAt);
+  // Under a time budget: minutes spent of the minutes given (`12/30m`).
+  if (run.allotMs) return `${Math.max(0, Math.floor(elapsed / 60_000))}/${Math.round((run.allotMs + (run.extendedMs ?? 0)) / 60_000)}m`;
+  return formatDuration(elapsed);
 }
 
 function slotView(id: SlotId, runs: AgentRun[], now: number): SlotView {
@@ -89,7 +99,7 @@ function slotView(id: SlotId, runs: AgentRun[], now: number): SlotView {
   };
 }
 
-export function sceneMetrics(task: Task, runs: AgentRun[], now: number): SceneMetrics {
+export function sceneMetrics(task: Task, runs: AgentRun[], now: number, time?: SceneTime): SceneMetrics {
   const checklist = planChecklist(task.plan ?? "", runs);
   const total = checklist.length;
   const done = checklist.filter((step) => step.status === "done").length;
@@ -98,7 +108,7 @@ export function sceneMetrics(task: Task, runs: AgentRun[], now: number): SceneMe
   const elapsed = Number.isFinite(created) ? Math.max(0, now - created) : 0;
   return {
     ...summary,
-    elapsedLabel: formatDuration(elapsed),
+    elapsedLabel: time ? `${formatMinutes(time.usedMs)} of ${formatMinutes(time.totalMs)}` : formatDuration(elapsed),
     slots: SLOT_IDS.map((id) => slotView(id, runs, now)),
   };
 }

package/src/pi/zen.ts

@@ -37,7 +37,8 @@ import {
   type LargeSlot,
   type LargeTaskRow,
 } from "./zen-large.ts";
-import { runStatus, sceneMetrics, slotSituation, type SceneMetrics, type SlotView } from "./zen-metrics.ts";
+import { runStatus, sceneMetrics, slotSituation, type SceneMetrics, type SceneTime, type SlotView } from "./zen-metrics.ts";
+import { formatMinutes } from "../state/budget.ts";
 import { feedLine, QUIET_MS, quietFor } from "./run-summary.ts";
 import { shortDuration } from "../text.ts";
 
@@ -378,18 +379,22 @@ function checklistRow(step: PlanStep, ordinal: number): string {
   return `  ${icon} ${ordinal}. ${step.text}`;
 }
 
-function headerLine(task: Task, now: number, quiet: boolean): string {
+function headerLine(task: Task, now: number, quiet: boolean, time?: SceneTime): string {
   const paused = task.paused ? " (paused)" : "";
-  const elapsed = formatDuration(now - Date.parse(task.createdAt));
+  const elapsed = time ? `${formatMinutes(time.usedMs)} of ${formatMinutes(time.totalMs)}` : formatDuration(now - Date.parse(task.createdAt));
   const mode = quiet ? "tools hidden (alt+t)" : "tools shown";
   return `bot-lobby ${task.id} · ${task.state}${paused}   ⏱ ${elapsed} · ${mode}`;
 }
 
-/** The pending approval or blocker the user must resolve, with its severity. */
-function taskAlert(task: Task): { text: string; kind: "warning" | "error" } | undefined {
+/** The pending approval or blocker the user must resolve, with its severity; then a spent time budget. */
+function taskAlert(task: Task, time?: SceneTime): { text: string; kind: "warning" | "error" } | undefined {
   const pending = task.approvals.filter((approval) => approval.status === "pending");
   if (pending.length > 0) return { text: `approvals pending: ${pending.map((approval) => approval.id).join(", ")}`, kind: "warning" };
   if (task.blockers.length > 0) return { text: `blocked: ${truncate(task.blockers[0]!.reason, 60)}`, kind: "error" };
+  if (time && time.usedMs >= time.totalMs * 0.9) {
+    const spent = time.usedMs >= time.totalMs;
+    return { text: `time budget ${spent ? "spent" : "nearly spent"}: ${formatMinutes(time.usedMs)} of ${formatMinutes(time.totalMs)}`, kind: "warning" };
+  }
   return undefined;
 }
 
@@ -518,10 +523,10 @@ function compactPanel(
   opts: PanelOptions,
   width: number,
 ): string[] {
-  const metrics = sceneMetrics(task, runs, now);
+  const metrics = sceneMetrics(task, runs, now, opts.time);
   const expressions = opts.expressions ?? {};
   const strip = opts.still ? [] : compactStrip(task.state, metrics.slots, expressions, opts.theme);
-  const fixed = [...bannerLines(width), headerLine(task, now, quiet), ...strip];
+  const fixed = [...bannerLines(width), headerLine(task, now, quiet, opts.time), ...strip];
   const tail = tailLines(task, runs, now, tick, steps, opts.theme);
   const room = Math.max(0, MAX_PANEL_LINES - fixed.length - tail.length);
   return [...fixed, ...tail, ...checklistLines(steps, room)].map((line) => clip(line, width));
@@ -577,8 +582,8 @@ function sceneInput(
   steps: PlanStep[],
   opts: PanelOptions,
 ): LargeSceneInput {
-  const metrics = sceneMetrics(task, runs, now);
-  const alert = taskAlert(task);
+  const metrics = sceneMetrics(task, runs, now, opts.time);
+  const alert = taskAlert(task, opts.time);
   return {
     taskId: task.id,
     taskTitle: task.title,
@@ -616,6 +621,8 @@ export interface PanelOptions {
   oracleMotion?: OracleMotion;
   /** Leave out the oracle and agent animations: status, alert, activity and checklist only. */
   still?: boolean;
+  /** The task's time budget: the elapsed label reads against it. */
+  time?: SceneTime;
 }
 
 /** The oracle's clocked animation state beyond its expression frame (see expressions.ts). */

package/src/roles/reviewer.ts

@@ -30,15 +30,23 @@ function parseVerdict(text: string | undefined): Verdict {
   return "blocked";
 }
 
+/** The severity a finding was tagged with, or undefined when it carries none. */
+function taggedSeverity(text: string): Severity | undefined {
+  const match = /^\[([^\]]+)\]/.exec(text);
+  return SEVERITIES.find((candidate) => match?.[1]?.toLowerCase().includes(candidate));
+}
+
 function parseFinding(text: string): ReviewFinding {
   const match = /^\[([^\]]+)\]\s*(.*)$/.exec(text);
-  const severity = SEVERITIES.find((candidate) => match?.[1]?.toLowerCase().includes(candidate)) ?? "info";
-  return { severity, text: (match?.[2] ?? text).trim() };
+  return { severity: taggedSeverity(text) ?? "info", text: (match?.[2] ?? text).trim() };
 }
 
 /** The QA gate never passes by default: a PASS must cite at least one executed check. */
 export const UNVERIFIED_PASS = "unverified pass: PASS without executed checks under ## Verification, downgraded to CHANGES_REQUIRED";
 
+/** Minor and info findings never hold the gate; what the reviewer asked for is kept as follow-ups. */
+export const MINOR_ONLY = "CHANGES_REQUIRED for minor or info findings only: passed, its asks kept as follow-ups";
+
 /** A verification bullet names a command or check and its result (`- cmd — result`). */
 function executedChecks(verification: string): string[] {
   return bullets(verification).filter((entry) => /\S\s*(?:—|–|-{1,2}|:|=>|→)\s*\S/.test(entry));
@@ -49,23 +57,34 @@ export function parseReviewResult(domain: Domain, raw: string): ReviewResult {
   const sections = parseSections(raw);
   const verification = findSection(sections, "verification") ?? "";
   const requiredChanges = bullets(findSection(sections, "required changes"));
+  const entries = bullets(findSection(sections, "findings"));
   let verdict = parseVerdict(findSection(sections, "verdict"));
   let downgraded: string | undefined;
-  if (verdict === "pass" && executedChecks(verification).length === 0) {
+  let relaxed: string | undefined;
+  const checked = executedChecks(verification).length > 0;
+  if (verdict === "pass" && !checked) {
     verdict = "changes_required";
     downgraded = UNVERIFIED_PASS;
     requiredChanges.push("Re-run the QA gate and record the checks actually executed, each as `- command — result`.");
+  } else if (
+    verdict === "changes_required" && checked && entries.length > 0
+    // Only findings explicitly tagged minor or info: an untagged one may be serious.
+    && entries.every((entry) => { const severity = taggedSeverity(entry); return severity === "minor" || severity === "info"; })
+  ) {
+    verdict = "pass";
+    relaxed = MINOR_ONLY;
   }
   return {
     domain,
     role: "reviewer",
     verdict,
-    findings: bullets(findSection(sections, "findings")).map(parseFinding),
+    findings: entries.map(parseFinding),
     verification,
     requiredChanges,
     optionalImprovements: bullets(findSection(sections, "optional improvements")),
     pushback: parsePushback(sections),
     ...(downgraded ? { downgraded } : {}),
+    ...(relaxed ? { relaxed } : {}),
     raw,
   };
 }