toolroll 0.9.82 → 0.9.84

package/dist/browser-crew.js

@@ -1,4 +1,5 @@
 import { chatControlHref, chatResultHref } from './chat-controls.js';
+import { startBuilderHref } from './needs-you.js';
 /** The index is navigation only. Controls retain their exact owning task, run,
  * decision and approval ceremony; opening a result keeps its saved execution. */
 export function browserWorkActionHref(item) {
@@ -25,13 +26,16 @@ export function browserWorkActionHref(item) {
     }
     if (runId !== null && (action.code === 'inspect-run' || action.code === 'reconcile-run'))
         return `/r/${runId}`;
+    // The task page only repeats that no builder is connected: lead to the command that connects one.
+    if (action.code === 'start-worker')
+        return startBuilderHref(taskId);
     const anchor = action.code === 'approve-scope' ? '#approve'
         : action.code === 'inspect-stop' || action.code === 'resume-run' ? '#task-control'
             // Retry (and Build again) is the task's status card itself, at the top: no anchor to its options.
             : action.code === 'unhold' ? '#task-actions'
                 : action.code === 'write-scope' || action.code === 'select-agent' ? '#scope'
                     : action.code === 'inspect-hold' ? '#holds'
-                        : action.code === 'start-worker' || action.code === 'repair-dependency' ? '#run-status' : '';
+                        : action.code === 'repair-dependency' ? '#run-status' : '';
     return `/t/${encodeURIComponent(item.rootId)}?version=${encodeURIComponent(taskId)}` + anchor;
 }
 /** Render an already-admitted page without repeating its database query. Every task reads its one headline, the

package/dist/browser-workspace.d.ts

@@ -1464,6 +1464,13 @@ export type BrowserWorkspace = {
     sensitive: boolean;
     /** Passwordless is on for this signed-in browser: ceremony password fields are left out (docs/plans/passwordless.md). */
     passwordless?: boolean;
+    /** The session's open project (its path), or null: the sidebar's project picker names it. */
+    openProject?: string | null;
+    /** The settings frame's breadcrumb ("Settings / <page>"; settings-kit.ts): the header shows it as links. */
+    crumbs?: {
+        label: string;
+        href: string | null;
+    }[];
     /** What this person named their lead (Settings → Lead): the chat header and every lead message say it. */
     leadName?: string;
     refreshUrl: string;

package/dist/contracts/console-api.d.ts

