@a-t-h-i/bot-lobby 0.6.38 → 0.6.40

package/src/knowledge/repo-map.ts

@@ -0,0 +1,165 @@
+/**
+ * The repository map: what an agent would otherwise spend its first turns on
+ * `find`, `grep` and `read` to learn. The repository's layout, and the files
+ * whose path, opening comment or top-level names match the step, each with
+ * what it says it is for, the names it declares, and what an earlier scout
+ * noted about it while the file is unchanged. It is read from the file index
+ * (refreshed by size and modification time) with no model, so it works with
+ * the classifier off; a large repository that is not indexed in time is left
+ * out rather than waited for.
+ */
+import type { FileHinter, FileScope, IndexedFile } from "../classifier/files.ts";
+import { indexFiles, terms } from "../classifier/files.ts";
+import { dataRoot } from "../state/project.ts";
+import { currentNotes, type FileNote } from "./file-notes.ts";
+
+export interface RepoMapOptions {
+  exclude?: readonly string[];
+  /** The map's size, header included. */
+  maxChars?: number;
+  /** Matching files listed at most. */
+  maxFiles?: number;
+  /** How long to wait for the index; the map is left out after that (the index still finishes and is cached). */
+  budgetMs?: number;
+}
+
+export const REPO_MAP_CHARS = 3500;
+export const REPO_MAP_FILES = 20;
+export const REPO_MAP_BUDGET_MS = 2500;
+/** A file needs at least this much in common with the step to be listed: a path word, or a name and an excerpt word. */
+const MIN_SCORE = 3;
+const LINE_CHARS = 240;
+const NAMES_SHOWN = 8;
+const PURPOSE_SHOWN = 90;
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** A word matches a token that is the same word, or the same stem when both are four letters or more (`classifier`, `classifiers`). */
+function matches(word: string, tokens: ReadonlySet<string>): boolean {
+  if (tokens.has(word)) return true;
+  if (word.length < 4) return false;
+  for (const token of tokens) if (token.length >= 4 && (token.startsWith(word) || word.startsWith(token))) return true;
+  return false;
+}
+
+/** How much a file has in common with the step: named outright, then words in its path, names and excerpt. */
+function scoreFile(file: IndexedFile, words: readonly string[], query: string, note?: FileNote): number {
+  const path = file.path.toLowerCase();
+  const name = path.slice(path.lastIndexOf("/") + 1);
+  const stem = name.replace(/\.[^.]+$/, "");
+  let score = 0;
+  if (query.includes(path)) score += 10;
+  else if (stem.length >= 4 && new RegExp(`(^|[^\\w-])${escapeRegExp(name)}\\b|\\b${escapeRegExp(stem)}\\.\\w+\\b`).test(query)) score += 6;
+  const pathTokens = new Set(terms(file.path));
+  const symbolTokens = new Set(terms((file.symbols ?? []).join(" ")));
+  const excerptTokens = new Set(terms(file.excerpt));
+  const noteTokens = new Set(note ? terms(note.note) : []);
+  for (const word of words) {
+    if (matches(word, pathTokens)) score += 3;
+    if (matches(word, symbolTokens)) score += 2;
+    if (matches(word, excerptTokens)) score += 1;
+    if (matches(word, noteTokens)) score += 1;
+  }
+  return score;
+}
+
+/** The files most worth listing for a step, best first: at most `max`, each sharing enough with it. */
+export function rankForMap(query: string, files: readonly IndexedFile[], max = REPO_MAP_FILES, notes: ReadonlyMap<string, FileNote> = new Map()): IndexedFile[] {
+  const words = terms(query);
+  const lowered = query.toLowerCase();
+  return files
+    .map((file, index) => ({ file, index, score: scoreFile(file, words, lowered, notes.get(file.path)), depth: file.path.split("/").length }))
+    .filter((entry) => entry.score >= MIN_SCORE)
+    .sort((a, b) => b.score - a.score || a.depth - b.depth || a.index - b.index)
+    .slice(0, max)
+    .map((entry) => entry.file);
+}
+
+/** The layout in one line: top-level folders by size, with the folders inside the large ones, then root files. */
+export function layoutLine(files: readonly IndexedFile[], max = 600): string {
+  const top = new Map<string, { count: number; inner: Map<string, number> }>();
+  const rootFiles: string[] = [];
+  for (const { path } of files) {
+    const parts = path.split("/");
+    if (parts.length === 1) {
+      rootFiles.push(path);
+      continue;
+    }
+    const dir = top.get(parts[0]!) ?? { count: 0, inner: new Map<string, number>() };
+    dir.count += 1;
+    if (parts.length > 2) dir.inner.set(parts[1]!, (dir.inner.get(parts[1]!) ?? 0) + 1);
+    top.set(parts[0]!, dir);
+  }
+  const dirs = [...top].sort((a, b) => b[1].count - a[1].count).map(([name, dir]) => {
+    const inner = [...dir.inner].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([child]) => child);
+    return dir.count >= 20 && inner.length > 1 ? `${name}/ (${dir.count}: ${inner.join(", ")})` : `${name}/ (${dir.count})`;
+  });
+  const line = [...dirs, ...rootFiles.slice(0, 6)].join(" · ");
+  return line.length > max ? `${line.slice(0, max - 1).replace(/\s*·?\s*\S*$/, "")} …` : line;
+}
+
+/** One file's map entry: path, purpose and names on one line, an unchanged file's scout note under it. */
+function fileEntry(file: IndexedFile, note?: FileNote): string {
+  const symbols = file.symbols ?? [];
+  const names = symbols.length > NAMES_SHOWN ? `${symbols.slice(0, NAMES_SHOWN).join(", ")}, …` : symbols.join(", ");
+  const purpose = file.purpose && file.purpose.length > PURPOSE_SHOWN ? `${file.purpose.slice(0, PURPOSE_SHOWN - 1).replace(/\s+\S*$/, "")}…` : file.purpose;
+  const head = [`- \`${file.path}\``, purpose ? ` — ${purpose}` : "", names ? ` · ${names}` : ""].join("");
+  const line = head.length > LINE_CHARS ? `${head.slice(0, LINE_CHARS - 1)}…` : head;
+  if (!note) return line;
+  return `${line}\n  scout (${note.domain}, ${note.at.slice(0, 10)}${note.lines ? `, lines ${note.lines}` : ""}): ${note.note}`;
+}
+
+const MAP_INTRO = "The repository's layout and the files that match this step, read from the files themselves: path — what the file says it is for · the top-level names it declares. Scout notes are what an earlier scout found in a file that has not changed since. Go straight to the file you need; search only for what the map does not answer, and verify what you rely on.";
+
+/** The map's text for ranked files, kept within `maxChars`; "" when no file matches. */
+export function renderRepoMap(layout: string, files: readonly IndexedFile[], notes: ReadonlyMap<string, FileNote>, maxChars = REPO_MAP_CHARS): string {
+  if (files.length === 0) return "";
+  const lines = ["## Repository map", "", MAP_INTRO, "", `Layout: ${layout}`, "", "Files that match this step:"];
+  let size = lines.join("\n").length;
+  let listed = 0;
+  for (const file of files) {
+    const entry = fileEntry(file, notes.get(file.path));
+    if (size + entry.length + 1 > maxChars) break;
+    lines.push(entry);
+    size += entry.length + 1;
+    listed += 1;
+  }
+  return listed > 0 ? lines.join("\n") : "";
+}
+
+/** Resolve with the value, or undefined once `ms` pass first. */
+function within<T>(promise: Promise<T>, ms: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), ms);
+  });
+  return Promise.race([promise, late]).finally(() => clearTimeout(timer));
+}
+
+/** The repository map for a step; "" when nothing matches, the index fails or it is not ready within the budget. */
+export async function repoMap(scope: FileScope, query: string, options: RepoMapOptions = {}): Promise<string> {
+  const indexing = indexFiles(scope, options.exclude ?? []);
+  indexing.catch(() => undefined);
+  const files = await within(indexing.catch(() => undefined), options.budgetMs ?? REPO_MAP_BUDGET_MS);
+  if (!files || files.length === 0) return "";
+  const max = options.maxFiles ?? REPO_MAP_FILES;
+  // Rank twice: notes only exist for some files, so read them for a wider first cut, then rank with them.
+  const wide = rankForMap(query, files, max * 2);
+  const notes = await currentNotes(dataRoot(scope.root, scope.configDir), scope.cwd, wide.map((file) => file.path));
+  return renderRepoMap(layoutLine(files), rankForMap(query, wide, max, notes), notes, options.maxChars ?? REPO_MAP_CHARS);
+}
+
+/** A hinter that also hands each step the repository map, while `on()` says so. */
+export function withRepoMap(hinter: FileHinter, scope: FileScope, settings: () => { on: boolean; exclude: readonly string[] }): FileHinter {
+  return {
+    async block(query, signal, context) {
+      const { on, exclude } = settings();
+      const map = on ? repoMap(scope, query, { exclude }).catch(() => "") : Promise.resolve("");
+      const [likely, mapped] = await Promise.all([hinter.block(query, signal, context), map]);
+      return [likely, mapped].filter(Boolean).join("\n\n");
+    },
+    tools: () => hinter.tools(),
+  };
+}

