toolroll 0.9.81 → 0.9.83

package/dist/operate.js

@@ -60,6 +60,9 @@ import { runRequestedUndos, sendSubagentWeeklies } from "./subagent-week.js";
 import { refreshConnections } from "./mcp-connect.js";
 import { releaseCheckPurposeFor, releaseTermsFor } from "./release-carry.js";
 import { refreshTrustedMains, settleReleaseChecks } from "./nightly-check.js";
+import { githubNightlyRepos, readGithubNightlies } from "./nightly-github.js";
+import { exec as releaseExec, githubReads } from "./release-adapters.js";
+import { releaseTools } from "./release-git.js";
 import { SECRETS_FIRST, startToolSecrets, toolSecretStorage } from "./project-tools.js";
 import { followDiscord } from "./discord.js";
 import { followTeams } from "./teams.js";
@@ -99,7 +102,7 @@ import { taskReviewBrief, renderReviewBrief } from "./task-review-brief.js";
  * **Nothing ever prompts.** There is no terminal on the other end at 3am.
  */
 import { homedir, hostname } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { releaseStalledUpdate, waitingUpdate } from "./toolroll-update.js";
 import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, parseCapabilityKey, verifiedAuthor, isDigestTime, predecessorWatches, RESULT_SCREENSHOTS, lifecycleOf, reportLifecycle, beatLifecycle, } from "./store.js";
 import { createHash, randomBytes, randomInt, randomUUID } from "node:crypto";
@@ -107,7 +110,7 @@ import { claimInstance, clearInstance, openInstanceSocket } from "./console-inst
 import { authorizePlanUnderMode } from "./plan-auto.js";
 import { ghDispatchAdapter, mirrorTaskId, syncPass } from "./sync.js";
 import { LIVE_FILE_BOUND, LIVE_RETAIN_MS, sweepLiveLogs } from "./live.js";
-import { addRepos, removeRepos, updateRepos, loadRepos, loadProjectRegistry, updateProjectRegistry } from "./repos.js";
+import { addRepos, removeRepos, updateRepos, loadRepos, loadProjectRegistry, updateProjectRegistry, registryRemovals } from "./repos.js";
 import { deleteProject, holdingsWords, projectHoldings, projectRunning } from "./project-delete.js";
 import { pushPass } from "./push.js";
 import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, realpathSync, renameSync, unlinkSync, writeSync, writeFileSync } from "node:fs";
@@ -178,6 +181,8 @@ import { createDecisionServer } from "./serve.js";
 import { readTailnetNames } from "./tailnet.js";
 import { daemonLaunchCommand, daemonStatus, installReplacingLegacy, installedLegacyDaemon, planDaemon, uninstallDaemon, awaitFreshHeartbeat, } from "./daemon.js";
 import { bridgePass, clearBotToken, createTransport, followBridge, hashPairingCode, loadBotToken, mintPairingCode, networkFence, networkFenceLine, redactToken, saveBotToken, PAIRING_TTL_MS, TOKEN_ENV, telegramHookSecret, telegramPushUrl, } from "./telegram.js";
+import { projectIdentities } from "./project-identity.js";
+import { lookIdentities } from "./folder-look.js";
 import { scanRepo } from "./capscan.js";
 import { computeGaps, describeCapability } from "./gaps.js";
 import { ask as promptAsk, askHidden as promptHidden, confirm as promptConfirm, interactive as promptInteractive, underAgent } from "./prompt.js";