@@ -106,7 +106,8 @@ export declare const CONSOLE_FORMS: {
     readonly toolsConnect: FormContract<"access" | "also" | "kit" | "password" | "repo" | "service" | "shown" | "template">;
     readonly toolsChange: FormContract<"action" | "catalog" | "import" | "name" | "password" | "repo" | "secret" | "secrets" | "shown" | "target" | "transport" | "value">;
     readonly appearance: FormContract<"accent" | "quiet" | "return" | "theme">;
-    readonly models: FormContract<"agent" | "enabled" | "phase" | "tool">;
+    readonly models: FormContract<"enabled" | "tool">;
+    readonly modelsChange: FormContract<"build" | "build-light" | "build-strong" | "change" | "digest" | "password" | "plan" | "plan-strong" | "preset" | "repair" | "review" | "review-strong" | "scope" | "switch" | "to">;
     readonly knowledgeRefresh: FormContract<"repo">;
     readonly knowledgeProposal: FormContract<"decision" | "proposal" | "repo">;
     readonly knowledgeDecision: FormContract<"action" | "claim" | "decision" | "reason" | "repo" | "why">;

package/dist/contracts/console-api.js

@@ -115,7 +115,11 @@ export const CONSOLE_FORMS = {
     toolsConnect: formContract("POST /settings/tools/connect", ["repo", "also", "service", "template", "kit", "shown", "password", "access"]),
     toolsChange: formContract("POST /settings/tools/change", ["repo", "shown", "action", "name", "password", "catalog", "transport", "target", "secrets", "import", "secret", "value"]),
     appearance: formContract("POST /settings/appearance", ["accent", "quiet", "return", "theme"]),
-    models: formContract("POST /settings/models/check, /settings/models/watch, /settings/models/update, /settings/models/agent", ["enabled", "tool", "phase", "agent"]),
+    models: formContract("POST /settings/models/check, /settings/models/watch, /settings/models/update", ["enabled", "tool"]),
+    // The one Models editor (docs/plans/spend-dashboard.md slice 3): every role at a scope in one save, or a previewed
+    // preset or switch; the digest is what the page showed, and the change digest what the preview showed.
+    modelsChange: formContract("POST /settings/models/agent, /settings/models/apply", ["password", "scope", "digest", "change", "preset", "switch", "to",
+        "plan", "plan-strong", "build-light", "build", "build-strong", "repair", "review", "review-strong"]),
     knowledgeRefresh: formContract("POST /settings/knowledge/refresh", ["repo"]),
     knowledgeProposal: formContract("POST /settings/knowledge/proposal", ["repo", "decision", "proposal"]),
     knowledgeDecision: formContract("POST /settings/knowledge/decision", ["repo", "action", "claim", "why", "decision", "reason"]),

package/dist/control-setup.d.ts

@@ -13,6 +13,7 @@ export declare function previewSetup(store: Store, repo: string, inputs: SetupIn
     seconds?: never;
     provider?: never;
     model?: never;
+    models?: never;
 } | {
     message?: never;
     ok: true;
@@ -21,6 +22,13 @@ export declare function previewSetup(store: Store, repo: string, inputs: SetupIn
     seconds: number;
     provider: "claude" | "cline" | "codex" | "cursor" | "gemini" | "goose" | "opencode" | "openrouter" | "qwen";
     model: string;
+    models: {
+        rows: (import("./model-choices.js").DiffRow & {
+            inherited: import("./model-choices.js").Pair | null;
+        })[];
+        state: string;
+        change: string;
+    } | null;
 };
 export declare function approveSetup(store: Store, repo: string, inputs: SetupInputs, fingerprint: string, by: string, token: string, now: Date): {
     ok: false;
@@ -30,6 +38,7 @@ export declare function approveSetup(store: Store, repo: string, inputs: SetupIn
     seconds?: never;
     provider?: never;
     model?: never;
+    models?: never;
 } | {
     ok: true;
 };

package/dist/control-setup.js

@@ -2,6 +2,8 @@ import { createHash } from "node:crypto";
 import { hasDisguisedText } from "./decision.js";
 import { authenticateApprover } from "./scope.js";
 import { isProviderId, validateSpec } from "./provider.js";
+import { INSTALLATION_SCOPE } from "./agentconfig.js";
+import { ALL_SLOTS, applyModelChoices, DEFAULT_PRESET, presetChange, previewModelChange, rowAt } from "./model-choices.js";
 export function previewSetup(store, repo, inputs) {
     if (!isProviderId(inputs.provider))
         return { ok: false, message: "Choose an installed provider." };
@@ -18,19 +20,36 @@ export function previewSetup(store, repo, inputs) {
     const seconds = Number(inputs.seconds);
     if (!/^[1-9][0-9]*$/.test(inputs.seconds) || !Number.isInteger(seconds) || seconds < 1 || seconds > 3600)
         return { ok: false, message: "Setup timeout must be 1–3600 seconds." };
-    const fingerprint = createHash("sha256").update(JSON.stringify({ repo, inputs, beforeSetup: store.liveWorktreeSetup(repo), beforeConfig: store.phaseConfig(repo, "build") })).digest("hex");
-    return { ok: true, fingerprint, command, seconds, provider: inputs.provider, model: inputs.model.trim() };
+    const models = installationModels(store);
+    const fingerprint = createHash("sha256").update(JSON.stringify({ repo, inputs, beforeSetup: store.liveWorktreeSetup(repo), beforeConfig: store.phaseConfig(repo, "build"),
+        ...(models === null ? {} : { models: [models.state, models.change] }) })).digest("hex");
+    return { ok: true, fingerprint, command, seconds, provider: inputs.provider, model: inputs.model.trim(), models };
 }
 export function approveSetup(store, repo, inputs, fingerprint, by, token, now) {
     return store.transact(() => {
-        if (!authenticateApprover(store, by, token, repo).ok)
+        const proved = authenticateApprover(store, by, token, repo);
+        if (!proved.ok)
             return { ok: false, message: "Your operator credential is required." };
         const preview = previewSetup(store, repo, inputs);
         if (!preview.ok)
             return preview;
         if (preview.fingerprint !== fingerprint)
             return { ok: false, message: "Setup changed. Review it again." };
-        store.setPhaseConfig(repo, "build", preview.provider, preview.model, by, now);
+        if (preview.models !== null) {
+            // The installation's models, through Settings → Models' one write path (an instance operator's act). The proof
+            // above ran in this same transaction, so the generation read here is the one it was checked against.
+            if (!store.isInstanceOperator(by))
+                return { ok: false, message: "Models for this installation aren't chosen yet. An instance operator sets them up first." };
+            const applied = applyModelChoices(store, { scope: INSTALLATION_SCOPE, change: presetChange(DEFAULT_PRESET), expected: { state: preview.models.state, change: preview.models.change }, strict: true, knownProject: () => false }, { actor: by, generation: store.accountOf(by)?.generation ?? -1, method: proved.method, live: () => true }, now);
+            if (!applied.ok)
+                return { ok: false, message: applied.problem };
+        }
+        // The project's own builder only when it differs from what it inherits: a project left on the installation's
+        // routine builder keeps following the installation's sizes and presets.
+        const inherited = store.phaseConfig(INSTALLATION_SCOPE, "build");
+        const same = inherited !== null && inherited.provider === preview.provider && inherited.model === preview.model;
+        if (!same || store.phaseConfig(repo, "build") !== null)
+            store.setPhaseConfig(repo, "build", preview.provider, preview.model, by, now);
         if (preview.command === "")
             store.clearWorktreeSetup(repo, by, now);
         else
@@ -38,3 +57,11 @@ export function approveSetup(store, repo, inputs, fingerprint, by, token, now) {
         return { ok: true };
     });
 }
+// Last in the file, so the password tripwire's function positions (password-freshness.test.ts) stay as reviewed.
+/** A new installation, nothing chosen yet: setup applies the default preset ("Sized by job") with the project's
+ * builder, previewed here row by row, so the first task files on exact models for every size. */
+function installationModels(store) {
+    if (!ALL_SLOTS.every(slot => rowAt(store, INSTALLATION_SCOPE, slot) === null))
+        return null;
+    return previewModelChange(store, INSTALLATION_SCOPE, presetChange(DEFAULT_PRESET));
+}

package/dist/control-ui.d.ts

@@ -28,4 +28,10 @@ export declare function controlSetupHtml(data: {
     };
 }): Html;
 /** `fields` may still carry the session's csrf (a caller's habit): postForm writes the one CSRF field. */
-export declare function setupPreviewHtml(inputs: SetupInputs, fields: Record<string, string>): Html;
+export declare function setupPreviewHtml(inputs: SetupInputs, fields: Record<string, string>, models?: {
+    label: string;
+    rows: {
+        role: string;
+        model: string;
+    }[];
+} | null): Html;

package/dist/control-ui.js

@@ -27,7 +27,8 @@ export function controlSetupHtml(data) {
         html `<p>Give the agent the project's Toolroll handoff instructions.</p>${postForm("/control/instructions-preview", html `<button>Review instructions</button>`, { hidden: { repo: data.repo } })}`}</section><p><a href="/fleet">Configure planning, repair, and review agents</a> · <a href="/tasks/new">Describe a task</a></p>`;
 }
 /** `fields` may still carry the session's csrf (a caller's habit): postForm writes the one CSRF field. */
-export function setupPreviewHtml(inputs, fields) {
+export function setupPreviewHtml(inputs, fields, models = null) {
     const { csrf: _csrf, ...rest } = fields;
-    return html `<h1>Approve project setup</h1><div class="card"><p>${fields.repo ?? ""}</p><p><strong>Builder:</strong> ${inputs.provider} · ${inputs.model}</p><p><strong>Preparation:</strong></p><pre class="recap">${inputs.command || "No preparation command"}</pre><p>Preparation timeout: ${inputs.seconds} seconds.</p><p>The builder default applies to new tasks. Preparation applies to subsequent runs, including already approved tasks. Existing signed task settings and verification rules remain in force.</p>${postForm("/control/setup-approve", html `${reauth(html `<label>Your password<input type="password" name="token" autocomplete="current-password" required></label>`)}<button>Approve project setup</button>`, { hidden: { ...rest, ...inputs } })}</div>`;
+    const chosen = models === null ? "" : html `<p><strong>Models for every project:</strong> ${models.label}</p><ul>${models.rows.map(row => html `<li>${row.role}: <span class="mono">${row.model}</span></li>`)}</ul><p class="meta">Change them later in Settings → Models.</p>`;
+    return html `<h1>Approve project setup</h1><div class="card"><p>${fields.repo ?? ""}</p><p><strong>Builder:</strong> ${inputs.provider} · ${inputs.model}</p>${chosen}<p><strong>Preparation:</strong></p><pre class="recap">${inputs.command || "No preparation command"}</pre><p>Preparation timeout: ${inputs.seconds} seconds.</p><p>The builder default applies to new tasks. Preparation applies to subsequent runs, including already approved tasks. Existing signed task settings and verification rules remain in force.</p>${postForm("/control/setup-approve", html `${reauth(html `<label>Your password<input type="password" name="token" autocomplete="current-password" required></label>`)}<button>Approve project setup</button>`, { hidden: { ...rest, ...inputs } })}</div>`;
 }

package/dist/dispatch.d.ts

@@ -6,6 +6,7 @@
  * fleet observations on top for people and agents reading the queue. A
  * diagnosis can go stale; it can never grant a lease.
  */
+import { type Runner } from "./runner.js";
 import { type ChatSnapshot, type ReviewRequestOrigin, type ReviewRetryState, type Store, type TaskState } from "./store.js";
 export declare const DEFAULT_MAX_OPEN_DECISIONS = 5;
 export type TaskReadinessBlocker = {
@@ -95,6 +96,20 @@ export declare function dispatchRoleFor(store: Store, taskRef: number, now: Date
 /** The first requirement this task fails, in words, or null. */
 export declare function missingCapability(store: Store, taskRef: number, dispatchRepo: string | null, now: Date): string | null;
 /** The read-side lifecycle answer. Project access limits dependency detail, never the readiness gate. */
+/** The builders that may take work in `repo`, as dispatch decides: registered and not retired (`all`), bound to the
+ * project (`eligible`; only the assigned one when a task names one), and checking in now (`alive`). The first-run
+ * "Builder connected" step reads the same answer, so it is done only when a task there could start. */
+export declare function buildersFor(store: Store, repo: string, now: Date, assignedRunner?: string | null): {
+    all: Runner[];
+    eligible: Runner[];
+    alive: Runner[];
+};
+/** Whether a task in `repo` could start for want of nothing but a person: a live builder bound to it. */
+export declare function builderReadyFor(store: Store, repo: string | null, now: Date): boolean;
+/** The project the first-run "Builder connected" step speaks for, on Chat and the board alike: the open one; else the
+ * saved project of the first filed task the viewer may see (All projects); else, only before any task exists, the
+ * first managed project. Null when tasks exist but none sits in a project the viewer may see: then nothing says done. */
+export declare function firstRunBuilderRepo(store: Store, selected: string | null, visible: (repo: string | null) => boolean, managed: readonly string[]): string | null;
 export declare function diagnoseTaskDispatch(store: Store, taskId: string, now: Date, readableRepos?: readonly string[] | null): DispatchDiagnosis | null;
 export declare function diagnosisIsDispatchable(diagnosis: DispatchDiagnosis | null): boolean;
 /** Attach the same lifecycle answer to the bounded fleet snapshot used by

package/dist/dispatch.js

@@ -160,6 +160,31 @@ function approvedProfile(scope) {
     return scope.approvedProfile ?? scope.profile ?? null;
 }
 /** The read-side lifecycle answer. Project access limits dependency detail, never the readiness gate. */
+/** The builders that may take work in `repo`, as dispatch decides: registered and not retired (`all`), bound to the
+ * project (`eligible`; only the assigned one when a task names one), and checking in now (`alive`). The first-run
+ * "Builder connected" step reads the same answer, so it is done only when a task there could start. */
+export function buildersFor(store, repo, now, assignedRunner = null) {
+    const all = store.listRunners().filter(one => one.retiredAt === null);
+    const bound = all.filter(one => one.repos.includes(repo));
+    const eligible = assignedRunner === null ? bound : bound.filter(one => one.name === assignedRunner);
+    return { all, eligible, alive: eligible.filter(one => isAlive(one, now)) };
+}
+/** Whether a task in `repo` could start for want of nothing but a person: a live builder bound to it. */
+export function builderReadyFor(store, repo, now) {
+    return repo !== null && buildersFor(store, repo, now).alive.length > 0;
+}
+/** The project the first-run "Builder connected" step speaks for, on Chat and the board alike: the open one; else the
+ * saved project of the first filed task the viewer may see (All projects); else, only before any task exists, the
+ * first managed project. Null when tasks exist but none sits in a project the viewer may see: then nothing says done. */
+export function firstRunBuilderRepo(store, selected, visible, managed) {
+    if (selected !== null)
+        return selected;
+    const placed = store.handle.prepare("SELECT repo FROM task_ref WHERE repo IS NOT NULL ORDER BY id").all();
+    const first = placed.find(row => visible(row.repo));
+    if (first !== undefined)
+        return first.repo;
+    return store.hasAnyWork() ? null : managed[0] ?? null;
+}
 export function diagnoseTaskDispatch(store, taskId, now, readableRepos = null) {
     const task = store.getTask(taskId);
     const ref = store.lookupRef(taskId);
@@ -271,9 +296,7 @@ export function diagnoseTaskDispatch(store, taskId, now, readableRepos = null) {
     const gap = missingCapability(store, ref.id, ref.repo, now);
     if (gap !== null)
         return answer("missing-requirement", "waiting", "Missing a requirement", gap, { action: "repair-capability", role });
-    const all = store.listRunners().filter(one => one.retiredAt === null);
-    const bound = all.filter(one => one.repos.includes(ref.repo));
-    const eligible = ref.assignedRunner === null ? bound : bound.filter(one => one.name === ref.assignedRunner);
+    const { all, eligible, alive } = buildersFor(store, ref.repo, now, ref.assignedRunner);
     if (eligible.length === 0) {
         const detail = ref.assignedRunner === null
             ? all.length === 0
@@ -282,7 +305,6 @@ export function diagnoseTaskDispatch(store, taskId, now, readableRepos = null) {
             : `This task is assigned to ${ref.assignedRunner}, but that builder is not connected to this project.`;
         return answer("no-worker-registered", "waiting", "Builder not connected", detail, { action: "start-worker", role });
     }
-    const alive = eligible.filter(one => isAlive(one, now));
     if (alive.length === 0) {
         return answer("no-worker-online", "waiting", "Builder disconnected", `${eligible.length === 1 ? "The builder for this project has" : "All builders for this project have"} stopped checking in. This task starts automatically when ${eligible.length === 1 ? "it reconnects" : "one reconnects"}.`, { action: "start-worker", role });
     }

package/dist/first-run.d.ts

@@ -25,7 +25,7 @@ export type FirstRunAction = {
 };
 /** `checking`: the answer is not in yet, so the step is shown neither done nor to do. */
 export type FirstRunStep = {
-    key: "agent" | "project" | "task";
+    key: "agent" | "project" | "builder" | "task";
     title: string;
     done: boolean;
     action: FirstRunAction | null;
@@ -39,8 +39,11 @@ export type FirstRunFacts = {
     firstResultAt: string | null;
     signInCommand?: string;
 };
-/** The three steps, each done or with the one action that does it; null once the first result has arrived. */
+/** The steps (the builder step is added by withBuilderStep), each done or with the one action that does it; null once the first result has arrived. */
 export declare function firstRunSteps(facts: FirstRunFacts): FirstRunStep[] | null;
+/** The builder step, before the first task: under `toolroll serve` nothing connects a builder, and a task filed then
+ * waits forever, so the steps never all read done without one. It leads to Start a builder, which shows the command. */
+export declare function withBuilderStep(steps: FirstRunStep[] | null, connected: boolean): FirstRunStep[] | null;
 export type OpenIssue = {
     number: number;
     title: string;

package/dist/first-run.js

@@ -1,5 +1,5 @@
 /**
- * The first run: three plain steps to a first result, and three first tasks
+ * The first run: four plain steps to a first result, and three first tasks
  * to try. Everything here is derived from live facts on each render; the
  * list retires permanently with the first Ready result (the
  * 'first-success-at' installation fact). A suggestion only drafts words in
@@ -8,6 +8,7 @@
 import { run } from "./exec.js";
 import { hardenedGit } from "./teardown-git.js";
 import { githubIssues } from "./issues.js";
+import { START_BUILDER_HREF } from "./needs-you.js";
 export const SIGN_IN_COMMAND = "claude auth login";
 export const SANDBOX_COMMAND = "npx toolroll demo";
 /** How a person starts on a real project (the demo hands off to this). */
@@ -27,7 +28,7 @@ export function signInCommandFor(states, platform) {
         return "codex login";
     return `npm install -g @anthropic-ai/claude-code${platform === "win32" ? ";" : " &&"} ${SIGN_IN_COMMAND}`;
 }
-/** The three steps, each done or with the one action that does it; null once the first result has arrived. */
+/** The steps (the builder step is added by withBuilderStep), each done or with the one action that does it; null once the first result has arrived. */
 export function firstRunSteps(facts) {
     if (facts.firstResultAt !== null)
         return null;
@@ -39,6 +40,16 @@ export function firstRunSteps(facts) {
         { key: "task", title: "Your first task", done: facts.hasTask, action: facts.hasTask ? null : { kind: "link", label: "New task", href: "/tasks/new" } },
     ];
 }
+/** The builder step, before the first task: under `toolroll serve` nothing connects a builder, and a task filed then
+ * waits forever, so the steps never all read done without one. It leads to Start a builder, which shows the command. */
+export function withBuilderStep(steps, connected) {
+    if (steps === null)
+        return null;
+    const builder = { key: "builder", title: "Builder connected", done: connected,
+        action: connected ? null : { kind: "link", label: "Start a builder", href: START_BUILDER_HREF } };
+    const task = steps.findIndex(one => one.key === "task");
+    return task < 0 ? [...steps, builder] : [...steps.slice(0, task), builder, ...steps.slice(task)];
+}
 export const GENERIC_FIRST_TASKS = [
     { source: "generic", label: "Add a test for an untested function", draft: "Find one function without a test and add a focused test for it." },
     { source: "generic", label: "Fix a lint warning", draft: "Fix one lint warning without changing behaviour." },

package/dist/first-tasks-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/first-tasks-child.js

@@ -0,0 +1,11 @@
+/**
+ * Started only by learning-look.ts: one project's first-task suggestions (first-run.ts findFirstTasks), in a process
+ * of its own so the hardened git's synchronous reads of the project's folder never hold the console's thread. Its one
+ * argument is JSON naming the project; it prints the suggestions as JSON and ends.
+ */
+import { findFirstTasks } from "./first-run.js";
+const input = JSON.parse(process.argv[2] ?? "null");
+if (input === null || typeof input.repo !== "string" || input.repo === "" || input.repo.includes("\0"))
+    process.exit(2);
+const found = await findFirstTasks(input.repo);
+process.stdout.write(JSON.stringify(found), () => process.exit(0));

package/dist/folder-look.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Reads of a person's own folders, kept off the console's thread.
+ *
+ * A folder can stop answering: a drive that disconnected without unmounting, a folder macOS keeps in iCloud (Desktop &
+ * Documents), or one behind a privacy prompt nobody has answered. Opening it then blocks until the system answers, and
+ * a synchronous read on the console's thread freezes every page with it (the 0.9.82 deploy, 2026-10-31: the console
+ * listened for twenty minutes without answering, its main thread inside a directory read). So every such read runs in a
+ * child process, the same read it always was, and the console waits for it only as long as a deadline allows: a folder
+ * that didn't answer degrades the one thing that needed it, in plain words, and the next look tries again.
+ *
+ * A look never goes into another mounted drive, /Volumes, or the protected folders under ~/Library, unless that is the
+ * folder the person chose. Its answers are filesystem data, read exactly as before (directory names, a repository's
+ * `.git/config` as a plain bounded file never followed through a link), and the caller still checks every path against
+ * its own ceiling.
+ */
+/** How long the console waits for a look before saying the folder didn't answer. */
+export declare const FOLDER_LOOK_MS = 4000;
+/** The `url` of `[remote "origin"]` in a git config's text. Plain JavaScript with no outside names: the look's child
+ * runs this same function (its source is sent along), so the parent and the child read a config one way. */
+export declare function originUrlIn(config: string): string | null;
+export type FolderLookRequest = 
+/** One folder's sub-folders, as the browse page shows them: at most 400 kept of 2,000 entries read, links resolved
+ * and kept only inside a root. */
+{
+    op: "list";
+    path: string;
+    roots: readonly string[];
+    home: string;
+}
+/** The origin of each registered project, and of each repository directly in a root (at most 400 folders a root). */
+ | {
+    op: "origins";
+    registered: readonly string[];
+    roots: readonly string[];
+    home: string;
+}
+/** Where each path really is (its real path, when that is a folder): a project's identity, resolved off the thread. */
+ | {
+    op: "identities";
+    paths: readonly string[];
+}
+/** A project's own `.mcp.json`, read as a plain bounded file and parsed (null when absent or not a JSON object). */
+ | {
+    op: "projectMcp";
+    path: string;
+};
+/** One look under way: its answer, and when its process has ended (a stuck child can outlive its answer). */
+export type FolderLookRun = {
+    answer: Promise<unknown>;
+    ended: Promise<void>;
+};
+/** Starts one look. Production starts a child process; tests pass their own. */
+export type FolderLookRunner = (request: FolderLookRequest, deadlineMs: number) => FolderLookRun;
+/** `started`: when the process that answered was started, in this console's order of starts. A caller that joined a
+ * look already under way gets that look's start, never its own, so an older answer always reads as older. */
+export type FolderLook<T> = {
+    ok: true;
+    value: T;
+    started?: number;
+} | {
+    ok: false;
+    why: "no-answer" | "failed";
+};
+/** At most this many look processes at once, stuck ones included: a folder that never answers costs one each. */
+export declare const FOLDER_LOOK_CHILDREN = 8;
+/** The production look: the script above in a child process of this same Node (or Electron as Node), killed at its
+ * deadline. Its environment carries nothing of this process's (no NODE_OPTIONS, no secrets). At the deadline its pipe
+ * is closed and nothing of it keeps this process alive; `ended` settles only when the process has really gone. */
+export declare const childLook: FolderLookRunner;
+/** How many look processes are running now (stuck ones included). */
+export declare function folderLooksRunning(): number;
+/**
+ * One look, answered within `deadlineMs` whatever the folder does: its value, or that the folder didn't answer (it ran
+ * past the deadline, the same look is still stuck, or every child slot is held) or the look failed. A look already
+ * under way for the same request is joined, never started twice.
+ */
+export declare function lookFolders(request: FolderLookRequest, options?: {
+    runner?: FolderLookRunner;
+    deadlineMs?: number;
+}): Promise<FolderLook<unknown>>;
+export type FolderEntry = {
+    name: string;
+    path: string;
+    git: boolean;
+};
+export type FolderLookOptions = {
+    runner?: FolderLookRunner;
+    deadlineMs?: number;
+    home?: string;
+};
+/** A folder's sub-folders for the browse page (null `at`: outside every root, or not a folder). */
+export declare function listFolder(path: string, roots: readonly string[], options?: FolderLookOptions): Promise<FolderLook<{
+    at: string | null;
+    entries: FolderEntry[];
+}>>;
+/** The origin URL of each registered project, and the repositories directly in each root with theirs. */
+export declare function localOrigins(registered: readonly string[], roots: readonly string[], options?: FolderLookOptions): Promise<FolderLook<{
+    registered: {
+        path: string;
+        url: string | null;
+    }[];
+    found: {
+        path: string;
+        url: string | null;
+    }[];
+}>>;
+/** Each path's identity (its real path when that is a folder, else null), resolved off the thread. */
+export declare function lookIdentities(paths: readonly string[], options?: FolderLookOptions): Promise<FolderLook<Map<string, string | null>>>;
+/** A project's own `.mcp.json` (parsed object, or null when absent or not one), read off the thread. */
+export declare function lookProjectMcp(repo: string, options?: FolderLookOptions): Promise<FolderLook<Record<string, unknown> | null>>;