package/src/lobby/host.ts

@@ -159,6 +159,8 @@ export interface LobbyService {
   configChanged?(): void;
   /** The models Pi offers, for the settings page's picker. */
   models?(): ModelChoice[];
+  /** The classifier models pi can call with its logins, for the classifier's picker. */
+  classifierModels?(): Array<{ id: string; label: string }>;
   /** The model this window's session runs on (`provider/id`), when it has one. */
   sessionModel?(): string | undefined;
   /** The Issues tab is switched on (`lobby.issues`). */

package/src/lobby/quickfix.ts

@@ -21,7 +21,7 @@ import { fellShort, profileLabel, routeLabel, type EffortRoute, type EffortRoute
 import { existsSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 import type { LintConfig } from "../schemas/configuration.ts";
-import { repositoryTop } from "../execution/git.ts";
+import { changedFiles, commitFiles, commitMessage, MAX_COMMIT_SUBJECT, repositoryTop } from "../execution/git.ts";
 import type { LintExec } from "../execution/lint.ts";
 import { scriptsFor, type ScriptPicker } from "../scripts/pick.ts";
 import { dataRoot } from "../state/project.ts";
@@ -72,6 +72,10 @@ export interface QuickFixJob {
   routed?: boolean;
   /** An earlier run was cut off when pi stopped: some of its edits may already be in the tree. */
   interrupted?: boolean;
+  /** Files (relative to the repository) that had uncommitted changes before its first run: never its to commit. */
+  before?: string[];
+  /** The commit its changes went in, and its message's first line. */
+  commit?: { sha: string; subject: string };
 }
 
 /** How a job enters the queue besides its prompt. */
@@ -136,6 +140,24 @@ export function quickFixPrompt(instructions?: string): string {
   return custom ? `${loadPrompt("quickfix.md")}\n\n## Custom Instructions\n\n${custom}` : loadPrompt("quickfix.md");
 }
 
+/**
+ * The commit message a quick fix's report gives under `## Commit`, kept short
+ * (see `commitMessage`); the request's first line, clipped, when it gives none
+ * or one too long.
+ */
+export function quickFixCommitMessage(job: Pick<QuickFixJob, "prompt" | "report">): string {
+  const section = /^## Commit[^\n]*\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(job.report ?? "")?.[1]?.replace(/^\s*```[^\n]*\n?|```\s*$/g, "").trim();
+  if (section) {
+    try {
+      return commitMessage(section);
+    } catch {
+      // Too long or empty: the request names it instead.
+    }
+  }
+  const title = jobTitle(job).replace(/\s+/g, " ");
+  return title.length > MAX_COMMIT_SUBJECT ? `${title.slice(0, MAX_COMMIT_SUBJECT - 1).trimEnd()}…` : title;
+}
+
 /** First line of a prompt, for lists. */
 export function jobTitle(job: Pick<QuickFixJob, "prompt">): string {
   return job.prompt.split("\n").find((line) => line.trim())?.trim() ?? "(empty)";
@@ -301,6 +323,8 @@ export class QuickFixQueue {
     }
     this.deps.feed?.log(QUICK_FIX_SOURCE, `started: ${jobTitle(job)}`, "info", job.startedAt);
     this.edits.set(job.id, new EditLog(this.deps.cwd));
+    // What was uncommitted before it ran is someone else's; a run cut off and resumed keeps its first look.
+    job.before ??= (await changedFiles(this.deps.cwd))?.files ?? [];
     try {
       const [likely, route, scripts] = await Promise.all([
         this.likely(job.prompt, controller.signal),
@@ -363,6 +387,12 @@ export class QuickFixQueue {
       job.error = result.error;
       job.usage = result.usage;
       if (result.model) job.model = result.model;
+      const edited = this.edits.get(job.id)?.list() ?? [];
+      if (job.status === "success" && edited.length > 0) {
+        // Lint reads what changed since HEAD, so it goes before the commit.
+        await this.lintAfter(job, edited);
+        await this.commitAfter(job, edited);
+      }
     } catch (error) {
       job.status = "failed";
       job.error = (error as Error).message;
@@ -440,11 +470,34 @@ export class QuickFixQueue {
     this.deps.feed?.log(QUICK_FIX_SOURCE, `${outcome}: ${jobTitle(job)}`, ok ? "success" : job.status === "cancelled" ? "warning" : "error", job.finishedAt);
     appendMetrics(this.deps.root, this.deps.configDir, [quickFixMetric(job)]);
     this.deps.notify?.(`bot-lobby quick fix ${outcome}: ${jobTitle(job)}`, ok ? "info" : "warning");
-    if (ok && edited.length > 0) void this.lintAfter(job, edited);
     this.changed();
     this.pump();
   }
 
+  /**
+   * Commit what a finished quick fix edited, with the message its report
+   * gives: only its own files, never one that held uncommitted changes before
+   * it ran. A refused commit is a line in the activity log; the fix stands.
+   */
+  private async commitAfter(job: QuickFixJob, edited: readonly string[]): Promise<void> {
+    const top = await repositoryTop(this.deps.cwd);
+    if (!top) return;
+    const before = new Set(job.before ?? []);
+    const files = edited.map((file) => relative(top, file).split("\\").join("/")).filter((file) => file && !file.startsWith("..") && !isAbsolute(file) && !before.has(file));
+    const own = relative(top, dataRoot(this.deps.root, this.deps.configDir)).split("\\").join("/");
+    const ours = own && !own.startsWith("..") ? files.filter((file) => !file.startsWith(`${own}/`)) : files;
+    if (ours.length === 0) return;
+    const message = quickFixCommitMessage(job);
+    try {
+      const commit = await commitFiles(top, ours, message);
+      if (!commit) return;
+      job.commit = { sha: commit.commit, subject: message.split("\n")[0]! };
+      this.deps.feed?.log(QUICK_FIX_SOURCE, `committed ${commit.commit.slice(0, 7)}: ${job.commit.subject}`, "info");
+    } catch (error) {
+      this.deps.feed?.log(QUICK_FIX_SOURCE, `not committed: ${(error as Error).message.split("\n")[0]}`, "warning");
+    }
+  }
+
   /**
    * The lint gate's pass over what a quick fix touched (only problems on the
    * lines it changed are its own): a line in the activity log, never a hold,

package/src/lobby/service.ts

@@ -33,7 +33,7 @@ import { startPlannedTask } from "../pi/start-task.ts";
 import { pendingRequest, startRequest } from "../pi/route.ts";
 import { deliverComments, setAuto } from "../pi/owner.ts";
 import { chatFromEntries, lobbyFeed, type ChatEntry } from "./feed.ts";
-import { classifier, effortFor, hintsFor } from "../classifier/instance.ts";
+import { availableClassifiers, classifier, effortFor, hintsFor } from "../classifier/instance.ts";
 import { launchPi, SessionRegistry, type BackgroundSession, type SessionLauncher } from "./sessions.ts";
 import { SessionChats } from "./session-files.ts";
 import { answerMessage, questionnaires, settledQuestions } from "./ask.ts";
@@ -801,6 +801,7 @@ export function createLobbyService(state: Runtime): LobbyService {
         return [];
       }
     },
+    classifierModels: () => availableClassifiers().map((model) => ({ id: model.id, label: model.label })),
     issuesEnabled: () => loadConfig().lobby.issues,
     recovered: () => state.recovered,
     seatLabel: (member) => {

package/src/master/master.ts

@@ -15,6 +15,10 @@ import { parseWorkerResult, validateWorkerResult } from "../roles/worker.ts";
 import { parseReviewResult, validateReviewResult } from "../roles/reviewer.ts";
 import { truncate } from "../text.ts";
 import { isScoutResultUsable, parseScoutResult, validateScoutResult } from "../roles/scout.ts";
+import { treeState } from "../execution/git.ts";
+import { toolBudgetEnv, toolBudgetNote } from "../pi/tool-budget.ts";
+import { recordFileNotes } from "../knowledge/file-notes.ts";
+import { readCachedScout, scoutKey, writeCachedScout } from "./scout-cache.ts";
 import type { FileHinter } from "../classifier/files.ts";
 import type { KnowledgePaths, KnowledgePicker } from "../classifier/knowledge.ts";
 import { fellShort, profileLabel, routeLabel, type EffortRoute, type EffortRouter } from "../classifier/effort.ts";
@@ -24,6 +28,8 @@ export interface ScoutOutcome {
   run: AgentRun;
   issues: string[];
   usable: boolean;
+  /** When these findings were taken, if they were reused: the same question on a tree that has not changed since. */
+  reused?: string;
 }
 
 export interface ScoutRequest {
@@ -97,7 +103,7 @@ function scoutContext(request: ScoutRequest, domain: Domain, selected: Knowledge
     task: request.taskText,
     ...selected,
     instructions: request.config.agents[domain].instructions,
-    workflowContext: [`Task state: scouting. Domain: ${domain}. Read-only reconnaissance; no implementation.`, likely, request.time?.note ?? ""].filter(Boolean).join("\n\n"),
+    workflowContext: [`Task state: scouting. Domain: ${domain}. Read-only reconnaissance; no implementation.`, toolBudgetNote(request.config.scout.maxToolCalls), likely, request.time?.note ?? ""].filter(Boolean).join("\n\n"),
   };
 }
 
@@ -139,8 +145,38 @@ function toOutcome(run: AgentRun, domain: Domain): ScoutOutcome {
   return { result, run, issues: validateScoutResult(result), usable: isScoutResultUsable(result) };
 }
 
-/** Run the selected domain scouts concurrently and persist their findings. */
+/**
+ * Run the selected domain scouts concurrently and persist their findings. A
+ * domain asked the same thing before on an unchanged tree reuses its earlier
+ * findings (`workflow.reuseScouts`); every new finding's Relevant Files are
+ * kept as file notes for the repository map.
+ */
 export async function runScouts(request: ScoutRequest, run: ProcessRunner = spawnPiProcess): Promise<ScoutOutcome[]> {
+  const dataDir = request.dataRoots[0];
+  const tree = dataDir && request.config.workflow.reuseScouts ? await treeState(request.cwd, request.dataRoots) : undefined;
+  const keys = request.domains.map((domain) => scoutKey(domain, scoutInstruction(request, domain), request.taskText));
+  const cached = keys.map((key) => (dataDir && tree ? readCachedScout(dataDir, key, tree) : undefined));
+  const fresh = request.domains.filter((_domain, index) => !cached[index]);
+  const ran = fresh.length > 0 ? await scoutDomains({ ...request, domains: fresh }, run) : [];
+  let next = 0;
+  const outcomes = request.domains.map((_domain, index) => cached[index] ?? ran[next++]!);
+  saveScoutResults(request.taskDir, outcomes);
+  if (dataDir) await remember(dataDir, request, outcomes, keys, tree);
+  return outcomes;
+}
+
+/** Keep what new scouts found: their answers for reuse while the tree is as it was, their files' notes for the map. */
+async function remember(dataDir: string, request: ScoutRequest, outcomes: readonly ScoutOutcome[], keys: readonly string[], tree: string | undefined): Promise<void> {
+  const found = outcomes.map((outcome, index) => ({ outcome, key: keys[index]! })).filter(({ outcome }) => !outcome.reused && outcome.usable);
+  if (found.length === 0) return;
+  // Scouts only read: a tree that changed meanwhile was changed by someone else, and their answers may not match it.
+  if (tree && (await treeState(request.cwd, request.dataRoots)) === tree) {
+    for (const { outcome, key } of found) writeCachedScout(dataDir, key, tree, outcome);
+  }
+  await Promise.all(found.map(({ outcome }) => recordFileNotes(dataDir, request.cwd, outcome.result.domain, outcome.result.relevantFiles).catch(() => 0)));
+}
+
+async function scoutDomains(request: ScoutRequest, run: ProcessRunner): Promise<ScoutOutcome[]> {
   // Each scout gets the files most likely to answer its own instruction and focus.
   const [likely, selected] = await Promise.all([
     Promise.all(request.domains.map((domain) => likelyFor(request.hints, `${request.instruction}\n${domainSpec(domain).scoutFocus}`, request.signal, request.taskText))),
@@ -156,6 +192,7 @@ export async function runScouts(request: ScoutRequest, run: ProcessRunner = spaw
     instruction: scoutInstruction(request, domain),
     context: scoutContext(request, domain, selected[index]!, likely[index]),
     ...(extraTools.length > 0 ? { extraTools } : {}),
+    env: toolBudgetEnv(request.config.scout.maxToolCalls),
     ...profileFields(request.config, request.profile, domain, "scout"),
     ...(request.time ? { time: { ...request.time } } : {}),
     cwd: request.cwd,
@@ -177,7 +214,6 @@ export async function runScouts(request: ScoutRequest, run: ProcessRunner = spaw
       return position >= 0 ? toOutcome(reruns[position]!, reruns[position]!.domain) : outcome;
     });
   }
-  saveScoutResults(request.taskDir, outcomes);
   return outcomes;
 }
 export function scoutResultPath(taskDir: string, domain: Domain): string {

package/src/master/scout-cache.ts

@@ -0,0 +1,70 @@
+/**
+ * Scout findings kept for reuse. A scout asked the same thing (same domain,
+ * same instruction, same task) on a work tree that has not changed since it
+ * last answered gives the same answer, so the engine hands the oracle the
+ * earlier findings instead of running it again: after a crash and resume, or
+ * when the oracle repeats a question. Any change to the tree (a commit, an
+ * edit, a new file) makes every cached answer stale.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Domain } from "../schemas/agent.ts";
+import type { ScoutOutcome } from "./master.ts";
+
+interface CachedScout {
+  version: 1;
+  tree: string;
+  at: string;
+  outcome: ScoutOutcome;
+}
+
+/** Cached answers older than this are dropped when the next one is written. */
+export const SCOUT_CACHE_DAYS = 7;
+
+export function scoutCacheDir(dataDir: string): string {
+  return join(dataDir, "cache", "scouts");
+}
+
+/** The question a scout is asked, as a file name. */
+export function scoutKey(domain: Domain, instruction: string, taskText: string): string {
+  return createHash("sha256").update(JSON.stringify([domain, instruction.trim(), taskText.trim()])).digest("hex").slice(0, 32);
+}
+
+/** The earlier answer to this question on this tree, marked with when it was taken; undefined when there is none or the tree changed. */
+export function readCachedScout(dataDir: string, key: string, tree: string): ScoutOutcome | undefined {
+  try {
+    const cached = JSON.parse(readFileSync(join(scoutCacheDir(dataDir), `${key}.json`), "utf8")) as Partial<CachedScout>;
+    if (cached.version !== 1 || cached.tree !== tree || !cached.outcome?.usable || !cached.at) return undefined;
+    return { ...cached.outcome, reused: cached.at };
+  } catch {
+    return undefined;
+  }
+}
+
+function pruneScoutCache(dir: string, now: number): void {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    try {
+      if (now - statSync(path).mtimeMs > SCOUT_CACHE_DAYS * 86_400_000) rmSync(path, { force: true });
+    } catch {
+      // Gone already.
+    }
+  }
+}
+
+/** Keep a usable answer for this question on this tree; failures are ignored (the cache only saves time). */
+export function writeCachedScout(dataDir: string, key: string, tree: string, outcome: ScoutOutcome, now = new Date()): void {
+  if (!outcome.usable) return;
+  const dir = scoutCacheDir(dataDir);
+  try {
+    mkdirSync(dir, { recursive: true });
+    pruneScoutCache(dir, now.getTime());
+    const path = join(dir, `${key}.json`);
+    const { reused: _reused, ...fresh } = outcome;
+    writeFileSync(`${path}.tmp`, JSON.stringify({ version: 1, tree, at: now.toISOString(), outcome: fresh } satisfies CachedScout));
+    renameSync(`${path}.tmp`, path);
+  } catch {
+    // Without the cache the scout just runs next time.
+  }
+}

package/src/master/synthesis.ts

@@ -1,4 +1,5 @@
 import type { Domain } from "../schemas/agent.ts";
+import type { RelevantFile } from "../schemas/findings.ts";
 import { truncate } from "../text.ts";
 import type { ScoutOutcome } from "./master.ts";
 
@@ -34,16 +35,23 @@ export function detectSharedFiles(outcomes: ScoutOutcome[]): { path: string; dom
     .map(([path, domains]) => ({ path, domains: [...domains] }));
 }
 
+/** A relevant file as `path:lines — why`, the way a brief should point at it. */
+export function fileAnchor(file: RelevantFile, reasonChars = 140): string {
+  const anchor = file.lines ? `${file.path}:${file.lines}` : file.path;
+  return file.reason ? `${anchor} — ${truncate(file.reason, reasonChars)}` : anchor;
+}
+
 function describeOutcome(outcome: ScoutOutcome, rawLimit: number): string {
   const { result } = outcome;
+  const reused = outcome.reused ? `, reused from ${outcome.reused.slice(0, 16).replace("T", " ")} UTC: same question, tree unchanged` : "";
   const lines = [
-    `### ${result.domain} (${outcome.run.status}${outcome.usable ? "" : ", unusable"}) — confidence: ${result.confidence}`,
+    `### ${result.domain} (${outcome.run.status}${outcome.usable ? "" : ", unusable"}${reused}) — confidence: ${result.confidence}`,
     result.scope ? `Scope: ${result.scope}` : "",
     ...result.findings.slice(0, 12).map((finding) => `- ${finding}`),
     ...result.risks.slice(0, 5).map((risk) => `- RISK: ${risk}`),
     ...result.recommendations.slice(0, 5).map((rec) => `- REC: ${rec}`),
     result.relevantFiles.length > 0
-      ? `Files: ${result.relevantFiles.slice(0, 10).map((file) => file.path).join(", ")}`
+      ? `Files:\n${result.relevantFiles.slice(0, 10).map((file) => `- ${fileAnchor(file)}`).join("\n")}`
       : "",
     outcome.issues.length > 0 ? `Issues: ${outcome.issues.join("; ")}` : "",
     result.raw.trim() ? `Raw (truncated): ${truncate(result.raw.trim(), rawLimit)}` : "",

package/src/pi/model-settings.ts

@@ -47,7 +47,7 @@ interface EntryPatch {
 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;
-  else if (kind === "scout") next.scout = { model: patch.model ?? config.scout.model, timeoutMs: patch.timeoutMs ?? config.scout.timeoutMs };
+  else if (kind === "scout") next.scout = { ...config.scout, 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;
@@ -83,10 +83,12 @@ export function prefillModels(config: BotLobbyConfig, sessionModel: string | und
   return { config: next, filled };
 }
 
-/** `on · OpenCode Zen · jev-1.13-free · key stored in pi`, for the settings menu and `/bot-lobby config`. */
+/** `on · OpenCode Zen · jev-1.13-free · key stored in pi` (or `on · openai/gpt-5-nano · your pi login`), for the settings menu and `/bot-lobby config`. */
 export function classifierSummary(config: BotLobbyConfig, status: StatusSource | undefined): string {
+  const state = config.classifier.enabled ? "on" : "off";
+  if (config.classifier.engine) return [state, config.classifier.engine, "your pi login"].join(" · ");
   const { host, model } = jevEndpoint(config.classifier, status);
   const via = config.classifier.provider === "auto" ? `${host.label} (auto)` : host.label;
-  return [config.classifier.enabled ? "on" : "off", via, model, `key ${describeKey(host, status)}`].join(" · ");
+  return [state, via, model, `key ${describeKey(host, status)}`].join(" · ");
 }
 

package/src/pi/plan-checklist.ts

@@ -438,7 +438,8 @@ export function stepWork(steps: readonly string[], runs: readonly AgentRun[], no
     const ms = Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, end - start) : 0;
     for (const index of covered) {
       if (!run.parentRunId) work[index]!.ms += ms;
-      if (run.status === "running") {
+      // A run that has finished is off the step, whatever its last status said.
+      if (run.status === "running" && !run.finishedAt) {
         work[index]!.active = true;
         work[index]!.activeAgentCount += 1;
         work[index]!.runIds.push(run.runId);

package/src/pi/tool-budget.ts

@@ -0,0 +1,66 @@
+/**
+ * A hard limit on a subagent's tool calls, enforced inside its own process so
+ * it holds on every provider and model. The engine sets the budget through
+ * `BOT_LOBBY_TOOL_BUDGET` (scouts get `scout.maxToolCalls`). At 60% the next
+ * tool result tells the agent to wrap up; past the limit every call is
+ * refused with the reason, so the agent writes its report with what it has.
+ * An agent that keeps calling anyway is stopped after a few refusals.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export const TOOL_BUDGET_ENV = "BOT_LOBBY_TOOL_BUDGET";
+
+export interface ToolBudget {
+  /** The call after which the agent is told to wrap up. */
+  warnAt: number;
+  /** Calls past this are refused. */
+  max: number;
+}
+
+/** Refusals in a row after which the run is stopped rather than refused again. */
+export const MAX_REFUSALS = 5;
+
+/** The env that gives a subagent `max` tool calls; none for 0 (no limit). */
+export function toolBudgetEnv(max: number): Record<string, string> {
+  return max > 0 ? { [TOOL_BUDGET_ENV]: String(Math.round(max)) } : {};
+}
+
+export function parseToolBudget(value: string | undefined): ToolBudget | undefined {
+  const max = Number(value);
+  if (!value || !Number.isFinite(max) || max < 1) return undefined;
+  return { warnAt: Math.max(1, Math.round(max * 0.6)), max: Math.round(max) };
+}
+
+/** What the agent is told up front, in its workflow context. */
+export function toolBudgetNote(max: number): string {
+  const budget = parseToolBudget(String(max));
+  return budget ? `Tool budget: at most ${budget.max} tool calls. After ${budget.warnAt} you are told to wrap up; past ${budget.max} every call is refused and you report with what you have.` : "";
+}
+
+export function budgetWarning(used: number, budget: ToolBudget): string {
+  return `bot-lobby: ${used} of your ${budget.max} tool calls are used. Stop exploring: check only what your answer still needs, then write your report.`;
+}
+
+export function budgetRefusal(budget: ToolBudget): string {
+  return `bot-lobby: your ${budget.max} tool calls are spent, so this call was not run. Write your report now in the required format with what you have, and mark what you did not verify as an assumption.`;
+}
+
+/** Count the agent's own tool calls (not those a tool made for it), warn once, then refuse. */
+export function registerToolBudget(pi: ExtensionAPI, budget = parseToolBudget(process.env[TOOL_BUDGET_ENV])): void {
+  if (!budget) return;
+  let used = 0;
+  let refused = 0;
+  let warned = false;
+  pi.on("tool_call", (event) => {
+    if (event.parentToolCallId) return undefined;
+    used += 1;
+    if (used <= budget.max) return undefined;
+    refused += 1;
+    return { block: true, reason: budgetRefusal(budget), ...(refused >= MAX_REFUSALS ? { terminate: true } : {}) };
+  });
+  pi.on("tool_result", (event) => {
+    if (event.parentToolCallId || warned || used < budget.warnAt || used > budget.max) return undefined;
+    warned = true;
+    return { content: [...event.content, { type: "text" as const, text: budgetWarning(used, budget) }] };
+  });
+}

package/src/pi/tools.ts

@@ -60,6 +60,7 @@ const OrchestrateSchema = Type.Object({
   ),
   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/script: the decision, completion summary, knowledge text, or the script itself" })),
+  message: Type.Optional(Type.String({ description: "complete: the commit message for the agents' changes, which the engine commits (only their files): a first line of 72 characters or fewer saying what changed, at most three short lines below it" })),
   file: Type.Optional(Type.String({ description: "compact: the knowledge file to rewrite, e.g. knowledge.md; script: a script a worker drafted, to save instead of text" })),
   name: Type.Optional(Type.String({ description: "whiteboard: name for the new Excalidraw session; script: the file name, what it does in snake_case with its language's extension (seed_public_holidays.py, run_changed_tests.sh)" })),
   purpose: Type.Optional(Type.String({ description: "script: one line on what the script does" })),

package/src/roles/markdown.ts

@@ -56,9 +56,17 @@ export function bullets(text: string | undefined): string[] {
     .filter((line) => line.length > 0);
 }
 
-/** Parse a `path — reason` bullet into its parts. */
-export function parseFileBullet(text: string): { path: string; reason: string } {
+/** Split a `path:12-40` (or `path#L12-L40`) anchor into the path and its lines. */
+function splitAnchor(anchor: string): { path: string; lines?: string } {
+  const match = /^(.+?)(?::|#L)(\d+)(?::\d+)?(?:\s*[-–]\s*L?(\d+)(?::\d+)?)?$/.exec(anchor);
+  if (!match) return { path: anchor };
+  return { path: match[1]!, lines: match[3] && match[3] !== match[2] ? `${match[2]}-${match[3]}` : match[2]! };
+}
+
+/** Parse a `path — reason` bullet (the path may carry lines: `path:12-40`) into its parts. */
+export function parseFileBullet(text: string): { path: string; lines?: string; reason: string } {
   const match = /^`?([^`\s]+)`?\s*(?:[—–]|--|-)\s*(.*)$/.exec(text);
-  if (match) return { path: match[1]!, reason: match[2]!.trim() };
-  return { path: text.trim(), reason: "" };
+  const [anchor, reason] = match ? [match[1]!, match[2]!.trim()] : [text.trim().replace(/^`|`$/g, ""), ""];
+  const { path, lines } = splitAnchor(anchor);
+  return lines ? { path, lines, reason } : { path, reason };
 }

package/src/roles/scout.ts

@@ -12,7 +12,8 @@ export const scoutSpec: RoleSpec = {
     "Respond with exactly these sections and nothing else:",
     "`## Scope`, `## Findings`, `## Relevant Files`, `## Existing Patterns`,",
     "`## Risks`, `## Recommendations`, `## Confidence`.",
-    "Use `- ` bullets. `## Relevant Files` entries are `- \\`path\\` — reason`.",
+    "Use `- ` bullets. `## Relevant Files` entries are `- \\`path:start-end\\` — reason`, with the lines of the code that matters",
+    "(`path:42` for one line, the bare `path` only when the whole file does), so the worker opens the exact place.",
     "`## Confidence` is exactly one of `High`, `Medium`, `Low`.",
     "Keep the whole response under 400 words. Report uncertainty; do not implement.",
     "An optional `## Pushback` (`**Request:**`, `**Reason:**`, optional `**Alternative:**`) flags a change you",