@@ -247,6 +252,7 @@ import { installationStatus, renderInstallationStatus, renderTaskWait, repairSta
 import { latestRelease, newerRelease, notifySecurityRelease, notifyVersionLive, recordRunnerVersion, startUpdateChecks, updateLine } from "./releases.js";
 import { installMethod } from "./install-method.js";
 import { PACKAGE_VERSION } from "./version.js";
+import { machineActing } from "./scope.js";
 /**
  * 0 done · 1 broke · 2 bad usage · 3 ran fine, the answer is no.
  *
@@ -676,6 +682,9 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "choose", "note", "max-open-decisions", "name", "days", "publication", "auto-approve", "review-auto", "port", "host", "allow-host",
     "for", "tick-every", "bridge-every", "reconcile-every", "incarnation",
     "say", "ceiling-usd", "cap-usd",
+    // evals: the cases a diagnostic campaign runs, its k, an attempt's world and what its builds may not read, and the
+    // stuck campaign a person ends (recover --abandon).
+    "case", "k", "world", "deny", "abandon",
     "token-file", "bin", "poll", "github", "remote", "head-prefix", "password",
     // v102: project rules.
     "not-requester", "protect", "protect-paths",
@@ -714,6 +723,8 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "release",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
+    // evals run: a report-only campaign; keep each attempt's world for a look afterwards.
+    "diagnostic", "keep",
     // task scope --release ... --no-carry: every later commit asks again.
     "no-carry",
     "json", "yes", "all", "brief", "local", "history", "latest-watch", "dry-run", "file",
@@ -1147,6 +1158,8 @@ async function dispatch(command, positional, flags, context) {
     switch (command) {
         case "status":
             return statusCommand(positional, flags, context);
+        case "evals":
+            return evalsCommand(positional, flags, context);
         case "ready":
             return readyCommand(flags, context);
         case "task":
@@ -3928,7 +3941,13 @@ async function startConsole(options) {
     const { context } = options;
     // A git incident (teardown-git.ts) raises an attention notification in this console's outbox.
     noticeGitIncidents(context.store, context.clock);
+    // Every project folder this console starts with is resolved off its thread, under a deadline: one that doesn't
+    // answer (a drive away, an iCloud folder macOS is holding) stays unresolved, kept restrictive, and is looked at again
+    // by the background pass; the console starts and answers either way (project-identity.ts).
+    const identities = projectIdentities();
+    await identities.refresh([...options.repos ?? [], ...options.projectRoots ?? [], ...context.store.listProjects().map(one => one.path), ...context.store.knownRepos()]);
     const server = createDecisionServer({
+        identities,
         store: context.store,
         // Sign-in, integration and model checks, and the tidy-ups no page visit does (docs/plans/get-side-effects.md).
         backgroundChecks: true,
@@ -6279,6 +6298,10 @@ async function runWatchLoop(args) {
             const settledChecks = settleReleaseChecks(store, context.evidenceRoot, context.clock());
             if (settledChecks > 0)
                 progress(`watch: settled ${settledChecks} release check(s)`);
+            // GitHub's nightly as release debt (nightly-github.ts): each opted-in project at most every 30 minutes, 60 s in
+            // all. A test's injected agent runner means a test: no real gh.
+            if (context.agentRunner === undefined)
+                await refreshGithubNightlies(store, context.clock);
             // A finished check may send a build's card down its failure path: now, not on the next beat.
             if (ran + batched > 0)
                 moveCards(store, repo, context.clock(), context.evidenceRoot);
@@ -7040,6 +7063,8 @@ async function upCommand(flags, context) {
     // folders they may be added from are installation state, not arguments a
     // person must repeat on every start.
     const registryPath = registryPathOf(context);
+    // Read before the list itself: a line removed after this (even if saved again) counts differently from now on.
+    const removalsAtStart = registryRemovals(registryPath);
     const loadedRegistry = await loadProjectRegistry(registryPath);
     if ("error" in loadedRegistry)
         return fail(write, json, "up", "registry", loadedRegistry.error, EXIT.refused);
@@ -7063,23 +7088,28 @@ async function upCommand(flags, context) {
     // soon as a projects folder or saved repository exists.
     const repos = [];
     const proveRepo = async (input) => {
-        const top = await gitRun("git", ["rev-parse", "--show-toplevel"], { cwd: resolve(input) });
-        if (top.code !== 0)
-            return null;
-        try {
-            return realpathSync(top.stdout.trim());
-        }
-        catch {
-            return null;
-        }
+        // The checkout's real path is read off the thread, under a deadline (folder-look.ts): a folder that doesn't answer
+        // is unavailable, never a wait.
+        return (await upProveSaved(gitRun, input))?.root ?? null;
     };
+    // A saved project that doesn't answer now (a drive not connected, a folder macOS is holding) is looked at again
+    // while this start runs, and connects once it answers (upDeferredRetry).
+    const deferredRepos = [];
+    const deferredGenerations = {};
+    // The saved line(s) each project was proved from, so its removal is judged by its own line alone.
+    const repoLines = {};
     for (const input of loadedRegistry.repos) {
         const root = await proveRepo(input);
         if (root === null) {
-            progress(`saved project unavailable — skipped ${input}`);
+            progress(`saved project unavailable — skipped ${input}; it connects when it's back`);
+            deferredRepos.push(input);
+            // An unreadable removal record leaves no count that could match later: the authority can't be used.
+            deferredGenerations[input] = removalsAtStart === null ? -1 : removalsAtStart[input] ?? 0;
         }
-        else if (!repos.includes(root)) {
-            repos.push(root);
+        else {
+            if (!repos.includes(root))
+                repos.push(root);
+            (repoLines[root] ??= []).push(input);
         }
     }
     const explicitRepos = context.repoList ?? [];
@@ -7103,7 +7133,9 @@ async function upCommand(flags, context) {
         if (cwdRepo !== null)
             pinnedRepos.add(cwdRepo);
     }
-    if (repos.length === 0 && projectRoots.length === 0)
+    // Saved projects that are only away for now still start the service: it serves an empty, restrictive set until they
+    // answer (never the unscoped mode), and connects each as it comes back.
+    if (repos.length === 0 && projectRoots.length === 0 && deferredRepos.length === 0)
         return fail(write, json, "up", "no-projects", "choose where your projects live once: `toolroll up --project-root <dir>`", EXIT.refused);
     // A person at a terminal reads three lines (onboarding); the folders are for --verbose, a service log, or an agent.
     const quietStart = !json && !flags.has("verbose") && (context.upSeams?.terminal ?? process.stdout.isTTY === true) && !underAgent(context.upSeams?.env ?? process.env);
@@ -7361,6 +7393,9 @@ async function upCommand(flags, context) {
                 type: "start", role: "worker", databaseFile: context.databaseFile, containment: containmentFlag, build,
                 config: {
                     runner: runnerName, token: runnerToken, repos: generation === 1 ? [...repos] : [...currentRepos], pinnedRepos: [...pinnedRepos], projectRoots, registryPath, pool,
+                    // What this start still holds for its saved projects that were away: a restarted worker never gets back an
+                    // authority an earlier one gave up (connected, or removed from the saved list).
+                    deferredRepos: [...deferredRepos], deferredGenerations: { ...deferredGenerations }, repoLines,
                     forMs: forGiven === undefined ? null : Number(forGiven), publicUrl: publicUrlFlag ?? null, stopGraceMs, verbose: flags.has("verbose"),
                     terminal: context.upSeams?.terminal ?? process.stdout.isTTY === true,
                     // A restart waits out a crashed predecessor's lease (at most a minute), then recovers it: as a fresh `up` after a crash.
@@ -7370,6 +7405,12 @@ async function upCommand(flags, context) {
             onMessage: message => {
                 if (message.type === "log")
                     roleLine("worker")(message.line);
+                else if (message.type === "deferred") {
+                    // Only ever narrows: a worker's word can't give back an authority this start no longer holds.
+                    const narrowed = upNarrowDeferred(deferredRepos, message.repos);
+                    deferredRepos.length = 0;
+                    deferredRepos.push(...narrowed);
+                }
                 else if (message.type === "repos") {
                     // The console's admitted projects widen only to what the builder is bound to in the store (the worker binds
                     // through the authenticated door before it reports): a worker's word alone admits nothing.
@@ -12078,15 +12119,9 @@ async function runUpWorkerRole(context, config, port, build) {
     const pinnedRepos = new Set(config.pinnedRepos);
     const gitRun = context.gitRunner ?? ((file, args, opts) => run(file, [...args], { ...(opts?.cwd === undefined ? {} : { cwd: opts.cwd }), timeoutMs: 10_000 }));
     const proveRepo = async (input) => {
-        const top = await gitRun("git", ["rev-parse", "--show-toplevel"], { cwd: resolve(input) });
-        if (top.code !== 0)
-            return null;
-        try {
-            return realpathSync(top.stdout.trim());
-        }
-        catch {
-            return null;
-        }
+        // The checkout's real path is read off the thread, under a deadline (folder-look.ts): a folder that doesn't answer
+        // is unavailable, never a wait.
+        return (await upProveSaved(gitRun, input))?.root ?? null;
     };
     // The proved set this worker builds; `up` relays each change to the console.
     const activeRepos = new Set(config.repos);
@@ -12271,8 +12306,17 @@ async function runUpWorkerRole(context, config, port, build) {
             await pause(follower === null ? 2_000 : 5_000);
         }
     })();
-    const dynamicCeiling = resolveCeiling(config.repos, config.projectRoots).ceiling;
+    // The start's own projects and folders were resolved by `up`: taken as they are, never read again on this thread.
+    const dynamicCeiling = resolveCeiling(config.repos, config.projectRoots, path => resolve(path)).ceiling;
     const rejected = new Set();
+    // Saved lines' identities, resolved off the thread under a deadline (project-identity.ts): a line whose folder
+    // doesn't answer is skipped this pass, and never holds up the others.
+    const lineIdentities = projectIdentities();
+    /** The saved line(s) each active project came from: `up`'s proof for the start's own, the line admitted for later ones. */
+    const admittedLines = new Map(Object.entries(config.repoLines ?? {}));
+    const deferred = upDeferredRetry(config.deferredRepos ?? [], input => upProveSaved(gitRun, input));
+    const deferredGenerations = config.deferredGenerations ?? {};
+    const reportDeferred = () => port.send({ type: "deferred", repos: deferred.list() });
     const registrySupervisor = (async () => {
         const sleep = (ms) => new Promise(resolveSleep => setTimeout(resolveSleep, ms));
         while (!stopping) {
@@ -12282,11 +12326,19 @@ async function runUpWorkerRole(context, config, port, build) {
                 stop();
                 break;
             }
+            // A saved line removed while this start runs takes the start's authority for it with it, for good.
+            if (deferred.keepOnly(loaded.repos))
+                reportDeferred();
+            const plain = loaded.repos.filter(one => !deferred.has(one));
+            await lineIdentities.refresh(plain);
             // Removed from the saved list: stop building it and take it out of the console. A pinned start keeps its own.
-            const saved = new Set(loaded.repos.map(one => canonicalProject(one) ?? one));
+            // Each project is judged by its own saved line (the one it was proved or admitted from, or itself), never by
+            // whether some other folder answered: an unrelated folder that is away never keeps a removed project building.
+            const saved = new Set(loaded.repos);
             let removed = false;
             for (const repo of [...activeRepos]) {
-                if (stopping || pinnedRepos.has(repo) || saved.has(repo))
+                const lines = admittedLines.get(repo) ?? [repo];
+                if (stopping || pinnedRepos.has(repo) || saved.has(repo) || lines.some(line => saved.has(line)))
                     continue;
                 activeRepos.delete(repo);
                 removed = true;
@@ -12299,12 +12351,23 @@ async function runUpWorkerRole(context, config, port, build) {
             for (const candidate of loaded.repos) {
                 if (stopping)
                     break;
-                const canonical = canonicalProject(candidate);
+                // Skipped at start because it didn't answer: connected on the start's own authority once it does.
+                if (deferred.has(candidate)) {
+                    await connectDeferred(candidate);
+                    continue;
+                }
+                const canonical = lineIdentities.known(candidate);
+                // Not answered yet: looked at again on the next pass.
+                if (canonical === undefined)
+                    continue;
                 // Still letting go of an earlier removal: it rejoins on the next pass after its watch has stopped.
                 if (canonical !== null && (activeRepos.has(canonical) || releasedRepos.has(canonical)))
                     continue;
                 const approvedAdditions = context.additionalProjectRepos?.() ?? [];
-                const admittedCeiling = resolveCeiling([...dynamicCeiling.repos, ...approvedAdditions], dynamicCeiling.roots).ceiling;
+                // A start serving nothing yet (its saved projects all away) is an empty ceiling, never the unscoped mode: a
+                // name that matches no path stands in, so a line saved later still needs its recorded admission.
+                const admittedRepos = [...dynamicCeiling.repos, ...approvedAdditions];
+                const admittedCeiling = { repos: admittedRepos.length === 0 && dynamicCeiling.roots.length === 0 ? ["/\0nothing-admitted"] : admittedRepos, roots: dynamicCeiling.roots, canon: (path) => lineIdentities.known(path) ?? null };
                 // A project added after this start (`repos add`, the lead, the console) carries its recorded admission; a
                 // registry line alone is not authority. Either way the folder is proved to be that Git checkout again.
                 const allowed = canonical !== null &&
@@ -12318,6 +12381,7 @@ async function runUpWorkerRole(context, config, port, build) {
                     continue;
                 }
                 rejected.delete(candidate);
+                admittedLines.set(canonical, [...new Set([...admittedLines.get(canonical) ?? [], candidate])]);
                 await launchRepo(canonical, true);
             }
             if (!stopping)
@@ -12327,6 +12391,61 @@ async function runUpWorkerRole(context, config, port, build) {
         fatal = `the project registry stopped (${describe(error)})`;
         stop();
     });
+    /**
+     * A saved project the start couldn't reach, back now: connected only as the very folder that was saved (a parent
+     * checkout found because the saved one lost its .git is another project, needing its own admission), and only while
+     * the line is still saved, checked under the saved list's lock with the binding made inside it, so a removal racing
+     * the proof always wins.
+     */
+    async function connectDeferred(candidate) {
+        const proved = await deferred.retry(candidate);
+        if (proved === null || stopping)
+            return;
+        // Only the very folder that was saved: the saved line must still resolve to itself, and git's checkout must be that
+        // folder. A parent checkout, or the saved path now leading somewhere else, is another project needing admission.
+        if (proved.line !== candidate || proved.root !== candidate) {
+            deferred.revoke(candidate);
+            reportDeferred();
+            progress(proved.root !== proved.line
+                ? `saved project not connected — ${candidate} came back as part of ${proved.root}; add it again to connect it`
+                : `saved project not connected — ${candidate} now leads to ${proved.line}; add it again to connect it`);
+            return;
+        }
+        const root = candidate;
+        if (activeRepos.has(root) || releasedRepos.has(root)) {
+            deferred.revoke(candidate);
+            reportDeferred();
+            return;
+        }
+        // Bound under the saved list's lock: the line is still saved AND has not been removed since this start read it
+        // (its removal count unchanged, so a removal and a save again during the proof still counts as removed).
+        let launching = null;
+        let removedSince = false;
+        await updateProjectRegistry(registryPath, current => {
+            if (stopping || !deferred.has(candidate))
+                return current;
+            const count = registryRemovals(registryPath)?.[candidate] ?? (registryRemovals(registryPath) === null ? -2 : 0);
+            if (!current.repos.includes(candidate) || count !== deferredGenerations[candidate]) {
+                deferred.revoke(candidate);
+                removedSince = true;
+                return current;
+            }
+            deferred.revoke(candidate);
+            admittedLines.set(root, [candidate]);
+            launching = launchRepo(root, true);
+            return current;
+        });
+        if (removedSince) {
+            reportDeferred();
+            progress(`saved project not connected — ${candidate} was removed while it was away; add it again to connect it`);
+            return;
+        }
+        if (launching === null)
+            return;
+        reportDeferred();
+        progress(`saved project is back — connecting ${root}`);
+        await launching;
+    }
     // Provider readiness (v47): this machine's non-spending observations, recorded under its own runner name ONCE at
     // start — so every route projection can say ready / unavailable / unknown per provider, and the dispatch gate can
     // halt a leg this machine cannot run. Production only: a test's injected agent runner is a fake, and its readiness
@@ -12373,3 +12492,199 @@ async function runUpWorkerRole(context, config, port, build) {
     }
     return EXIT.ok;
 }
+/** GitHub's nightly as release debt (docs/plans/evals-nightly.md, part A): the watch loop's background read of each
+ * opted-in project's nightly runs, at most every 30 minutes, within a 60 s overall deadline, through the plane's own gh
+ * (release-adapters.ts githubReads). Nothing is read for a project that never opted in. */
+export async function refreshGithubNightlies(store, now, reads) {
+    if (githubNightlyRepos(store).length === 0)
+        return 0;
+    return readGithubNightlies(store, { gh: reads ?? githubReads(releaseExec, releaseTools().gh, { retry: true }), now });
+}
+/**
+ * `toolroll evals run | attempt | cases | recover` (docs/plans/evals-nightly.md, part C).
+ *
+ * - `run [--diagnostic] [--case a,b] [--k n] --as <you> --token <password>`: admit a campaign (a person's proof, the
+ *   no release busy) and run it to its end from this installed plane. With no flags it is canonical,
+ *   refused while any case is a draft. Each attempt is a child process: `evals attempt`.
+ * - `attempt <campaign> <case> <n> --world <dir> --db <world db>`: one attempt's world (eval-world.ts). Only under its
+ *   runner's dispatch gate, and only on the world's own database.
+ * - `cases`: each installed case, its version, its pin, and whether a person has validated it yet.
+ * - `recover [--abandon <campaign>]`: settle campaigns whose runner stopped; with --abandon, a person ends a stuck one.
+ */
+export async function evalsCommand(positional, flags, context) {
+    const { write, json } = context;
+    // Loaded when an eval command runs, so no other command (nor the console's bundle) pays for the eval runner.
+    const { admitEvalCampaign, campaignSpending, EVALS_ROOT, installedBuildDigest, loadEvalSet, planCampaign, recoverEvalCampaigns, runEvalCampaign } = await import("./evals.js");
+    const { inEvalWorld } = await import("./eval-gate.js");
+    const { evalCliEntry, runEvalWorld } = await import("./eval-world.js");
+    const action = positional[0];
+    const command = `evals${action === undefined ? "" : ` ${action}`}`;
+    const usage = "Use: toolroll evals run [--diagnostic] [--case <ids>] [--k <n>] --as <you> --token <password> | toolroll evals cases | toolroll evals recover [--abandon <campaign> --as <you> --token <password>]";
+    if (action === "recover" && flags.has("abandon"))
+        return evalsAbandonCommand(flags, context);
+    if (action === "recover") {
+        // A campaign whose runner stopped: its unfinished attempts recorded as interrupted, then it ends incomplete.
+        const recovered = recoverEvalCampaigns(context.store, context.clock());
+        return succeed(write, json, command, { campaigns: recovered }, () => recovered.length === 0 ? ["No campaign is running."] : recovered.map(one => `${one.id}: ${one.recovered ? "recovered" : "left running"} (${one.why})`));
+    }
+    if (action === "cases") {
+        const set = loadEvalSet();
+        if (!set.ok)
+            return fail(write, json, command, "unreadable", set.problem, EXIT.failed);
+        const cases = set.cases.map(one => ({ id: one.id, kind: one.kind, version: one.version, pin: one.pin, validatedBy: one.validatedBy, draft: one.validatedBy === null }));
+        return succeed(write, json, command, { manifestDigest: set.manifestDigest, cases }, () => cases.map(one => `${one.id} (${one.kind}) ${one.version.slice(0, 12)} on ${one.pin.model}: ${one.draft ? "draft, awaiting a person's validation" : `validated by ${one.validatedBy}`}`));
+    }
+    if (action === "attempt") {
+        // Only its campaign's runner starts an attempt: under the runner's dispatch gate, on the world's own database.
+        if (!inEvalWorld())
+            return fail(write, json, command, "refused", "An eval attempt runs only from its campaign's runner.", EXIT.refused);
+        const [, campaign, caseId, n] = positional;
+        const world = text(flags, "world");
+        if (campaign === undefined || caseId === undefined || n === undefined || !/^[1-9][0-9]?$/.test(n) || world === undefined)
+            return fail(write, json, command, "usage", "Use: toolroll evals attempt <campaign> <case> <n> --world <dir> --db <world>/toolroll/orders.db", EXIT.usage);
+        let worldDir;
+        try {
+            worldDir = realpathSync(world);
+        }
+        catch {
+            return fail(write, json, command, "refused", "The world's folder can't be read.", EXIT.refused);
+        }
+        if (resolve(context.databaseFile) !== join(worldDir, "toolroll", "orders.db"))
+            return fail(write, json, command, "refused", "An eval attempt runs only on its world's own database.", EXIT.refused);
+        const set = loadEvalSet();
+        const one = set.ok ? set.cases.find(item => item.id === caseId) : undefined;
+        if (one === undefined)
+            return fail(write, json, command, "refused", set.ok ? `No case is named ${caseId}.` : set.problem, EXIT.refused);
+        const deny = (text(flags, "deny") ?? "").split(",").filter(path => path !== "" && isAbsolute(path));
+        const report = await runEvalWorld(one, { worldDir, databaseFile: context.databaseFile, deny, timeoutMs: one.timeoutMinutes * 60_000 });
+        return succeed(write, json, command, { ...report }, () => [JSON.stringify(report)]);
+    }
+    if (action !== "run" || positional.length !== 1)
+        return fail(write, json, command, "usage", usage, EXIT.usage);
+    if (inEvalWorld())
+        return fail(write, json, command, "refused", "An eval world doesn't start campaigns of its own.", EXIT.refused);
+    if (machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined)
+        return fail(write, json, command, "person-only", "Only a person starts an eval campaign: it spends money.", EXIT.refused);
+    const k = text(flags, "k");
+    const cases = text(flags, "case");
+    const set = loadEvalSet();
+    if (!set.ok)
+        return fail(write, json, command, "unreadable", set.problem, EXIT.failed);
+    const planned = planCampaign(set, { ...(cases === undefined ? {} : { cases: cases.split(",").filter(Boolean) }), ...(k === undefined ? {} : { k: Number(k) }), diagnostic: flag(flags, "diagnostic") });
+    if (!planned.ok)
+        return fail(write, json, command, "refused", planned.problem, EXIT.refused);
+    const acting = await askCredentials(flags, context);
+    if (acting === null)
+        return fail(write, json, command, "usage", "An eval campaign is started with your password: add --as <you> --token <password>.", EXIT.usage);
+    const { plan } = planned;
+    const buildDigest = () => installedBuildDigest(PACKAGE_VERSION);
+    const sealed = { cases: plan.cases.map(one => ({ id: one.id, version: one.version, pin: one.pin, maxDispatches: one.maxDispatches })), k: plan.k, baseline: null, evals: EVALS_ROOT };
+    // A campaign whose runner stopped no longer holds its place.
+    recoverEvalCampaigns(context.store, context.clock());
+    const admitted = admitEvalCampaign(context.store, { kind: "eval", canonical: plan.canonical, manifestDigest: set.manifestDigest, buildDigest: buildDigest(), version: PACKAGE_VERSION, k: plan.k,
+        sealed, as: acting.name, token: acting.token, now: context.clock() });
+    if (!admitted.ok)
+        return fail(write, json, command, admitted.reason, admitted.message, EXIT.refused);
+    const stateDir = dirname(context.databaseFile);
+    const entry = evalCliEntry();
+    const keep = ["PATH", "HOME", "USER", "LOGNAME", "LANG", "SHELL", "TMPDIR"];
+    const ended = await runEvalCampaign(context.store, admitted.id, plan.cases, {
+        // Beside the plane's state folder, never inside it: a world's builds read-deny the plane's state.
+        workRoot: join(dirname(stateDir), "toolroll-eval-worlds", admitted.id),
+        buildDigest,
+        keepWorlds: flag(flags, "keep"),
+        now: context.clock,
+        command: input => ({ file: entry.file, args: [...entry.args, "evals", "attempt", input.campaign, input.caseId, String(input.n), "--world", input.worldDir, "--deny", stateDir, "--db", input.databaseFile, "--json"],
+            env: { ...Object.fromEntries(keep.flatMap(name => process.env[name] === undefined ? [] : [[name, process.env[name]]])), XDG_CONFIG_HOME: join(input.worldDir, "config") } }),
+    });
+    const rows = context.store.handle.prepare("SELECT case_id, n, replaces, outcome, error_why, api_microusd, subscription_microusd, usage_unknown FROM eval_attempt WHERE campaign = ? ORDER BY case_id, n, replaces").all(admitted.id);
+    const nullable = (value) => value === null || value === undefined ? null : Number(value);
+    const attempts = rows.map(row => ({ case: String(row["case_id"]), n: Number(row["n"]), replaces: Number(row["replaces"]), outcome: row["outcome"] === null ? null : String(row["outcome"]),
+        why: row["error_why"] === null ? null : String(row["error_why"]), apiMicrousd: nullable(row["api_microusd"]), subscriptionMicrousd: nullable(row["subscription_microusd"]), usageUnknown: Number(row["usage_unknown"]) === 1 }));
+    // What was actually spent, as recorded: API dollars and subscription usage apart, unknown never shown as measured.
+    const spent = campaignSpending(context.store, admitted.id);
+    const dollars = (micro, unknown) => micro === null ? `unknown (${unknown} attempt${unknown === 1 ? "" : "s"} with unknown spending)` : `$${(micro / 1_000_000).toFixed(2)}`;
+    return succeed(write, json, command, { campaign: admitted.id, canonical: plan.canonical, state: ended.state, why: ended.why, attempts, spending: spent }, () => [
+        `Campaign ${admitted.id} (${plan.canonical ? "canonical" : "diagnostic"}) is ${ended.state}${ended.why === null ? "" : `: ${ended.why}`}.`,
+        ...attempts.map(one => `${one.case} #${one.n}${one.replaces === 0 ? "" : " (replacement)"}: ${one.outcome ?? "not finished"}${one.why === null ? "" : ` — ${one.why}`}`),
+        `API dollars: ${dollars(spent.apiMicrousd, spent.unknownAttempts)}. Subscription usage, not billed: ${dollars(spent.subscriptionMicrousd, spent.unknownAttempts)}.`,
+    ]);
+}
+/**
+ * `toolroll evals recover --abandon <campaign> --as <you> --token <password>` (PR #263 review): a person ends a campaign
+ * recovery can't settle (its runner or a world's processes can't be proven gone). Its unfinished attempts are recorded
+ * as errors and its spending as unknown, and it ends incomplete; nothing is signalled and no world is removed. A lead
+ * token, a machine or an eval world is refused; the password is checked inside the write (evals.ts abandonEvalCampaign).
+ */
+async function evalsAbandonCommand(flags, context) {
+    const { write, json } = context;
+    const command = "evals recover";
+    const { abandonEvalCampaign } = await import("./evals.js");
+    const { inEvalWorld } = await import("./eval-gate.js");
+    const id = text(flags, "abandon");
+    if (id === undefined || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(id))
+        return fail(write, json, command, "usage", "Use: toolroll evals recover --abandon <campaign> --as <you> --token <password>", EXIT.usage);
+    if (inEvalWorld() || machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined)
+        return fail(write, json, command, "person-only", "Only a person abandons an eval campaign.", EXIT.refused);
+    const acting = await askCredentials(flags, context);
+    if (acting === null)
+        return fail(write, json, command, "usage", "A campaign is abandoned with your password: add --as <you> --token <password>.", EXIT.usage);
+    const ended = abandonEvalCampaign(context.store, { id, as: acting.name, token: acting.token, now: context.clock() });
+    if (!ended.ok)
+        return fail(write, json, command, ended.reason, ended.message, EXIT.refused);
+    return succeed(write, json, command, { campaign: id, state: "incomplete", attempts: ended.attempts, spending: "unknown" }, () => [`Campaign ${id} ended incomplete. ${ended.attempts} unfinished attempt${ended.attempts === 1 ? "" : "s"} recorded as errors; what it spent is unknown. Nothing was stopped: check for its processes yourself.`]);
+}
+/**
+ * The saved projects an `up` start couldn't reach (upCommand): each is proved again every `everyMs` while the worker
+ * runs, by `prove` (upProveSaved), so a folder that answers again connects without a restart. Only what the start itself
+ * read from the saved list is here, and the set only shrinks: a line connected, removed from the saved list
+ * (`keepOnly`) or come back as some other checkout (`revoke`) is gone for good, so a line saved again later needs its
+ * recorded admission like any other addition. `retry` answers the proof when one is due and answered, else null.
+ */
+export function upDeferredRetry(inputs, prove, everyMs = 5_000, now = Date.now) {
+    // Wall time, not the store's clock (a test's may stand still): this is only how often a folder is asked.
+    const nextAt = new Map(inputs.map(input => [input, now() + everyMs]));
+    return {
+        has: input => nextAt.has(input),
+        list: () => [...nextAt.keys()],
+        retry: async (input) => {
+            const due = nextAt.get(input);
+            if (due === undefined || now() < due)
+                return null;
+            nextAt.set(input, now() + everyMs);
+            return prove(input);
+        },
+        revoke: input => { nextAt.delete(input); },
+        keepOnly: saved => {
+            const keep = new Set(saved);
+            let changed = false;
+            for (const input of [...nextAt.keys()])
+                if (!keep.has(input)) {
+                    nextAt.delete(input);
+                    changed = true;
+                }
+            return changed;
+        },
+    };
+}
+/**
+ * Whether a saved project's folder is a Git checkout now, read without blocking this thread: `git rev-parse
+ * --show-toplevel` (bounded, its own process), then the real paths of the saved line and of the checkout, resolved off
+ * the thread under a deadline (folder-look.ts). Null when it isn't one, or didn't answer.
+ */
+export async function upProveSaved(gitRun, input, look = {}) {
+    const top = await gitRun("git", ["rev-parse", "--show-toplevel"], { cwd: resolve(input) });
+    if (top.code !== 0)
+        return null;
+    const answered = await lookIdentities([resolve(input), top.stdout.trim()], look);
+    if (!answered.ok)
+        return null;
+    const line = answered.value.get(resolve(input)) ?? null, root = answered.value.get(top.stdout.trim()) ?? null;
+    return line === null || root === null ? null : { line, root };
+}
+/** What `up` hands its next worker after the worker reports which saved projects it still holds start authority for:
+ * only what both still hold. A worker's report can give up an authority, never add or give back one. */
+export function upNarrowDeferred(held, reported) {
+    const kept = new Set(reported);
+    return held.filter(one => kept.has(one));
+}

package/dist/project-identity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Project identities as the console uses them, without touching a person's folders on its thread.
+ *
+ * A project's identity is its real path (project.ts canonicalProject). Resolving one reads the folder, and a folder can
+ * stop answering (folder-look.ts), so the console never resolves one on a page or at startup on its own thread:
+ *
+ * - `hot` (display and grouping only): the last answer, else the path as saved. Nothing is started by asking.
+ * - `strict` (visibility and authorization): only a resolved identity; an unknown one fails closed until the next
+ *   refresh resolves it, so a stored path that leads outside its root never passes on its spelling.
+ * - `vouched` (a path a request names): only a path whose identity is known, or one that is exactly a saved identity.
+ *   Anything else is refused this time and resolved by the next background pass, never resolved inline.
+ * - `resolveNow` (an action that needs a path checked now, a POST): resolved off the thread under the look's deadline.
+ * - `refresh` (the console's start and its background pass): resolves what was asked about and what has gone stale.
+ *
+ * An embedder or test that passes no identities gets `syncProjectIdentities`: the old synchronous reads, unchanged.
+ */
+import { type FolderLookOptions } from "./folder-look.js";
+export type ProjectIdentities = {
+    /** For display and grouping only: the last known identity, else the path as saved (resolved lexically). Reads
+     * nothing. Never an authorization answer: use `strict`. */
+    hot: (path: string) => string;
+    /** For authorization: the known real folder path, else null (unknown or not a folder: fail closed until resolved).
+     * Reads nothing; an unknown path is asked about on the next refresh. */
+    strict: (path: string) => string | null;
+    /** The known identity: a real folder path, null (not a folder), or undefined (never answered). Reads nothing. */
+    known: (path: string) => string | null | undefined;
+    /** A request's path: its known identity, or the path itself when it is exactly one of `saved` (projects the plane
+     * itself proved and admitted); else undefined. */
+    vouched: (path: string, saved: () => Iterable<string>) => string | undefined;
+    /** This path's identity now, off the thread: a real folder path, null, or "no-answer" past the deadline. */
+    resolveNow: (path: string) => Promise<string | null | "no-answer">;
+    /** Resolve `paths`, everything asked about since, and answers older than a minute. False when some didn't answer. */
+    refresh: (paths: Iterable<string>) => Promise<boolean>;
+};
+export declare function projectIdentities(look?: FolderLookOptions, now?: () => number): ProjectIdentities;
+/** The synchronous reads, as before: for embedders and tests that pass no identities. */
+export declare function syncProjectIdentities(): ProjectIdentities;