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

package/src/workflow/workflow.ts

@@ -1,6 +1,7 @@
-import { join } from "node:path";
+import { mkdirSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 import type { BotLobbyConfig, ProfileResolver } from "../schemas/configuration.ts";
-import type { AgentRun, Pushback, ResearchResult, ReviewResult } from "../schemas/findings.ts";
+import type { AgentRun, Pushback, ResearchResult, ReviewResult, WorkerResult } from "../schemas/findings.ts";
 import {
   MAX_RUN_LOG,
   MAX_WORKER_RECORDS,
@@ -21,12 +22,17 @@ import { appendCompletedTask, appendDecision, applyKnowledge, readFileOr, writeF
 import { compactKnowledgeFile, overThreshold } from "../knowledge/compactor.ts";
 import { knowledgeDir, type KnowledgeAgent } from "../knowledge/paths.ts";
 import { writeScratchpad } from "../state/persistence.ts";
-import { spawnPiProcess, type ProcessRunner } from "../execution/pi-runner.ts";
+import { spawnPiProcess, type ProcessRunner, type RelayAsk } from "../execution/pi-runner.ts";
+import { previewDir } from "../ask/relay.ts";
+import type { AskQuestion, AskResult } from "../ask/types.ts";
 import { mapConcurrent } from "../execution/agent-runner.ts";
 import { parseWorkerResult } from "../roles/worker.ts";
 import { autoNote, DESK_TOOLS, DeskSession } from "../desk/session.ts";
 import type { Handover } from "../desk/desk.ts";
-import { readRepositoryDiff } from "../execution/git.ts";
+import { changedFiles, commitBefore, headCommit, readRepositoryDiff } from "../execution/git.ts";
+import { appendChange, explainChanges, provenanceLines, provenanceSummary, readChanges, type FileProvenance } from "../state/changes.ts";
+import { budgetLine, budgetState, formatMinutes, MIN_READ_MS, parseMinutes, qaAllotment, readBudget, readerAllotment, updateBudget, workerAllotment, type Allotment, type BudgetState, type TaskBudget } from "../state/budget.ts";
+import type { AgentTime } from "../execution/agent-runner.ts";
 import {
   loadScoutResults,
   runReviewer,
@@ -41,7 +47,7 @@ import {
 import { researchResultPath, runResearch, type ResearchOutcome, type ResearchRequest } from "../master/research.ts";
 import { assessReconnaissance, completionBlockers, decideReviewLoop, recordDecision } from "../master/decisions.ts";
 import { detectSharedFiles, summarizeOutcomes } from "../master/synthesis.ts";
-import { truncate } from "../text.ts";
+import { tail, truncate } from "../text.ts";
 import { isAutoMode } from "../state/auto.ts";
 import { assertNoPendingApprovals, pendingApprovals, requestApproval, resolveApproval } from "./approvals.ts";
 import { pingApproval } from "../pi/notify.ts";
@@ -69,6 +75,7 @@ export const ORCHESTRATE_ACTIONS = [
   "block",
   "resume",
   "decide",
+  "budget",
   "status",
   "cancel",
 ] as const;
@@ -93,7 +100,9 @@ export interface OrchestrateParams {
   /** implement: the concrete instruction for the worker. */
   task?: string;
   /** implement: several domains at once, run in parallel through the file desk. */
-  assignments?: Array<{ domain: string; task: string }>;
+  assignments?: Array<{ domain: string; task: string; minutes?: number }>;
+  /** implement: minutes the step may take under the task's time budget; budget: extra minutes to ask the user for. */
+  minutes?: number;
   /** knowledge: which persistent file the text belongs to. */
   kind?: KnowledgeKind;
   /** compact: the knowledge file being rewritten. */
@@ -118,6 +127,8 @@ export interface WorkflowDeps {
   onUpdate?: (run: AgentRun) => void;
   ask: (question: string) => Promise<string | undefined>;
   choose: (title: string, options: string[]) => Promise<string | undefined>;
+  /** Puts an agent's questions to the user (the questionnaire, `from` naming the agent); absent without a UI. */
+  askQuestions?: (questions: AskQuestion[], from: string, signal?: AbortSignal) => Promise<AskResult>;
   notify: (message: string, level?: "info" | "warning" | "error") => void;
   runProcess?: ProcessRunner;
   /** Likely files for scouts and workers, while the classifier's file hints are on. */
@@ -302,11 +313,14 @@ async function handleScout(task: Task, params: OrchestrateParams, deps: Workflow
   if (task.state === "created") transition(task, "clarifying");
   if (task.state === "clarifying") transition(task, "scouting");
   const verifying = task.state === "synthesizing";
+  const instruction = params.instruction?.trim() || "Investigate this request and report findings the Master needs.";
+  const time = readerTime(task, deps, "SCOUTS", instruction, SCOUT_SHARE, deps.config.scout.timeoutMs, "scouting");
   const outcomes = await runScouts(
     {
       taskId: task.id,
       taskText: taskRequest(task),
-      instruction: params.instruction?.trim() || "Investigate this request and report findings the Master needs.",
+      instruction,
+      ...(time ? { time } : {}),
       domains,
       cwd: deps.cwd,
       dataRoots: readDataRoots(deps.root, deps.configDir),
@@ -320,6 +334,7 @@ async function handleScout(task: Task, params: OrchestrateParams, deps: Workflow
     },
     deps.runProcess ?? spawnPiProcess,
   );
+  if (time) settleAllotment(task, deps, time.id, "finished");
   if (!verifying) transition(task, "synthesizing");
   const involved = outcomes.filter((outcome) => outcome.usable).map((outcome) => outcome.result.domain);
   task.domains = [...new Set([...task.domains, ...involved])];
@@ -331,7 +346,7 @@ async function handleScout(task: Task, params: OrchestrateParams, deps: Workflow
 const RESEARCH_STATES: TaskState[] = TASK_STATES.filter((state) => !TERMINAL_STATES.includes(state));
 
 const RESEARCH_DEGRADED =
-  "The researcher is spawned with read-only repository tools plus web_search, fetch_content, source_check and get_search_content. If pi-web-access is not installed, the pi CLI silently ignores those tool names, so research degrades to repository-only and cannot cite the internet.";
+  "The researcher is spawned with read-only repository tools plus bot-lobby's web tools (web_search, fetch_content, source_check, get_search_content). A run without sources usually means the web could not be reached or the search was refused: its tool errors say which (DuckDuckGo, the default, throttles automated searches; BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY or SEARXNG_URL gives a dependable search).";
 
 function bulletSection(label: string, items: string[], limit: number): string {
   if (items.length === 0) return "";
@@ -403,11 +418,13 @@ function researchRequestFor(
   domain: Domain,
   instruction: string,
   taskDir: string,
+  time?: AgentTime,
 ): ResearchRequest {
   return {
     taskId: task.id,
     domain,
     instruction,
+    ...(time ? { time } : {}),
     config: deps.config,
     profile: deps.profile,
     cwd: deps.cwd,
@@ -423,7 +440,9 @@ async function handleResearch(task: Task, params: OrchestrateParams, deps: Workf
   const instruction = params.instruction?.trim();
   if (!instruction) throw new Error("research requires instruction (the question to investigate)");
   const taskDir = taskDirFor(deps.root, deps.configDir, task.id);
-  const outcome = await runResearch(researchRequestFor(deps, task, domain, instruction, taskDir), deps.runProcess ?? spawnPiProcess);
+  const time = readerTime(task, deps, "RESEARCH", instruction, RESEARCH_SHARE, deps.config.researcher.timeoutMs ?? deps.config.workflow.agentTimeoutMs, "research");
+  const outcome = await runResearch(researchRequestFor(deps, task, domain, instruction, taskDir, time), deps.runProcess ?? spawnPiProcess);
+  if (time) settleAllotment(task, deps, time.id, "finished");
   appendResearchLog(taskDir, domain, outcome);
   recordAdvisoryPushbacks(task, [{ pushback: outcome.result.pushback, who: domain }]);
   return researchReport(outcome, researchResultPath(taskDir, domain));
@@ -592,19 +611,48 @@ function updateScratchpad(deps: WorkflowDeps, task: Task, outcome: WorkerOutcome
   writeScratchpad(dir, domain, [existing, entry].filter(Boolean).join("\n\n"), deps.config.knowledge);
 }
 
-function workerTaskText(task: Task): string {
+/** Plan sections a reader must never lose to a cut: what the work is for, and how it is judged. */
+const KEEP_PLAN_SECTIONS = /objective|goal|acceptance|criteria|testing|tests?\b/i;
+
+/**
+ * The plan within `budget` characters: whole when it fits; otherwise the
+ * objective, acceptance criteria and testing sections whole (a head cut used
+ * to drop them, as they come last), then the others in order while they fit,
+ * naming any left out.
+ */
+export function planWithin(plan: string, budget: number): string {
+  if (plan.length <= budget) return plan;
+  const sections = plan.split(/\n(?=#{1,4}\s)/);
+  const keep = sections.map((section) => KEEP_PLAN_SECTIONS.test(section.split("\n")[0] ?? ""));
+  let used = sections.reduce((total, section, index) => total + (keep[index] ? section.length + 1 : 0), 0);
+  const chosen = sections.map((section, index) => {
+    if (keep[index]) return true;
+    if (used + section.length + 1 > budget) return false;
+    used += section.length + 1;
+    return true;
+  });
+  const left = sections.filter((_, index) => !chosen[index]).map((section) => (section.split("\n")[0] ?? "").replace(/^#+\s*/, "").trim() || "preamble");
+  const text = sections.filter((_, index) => chosen[index]).join("\n");
+  const note = left.length > 0 ? `\n\n[Left out for length: ${left.join(", ")}. The whole plan is plan.md in the task folder.]` : "";
+  return `${truncate(text, budget)}${note}`;
+}
+
+function workerTaskText(task: Task, planBudget = 6000): string {
   return [
     `Requirements: ${taskRequest(task)}`,
     task.proposal ? `Approved objective: ${task.proposal}` : "",
-    task.plan ? `Approved plan:\n${truncate(task.plan, 6000)}` : "",
+    task.plan ? `Approved plan:\n${planWithin(task.plan, planBudget)}` : "",
     task.amendments.length > 0 ? `User amendments:\n${task.amendments.map((entry) => `- ${entry}`).join("\n")}` : "",
   ]
     .filter((line) => line.length > 0)
     .join("\n\n");
 }
 
-function workerRequest(deps: WorkflowDeps, task: Task, domain: Domain, instruction: string): WorkerRequest {
+function workerRequest(deps: WorkflowDeps, task: Task, domain: Domain, instruction: string, time?: AgentTime): WorkerRequest {
+  const ask = askRelay(task, deps, domain);
   return {
+    ...(time ? { time } : {}),
+    ...(ask ? { ask } : {}),
     taskId: task.id,
     domain,
     instruction,
@@ -621,6 +669,49 @@ function workerRequest(deps: WorkflowDeps, task: Task, domain: Domain, instructi
   };
 }
 
+/** Agents that may ask the user themselves: the designer, whose choices are the user's to see. */
+const ASKING_DOMAINS: ReadonlySet<Domain> = new Set(["designer"]);
+
+/**
+ * The relay for a worker allowed to ask the user: its questions wait their
+ * turn behind any other dialog, go to the user with every clock stopped, and
+ * the answers become task decisions. Never in auto mode (nobody to ask), and
+ * never without a UI.
+ */
+function askRelay(task: Task, deps: WorkflowDeps, domain: Domain): { onAsk: RelayAsk; previews: string } | undefined {
+  if (!ASKING_DOMAINS.has(domain) || !deps.askQuestions || isAutoMode(deps.root, deps.configDir, task.id)) return undefined;
+  const askQuestions = deps.askQuestions;
+  const label = AGENT_LABELS[domain];
+  const previews = previewDir(task.id);
+  try {
+    mkdirSync(previews, { recursive: true });
+  } catch {
+    // Without the folder it can still ask with Markdown previews.
+  }
+  const onAsk: RelayAsk = (questions, signal) =>
+    oneAtATime(async () => {
+      if (signal.aborted) return { answers: [], cancelled: true };
+      if (isAutoMode(deps.root, deps.configDir, task.id)) {
+        return { answers: [], cancelled: true, globalNote: "Auto mode is on, so nobody can answer: decide with the options you recommend and say in your report what you chose and why." };
+      }
+      const result = await askQuestions(questions, label, signal);
+      recordDecision(task, askedDecision(label, questions, result), domain);
+      return result;
+    });
+  return { onAsk, previews };
+}
+
+/** An agent's questions and the user's answers, as the task's decision record keeps them. */
+export function askedDecision(label: string, questions: readonly AskQuestion[], result: AskResult): string {
+  if (result.answers.length === 0) return `${label} asked the user about ${questions.map((question) => question.header).join(", ")}; they did not answer, so ${label} decides.`;
+  const lines = questions.map((question, index) => {
+    const answer = result.answers.find((entry) => entry.questionIndex === index);
+    const text = !answer ? "not answered" : answer.kind === "multi" ? (answer.selected ?? []).join(", ") : `${answer.answer ?? ""}${answer.kind === "custom" ? " (in their words)" : ""}`;
+    return `[${question.header}] ${oneLine(question.question, 120)} → ${oneLine(text, 200)}`;
+  });
+  return `${label} asked the user: ${lines.join("; ")}`;
+}
+
 /** Remember a worker delegation so the checklist replays it after a reload. */
 function recordWorkerRun(task: Task, run: AgentRun): void {
   const record: WorkerRunRecord = {
@@ -637,6 +728,8 @@ function recordWorkerRun(task: Task, run: AgentRun): void {
 interface Assignment {
   domain: Domain;
   instruction: string;
+  /** Minutes the oracle gave the step, under a time budget. */
+  minutes?: number;
 }
 
 /** The delegation as a list: `assignments` for a parallel batch, otherwise the single domain/task. */
@@ -645,7 +738,7 @@ function parseAssignments(params: OrchestrateParams): Assignment[] {
     const list = params.assignments.map((entry) => {
       const instruction = entry.task?.trim();
       if (!instruction) throw new Error("every assignment needs a task (what to implement)");
-      return { domain: parseDomain(entry.domain, "implement"), instruction };
+      return { domain: parseDomain(entry.domain, "implement"), instruction, ...(entry.minutes ? { minutes: entry.minutes } : {}) };
     });
     const domains = list.map((entry) => entry.domain);
     if (new Set(domains).size !== domains.length) throw new Error("parallel assignments need distinct domains (one worker per domain)");
@@ -654,18 +747,96 @@ function parseAssignments(params: OrchestrateParams): Assignment[] {
   const domain = parseDomain(params.domain, "implement");
   const instruction = params.task?.trim();
   if (!instruction) throw new Error("implement requires task (what to implement)");
-  return [{ domain, instruction }];
+  return [{ domain, instruction, ...(params.minutes ? { minutes: params.minutes } : {}) }];
+}
+
+/**
+ * What the working tree held when this task's agents started: the QA gate
+ * reads those files as pre-existing. Taken before the first worker only, so
+ * a task already under way when provenance arrived is not misread.
+ */
+async function takeBaseline(task: Task, deps: WorkflowDeps): Promise<void> {
+  if (task.baseline || (task.workerRuns?.length ?? 0) > 0) return;
+  const [tree, head] = await Promise.all([treeChanges(deps), headCommit(deps.cwd)]);
+  task.baseline = { at: new Date().toISOString(), files: tree?.files ?? [], ...(head ? { head } : {}) };
+}
+
+/**
+ * The commit the task's work is measured from: HEAD when its first worker
+ * started, or, for a task begun before that was recorded, the newest commit
+ * before the task was created. Work committed since then is still the task's
+ * to review; a diff against HEAD alone showed it as nothing.
+ */
+async function reviewBase(task: Task, deps: WorkflowDeps): Promise<string | undefined> {
+  return task.baseline?.head ?? (await commitBefore(deps.cwd, task.createdAt));
+}
+
+/** bot-lobby's own records, relative to the working folder, when they sit inside it. */
+function ownRecords(deps: WorkflowDeps): string[] {
+  const own = relative(deps.cwd, dataRoot(deps.root, deps.configDir));
+  return own && !own.startsWith("..") && !isAbsolute(own) ? [own.split("\\").join("/")] : [];
+}
+
+/** The working tree's changed files, without bot-lobby's own records (its data folder may sit untracked in the project). */
+async function treeChanges(deps: WorkflowDeps, base?: string): Promise<{ top: string; files: string[] } | undefined> {
+  const tree = await changedFiles(deps.cwd, base);
+  if (!tree) return undefined;
+  let data = dataRoot(deps.root, deps.configDir);
+  try {
+    data = realpathSync(data);
+  } catch {
+    // Not created yet: nothing of it can be in the tree.
+  }
+  const own = relative(tree.top, data);
+  if (!own || own.startsWith("..") || isAbsolute(own)) return tree;
+  const prefix = `${own.split("\\").join("/")}/`;
+  return { top: tree.top, files: tree.files.filter((file) => !file.startsWith(prefix)) };
+}
+
+/** Every changed file of the working tree, explained for this task; undefined without a baseline or git. */
+async function changeProvenance(deps: WorkflowDeps, task: Task, base?: string): Promise<FileProvenance[] | undefined> {
+  if (!task.baseline) return undefined;
+  const tree = await treeChanges(deps, base);
+  if (!tree) return undefined;
+  return explainChanges(task, tree.files, tree.top, readChanges(deps.root, deps.configDir, task.createdAt));
+}
+
+/** Who changed the tree, for the Master: counts, and what the changes that are not this task's mean for it. */
+function provenanceNote(files: readonly FileProvenance[] | undefined): string {
+  if (!files || files.length === 0) return "";
+  const kinds = new Set(files.flatMap((file) => file.kinds));
+  return [
+    `Changed files: ${provenanceSummary(files)}.`,
+    kinds.has("quickfix") ? "The user asked for the quick fixes directly: never revert them or send them back as fixes." : "",
+    kinds.has("pre-existing") || kinds.has("other-task") ? "Pre-existing changes and other tasks' are not this task's to review or revert." : "",
+    kinds.has("unattributed") ? "No agent recorded the unattributed edits: ask the user before counting them in or reverting them." : "",
+  ]
+    .filter((line) => line.length > 0)
+    .join(" ");
 }
 
 /** Record one worker's outcome on the task and return its report for the Master. */
-function absorbWorkerOutcome(task: Task, deps: WorkflowDeps, outcome: WorkerOutcome): string {
+function absorbWorkerOutcome(task: Task, deps: WorkflowDeps, outcome: WorkerOutcome, time?: WorkerTime): string {
   const domain = outcome.result.domain;
   recordWorkerRun(task, outcome.run);
+  if (time) settleAllotment(task, deps, time.id, stoppedForTime(outcome) ? "out of time" : outcome.run.status === "success" ? "finished" : "stopped");
+  appendChange(deps.root, deps.configDir, {
+    source: "worker",
+    id: outcome.run.runId,
+    taskId: task.id,
+    domain,
+    what: (outcome.run.instruction ?? "").split("\n").find((line) => line.trim())?.trim() ?? domain,
+    files: outcome.run.edited ?? [],
+    startedAt: outcome.run.startedAt,
+    finishedAt: outcome.run.finishedAt ?? new Date().toISOString(),
+    status: outcome.run.status,
+  });
   const approvals = recordWorkerApprovals(task, outcome, deps.config, isAutoMode(deps.root, deps.configDir, task.id));
   const pushback = recordPushback(task, outcome);
   task.blockers = [...task.blockers.filter((blocker) => blocker.domain !== domain), ...outcome.result.blockers];
   updateScratchpad(deps, task, outcome);
-  return workerReport(outcome, approvals, pushback);
+  const spent = timeReport(outcome);
+  return spent ? `${workerReport(outcome, approvals, pushback)}\n${spent}` : workerReport(outcome, approvals, pushback);
 }
 
 async function handleImplement(task: Task, params: OrchestrateParams, deps: WorkflowDeps): Promise<string> {
@@ -673,13 +844,23 @@ async function handleImplement(task: Task, params: OrchestrateParams, deps: Work
   const assignments = parseAssignments(params);
   for (const { domain } of assignments) assertNoPendingApprovals(task, domain);
   for (const { domain } of assignments) if (!task.domains.includes(domain)) task.domains.push(domain);
+  // Under a time budget every step is given its share before any starts; a spent budget starts none.
+  const times = workerTimes(task, deps, assignments);
   if (task.state !== "implementing") transition(task, "implementing");
-  if (assignments.length === 1) {
-    const { domain, instruction } = assignments[0]!;
-    const outcome = await runWorker(workerRequest(deps, task, domain, instruction), deps.runProcess ?? spawnPiProcess);
-    return absorbWorkerOutcome(task, deps, outcome);
+  await takeBaseline(task, deps);
+  let report: string;
+  try {
+    if (assignments.length === 1) {
+      const { domain, instruction } = assignments[0]!;
+      const outcome = await runWorker(workerRequest(deps, task, domain, instruction, times.get(domain)), deps.runProcess ?? spawnPiProcess);
+      report = absorbWorkerOutcome(task, deps, outcome, times.get(domain));
+    } else report = await runParallelWorkers(task, deps, assignments, times);
+  } finally {
+    // A step that never reported (the call failed) does not stay "running" in the budget.
+    for (const time of times.values()) settleAllotment(task, deps, time.id, "stopped");
   }
-  return runParallelWorkers(task, deps, assignments);
+  const note = provenanceNote(await changeProvenance(deps, task, task.baseline?.head));
+  return note ? `${report}\n\n${note}` : report;
 }
 
 /**
@@ -687,14 +868,14 @@ async function handleImplement(task: Task, params: OrchestrateParams, deps: Work
  * before editing it, queues for a busy one, and hands it over with a note; a
  * worker that finishes hands over whatever it still holds automatically.
  */
-async function runParallelWorkers(task: Task, deps: WorkflowDeps, assignments: Assignment[]): Promise<string> {
+async function runParallelWorkers(task: Task, deps: WorkflowDeps, assignments: Assignment[], times: ReadonlyMap<Domain, WorkerTime>): Promise<string> {
   const session = new DeskSession({ cwd: deps.cwd });
   await session.open();
   let outcomes: WorkerOutcome[];
   let unenforced: Domain[];
   try {
     outcomes = await mapConcurrent(assignments, deps.config.workflow.maxParallelWorkers, ({ domain, instruction }) => {
-      const request = workerRequest(deps, task, domain, instruction);
+      const request = workerRequest(deps, task, domain, instruction, times.get(domain));
       request.agent = {
         env: session.env(domain),
         extraTools: DESK_TOOLS,
@@ -710,7 +891,7 @@ async function runParallelWorkers(task: Task, deps: WorkflowDeps, assignments: A
   } finally {
     await session.close();
   }
-  const reports = outcomes.map((outcome) => absorbWorkerOutcome(task, deps, outcome));
+  const reports = outcomes.map((outcome) => absorbWorkerOutcome(task, deps, outcome, times.get(outcome.result.domain)));
   return [
     `Parallel batch: ${assignments.map((entry) => entry.domain).join(", ")}.`,
     ...reports,
@@ -765,28 +946,52 @@ function recordReview(task: Task, domain: Domain, result: ReviewResult): void {
     createdAt: new Date().toISOString(),
   });
 }
-function allScratchpads(deps: WorkflowDeps, task: Task): string {
+/** Each domain's scratchpad, its newest entries kept when it is long (the latest fix round matters most). */
+function allScratchpads(deps: WorkflowDeps, task: Task, perDomain = 1500): string {
   return (["designer", "backend", "qa"] as Domain[])
-    .map((domain) => scratchpadSummary(deps, task, domain).trim())
+    .map((domain) => tail(scratchpadSummary(deps, task, domain).trim(), perDomain))
     .filter((text) => text.length > 0)
     .join("\n\n---\n\n");
 }
 
+/**
+ * What the last QA round asked for, so the next one verifies it instead of
+ * reviewing everything from scratch (and finding new things each time).
+ */
+function previousRound(task: Task): string {
+  const rounds = task.reviewRecords.filter((record) => record.domain === "qa");
+  const last = rounds.at(-1);
+  if (!last || last.verdict === "pass") return "";
+  const asks = [
+    ...last.findings.filter((finding) => finding.severity === "critical" || finding.severity === "major").map((finding) => `[${finding.severity}] ${finding.text}`),
+    ...last.requiredChanges,
+  ];
+  if (asks.length === 0) return "";
+  return [
+    `This is QA round ${rounds.length + 1}. Round ${rounds.length} (${last.verdict.toUpperCase()}) asked for:`,
+    ...asks.slice(0, 20).map((ask) => `- ${truncate(ask, 300)}`),
+    "Verify each of these first and say which are addressed. Do not start the review over: a new blocking finding must be critical or major (a problem the fixes introduced, or an unmet acceptance criterion); anything else goes under Optional Improvements.",
+  ].join("\n");
+}
+
 const QA_INSTRUCTION = [
   "Run the QA quality gate for the completed feature.",
   "Verify requirements, acceptance criteria, regression risk, edge cases, security, accessibility,",
   "UX, reliability, and tests. Passing automated tests alone is not acceptance.",
 ].join(" ");
 
-/** The QA gate looks at every domain's work, not just one worker's diff. */
-function qaRequest(deps: WorkflowDeps, task: Task, diff: string, instruction?: string): ReviewerRequest {
+/** The QA gate looks at every domain's work, not just one worker's diff, knowing who changed each file. */
+function qaRequest(deps: WorkflowDeps, task: Task, diff: string, instruction?: string, provenance?: readonly FileProvenance[]): ReviewerRequest {
+  const rounds = previousRound(task);
   return {
     taskId: task.id,
     domain: "qa",
-    taskText: `${workerTaskText(task)}\n\nAcceptance criteria and plan:\n${truncate(task.plan ?? "", 5000)}`,
+    taskText: workerTaskText(task, 9000),
     workerSummary: allScratchpads(deps, task),
+    ...(rounds ? { previousRound: rounds } : {}),
     scoutOutcomes: loadScoutResults(taskReadDirs(deps.root, deps.configDir, task.id), [...new Set<Domain>(["qa", ...task.domains])]),
     diff,
+    ...(provenance && provenance.length > 0 ? { provenance: provenanceLines(provenance) } : {}),
     instruction: instruction?.trim() || QA_INSTRUCTION,
     cwd: deps.cwd,
     dataRoots: readDataRoots(deps.root, deps.configDir),
@@ -797,22 +1002,30 @@ function qaRequest(deps: WorkflowDeps, task: Task, diff: string, instruction?: s
   };
 }
 
-function qaReport(outcome: ReviewerOutcome, decision: "accept" | "iterate" | "blocked"): string {
+/** What the loop does after a QA round: finish, fix and review again, stop, or (the user's call) accept the work as it is. */
+type LoopDecision = "accept" | "iterate" | "blocked" | "waived";
+
+function qaReport(outcome: ReviewerOutcome, decision: LoopDecision, provenance?: readonly FileProvenance[]): string {
   const { result, run, issues } = outcome;
+  const passed = result.verdict === "pass";
   return [
-    `QA gate: ${result.verdict.toUpperCase()} (run ${run.status}${run.error ? `: ${run.error}` : ""})`,
+    `QA gate: ${result.verdict.toUpperCase()} (run ${run.status}${run.error ? `: ${run.error}` : ""})${result.relaxed ? " — only minor findings, which never hold the gate" : ""}`,
     result.findings.length > 0
       ? `Findings:\n${result.findings.map((finding) => `- [${finding.severity}] ${truncate(finding.text, 300)}`).join("\n")}`
       : "",
     result.requiredChanges.length > 0
-      ? `Required changes:\n${result.requiredChanges.map((change) => `- ${truncate(change, 300)}`).join("\n")}`
+      ? `${passed ? "Follow-ups (not blocking; mention them to the user, do not start a fix round for them)" : "Required changes"}:\n${result.requiredChanges.map((change) => `- ${truncate(change, 300)}`).join("\n")}`
       : "",
     decision === "accept"
       ? "The QA gate passed. Record any distilled knowledge, then call action=complete."
-      : "The QA gate did not pass: delegate the required changes to the owning domain, then re-run action=qa.",
-    decision === "blocked" ? "The review limit is reached: mark the task blocked and tell the user." : "",
+      : decision === "waived"
+        ? "The user accepted the work as it is, without a QA pass. Call action=complete now with a short summary that names what QA still asked for."
+        : decision === "iterate"
+          ? "The QA gate did not pass: delegate the required changes to the owning domain, then re-run action=qa."
+          : "The review limit is reached and the user did not accept the work: mark the task blocked and tell the user what QA still asks for. They can accept it with /bot-lobby accept.",
     result.pushback ? pushbackLine(result.pushback, "qa") : "",
     issues.length > 0 ? `Issues: ${issues.join("; ")}` : "",
+    provenanceNote(provenance),
   ]
     .filter((line) => line.length > 0)
     .join("\n");
@@ -823,14 +1036,87 @@ async function handleQa(task: Task, params: OrchestrateParams, deps: WorkflowDep
   if (task.state !== "reviewing") transition(task, "reviewing");
   const iterations = (task.reviewIterations?.qa ?? 0) + 1;
   task.reviewIterations = { qa: iterations };
-  const diff = await readRepositoryDiff(deps.cwd);
-  const outcome = await runReviewer(qaRequest(deps, task, diff, params.task), deps.runProcess ?? spawnPiProcess);
+  const time = qaTime(task, deps);
+  const base = await reviewBase(task, deps);
+  const [diff, provenance] = await Promise.all([
+    readRepositoryDiff(deps.cwd, { ...(base ? { base } : {}), exclude: ownRecords(deps) }),
+    changeProvenance(deps, task, base),
+  ]);
+  const outcome = await runReviewer({ ...qaRequest(deps, task, diff, params.task, provenance), ...(time ? { time } : {}) }, deps.runProcess ?? spawnPiProcess);
+  if (time) settleAllotment(task, deps, time.id, "finished");
   task.qaVerdict = outcome.result.verdict;
   recordReview(task, "qa", outcome.result);
   recordAdvisoryPushbacks(task, [{ pushback: outcome.result.pushback, who: "qa" }]);
-  const decision = decideReviewLoop(outcome.result.verdict, iterations, deps.config.workflow.maxReviewIterations);
+  if (outcome.result.relaxed) recordDecision(task, `QA round ${iterations} passed: ${outcome.result.relaxed}.`, "qa");
+  let decision: LoopDecision = decideReviewLoop(outcome.result.verdict, iterations, reviewLimit(task, deps));
+  if (decision === "blocked") decision = await askAtReviewLimit(task, outcome.result, iterations, deps);
   if (decision === "accept") task.blockers = task.blockers.filter((blocker) => blocker.domain !== "qa");
-  return qaReport(outcome, decision);
+  return qaReport(outcome, decision, provenance);
+}
+
+/** Review rounds allowed: the configured limit plus any the user granted. */
+function reviewLimit(task: Task, deps: WorkflowDeps): number {
+  return deps.config.workflow.maxReviewIterations + (task.extraReviewRounds ?? 0);
+}
+
+/** What QA still asks for, one line each: its blocking findings and required changes. */
+function openAsks(result: Pick<ReviewResult, "findings" | "requiredChanges">): string[] {
+  return [
+    ...result.findings.filter((finding) => finding.severity === "critical" || finding.severity === "major").map((finding) => `[${finding.severity}] ${finding.text}`),
+    ...result.requiredChanges,
+  ];
+}
+
+const ACCEPT_WORK = "Accept the work as it is and complete the task";
+const ONE_MORE_ROUND = "Run one more fix round";
+
+/**
+ * The review limit is reached (or QA says BLOCKED): the user decides, not the
+ * loop. They can accept the work as it is, grant one more fix round, or leave
+ * the task blocked. Nobody is asked in auto mode or without a UI: it blocks.
+ */
+async function askAtReviewLimit(task: Task, result: ReviewResult, iterations: number, deps: WorkflowDeps): Promise<LoopDecision> {
+  if (isAutoMode(deps.root, deps.configDir, task.id)) return "blocked";
+  const asks = openAsks(result);
+  const checks = result.verification.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("-")).slice(0, 4);
+  const choice = await deps.choose(
+    [
+      `QA has not passed ${task.id} after ${iterations} round${iterations === 1 ? "" : "s"} (this one: ${result.verdict.toUpperCase()}).`,
+      asks.length > 0 ? `It still asks for:\n${asks.slice(0, 8).map((ask) => `- ${truncate(ask, 200)}`).join("\n")}` : "",
+      checks.length > 0 ? `Its checks:\n${checks.map((line) => truncate(line, 160)).join("\n")}` : "",
+    ].filter(Boolean).join("\n\n"),
+    [ACCEPT_WORK, ONE_MORE_ROUND, "Leave the task blocked"],
+  );
+  if (choice === ACCEPT_WORK) {
+    waiveQa(task, asks, `after ${iterations} QA round${iterations === 1 ? "" : "s"}`);
+    return "waived";
+  }
+  if (choice === ONE_MORE_ROUND) {
+    task.extraReviewRounds = (task.extraReviewRounds ?? 0) + 1;
+    recordDecision(task, `The user granted one more QA round after ${iterations}.`);
+    return "iterate";
+  }
+  return "blocked";
+}
+
+/**
+ * The user accepts the work as it stands: the QA gate is waived, blockers are
+ * cleared, and a blocked task returns to review so it can complete. Only the
+ * user's own choice (a dialog or /bot-lobby accept) ever gets here.
+ */
+export function waiveQa(task: Task, open: readonly string[], why: string): void {
+  task.qaWaiver = { at: new Date().toISOString(), open: open.map((ask) => truncate(ask, 300)) };
+  const cleared = task.blockers.map((blocker) => blocker.reason);
+  task.blockers = [];
+  if (task.state === "blocked") transition(task, "implementing");
+  if (task.state === "implementing") transition(task, "reviewing");
+  recordDecision(task, `The user accepted the work without a QA pass (${why}).${open.length > 0 ? ` QA still asked for: ${open.map((ask) => truncate(ask, 160)).join("; ")}.` : ""}${cleared.length > 0 ? ` Cleared blockers: ${cleared.join("; ")}.` : ""}`);
+}
+
+/** The last QA round's open asks, for a waiver made outside the loop. */
+export function lastQaAsks(task: Task): string[] {
+  const last = task.reviewRecords.filter((record) => record.domain === "qa").at(-1);
+  return last && last.verdict !== "pass" ? openAsks(last) : [];
 }
 
 /**
@@ -872,8 +1158,11 @@ function handleCompact(task: Task, params: OrchestrateParams, deps: WorkflowDeps
 }
 
 /** §63: record history, drop scratchpads, then mark the task completed. */
-function handleComplete(task: Task, params: OrchestrateParams, deps: WorkflowDeps): string {
-  requireState(task, ["reviewing"]);
+async function handleComplete(task: Task, params: OrchestrateParams, deps: WorkflowDeps): Promise<string> {
+  requireState(task, ["reviewing", "blocked"]);
+  // Without a QA pass only the user can let the task finish: they are asked, never overruled.
+  if (task.qaVerdict !== "pass" && !task.qaWaiver) await offerAcceptance(task, deps);
+  if (task.state === "blocked") throw new Error("cannot complete: the task is blocked, and the user did not accept its work as it is");
   const blockers = completionBlockers(task, pendingApprovals(task).length);
   if (blockers.length > 0) throw new Error(`cannot complete: ${blockers.join("; ")}`);
   const summary = params.text?.trim() || task.proposal || task.title;
@@ -890,6 +1179,21 @@ function handleComplete(task: Task, params: OrchestrateParams, deps: WorkflowDep
   return `Task ${task.id} completed. History recorded and temporary scratchpads removed.${advice}`;
 }
 
+/** Asked when the oracle completes a task QA has not passed (the user told it to finish, say). */
+async function offerAcceptance(task: Task, deps: WorkflowDeps): Promise<void> {
+  if (isAutoMode(deps.root, deps.configDir, task.id)) return;
+  const asks = lastQaAsks(task);
+  const rounds = task.reviewIterations.qa;
+  const choice = await deps.choose(
+    [
+      `Complete ${task.id} without a QA pass? ${rounds > 0 ? `QA ran ${rounds} round${rounds === 1 ? "" : "s"}; the last said ${(task.qaVerdict ?? "nothing").toUpperCase()}.` : "QA has not run."}`,
+      asks.length > 0 ? `It still asks for:\n${asks.slice(0, 8).map((ask) => `- ${truncate(ask, 200)}`).join("\n")}` : "",
+    ].filter(Boolean).join("\n\n"),
+    ["Complete it anyway", "Not yet"],
+  );
+  if (choice === "Complete it anyway") waiveQa(task, asks, "when the oracle completed it");
+}
+
 function flushDecisions(deps: WorkflowDeps, task: Task): void {
   const root = dataRoot(deps.root, deps.configDir);
   for (const decision of task.decisions) {
@@ -936,6 +1240,251 @@ function handleCancel(task: Task): string {
   return `Task ${task.id} abandoned. Its scratchpad is kept until the task is formally resolved.`;
 }
 
+/* ------------------------------------------------------------ time budget */
+
+/** Shares of what is left that a scout batch and the researcher are given (within their configured limits). */
+const SCOUT_SHARE = 0.1;
+const RESEARCH_SHARE = 0.15;
+/** Minutes a worker out of time is taken to ask for when its report names none. */
+const DEFAULT_MORE_MINUTES = 10;
+
+/** A delegation's time, with the allotment it is recorded under. */
+type WorkerTime = AgentTime & { id: string };
+
+/** The task's budget and where it stands, when it has one. */
+function budgetFor(task: Task, deps: WorkflowDeps): { budget: TaskBudget; state: BudgetState } | undefined {
+  const budget = readBudget(deps.root, deps.configDir, task.id);
+  return budget ? { budget, state: budgetState(task.id, budget, task.qaVerdict === "pass") } : undefined;
+}
+
+/** No new work starts once the budget is spent: the oracle asks the user for more, or wraps up. */
+function budgetSpent(state: BudgetState, what: string): Error {
+  const reserve = state.reserveMs > 0 ? `, ${formatMinutes(state.reserveMs)} of it kept for the QA gate` : "";
+  const wrap = state.reserveMs >= MIN_READ_MS ? "run action=qa on what is done" : "complete or block with what is done";
+  return new Error(`the task's time budget has no room for ${what}: ${formatMinutes(state.usedMs)} of ${formatMinutes(state.totalMs)} used, ${formatMinutes(state.leftMs)} left${reserve}. Ask the user for more time with action=budget (minutes and reason), or wrap up: ${wrap}.`);
+}
+
+/** What an agent is told about its time. */
+function timeNote(allotMs: number, state: BudgetState, worker: boolean): string {
+  return [
+    "## Time",
+    `You have ${formatMinutes(allotMs)} for this ${worker ? "step" : "work"}; the task has ${formatMinutes(state.leftMs)} of its ${formatMinutes(state.totalMs)} left.`,
+    worker
+      ? "At about 75% you get a heads-up. When the time is up you are asked to stop and report where you left off (`## Left Off`) and how much more you need (`## More Time`); the user decides whether you get it. Land the most important part first, and keep every file consistent as you go."
+      : "When the time is up you are asked to stop and report what you have, so cover the most important questions first.",
+  ].join("\n");
+}
+
+function recordAllotment(task: Task, deps: WorkflowDeps, entry: Omit<Allotment, "startedAt" | "granted">): void {
+  updateBudget(deps.root, deps.configDir, task.id, (budget) => {
+    budget.allotments.push({ ...entry, granted: 0, startedAt: new Date().toISOString() });
+  });
+}
+
+function settleAllotment(task: Task, deps: WorkflowDeps, id: string, outcome: NonNullable<Allotment["outcome"]>): void {
+  updateBudget(deps.root, deps.configDir, task.id, (budget) => {
+    const entry = budget.allotments.find((allotment) => allotment.id === id);
+    if (entry && !entry.endedAt) Object.assign(entry, { endedAt: new Date().toISOString(), outcome });
+  });
+}
+
+function oneLine(text: string, max: number): string {
+  return truncate(text.replace(/\s+/g, " ").trim(), max).replace(/\n\[\.\.\.\d+ characters omitted\]$/, "…");
+}
+
+/** A read-only batch's time (scouts, the researcher): a share of what is left, within its configured limit. */
+function readerTime(task: Task, deps: WorkflowDeps, who: string, what: string, share: number, limitMs: number, label: string): WorkerTime | undefined {
+  const now = budgetFor(task, deps);
+  if (!now) return undefined;
+  const ms = readerAllotment(now.state, share, limitMs);
+  if (ms === undefined) throw budgetSpent(now.state, label);
+  const id = `${who.toLowerCase()}-${Date.now().toString(36)}`;
+  recordAllotment(task, deps, { id, who, what: oneLine(what, 120), minutes: Math.round(ms / 60_000) });
+  return { id, endsAt: Date.now() + ms, allotMs: ms, note: timeNote(ms, now.state, false) };
+}
+
+/** The QA gate's time: its reserve at least, never more than is left. */
+function qaTime(task: Task, deps: WorkflowDeps): WorkerTime | undefined {
+  const now = budgetFor(task, deps);
+  if (!now) return undefined;
+  const ms = qaAllotment(now.state, deps.config.agents.qa.timeoutMs ?? deps.config.workflow.agentTimeoutMs);
+  if (ms === undefined) throw budgetSpent(now.state, "the QA gate");
+  const id = `qa-${Date.now().toString(36)}`;
+  recordAllotment(task, deps, { id, who: "QA gate", what: "review the task's work", minutes: Math.round(ms / 60_000) });
+  return { id, endsAt: Date.now() + ms, allotMs: ms, note: timeNote(ms, now.state, false) };
+}
+
+/** Plan domains still to build, the batch counted once: what is left before the QA reserve is split across them by default. */
+function openSlots(task: Task, batch: readonly Domain[]): number {
+  const built = new Set((task.workerRuns ?? []).filter((run) => run.status === "success").map((run) => run.domain));
+  return task.domains.filter((domain) => !built.has(domain) && !batch.includes(domain)).length + 1;
+}
+
+/**
+ * Each step's time, given before any starts: the minutes the oracle asked
+ * for (it divides by scope) or an even share, never past what is left before
+ * the QA gate's reserve. A spent budget starts nothing.
+ */
+function workerTimes(task: Task, deps: WorkflowDeps, assignments: readonly Assignment[]): Map<Domain, WorkerTime> {
+  const times = new Map<Domain, WorkerTime>();
+  const now = budgetFor(task, deps);
+  if (!now) return times;
+  const slots = openSlots(task, assignments.map((entry) => entry.domain));
+  for (const { domain, instruction, minutes } of assignments) {
+    const given = workerAllotment(now.state, minutes, slots);
+    if (!given) throw budgetSpent(now.state, `the ${domain} step`);
+    const id = `${domain}-${Date.now().toString(36)}`;
+    recordAllotment(task, deps, { id, who: AGENT_LABELS[domain], what: oneLine(instruction, 120), minutes: Math.round(given.ms / 60_000) });
+    if (given.note) recordDecision(task, `${AGENT_LABELS[domain]}'s step: ${given.note}.`);
+    times.set(domain, { id, endsAt: Date.now() + given.ms, allotMs: given.ms, note: timeNote(given.ms, now.state, true), onTimeUp: moreTimeFor(task, deps, domain, instruction, id) });
+  }
+  return times;
+}
+
+const AGENT_LABELS: Record<Domain, string> = { backend: "DEV", designer: "DESIGN", qa: "QA" };
+
+/** Out-of-time questions one at a time, even when parallel workers run out together. */
+let asking: Promise<unknown> = Promise.resolve();
+function oneAtATime<T>(ask: () => Promise<T>): Promise<T> {
+  const next = asking.then(ask, ask);
+  asking = next.catch(() => undefined);
+  return next;
+}
+
+/**
+ * A worker out of time has reported what it did, where it left off and how
+ * much more it needs. The user decides (auto mode: once, and only from what
+ * is left before the QA gate's reserve); a grant past that grows the budget,
+ * and the same agent carries on. Resolves with the ms granted, 0 to stop it.
+ */
+function moreTimeFor(task: Task, deps: WorkflowDeps, domain: Domain, instruction: string, id: string): NonNullable<AgentTime["onTimeUp"]> {
+  let asked = 0;
+  return (run, report) => oneAtATime(async () => {
+    const result = parseWorkerResult(domain, report);
+    // A report with nothing left to do finished in time.
+    if (!result.leftOff && !result.moreTime) return 0;
+    asked += 1;
+    const label = AGENT_LABELS[domain];
+    const wanted = result.moreTime?.minutes ?? DEFAULT_MORE_MINUTES;
+    const now = budgetFor(task, deps);
+    if (!now) return 0;
+    const minutes = await decideMoreTime(task, deps, { label, instruction, result, wanted, run, asked, state: now.state });
+    if (minutes <= 0) return 0;
+    const over = Math.max(0, Math.ceil((minutes * 60_000 - now.state.windowMs) / 60_000));
+    updateBudget(deps.root, deps.configDir, task.id, (budget) => {
+      budget.granted += over;
+      const entry = budget.allotments.find((allotment) => allotment.id === id);
+      if (entry) Object.assign(entry, { minutes: entry.minutes + minutes, granted: entry.granted + minutes });
+    });
+    recordDecision(task, `${label} ran out of time; ${isAutoMode(deps.root, deps.configDir, task.id) ? "auto mode gave it" : "the user gave it"} ${minutes} more minutes${over > 0 ? `, ${over} of them added to the task's budget` : ""}. Left off: ${oneLine(result.leftOff ?? result.moreTime?.reason ?? "", 200)}`);
+    return minutes * 60_000;
+  });
+}
+
+interface MoreTimeAsk {
+  label: string;
+  instruction: string;
+  result: WorkerResult;
+  wanted: number;
+  run: AgentRun;
+  asked: number;
+  state: BudgetState;
+}
+
+const MORE_TIME = "Give it the time it asks for";
+const OTHER_TIME = "Give a different amount";
+
+async function decideMoreTime(task: Task, deps: WorkflowDeps, ask: MoreTimeAsk): Promise<number> {
+  const { label, instruction, result, wanted, run, asked, state } = ask;
+  if (isAutoMode(deps.root, deps.configDir, task.id)) {
+    // Nobody to ask: once, and only from time the task still has before the QA gate's reserve.
+    if (asked === 1 && wanted * 60_000 <= state.windowMs) return wanted;
+    recordDecision(task, `Auto mode: ${label} ran out of time and was not given more (${asked > 1 ? "it already had more once" : `it asked for ${wanted} minutes, ${formatMinutes(state.windowMs)} were left`}).`);
+    return 0;
+  }
+  const over = Math.max(0, Math.ceil((wanted * 60_000 - state.windowMs) / 60_000));
+  const had = run.allotMs ?? 0;
+  const choice = await deps.choose(
+    [
+      `${label} is out of time: it had ${formatMinutes(had + (run.extendedMs ?? 0))} for "${oneLine(instruction, 160)}".`,
+      result.completed ? `Done so far: ${oneLine(result.completed, 400)}` : "",
+      result.leftOff ? `Left to do: ${oneLine(result.leftOff, 400)}` : "",
+      `It needs about ${wanted} more minutes${result.moreTime?.reason ? `: ${oneLine(result.moreTime.reason, 200)}` : ""}.`,
+      `The task has used ${formatMinutes(state.usedMs)} of ${formatMinutes(state.totalMs)} (${formatMinutes(state.leftMs)} left)${over > 0 ? `; ${wanted} more minutes adds ${over} to its budget` : ""}.`,
+      `Give ${label} ${wanted} more minutes to finish?`,
+    ].filter(Boolean).join("\n\n"),
+    [MORE_TIME, OTHER_TIME, `Stop ${label} here`],
+  );
+  if (choice === MORE_TIME) return wanted;
+  if (choice === OTHER_TIME) return parseMinutes((await deps.ask(`How many more minutes for ${label}?`)) ?? "") ?? 0;
+  recordDecision(task, `The user stopped ${label} at its time limit. Left off: ${oneLine(result.leftOff ?? "", 200)}`);
+  return 0;
+}
+
+/** Stopped at its time with work left: a report that finished everything as time ran out is not. */
+function stoppedForTime(outcome: WorkerOutcome): boolean {
+  return Boolean(outcome.run.timeUp && (outcome.result.leftOff || outcome.result.moreTime));
+}
+
+/** How a step's time went, for the oracle: out of time and stopped, or given more. */
+function timeReport(outcome: WorkerOutcome): string {
+  const { run, result } = outcome;
+  const label = AGENT_LABELS[result.domain];
+  if (stoppedForTime(outcome)) {
+    return [
+      `${label} ran out of its time and was not given more: this step is unfinished.`,
+      result.leftOff ? `Left off: ${oneLine(result.leftOff, 600)}` : "",
+      result.moreTime ? `It asked for ${result.moreTime.minutes ?? "more"} minutes${result.moreTime.reason ? `: ${oneLine(result.moreTime.reason, 300)}` : ""}.` : "",
+      "Decide with the user: trim the scope, ask for task time with action=budget, or wrap up with what is done.",
+    ].filter(Boolean).join("\n");
+  }
+  return run.extendedMs ? `${label} ran out of its ${formatMinutes(run.allotMs ?? 0)} and was given ${formatMinutes(run.extendedMs)} more.` : "";
+}
+
+/**
+ * `action=budget`: with no minutes, where the budget stands; with minutes and
+ * a reason, the oracle asks the user for more task time. Only the user can
+ * grant it; in auto mode nobody can, and the task wraps up.
+ */
+async function handleBudget(task: Task, params: OrchestrateParams, deps: WorkflowDeps): Promise<string> {
+  const now = budgetFor(task, deps);
+  if (!now) return "This task has no time budget. The user sets one with /bot-lobby budget <minutes>.";
+  const minutes = params.minutes;
+  if (!minutes || minutes <= 0) return allotmentReport(now.budget);
+  const reason = params.reason?.trim() || params.text?.trim();
+  if (!reason) throw new Error("budget requires reason: why the task needs more time");
+  if (isAutoMode(deps.root, deps.configDir, task.id)) {
+    recordDecision(task, `Auto mode: asked for ${minutes} more minutes (${oneLine(reason, 160)}), which only the user can give.`);
+    return "Auto mode: nobody can give the task more time. Wrap up with what is done: finish or drop the step in hand, run the QA gate if there is room, and tell the user what is left.";
+  }
+  const choice = await deps.choose(
+    [`The oracle asks for ${minutes} more minutes on ${task.id}: ${oneLine(reason, 400)}`, budgetLine(now.budget, now.state)].join("\n\n"),
+    [`Give ${minutes} more minutes`, OTHER_TIME, "No"],
+  );
+  const granted = choice === `Give ${minutes} more minutes` ? minutes : choice === OTHER_TIME ? parseMinutes((await deps.ask(`How many more minutes for ${task.id}?`)) ?? "") ?? 0 : 0;
+  if (granted <= 0) {
+    recordDecision(task, `The user did not give ${minutes} more minutes: ${oneLine(reason, 200)}`);
+    return "The user did not give more time. Wrap up with what is done and tell them what is left.";
+  }
+  updateBudget(deps.root, deps.configDir, task.id, (budget) => {
+    budget.granted += granted;
+  });
+  recordDecision(task, `The user gave the task ${granted} more minutes: ${oneLine(reason, 200)}`);
+  return `The user gave the task ${granted} more minutes.`;
+}
+
+/** What each delegation was given, newest last. */
+function allotmentReport(budget: TaskBudget): string {
+  const rows = budget.allotments.slice(-8).map((entry) => `- ${entry.who}: ${entry.minutes}m${entry.granted > 0 ? ` (${entry.granted} granted)` : ""} — ${entry.what}${entry.outcome ? ` · ${entry.outcome}` : entry.endedAt ? "" : " · running"}`);
+  return rows.length > 0 ? `Allotted so far:\n${rows.join("\n")}` : "Nothing allotted yet.";
+}
+
+/** Every orchestrate result ends with where the budget stands, when the task has one. */
+function budgetFooter(task: Task, deps: WorkflowDeps): string {
+  const now = budgetFor(task, deps);
+  return now ? `\n\n${budgetLine(now.budget, now.state)}` : "";
+}
+
 const HANDLERS: Record<OrchestrateAction, (task: Task, params: OrchestrateParams, deps: WorkflowDeps) => Promise<string> | string> = {
   clarify: handleClarify,
   scout: handleScout,
@@ -951,6 +1500,7 @@ const HANDLERS: Record<OrchestrateAction, (task: Task, params: OrchestrateParams
   block: handleBlock,
   resume: handleResume,
   decide: handleDecide,
+  budget: handleBudget,
   status: (task) => describeTask(task),
   cancel: handleCancel,
 };
@@ -991,11 +1541,11 @@ export async function runWorkflowAction(params: OrchestrateParams, deps: Workflo
     const message = await handler(task, params, tracked);
     const runs = recordRunLog(task, finished, deps);
     saveTask(deps.root, deps.configDir, task);
-    return { ok: true, taskId: task.id, state: task.state, message: `${message}${runsFooter(runs)}`, runs };
+    return { ok: true, taskId: task.id, state: task.state, message: `${message}${runsFooter(runs)}${budgetFooter(task, deps)}`, runs };
   } catch (error) {
     const runs = recordRunLog(task, finished, deps);
     saveTask(deps.root, deps.configDir, task);
-    return { ok: false, taskId: task.id, state: task.state, message: `Rejected: ${(error as Error).message}`, runs };
+    return { ok: false, taskId: task.id, state: task.state, message: `Rejected: ${(error as Error).message}${budgetFooter(task, deps)}`, runs };
   }
 }