@a-t-h-i/bot-lobby 0.6.39 → 0.6.41

package/src/classifier/instance.ts

@@ -13,11 +13,13 @@ import { scriptPicker } from "./scripts.ts";
 import type { ScriptPicker } from "../scripts/pick.ts";
 import { registerJevProvider, type KeySource, type KeyStatus } from "./hosts.ts";
 import { fileHinter, type FileHinter, type FileScope } from "./files.ts";
+import { withRepoMap } from "../knowledge/repo-map.ts";
 import { knowledgePicker, type KnowledgePicker } from "./knowledge.ts";
 import { lobbyFeed } from "../lobby/feed.ts";
 import { triageLine, triageWithContext } from "./triage.ts";
 import type { TaskTriage } from "../schemas/task.ts";
 import { effortRouter, type EffortRouter } from "./effort.ts";
+import { engineAnswer, engineClassifiers, type EngineAnswer, type EngineModel, type Registry } from "./models.ts";
 
 interface Binding {
   cwd: string;
@@ -25,6 +27,8 @@ interface Binding {
   configDir: string;
   keys: KeySource;
   status: (piProvider: string) => KeyStatus | undefined;
+  engine: EngineAnswer;
+  registry: Registry;
   notify?: (message: string, level: "info" | "warning" | "error") => void;
 }
 
@@ -35,6 +39,10 @@ export function classifier(): Classifier {
   instance ??= new Classifier({
     config: () => loadConfig().classifier,
     keys: async (piProvider) => binding?.keys(piProvider),
+    engine: (ref, request, options) => {
+      if (!binding) throw new Error(`${ref} is not reachable before a pi session starts`);
+      return binding.engine(ref, request, options);
+    },
     metrics: (record) => {
       if (binding) appendMetrics(binding.root, binding.configDir, [record]);
     },
@@ -43,9 +51,13 @@ export function classifier(): Classifier {
   return instance;
 }
 
-/** Likely files for agents working in a tree, with what was found logged to the lobby's activity feed. */
+/**
+ * Likely files for agents working in a tree, with what was found logged to the
+ * lobby's activity feed, and the repository map while `workflow.repoMap` is on.
+ */
 export function hintsFor(scope: FileScope): FileHinter {
-  return fileHinter(classifier(), scope, (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
+  const hinter = fileHinter(classifier(), scope, (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
+  return withRepoMap(hinter, scope, () => ({ on: loadConfig().workflow.repoMap, exclude: classifier().config.exclude }));
 }
 
 /** Relevant knowledge and shared scripts for agents, with what Jev kept and matched logged to the lobby's activity feed. */
@@ -84,6 +96,24 @@ export function keyStatus(piProvider: string): KeyStatus | undefined {
   return binding?.status(piProvider);
 }
 
+let classifierModels: EngineModel[] = [];
+
+/** Refresh the list of classifier models pi can call with its logins (it is read from the network). */
+async function refreshClassifierModels(): Promise<void> {
+  if (!binding) return;
+  try {
+    classifierModels = await engineClassifiers(binding.registry);
+  } catch {
+    // Keep the last list: the picker still offers chat models and custom ids.
+  }
+}
+
+/** The classifier models pi can call with the logins it holds (Jev on each host, clef, d1, …); refreshed as it is read. */
+export function availableClassifiers(): EngineModel[] {
+  void refreshClassifierModels();
+  return classifierModels;
+}
+
 /** Register the `typesafe` login entry and bind the classifier to each session's key store. */
 export function registerClassifier(pi: ExtensionAPI, configDir: string): void {
   registerJevProvider(pi);
@@ -93,6 +123,8 @@ export function registerClassifier(pi: ExtensionAPI, configDir: string): void {
       root: detectProjectRoot(ctx.cwd, configDir),
       configDir,
       keys: (piProvider) => ctx.modelRegistry.getApiKeyForProvider(piProvider),
+      registry: ctx.modelRegistry,
+      engine: engineAnswer(ctx.modelRegistry),
       status: (piProvider) => {
         try {
           return ctx.modelRegistry.getProviderAuthStatus(piProvider);
@@ -103,5 +135,6 @@ export function registerClassifier(pi: ExtensionAPI, configDir: string): void {
       // Subagents have nobody to tell; their runs still land in the metrics.
       ...(ctx.hasUI && !isSubagentProcess() ? { notify: (message: string, level: "info" | "warning" | "error") => ctx.ui.notify(message, level) } : {}),
     };
+    if (!isSubagentProcess()) void refreshClassifierModels();
   });
 }

package/src/classifier/models.ts

@@ -0,0 +1,115 @@
+/**
+ * The classifier's model when it is not Jev on a host: whatever
+ * `classifier.engine` names (`provider/id`), looked up in pi's own model
+ * registry, so it is called with the logins pi already holds (an OpenAI or
+ * Anthropic account, an API key, OpenRouter, …). A classifier model (Jev,
+ * Cloudflare's clef, Liquid's d1, Upstage's solar-decide, …) answers through
+ * pi's `classify`; a chat model answers the same questions as JSON (see
+ * `chat.ts`).
+ */
+import { clampThinkingLevel, type Api, type ClassifierApi, type ClassifierContext, type ClassifierModel, type Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Answer, SystemOneRequest, SystemOneResponse } from "./client.ts";
+import { chatClassify } from "./chat.ts";
+
+export type Registry = Pick<ExtensionContext["modelRegistry"], "find" | "findOfType" | "classify" | "streamSimple" | "getAvailableOfType">;
+
+/** One model the classifier can use, as the settings picker lists it. */
+export interface EngineModel {
+  id: string;
+  label: string;
+  kind: "classifier" | "chat";
+}
+
+export interface AnswerOptions {
+  signal?: AbortSignal;
+  timeoutMs: number;
+  /** A chat model gets at least this long: it writes its answers, a classifier model only scores them. */
+  chatTimeoutMs: number;
+}
+
+/** Answers a request with the model `ref` names; throws when pi has no such model or the call fails. */
+export type EngineAnswer = (ref: string, request: SystemOneRequest, options: AnswerOptions) => Promise<SystemOneResponse>;
+
+/** `provider/id` split at the first slash (ids may hold more: `openrouter/liquid/d1`). */
+export function splitRef(ref: string): { provider: string; id: string } | undefined {
+  const slash = ref.indexOf("/");
+  if (slash <= 0 || slash === ref.length - 1) return undefined;
+  return { provider: ref.slice(0, slash), id: ref.slice(slash + 1) };
+}
+
+/** pi's `bool` answers are Jev's `noul`; the rest carry over as they are. */
+function fromPi(answers: Record<string, unknown>): Record<string, Answer> {
+  const out: Record<string, Answer> = {};
+  for (const [key, answer] of Object.entries(answers)) {
+    const value = answer as { type?: string; probability?: number };
+    out[key] = value.type === "bool" ? { type: "noul", noul: value.probability ?? 0 } : (answer as Answer);
+  }
+  return out;
+}
+
+/** Jev's request as pi's classifier context: `noul` questions are `bool` there, everything else is sent as it is. */
+function toPi(request: SystemOneRequest): ClassifierContext {
+  return {
+    state: request.state,
+    questions: Object.fromEntries(Object.entries(request.questions).map(([key, question]) => [key, question.type === "noul" ? { ...question, type: "bool" } : question])),
+  } as unknown as ClassifierContext;
+}
+
+async function classifyWith(registry: Registry, model: ClassifierModel<ClassifierApi>, request: SystemOneRequest, options: AnswerOptions): Promise<SystemOneResponse> {
+  const result = await registry.classify(model, toPi(request), { timeoutMs: options.timeoutMs, ...(options.signal ? { signal: options.signal } : {}) });
+  if (result.stopReason !== "stop") throw new Error(result.errorMessage || (result.stopReason === "aborted" ? "cancelled" : "the classifier failed"));
+  return {
+    model: `${model.provider}/${result.model || model.id}`,
+    answers: fromPi(result.answers as Record<string, unknown>),
+    ...(result.usage ? { usage: { input_tokens: result.usage.input, output_tokens: result.usage.output } } : {}),
+  };
+}
+
+/** The least thinking a model allows: none when it can switch it off. */
+function leastThinking(model: Model<Api>): "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined {
+  if (!model.reasoning) return undefined;
+  const level = clampThinkingLevel(model, "off");
+  return level === "off" ? undefined : level;
+}
+
+async function chatWith(registry: Registry, model: Model<Api>, request: SystemOneRequest, options: AnswerOptions): Promise<SystemOneResponse> {
+  const reasoning = leastThinking(model);
+  const timeoutMs = Math.max(options.timeoutMs, options.chatTimeoutMs);
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => controller.abort(new Error(`timed out after ${timeoutMs} ms`)), timeoutMs);
+  try {
+    return await chatClassify(request, async ({ system, user, maxTokens }) => {
+      const stream = registry.streamSimple(model, { systemPrompt: system, messages: [{ role: "user", content: user, timestamp: Date.now() }] }, { maxTokens, signal: controller.signal, ...(reasoning ? { reasoning } : {}) });
+      const aborted = new Promise<never>((_, reject) => controller.signal.addEventListener("abort", () => reject(controller.signal.reason), { once: true }));
+      const reply = await Promise.race([stream.result(), aborted]);
+      if (reply.stopReason === "error" || reply.stopReason === "aborted") throw new Error(reply.errorMessage || `the model stopped (${reply.stopReason})`);
+      const text = reply.content.filter((part) => part.type === "text").map((part) => part.text).join("");
+      return { text, model: `${model.provider}/${model.id}`, usage: { input_tokens: reply.usage.input, output_tokens: reply.usage.output } };
+    }, Boolean(reasoning));
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+/** Answers with pi's registry: a classifier model natively, else a chat model through a JSON prompt. */
+export function engineAnswer(registry: Registry): EngineAnswer {
+  return async (ref, request, options) => {
+    const parts = splitRef(ref);
+    if (!parts) throw new Error(`"${ref}" is not a provider/model reference`);
+    const classifierModel = registry.findOfType("classifier", parts.provider, parts.id);
+    if (classifierModel) return classifyWith(registry, classifierModel, request, options);
+    const chatModel = registry.find(parts.provider, parts.id);
+    if (chatModel) return chatWith(registry, chatModel, request, options);
+    throw new Error(`pi has no model ${ref}: pick one you are signed in to in Settings → Classifier`);
+  };
+}
+
+/** The classifier models pi can call with the logins it holds, as the settings picker lists them. */
+export async function engineClassifiers(registry: Registry): Promise<EngineModel[]> {
+  const models = await registry.getAvailableOfType("classifier");
+  return models.map((model) => ({ id: `${model.provider}/${model.id}`, label: model.name && model.name !== model.id ? model.name : `${model.provider}/${model.id}`, kind: "classifier" as const }));
+}

package/src/execution/git.ts

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
-import { readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
 import { promisify } from "node:util";
 import { truncate } from "../text.ts";
 
@@ -31,6 +32,48 @@ export async function headCommit(cwd: string): Promise<string | undefined> {
   }
 }
 
+/** A path with its links resolved (git reports real paths), or as it is when it does not exist. */
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/** Changed files stat'ed at most for a tree's state; past this the status text alone stands for them. */
+const MAX_STATED = 2000;
+
+/**
+ * A fingerprint of the work tree: HEAD, and each changed or untracked file's
+ * status, size and modification time, leaving out paths under `ignore`
+ * (bot-lobby's own data). Two equal fingerprints mean nothing in the tree
+ * changed in between; undefined outside git.
+ */
+export async function treeState(cwd: string, ignore: readonly string[] = []): Promise<string | undefined> {
+  try {
+    const top = await git(cwd, ["rev-parse", "--show-toplevel"]);
+    const head = (await headCommit(top)) ?? "";
+    const { stdout } = await run("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: top, maxBuffer: MAX_BUFFER });
+    const skipped = ignore.map((dir) => relative(top, realPath(dir))).filter((dir) => dir && !dir.startsWith("..")).map((dir) => `${dir.split("\\").join("/")}/`);
+    const entries = stdout.split("\0").filter((entry) => entry.length > 3 && !skipped.some((dir) => entry.slice(3).startsWith(dir)));
+    const hash = createHash("sha1").update(head);
+    entries.forEach((entry, index) => {
+      hash.update(`\0${entry}`);
+      if (index >= MAX_STATED) return;
+      try {
+        const info = statSync(join(top, entry.slice(3)));
+        hash.update(`\0${info.size}:${info.mtimeMs}`);
+      } catch {
+        hash.update("\0gone");
+      }
+    });
+    return hash.digest("hex");
+  } catch {
+    return undefined;
+  }
+}
+
 /** The repository's top folder, or undefined (no git, not a repository). */
 export async function repositoryTop(cwd: string): Promise<string | undefined> {
   try {

package/src/index.ts

@@ -20,6 +20,7 @@ import { registerFreshContext } from "./pi/fresh-context.ts";
 import { registerAskTool } from "./ask/tool.ts";
 import { registerWebTools } from "./web/tools.ts";
 import { registerExcalidrawTools } from "./excalidraw/tools.ts";
+import { registerToolBudget } from "./pi/tool-budget.ts";
 
 export default function (pi: ExtensionAPI): void {
   registerAgentPermissions(pi);
@@ -54,4 +55,6 @@ export default function (pi: ExtensionAPI): void {
   if (isSubagentProcess()) registerDeskClient(pi);
   // Subagents look files up with the classifier (the engine allows the tool only while file hints are on).
   if (isSubagentProcess()) registerClassifierTools(pi);
+  // A subagent given a tool budget (scouts) is warned, then refused, so it reports instead of searching on.
+  if (isSubagentProcess()) registerToolBudget(pi);
 }

package/src/knowledge/file-notes.ts

@@ -0,0 +1,104 @@
+/**
+ * What scouts learned about files, kept across tasks. Each scout's Relevant
+ * Files (`path:lines — why it matters`) are recorded with a hash of the
+ * file's content, and the repository map shows a note again only while the
+ * file is unchanged, so a later agent starts from what an earlier one found
+ * instead of searching for it again. A changed file's note is never shown:
+ * it may no longer be true.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import type { Domain } from "../schemas/agent.ts";
+import type { RelevantFile } from "../schemas/findings.ts";
+
+export interface FileNote {
+  note: string;
+  /** The lines it is about (`12-40`), when the scout gave them. */
+  lines?: string;
+  /** sha1 of the file's content when the note was taken. */
+  hash: string;
+  domain: Domain;
+  at: string;
+}
+
+interface NotesFile {
+  version: 1;
+  files: Record<string, FileNote>;
+}
+
+/** Most notes kept; the oldest go first. */
+export const MAX_NOTES = 2000;
+const MAX_NOTE_CHARS = 240;
+/** Files larger than this are not hashed (the index skips them too). */
+const MAX_HASHED_BYTES = 256 * 1024;
+
+export function fileNotesPath(dataDir: string): string {
+  return join(dataDir, "cache", "file-notes.json");
+}
+
+export function readFileNotes(dataDir: string): Record<string, FileNote> {
+  try {
+    const parsed = JSON.parse(readFileSync(fileNotesPath(dataDir), "utf8")) as Partial<NotesFile>;
+    return parsed.version === 1 && parsed.files && typeof parsed.files === "object" ? parsed.files : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeFileNotes(dataDir: string, files: Record<string, FileNote>): void {
+  const path = fileNotesPath(dataDir);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(`${path}.tmp`, JSON.stringify({ version: 1, files } satisfies NotesFile));
+    renameSync(`${path}.tmp`, path);
+  } catch {
+    // Notes are an optimisation; without them agents search as before.
+  }
+}
+
+/** A file's content hash, or undefined when it is missing, not a file or too large. */
+export async function contentHash(cwd: string, path: string): Promise<string | undefined> {
+  try {
+    const full = join(cwd, path);
+    const info = await stat(full);
+    if (!info.isFile() || info.size > MAX_HASHED_BYTES) return undefined;
+    return createHash("sha1").update(await readFile(full)).digest("hex");
+  } catch {
+    return undefined;
+  }
+}
+
+/** A reported path relative to the tree (`./a.ts`, `/abs/tree/a.ts` → `a.ts`); undefined outside it. */
+export function treePath(cwd: string, path: string): string | undefined {
+  const plain = path.trim().replace(/^\.\//, "");
+  if (!plain) return undefined;
+  const rel = isAbsolute(plain) ? relative(cwd, plain) : plain;
+  return !rel || rel.startsWith("..") || isAbsolute(rel) ? undefined : rel.split("\\").join("/");
+}
+
+/** Record a scout's Relevant Files as notes, each with its file's current hash; files that are not there are skipped. */
+export async function recordFileNotes(dataDir: string, cwd: string, domain: Domain, files: readonly RelevantFile[], now = new Date()): Promise<number> {
+  const entries = await Promise.all(files.filter((file) => file.reason.trim()).map(async (file): Promise<[string, FileNote] | undefined> => {
+    const path = treePath(cwd, file.path);
+    const hash = path ? await contentHash(cwd, path) : undefined;
+    if (!path || !hash) return undefined;
+    const note = file.reason.trim().replace(/\s+/g, " ").slice(0, MAX_NOTE_CHARS);
+    return [path, { note, ...(file.lines ? { lines: file.lines } : {}), hash, domain, at: now.toISOString() }];
+  }));
+  const fresh = entries.filter((entry): entry is [string, FileNote] => entry !== undefined);
+  if (fresh.length === 0) return 0;
+  const notes = { ...readFileNotes(dataDir), ...Object.fromEntries(fresh) };
+  const kept = Object.entries(notes).sort((a, b) => b[1].at.localeCompare(a[1].at)).slice(0, MAX_NOTES);
+  writeFileNotes(dataDir, Object.fromEntries(kept));
+  return fresh.length;
+}
+
+/** The notes for `paths` whose file is unchanged since the note was taken. */
+export async function currentNotes(dataDir: string, cwd: string, paths: readonly string[]): Promise<Map<string, FileNote>> {
+  const notes = readFileNotes(dataDir);
+  const wanted = paths.filter((path) => notes[path]);
+  const hashes = await Promise.all(wanted.map((path) => contentHash(cwd, path)));
+  return new Map(wanted.filter((path, index) => hashes[index] === notes[path]!.hash).map((path) => [path, notes[path]!]));
+}

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/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 {