toolroll 0.9.61 → 0.9.63

package/dist/project-tools.js

@@ -9,20 +9,28 @@
  * leaves every build at once. Reviewers and the lead chat never get tools.
  *
  * Secret values (API keys, tokens, any env value) never enter the
- * database, a chat, a card or a log: they live in one 0600 file per tool
- * under ~/.toolroll/tool-secrets/ (or an older ~/.standing-orders/), are written only from the
- * console's password-gated screen, and reach exactly that project's
- * server processes at launch.
+ * database, a chat, a card or a log: they live in the operating system's
+ * keychain (tool-secret-store.ts) or, where there is none, in one 0600 file
+ * per tool in `tool-secrets` beside the database (files kept before under
+ * ~/.toolroll/tool-secrets/, or an older name's, move in on first use).
+ * They are written only from the console's password-gated screen, read when a
+ * run starts, and reach only that run's tool broker (tool-broker.ts), which
+ * gives them to the project's server processes and sign-in headers — never to
+ * the agent. A tool connected by signing in gives a run only an access token
+ * of its own (oauth-run-token.ts).
  */
 import { toolRefusal } from "./policy.js";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { scanForSecrets } from "./evidence.js";
 import { namedPath } from "./names.js";
+import { startToolBroker } from "./tool-broker.js";
+import { SecretStoreError, destroyOwnFile, prepareSecretFolder, registerSecretFolder, pathIn, readOwnFile, readSealed, removeValue, secretBackend, secretFolder, secretStorage, serviceOf, withSecretLock, withSecretLockAsync, writeOwnFile, writeSealed } from "./tool-secret-store.js";
+import { ACCESS, GRANTED, REFRESH, mintRunToken, mintsRunTokens, oneAtATime, runScope, scopeList, signedIn } from "./oauth-run-token.js";
 import { HEADER_NAME, SECRET_NAME, TOOL_NAME as NAME, TOOL_SPEC_LIMITS as LIMITS, readToolSpec } from "./contracts/integration-metadata.js";
 /** Env names a tool may never claim: the process's own plumbing, every
  * provider credential, and anything that changes how a program or its
@@ -176,60 +184,191 @@ export function toolCommandLine(spec) {
     return [spec.command, ...spec.args].map(part => /^[A-Za-z0-9@%+=:,./_-]+$/.test(part ?? "") ? part : JSON.stringify(part)).join(" ");
 }
 // ---- secrets -----------------------------------------------------------------
-export function toolSecretsDir(home = homedir()) {
-    return namedPath(home, ["tool-secrets"], { dot: true });
-}
-function secretFile(repo, tool, home) {
-    if (!NAME.test(tool))
-        throw new Error("Choose a tool by its name.");
-    return join(toolSecretsDir(home), createHash("sha256").update(repo).digest("hex").slice(0, 16), `${tool}.json`);
-}
-export function readToolSecrets(repo, tool, home = homedir()) {
-    const file = secretFile(repo, tool, home);
-    if (!existsSync(file))
-        return {};
+/**
+ * Where tool secrets were kept before (an existing ~/.toolroll/tool-secrets, or an older name's), read once when
+ * Toolroll starts so their files move in on first use. Never where new secrets go.
+ */
+export function legacyToolSecretsDir(home = homedir()) {
+    const found = namedPath(home, ["tool-secrets"], { dot: true });
+    return existsSync(found) ? found : null;
+}
+/** Commands that can start builds or serve the console: Toolroll's folder for secrets is made before any build runs. */
+export const SECRETS_FIRST = new Set(["serve", "up", "daemon", "watch", "worker", "tick", "build", "run", "reconcile", "bridge"]);
+/**
+ * Toolroll's folder for the secrets it holds, beside `databaseFile`, checked against the sealing key the database
+ * recorded: made now when `eager` (a command that can start builds), else the first time a secret is used.
+ * A folder that can't be used is said in Settings and `toolroll integrations`; every secret is refused until then.
+ */
+export function startToolSecrets(store, databaseFile, clock, options) {
+    const anchor = { read: () => store.toolSecretKeyDigest(), swap: (expected, next) => store.swapToolSecretKeyDigest(expected, next, clock()) };
+    // The old folder is found once, at the first start of a command that can start builds (so before any build ran), then
+    // read from the record.
+    const state = dirname(databaseFile), legacy = store.toolSecretLegacyDir(() => legacyToolSecretsDir(), clock(), { record: options.eager });
+    if (options.eager)
+        prepareSecretFolder(state, anchor, { standing: true, legacy });
+    else
+        registerSecretFolder(state, anchor, { legacy });
+}
+/** Toolroll's folder for secrets (tool-secret-store.ts): beside the database Toolroll started with, or a test's `state`. */
+export function toolSecretsDir(state) {
+    return secretFolder(state).dir;
+}
+const repoHash = (repo) => createHash("sha256").update(repo).digest("hex").slice(0, 16);
+const toolName = (tool) => { if (!NAME.test(tool))
+    throw new Error("Choose a tool by its name."); return tool; };
+/** A tool's own file in the folder: its secrets where there's no keychain, or the names of those set. */
+const toolFile = (folder, repo, tool, suffix, make = false) => pathIn(folder.dir, [repoHash(repo), `${toolName(tool)}${suffix}`], { make });
+/** The same tool's file where secrets were kept before Toolroll's folder; null when there was none. */
+const legacyFile = (folder, repo, tool) => folder.legacy === null ? null : pathIn(folder.legacy, [repoHash(repo), `${toolName(tool)}.json`]);
+/** A tool's keychain item: this Toolroll's folder and the project, hashed, and the tool's name. Never a secret. */
+const secretItem = (folder, repo, tool) => ({ service: serviceOf(folder), account: `${repoHash(repo)}.${toolName(tool)}` });
+const secretValues = (parsed) => parsed === null || typeof parsed !== "object" || Array.isArray(parsed) ? {}
+    : Object.fromEntries(Object.entries(parsed).filter((entry) => SECRET_NAME.test(entry[0]) && typeof entry[1] === "string"));
+const parsedValues = (text) => {
     try {
-        const parsed = JSON.parse(readFileSync(file, "utf8"));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-            return {};
-        return Object.fromEntries(Object.entries(parsed).filter((entry) => SECRET_NAME.test(entry[0]) && typeof entry[1] === "string"));
+        return secretValues(JSON.parse(text));
     }
     catch {
-        return {};
+        throw new SecretStoreError("A tool's stored secrets are damaged.");
     }
+};
+/** A secrets file (owner-only, never through a link); null when there is none. */
+function readSecretFile(file) {
+    const text = readOwnFile(file);
+    return text === null ? null : parsedValues(text);
 }
-function writeSecrets(repo, tool, values, home) {
-    const file = secretFile(repo, tool, home);
-    const dir = join(file, "..");
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    chmodSync(toolSecretsDir(home), 0o700);
-    chmodSync(dir, 0o700);
-    if (Object.keys(values).length === 0) {
+/** What the current store holds for a tool: its keychain item, or (no keychain) its file in Toolroll's folder; null when nothing. */
+function readStored(backend, folder, repo, tool) {
+    if (backend === null)
+        return readSecretFile(toolFile(folder, repo, tool, ".json"));
+    const text = readSealed(backend, folder, secretItem(folder, repo, tool));
+    return text === null ? null : parsedValues(text);
+}
+function writeStored(backend, folder, repo, tool, values, options = {}) {
+    if (backend !== null) {
+        const item = secretItem(folder, repo, tool);
+        if (Object.keys(values).length === 0) {
+            removeValue(backend, item);
+            return "ok";
+        }
+        return writeSealed(backend, folder, item, JSON.stringify(values), options);
+    }
+    const file = toolFile(folder, repo, tool, ".json", true);
+    if (Object.keys(values).length === 0)
+        destroyOwnFile(file);
+    else
+        writeOwnFile(file, JSON.stringify(values));
+    return "ok";
+}
+/** One change to a tool's secrets at a time, across Toolroll's processes, re-entrant within one. */
+const withToolLock = (folder, repo, tool, work) => withSecretLock(folder, `${repoHash(repo)}.${toolName(tool)}`, work);
+/** The names of a tool's secrets that have a value, kept beside them so a page never reads a value to say so. */
+function writeNames(folder, repo, tool, names) {
+    const file = toolFile(folder, repo, tool, ".names.json", true);
+    if (names.length === 0)
         rmSync(file, { force: true });
+    else
+        writeOwnFile(file, JSON.stringify([...names].sort()));
+}
+/**
+ * A tool's secrets moved into the current store from where they were kept before — the old home folder, or (now that
+ * there is a keychain) its file in Toolroll's folder — the first time they are used: stored, read back and compared,
+ * and only then is the file destroyed. What the store already holds (an earlier move, or a change since) wins over
+ * the file. A failure leaves the file as it was, and says so.
+ */
+function moveIn(backend, folder, repo, tool) {
+    const sources = [legacyFile(folder, repo, tool), backend === null ? null : toolFile(folder, repo, tool, ".json")].filter((one) => one !== null && existsSync(one));
+    if (sources.length === 0)
         return;
-    }
-    writeFileSync(file, JSON.stringify(values), { mode: 0o600 });
-    chmodSync(file, 0o600);
+    withToolLock(folder, repo, tool, () => {
+        for (const file of sources) {
+            // Damaged, a link, or not plainly Toolroll's: kept as it is, and never used.
+            let values;
+            try {
+                values = readSecretFile(file);
+            }
+            catch {
+                values = null;
+            }
+            if (values === null)
+                continue;
+            if (Object.keys(values).length > 0 && readStored(backend, folder, repo, tool) === null) {
+                if (writeStored(backend, folder, repo, tool, values, { create: true }) === "ok") {
+                    let back = null;
+                    try {
+                        back = readStored(backend, folder, repo, tool);
+                    }
+                    catch {
+                        back = null;
+                    }
+                    if (back === null || JSON.stringify(back) !== JSON.stringify(values)) {
+                        try {
+                            if (backend !== null)
+                                removeValue(backend, secretItem(folder, repo, tool));
+                        }
+                        catch { /* the file stays the copy that counts */ }
+                        throw new SecretStoreError("A tool's secrets couldn't be moved to the keychain; they stay in their file until they can.");
+                    }
+                }
+            }
+            const kept = readStored(backend, folder, repo, tool) ?? {};
+            writeNames(folder, repo, tool, Object.keys(kept));
+            destroyOwnFile(file);
+        }
+    });
+}
+/** A tool's secret values. Read only to test it, change it or start a run: a page reads which are set (secretsSetFor). */
+export function readToolSecrets(repo, tool, state) {
+    const folder = secretFolder(state);
+    const backend = secretBackend();
+    moveIn(backend, folder, repo, tool);
+    return readStored(backend, folder, repo, tool) ?? {};
 }
 /** Set (or, with an empty value, clear) one secret of one tool. */
-export function setToolSecret(repo, tool, name, value, home = homedir()) {
-    if (!SECRET_NAME.test(name) || RESERVED_ENV.has(name))
-        throw new Error("Choose one of the tool's secrets.");
-    if (value.length > 8_192 || /[\u0000\r\n]/.test(value))
-        throw new Error("A secret is one line, up to 8,192 characters.");
-    const values = readToolSecrets(repo, tool, home);
-    if (value === "")
-        delete values[name];
-    else
-        values[name] = value;
-    writeSecrets(repo, tool, values, home);
+export function setToolSecret(repo, tool, name, value, state) {
+    setToolSecrets(repo, tool, { [name]: value }, state);
 }
-export function setToolSecrets(repo, tool, values, home = homedir()) {
-    for (const [name, value] of Object.entries(values))
-        setToolSecret(repo, tool, name, value, home);
+/** Set (or, with empty values, clear) some secrets of one tool, in one change. */
+export function setToolSecrets(repo, tool, values, state) {
+    for (const [name, value] of Object.entries(values)) {
+        if (!SECRET_NAME.test(name) || RESERVED_ENV.has(name))
+            throw new Error("Choose one of the tool's secrets.");
+        if (value.length > 8_192 || /[\u0000\r\n]/.test(value))
+            throw new Error("A secret is one line, up to 8,192 characters.");
+    }
+    const folder = secretFolder(state);
+    withToolLock(folder, repo, tool, () => {
+        const current = readToolSecrets(repo, tool, state);
+        for (const [name, value] of Object.entries(values)) {
+            if (value === "")
+                delete current[name];
+            else
+                current[name] = value;
+        }
+        writeStored(secretBackend(), folder, repo, tool, current);
+        writeNames(folder, repo, tool, Object.keys(current));
+    });
+}
+export function clearToolSecrets(repo, tool, state) {
+    const folder = secretFolder(state);
+    withToolLock(folder, repo, tool, () => {
+        const backend = secretBackend();
+        if (backend !== null)
+            removeValue(backend, secretItem(folder, repo, tool));
+        for (const file of [toolFile(folder, repo, tool, ".json"), legacyFile(folder, repo, tool)])
+            if (file !== null && existsSync(file))
+                destroyOwnFile(file);
+        rmSync(toolFile(folder, repo, tool, ".names.json"), { force: true });
+    });
 }
-export function clearToolSecrets(repo, tool, home = homedir()) {
-    rmSync(secretFile(repo, tool, home), { force: true });
+/**
+ * One renewal of a sign-in at a time, across Toolroll's processes (a lock in its folder) and within one: a service
+ * that rotates its refresh token on every use would otherwise see the same one twice, and whichever answer was saved
+ * last would be the newest only by luck.
+ */
+export function renewingSignIn(repo, tool, state, work) {
+    const folder = secretFolder(state);
+    return oneAtATime(`${folder.root}\0${repo}\0${tool}`, () => withSecretLockAsync(folder, `${repoHash(repo)}.${toolName(tool)}.renew`, work));
 }
 /** Required secrets with no value yet: the tool is left out of builds until they are set. */
 export function missingSecrets(spec, values) {
@@ -540,26 +679,28 @@ function safeLine(text) {
 }
 const toml = (value) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 const tomlList = (values) => `[${values.map(toml).join(",")}]`;
-/** Claude: only these servers, written to a private 0600 file removed after the run (the provider adds `--strict-mcp-config`). */
-export function claudeToolArgs(launch) {
-    const servers = {};
-    for (const tool of launch.tools) {
-        const spec = tool.spec;
-        if (spec.transport === "stdio") {
-            servers[spec.name] = { type: "stdio", command: spec.command, args: spec.args, env: tool.values };
-        }
-        else {
-            const headers = {};
-            if (spec.bearer !== null && tool.values[spec.bearer])
-                headers["Authorization"] = `Bearer ${tool.values[spec.bearer]}`;
-            for (const [header, secret] of Object.entries(spec.headerSecrets))
-                if (tool.values[secret])
-                    headers[header] = tool.values[secret];
-            servers[spec.name] = { type: "http", url: spec.url, headers };
-        }
-    }
+/** The launch's broker, holding its tools' values; the agent gets only its address and token. */
+function brokerFor(launch, options) {
+    return startToolBroker(launch.tools.map(tool => ({ spec: tool.spec, values: tool.values, ...(options.enabledTools?.[tool.spec.name] === undefined ? {} : { actions: options.enabledTools[tool.spec.name] }) })), options.broker);
+}
+/** A private 0700 folder for one launch's files, and its cleanup with the broker's. */
+function launchFolder(broker) {
     const dir = mkdtempSync(join(tmpdir(), "so-tools-"));
     chmodSync(dir, 0o700);
+    return { dir, cleanup: () => { broker?.close(); rmSync(dir, { recursive: true, force: true }); } };
+}
+/**
+ * Claude: only these servers, in a private 0600 file removed after the run
+ * (the provider adds `--strict-mcp-config`). Each is the broker's address
+ * with this launch's token: Claude and its shell share one sandbox, so the
+ * file holds nothing a tool signs in with.
+ */
+export async function claudeToolArgs(launch, options = {}) {
+    const broker = launch.tools.length === 0 ? null : await brokerFor(launch, options);
+    const servers = {};
+    for (const tool of launch.tools)
+        servers[tool.spec.name] = { type: "http", url: broker.url(tool.spec.name), headers: { Authorization: `Bearer ${broker.token}` } };
+    const { dir, cleanup } = launchFolder(broker);
     const file = join(dir, "mcp.json");
     writeFileSync(file, JSON.stringify({ mcpServers: servers }), { mode: 0o600 });
     return {
@@ -567,32 +708,38 @@ export function claudeToolArgs(launch) {
         // A first `npx` download can take longer than the default start-up wait.
         env: launch.tools.length > 0 ? { MCP_TIMEOUT: "60000" } : {},
         omitEnv: [],
-        cleanup: () => rmSync(dir, { recursive: true, force: true }),
+        cleanup,
+        privateDir: dir,
+        ...(broker === null ? {} : { serverPids: broker.pids }),
     };
 }
 /** Where the tool launcher lives beside this module, built. */
 export function toolLauncherPath() {
     return fileURLToPath(new URL("./tool-launcher.js", import.meta.url));
 }
+/** The secret name a launch file gives the broker's token. */
+const BROKER_TOKEN = "TOOLROLL_TOOL_TOKEN";
 /**
- * Codex: each tool is named by `-c` and started through the launcher. The
- * operator's config.toml, rules, apps, plugins and hooks are already off
- * (the provider's CODEX_BUILD_ISOLATION_ARGV), and nothing of config.toml
- * is carried. Codex gives its own environment to the agent's shell whatever
- * its policy says, so no secret rides it: each tool's values sit in the
- * run's private 0600 file and reach only that tool's process.
+ * Codex: each tool is named by `-c` and started through the launcher, which
+ * relays it to the launch's broker. The operator's config.toml, rules, apps,
+ * plugins and hooks are already off (the provider's
+ * CODEX_BUILD_ISOLATION_ARGV), and nothing of config.toml is carried. Codex
+ * gives its own environment to the agent's shell whatever its policy says,
+ * so nothing rides it: the launch files name the broker and its token, and
+ * the folder holding them is fenced from the agent.
  */
-export function codexToolArgs(launch, options = {}) {
+export async function codexToolArgs(launch, options = {}) {
     const argv = [];
     if (launch.tools.length === 0)
         return { argv, env: {}, omitEnv: [], cleanup: () => undefined };
-    const dir = mkdtempSync(join(tmpdir(), "so-tools-"));
-    chmodSync(dir, 0o700);
+    const broker = await brokerFor(launch, options);
+    const { dir, cleanup } = launchFolder(broker);
     const launcher = options.launcher ?? toolLauncherPath();
     const node = options.node ?? process.execPath;
     for (const tool of launch.tools) {
         const file = join(dir, `${tool.spec.name}.json`);
-        writeFileSync(file, JSON.stringify({ spec: tool.spec, values: tool.values }), { mode: 0o600 });
+        const relay = { ...tool.spec, transport: "http", command: null, args: [], url: broker.url(tool.spec.name), secrets: [{ name: BROKER_TOKEN, optional: false }], bearer: BROKER_TOKEN, headerSecrets: {} };
+        writeFileSync(file, JSON.stringify({ spec: relay, values: { [BROKER_TOKEN]: broker.token } }), { mode: 0o600 });
         const key = `mcp_servers.${tool.spec.name}`;
         argv.push("-c", `${key}.command=${toml(node)}`, "-c", `${key}.args=${tomlList([launcher, file])}`, "-c", `${key}.startup_timeout_sec=60`, 
         // Adding a tool to a project is the operator's yes to its calls: an unattended build has no one to ask.
@@ -602,7 +749,7 @@ export function codexToolArgs(launch, options = {}) {
         if (enabled !== undefined)
             argv.push("-c", `${key}.enabled_tools=${tomlList(enabled)}`);
     }
-    return { argv, env: {}, omitEnv: [], cleanup: () => rmSync(dir, { recursive: true, force: true }), privateDir: dir };
+    return { argv, env: {}, omitEnv: [], cleanup, privateDir: dir, serverPids: broker.pids };
 }
 /** Gemini: no way yet to hand it exactly these servers, so it gets none. */
 export const GEMINI_NO_TOOLS_ARGV = ["--allowed-mcp-server-names", "standing-orders-none"];
@@ -631,14 +778,14 @@ export function projectToolsOf(store, repo) {
  * sealed gets today's list), each with every required secret set. What is
  * left out says why, in words the task page can show.
  */
-export function toolLaunchFor(store, runId, home = homedir()) {
+export function toolLaunchFor(store, runId, home) {
     const run = store.getRun(runId);
     const ref = run === null ? null : store.refById(run.taskRef);
     if (ref === null || ref.repo === null)
         return { tools: [], skipped: [] };
     const approved = store.getScope(ref.externalId)?.approvedDigest ?? null;
     const seal = approved === null ? null : store.toolSealFor(ref.externalId, approved);
-    const launch = { tools: [], skipped: [] };
+    const launch = { tools: [], skipped: [], repo: ref.repo };
     const claimed = new Map();
     const policy = store.orgPolicy();
     for (const tool of projectToolsOf(store, ref.repo)) {
@@ -652,13 +799,18 @@ export function toolLaunchFor(store, runId, home = homedir()) {
             launch.skipped.push({ name: tool.name, reason: "added or changed after this task was approved; approve it again to use it" });
             continue;
         }
-        const values = readToolSecrets(ref.repo, tool.name, home);
+        // A tool that declares no secret never reads the store: a store that isn't ready (a process that didn't start
+        // Toolroll's folder) or a keychain that refuses can't take a keyless tool out of the run.
+        const values = tool.spec.secrets.length === 0 ? {} : readToolSecrets(ref.repo, tool.name, home);
         const missing = missingSecrets(tool.spec, values);
         if (missing.length > 0) {
             launch.skipped.push({ name: tool.name, reason: `needs ${missing.join(", ")} set on the Tools page` });
             continue;
         }
-        const kept = Object.fromEntries(tool.spec.secrets.filter(one => (values[one.name] ?? "") !== "").map(one => [one.name, values[one.name]]));
+        // A tool connected by signing in launches with its access token alone: its refresh token, client and the rest
+        // stay in the store, and a run that renews gets an access token of its own (prepareRunTools).
+        const kept = signedIn(tool.spec) ? { [ACCESS]: values[ACCESS] }
+            : Object.fromEntries(tool.spec.secrets.filter(one => (values[one.name] ?? "") !== "").map(one => [one.name, values[one.name]]));
         const clash = Object.entries(kept).find(([name, value]) => claimed.has(name) && claimed.get(name) !== value);
         if (clash !== undefined) {
             launch.skipped.push({ name: tool.name, reason: `uses ${clash[0]} with a different value than another tool` });
@@ -670,33 +822,143 @@ export function toolLaunchFor(store, runId, home = homedir()) {
     }
     return launch;
 }
+/**
+ * Why a local tool that carries secrets can't start for this launch, or null when it can. Its server's environment
+ * holds the values, and a process of the same user can read another's (KERN_PROCARGS2, /proc/<pid>/environ) unless
+ * an OS fence stops it: only the macOS sandbox around a Claude build does. Codex's filesystem policy can't deny that
+ * read (OpenRouter uses the same harness); Claude's own file rules and Linux's bubblewrap don't stop it, and on Linux
+ * hidepid hides nothing from the same user, so Linux never starts one.
+ */
+export function secretToolRefusal(provider, containment) {
+    if (provider === "codex" || provider === "openrouter")
+        return "This tool needs a Claude build to protect its sign-in details.";
+    if (containment.platform === "linux")
+        return "Toolroll doesn't start tools with sign-in details on Linux: a build there could read them from the running tool.";
+    if (containment.platform !== "darwin" || containment.fence !== "macos-sandbox")
+        return "This build has no macOS sandbox, so it could read this tool's sign-in details. Toolroll didn't start it.";
+    return null;
+}
 /**
  * One attempt's tools, ready for its provider, and recorded on the run:
  * what it launched with and what was left out and why. The caller spawns
  * with `argv`/`env` and calls `cleanup` when the process is done.
  */
-export function prepareRunTools(store, runId, provider, options) {
+export async function prepareRunTools(store, runId, provider, options) {
     const launch = limitedTo(toolLaunchFor(store, runId, options.home), options.readOnly, options.withheld);
-    const enabledTools = options.readOnly === undefined ? {} : { enabledTools: options.readOnly };
-    const prepared = provider === "claude" ? claudeToolArgs(launch)
-        : provider === "codex" || provider === "openrouter" ? codexToolArgs(launch, enabledTools)
-            : { argv: [...GEMINI_NO_TOOLS_ARGV], env: {}, omitEnv: [], cleanup: () => undefined };
+    // A local server with secrets starts only where the build can't read its environment; the rest are left out,
+    // saying why, before the broker exists. Gemini starts none (below).
+    const refusal = provider === "gemini" ? null : secretToolRefusal(provider, options.containment);
+    if (refusal !== null) {
+        launch.tools = launch.tools.filter(one => {
+            if (one.spec.transport === "http" || Object.keys(one.values).length === 0)
+                return true;
+            launch.skipped.push({ name: one.spec.name, reason: refusal });
+            return false;
+        });
+    }
+    const revokes = provider === "gemini" ? [] : await signInRun(launch, { readOnly: options.readOnly !== undefined, now: options.now, ...(options.home === undefined ? {} : { home: options.home }), ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }) });
+    const revoke = () => Promise.all(revokes.splice(0).map(one => one())).then(() => undefined);
+    const offered = { ...(options.readOnly === undefined ? {} : { enabledTools: options.readOnly }), ...(options.broker === undefined ? {} : { broker: options.broker }) };
+    let launched;
+    try {
+        launched = provider === "claude" ? await claudeToolArgs(launch, offered)
+            : provider === "codex" || provider === "openrouter" ? await codexToolArgs(launch, offered)
+                : { argv: [...GEMINI_NO_TOOLS_ARGV], env: {}, omitEnv: [], cleanup: () => undefined };
+    }
+    catch (error) {
+        // Tokens were made for a run that won't start: each is revoked, and the run with them.
+        if (revokes.length === 0)
+            throw error;
+        await revoke();
+        throw new RunSignInError("This run's tools couldn't be prepared, so it didn't start; the sign-ins made for it were revoked.");
+    }
+    // The run's own sign-ins end with it: the broker closes first, so nothing uses a token as it is revoked.
+    const prepared = revokes.length === 0 ? launched : { ...launched, cleanup: () => { launched.cleanup(); void revoke(); } };
     const skipped = provider === "gemini"
         ? [...launch.skipped, ...launch.tools.map(one => ({ name: one.spec.name, reason: "Gemini builds can't use project tools yet" }))]
         : launch.skipped;
-    store.recordRunTools(runId, JSON.stringify({
-        provider,
-        tools: provider === "gemini" ? [] : launch.tools.map(one => ({ name: one.spec.name, digest: one.digest })),
-        skipped,
-    }), options.now);
+    try {
+        store.recordRunTools(runId, JSON.stringify({
+            provider,
+            tools: provider === "gemini" ? [] : launch.tools.map(one => ({ name: one.spec.name, digest: one.digest })),
+            skipped,
+        }), options.now);
+    }
+    catch (error) {
+        launched.cleanup();
+        await revoke();
+        throw revokes.length === 0 ? error : new RunSignInError("This run's tools couldn't be recorded, so it didn't start; the sign-ins made for it were revoked.");
+    }
     return prepared;
 }
+/** A run whose sign-ins couldn't all be made and kept: it doesn't start, and every token made for it is revoked. */
+export class RunSignInError extends Error {
+}
+/**
+ * Each signed-in tool's own access token for this run (oauth-run-token.ts), read and renewed here, outside the fence,
+ * one renewal at a time across Toolroll's processes. A rotated refresh token is saved before the run is let in; when
+ * it can't be, or anything else fails once a token is made, every token made for this run is revoked, the saved
+ * sign-in is left as it was, and the run doesn't start (RunSignInError). Only the new access token joins the launch.
+ * A tool that can't be signed in is left out, saying why. Returns how to revoke the run's tokens.
+ */
+async function signInRun(launch, options) {
+    const repo = launch.repo;
+    const revokes = [];
+    if (repo === undefined)
+        return revokes;
+    const kept = [];
+    try {
+        for (const tool of launch.tools) {
+            if (!signedIn(tool.spec)) {
+                kept.push(tool);
+                continue;
+            }
+            const minted = await renewingSignIn(repo, tool.spec.name, options.home, async () => {
+                const values = readToolSecrets(repo, tool.spec.name, options.home);
+                // No refresh token: the one access token the sign-in gave stays in the broker, like a key.
+                if (!mintsRunTokens(values))
+                    return { ok: true, token: null };
+                const scope = runScope(scopeList(values[GRANTED]), options.readOnly);
+                const answer = await mintRunToken(values, { scope, now: options.now, ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }) });
+                if (answer.ok && answer.token.revoke !== null)
+                    revokes.push(answer.token.revoke);
+                if (answer.ok && answer.token.rotated !== null) {
+                    try {
+                        setToolSecrets(repo, tool.spec.name, { [REFRESH]: answer.token.rotated }, options.home);
+                    }
+                    catch {
+                        throw new RunSignInError(`${tool.spec.name}'s renewed sign-in couldn't be saved, so this run didn't start. Check that the keychain is unlocked, then try again.`);
+                    }
+                }
+                return answer;
+            });
+            if (!minted.ok) {
+                launch.skipped.push({ name: tool.spec.name, reason: minted.reason });
+                continue;
+            }
+            if (minted.token === null) {
+                kept.push(tool);
+                continue;
+            }
+            kept.push({ ...tool, values: { [ACCESS]: minted.token.access } });
+        }
+    }
+    catch (error) {
+        await Promise.all(revokes.splice(0).map(one => one()));
+        if (error instanceof RunSignInError)
+            throw error;
+        throw new RunSignInError("A tool's sign-in couldn't be made for this run, so it didn't start. Check that the keychain is unlocked, then try again.");
+    }
+    launch.tools = kept;
+    return revokes;
+}
 /** A research step's launch: only the servers it may read, each limited to its read-only actions; the rest left out, saying why (`withheld`, when a service has its own reason). */
 function limitedTo(launch, readOnly, withheld = {}) {
     if (readOnly === undefined)
         return launch;
     const readable = (name) => (readOnly[name] ?? []).length > 0;
     return {
+        ...launch,
         tools: launch.tools.filter(one => readable(one.spec.name)),
         skipped: [...launch.skipped, ...launch.tools.filter(one => !readable(one.spec.name)).map(one => ({ name: one.spec.name, reason: withheld[one.spec.name] ?? "research reads only connected services' read-only actions" }))],
     };
@@ -707,7 +969,7 @@ export function noToolsArgs(provider) {
         return { argv: ["--mcp-config", '{"mcpServers":{}}'], env: {}, omitEnv: [], cleanup: () => undefined };
     if (provider === "gemini")
         return { argv: [...GEMINI_NO_TOOLS_ARGV], env: {}, omitEnv: [], cleanup: () => undefined };
-    return codexToolArgs({ tools: [], skipped: [] });
+    return { argv: [], env: {}, omitEnv: [], cleanup: () => undefined };
 }
 /** Add one tool (and, for an import, the values it brings) to a project's builds. */
 export function addToolTo(store, repo, input, source, by, now, options = {}) {
@@ -763,10 +1025,44 @@ export function toolStanding(tool, secretsSet) {
         return { ready: false, words: "Last test failed" };
     return { ready: true, words: `Working · ${tool.lastTest.tools.length} tool${tool.lastTest.tools.length === 1 ? "" : "s"}` };
 }
-/** Names of a tool's secrets that have a value (never the values). */
-export function secretsSetFor(repo, tool, home) {
-    const values = readToolSecrets(repo, tool.name, home);
-    return tool.secrets.filter(one => (values[one.name] ?? "") !== "").map(one => one.name);
+export const CREDENTIAL_MODES = {
+    "run-token": { words: "Short-lived token per run", detail: "Each run gets its own access token when it starts, revoked or left to expire when it ends. The refresh token stays with Toolroll." },
+    "held-key": { words: "Key held by Toolroll", detail: "Runs reach this tool through Toolroll, which adds the key. The key never enters a build." },
+    "no-key": { words: "No key needed", detail: null },
+};
+/** A tool's credential mode from the names of its secrets that are set (never their values); null while a key it needs is missing. */
+export function credentialModeOf(spec, secretsSet) {
+    const mode = spec.secrets.every(one => one.optional && !secretsSet.includes(one.name)) ? "no-key"
+        : signedIn(spec) && mintsRunTokens(secretsSet) ? "run-token"
+            : spec.secrets.some(one => !one.optional && !secretsSet.includes(one.name)) ? null
+                : "held-key";
+    return mode === null ? null : { mode, ...CREDENTIAL_MODES[mode] };
+}
+/** Names of a tool's secrets that have a value, never the values: in the keychain, from the names kept beside them. */
+export function secretsSetFor(repo, tool, state) {
+    const folder = secretFolder(state);
+    let names = null;
+    const backend = secretBackend();
+    if (backend !== null && !existsSync(toolFile(folder, repo, tool.name, ".json")) && (folder.legacy === null || !existsSync(legacyFile(folder, repo, tool.name)))) {
+        try {
+            const listed = JSON.parse(readOwnFile(toolFile(folder, repo, tool.name, ".names.json")) ?? "null");
+            names = Array.isArray(listed) ? listed.filter((one) => typeof one === "string") : null;
+        }
+        catch {
+            names = null;
+        }
+    }
+    if (names === null) {
+        const values = readToolSecrets(repo, tool.name, state);
+        names = Object.keys(values).filter(name => values[name] !== "");
+        if (backend !== null)
+            writeNames(folder, repo, tool.name, names);
+    }
+    return tool.secrets.filter(one => names.includes(one.name)).map(one => one.name);
+}
+/** Where this computer keeps tool secrets, in the words Settings and `toolroll integrations` share; `problem` when they can't be used. */
+export function toolSecretStorage() {
+    return secretStorage();
 }
 /** A command line split into program and arguments, honouring "double" and 'single' quotes. */
 export function splitCommandLine(line) {