toolroll 0.9.62 → 0.9.65

package/dist/project-delete.d.ts

@@ -1,4 +1,5 @@
-import { type ExecResult } from "./exec.js";
+import type { ExecResult } from "./exec.js";
+import type { Runner } from "./worktree.js";
 import { type Store } from "./store.js";
 /** What Toolroll names the branches it makes: toolroll/…, and standing-orders/… from before the rename. */
 export declare const OWN_BRANCH = "toolroll/";
@@ -52,4 +53,5 @@ export declare function deleteProject(store: Store, repo: string, options: {
     evidenceRoot: string | null;
     poolRoot: string | null;
     git?: GitRunner;
+    runner?: Runner;
 }): Promise<ProjectDeleteResult>;

package/dist/project-delete.js

@@ -14,7 +14,7 @@
  */
 import { existsSync, lstatSync, rmSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
-import { run } from "./exec.js";
+import { teardownGit, refusal } from "./teardown-git.js";
 import { BUILT_IN } from "./store.js";
 import { BRANCH_PREFIX, BRANCH_PREFIXES, isOwnBranch } from "./names.js";
 /** The tables whose history is the audit record itself: never touched. */
@@ -48,7 +48,7 @@ function doomed(db, repo) {
 const SETTINGS = [
     ["approval_policy", "repo"], ["verify_command", "repo"], ["worktree_setup", "repo"], ["backend_grant", "repo"], ["publication_grant", "repo"],
     ["intake_grant", "repo"], ["capability", "repo"], ["project_tool", "repo"], ["phase_config", "scope"], ["phase_tier_config", "scope"],
-    ["learning_policy", "repo"], ["operating_mode", "repo"], ["project_knowledge", "repo"],
+    ["learning_policy", "repo"], ["operating_mode", "repo"], ["project_knowledge", "repo"], ["live_detail_setting", "repo"],
     ["project_decision", "repo"], ["flow_script", "repo"], ["workflow_recipe", "repo"], ["team_lead_project", "project"],
 ];
 /** What Toolroll holds for a project, counted. */
@@ -100,7 +100,6 @@ export function projectRunning(store, repo, now) {
         ...(checkouts > 0 && building === 0 ? [`${plural(checkouts, "checkout")} ${checkouts === 1 ? "is" : "are"} in use`] : []),
     ];
 }
-const defaultGit = (args, cwd) => run("git", ["--no-optional-locks", ...args], { cwd, timeoutMs: 60_000 });
 /** Whether `path` is inside `root` (not the root itself). */
 const inside = (root, path) => { const rel = relative(resolve(root), resolve(path)); return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel); };
 /**
@@ -121,7 +120,10 @@ async function removeCheckoutsAndBranches(store, repo, d, git, poolRoot) {
     const ours = new Set(named);
     const left = [];
     let checkouts = 0, branches = 0;
-    const isRepo = existsSync(repo) && (await git(["rev-parse", "--git-dir"], repo)).code === 0;
+    const probe = existsSync(repo) ? await git(["rev-parse", "--git-dir"], repo) : null;
+    if (probe !== null && refusal(probe) !== null)
+        return { checkouts, branches, left: [refusal(probe)] };
+    const isRepo = probe?.code === 0;
     if (!isRepo) {
         // No repository to ask: only checkouts in Toolroll's own folder go.
         for (const row of recorded) {
@@ -277,7 +279,7 @@ function deleteRows(store, repo, d, now) {
     const mirrors = json(list(db, `SELECT local_task_id FROM external_mirror WHERE ${IN("local_task_id")}`, K));
     del("external_intent", IN("mirror"), mirrors);
     del("external_mirror", IN("local_task_id"), mirrors);
-    for (const [table, column] of [["scope_approval_vote", "task_id"], ["scope_author", "task_id"], ["plan_authorization", "task_id"], ["tool_seal", "task"], ["mcp_idempotency", "task_id"], ["coordinator_event", "task_id"], ["workflow_preview", "task_id"]])
+    for (const [table, column] of [["scope_approval_vote", "task_id"], ["scope_author", "task_id"], ["plan_authorization", "task_id"], ["tool_seal", "task"], ["mcp_idempotency", "task_id"], ["coordinator_event", "task_id"], ["workflow_preview", "task_id"], ["task_source", "task_id"]])
         del(table, IN(column), K);
     del("workflow_preview", "repo = ?", repo);
     del("coding_handoff_scope", `id IN (SELECT id FROM coding_handoff WHERE json_extract(payload, '$.repo') = ?)`, repo);
@@ -291,6 +293,8 @@ function deleteRows(store, repo, d, now) {
     // Flows, cards and subagents.
     del("flow_trigger_event", `${IN("card")} OR trigger IN (SELECT id FROM flow_trigger WHERE ${IN("flow")})`, C, F);
     del("flow_trigger", IN("flow"), F);
+    del("flow_unattended_run", `grant_id IN (SELECT id FROM flow_unattended_grant WHERE ${IN("flow")})`, F);
+    del("flow_unattended_grant", IN("flow"), F);
     for (const table of ["flow_card_watcher", "flow_comment", "flow_event", "flow_mail", "flow_step_run"])
         del(table, IN("card"), C);
     del("subagent_question", IN("id"), questions);
@@ -323,7 +327,9 @@ function deleteRows(store, repo, d, now) {
  * starts while the checkouts and branches go.
  */
 export async function deleteProject(store, repo, options) {
-    const git = options.git ?? defaultGit;
+    const hardened = teardownGit(options.runner ?? (options.git === undefined ? undefined :
+        (_file, args, execOptions) => options.git(args, execOptions.cwd)));
+    const git = (args, cwd) => hardened(cwd, args);
     const running = projectRunning(store, repo, options.now);
     if (running.length > 0)
         return { ok: false, reason: "running", said: `Nothing was deleted: ${running.join(", ")}. Stop it, then try again.`, running };

package/dist/project-file.d.ts

@@ -0,0 +1,3 @@
+/** A project file a script names, if it is one: inside the project, and there. Kept free of the runner's imports so a
+ * flow's "runs on its own" grant (flow-unattended.ts) resolves the very file a script would run. */
+export declare function projectFile(root: string, path: string): string | null;

package/dist/project-file.js

@@ -0,0 +1,16 @@
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+/** A project file a script names, if it is one: inside the project, and there. Kept free of the runner's imports so a
+ * flow's "runs on its own" grant (flow-unattended.ts) resolves the very file a script would run. */
+export function projectFile(root, path) {
+    if (path === "" || isAbsolute(path) || path.split(/[\\/]/).includes(".."))
+        return null;
+    try {
+        const base = realpathSync(root), full = realpathSync(join(root, path));
+        const inside = relative(base, full);
+        return inside !== "" && !inside.startsWith("..") && !isAbsolute(inside) && statSync(full).isFile() ? full : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/project-memory.d.ts

@@ -44,7 +44,9 @@ export type MemoryHit = {
 };
 /** Rebuild the index rows for one project from the stores of record. */
 export declare function reindexProjectMemory(store: Store, repo: string): void;
-/** Index conversation messages incrementally: private threads under their person, team conversations under their id and each project they cover. */
+/** Index conversation messages incrementally: private threads under their person, team conversations under their id and each project they cover.
+ * A message still waiting for a turn is not indexed: it is indexed when a turn takes it (the admitted-turn pass below,
+ * with the words the turn took), so a withdrawn, removed or edited waiting message never reaches search. */
 export declare function reindexConversations(store: Store): void;
 /** Search what this person may read: project entries for their projects, their own private chats, and team conversations they are in. */
 export declare function searchMemory(store: Store, args: {

package/dist/project-memory.js

@@ -218,38 +218,63 @@ export function reindexProjectMemory(store, repo) {
             insert.run('decision', String(row['id']), repo, 'project', String(row['claim']), String(row['why']));
     });
 }
-/** Index conversation messages incrementally: private threads under their person, team conversations under their id and each project they cover. */
+/** Index conversation messages incrementally: private threads under their person, team conversations under their id and each project they cover.
+ * A message still waiting for a turn is not indexed: it is indexed when a turn takes it (the admitted-turn pass below,
+ * with the words the turn took), so a withdrawn, removed or edited waiting message never reaches search. */
 export function reindexConversations(store) {
-    const key = 'memory-search:messages';
+    const key = 'memory-search:messages', admittedKey = 'memory-search:admitted';
     const cursor = store.serviceCursor(key);
-    const rows = store.handle.prepare('SELECT m.id,m.thread,m.role,m.text,t.approver FROM lead_message m JOIN lead_thread t ON t.id=m.thread WHERE m.id>? ORDER BY m.id LIMIT 500').all(cursor);
-    if (rows.length === 0)
-        return;
+    const rows = store.handle.prepare('SELECT m.id,m.thread,m.role,m.text,m.pending,t.approver FROM lead_message m JOIN lead_thread t ON t.id=m.thread WHERE m.id>? ORDER BY m.id LIMIT 500').all(cursor);
     const insert = store.handle.prepare('INSERT INTO memory_search(kind,ref,repo,scope,title,body) VALUES (?,?,?,?,?,?)');
     const teamOf = store.handle.prepare('SELECT id, projects_json FROM team_conversation WHERE thread=?');
+    const indexOne = (row) => {
+        const id = Number(row['id']);
+        // Indexed exactly as stored (the search proves a hit against the stored words); blank means nothing to index.
+        const text = String(row['text']);
+        if (!text.trim() || text.length > 20_000)
+            return;
+        const team = teamOf.get(Number(row['thread']));
+        if (team) {
+            let projects = [];
+            try {
+                projects = JSON.parse(String(team['projects_json']));
+            }
+            catch {
+                projects = [];
+            }
+            for (const repo of projects.length ? projects : [''])
+                insert.run('conversation', `message:${id}`, repo, `conversation:${String(team['id'])}`, `${row['role']} in a team conversation`, text);
+        }
+        else
+            insert.run('conversation', `message:${id}`, '', `approver:${String(row['approver'])}`, `${row['role']} in a private chat`, text);
+    };
     store.transact(() => {
         let last = cursor;
         for (const row of rows) {
             last = Number(row['id']);
-            const text = String(row['text']).trim();
-            if (!text || text.length > 20_000)
+            if (Number(row['pending']) === 1)
                 continue;
-            const team = teamOf.get(Number(row['thread']));
-            if (team) {
-                let projects = [];
-                try {
-                    projects = JSON.parse(String(team['projects_json']));
-                }
-                catch {
-                    projects = [];
-                }
-                for (const repo of projects.length ? projects : [''])
-                    insert.run('conversation', `message:${last}`, repo, `conversation:${String(team['id'])}`, `${row['role']} in a team conversation`, text);
-            }
-            else
-                insert.run('conversation', `message:${last}`, '', `approver:${String(row['approver'])}`, `${row['role']} in a private chat`, text);
+            indexOne(row);
+        }
+        if (rows.length > 0)
+            store.setServiceCursor(key, last, new Date());
+        // Messages that waited and were then admitted (a personal queue row or a team room message bound to a turn since the
+        // last pass): one the walk passed while it waited (at or below the cursor this pass started from) is indexed now,
+        // with the words its turn took. One past it is left to the walk, so nothing is indexed twice. Found by the turn
+        // indexes on both queues: only queued messages are visited, never every turn. (After an update from before v128, a
+        // team message already indexed when it was saved gains a second copy once; search counts each entry once.)
+        const turnCursor = store.serviceCursor(admittedKey);
+        const admitted = store.handle.prepare(`SELECT message, turn FROM (SELECT message, turn_id AS turn FROM lead_queue WHERE turn_id > ?
+      UNION ALL SELECT message, turn_id AS turn FROM team_message WHERE turn_id > ?) ORDER BY turn LIMIT 500`).all(turnCursor, turnCursor);
+        if (admitted.length === 0)
+            return;
+        const taken = store.handle.prepare("SELECT m.id,m.thread,m.role,m.text,t.approver FROM lead_message m JOIN lead_thread t ON t.id=m.thread WHERE m.id=? AND m.pending=0 AND m.id<=?");
+        for (const one of admitted) {
+            const row = taken.get(Number(one['message']), cursor);
+            if (row !== undefined)
+                indexOne(row);
         }
-        store.setServiceCursor(key, last, new Date());
+        store.setServiceCursor(admittedKey, Number(admitted.at(-1)['turn']), new Date());
     });
 }
 const ftsQuery = (query) => {
@@ -269,11 +294,18 @@ export function searchMemory(store, args) {
         reindexProjectMemory(store, repo);
     const conversations = store.handle.prepare('SELECT conversation FROM team_participant WHERE account=? AND active=1').all(args.actor).map(row => `conversation:${String(row['conversation'])}`);
     const scopes = ['project', `approver:${args.actor}`, ...conversations];
+    const limit = Math.min(50, Math.max(1, args.limit ?? 12));
     const match = ftsQuery(query);
     if (!match)
         return [];
     const rows = store.handle.prepare(`SELECT kind, ref, repo, scope, title, snippet(memory_search, 5, '[', ']', '…', 24) AS snippet FROM memory_search
-    WHERE memory_search MATCH ? AND scope IN (SELECT value FROM json_each(?)) AND (repo='' OR repo IN (SELECT value FROM json_each(?))) ORDER BY bm25(memory_search) LIMIT ?`)
-        .all(match, JSON.stringify(scopes), JSON.stringify(repos), Math.min(50, Math.max(1, args.limit ?? 12)));
-    return rows.map(row => ({ kind: row['kind'], ref: String(row['ref']), repo: String(row['repo']), title: String(row['title']).slice(0, 200), snippet: String(row['snippet']).slice(0, 400) }));
+    WHERE memory_search MATCH ? AND scope IN (SELECT value FROM json_each(?)) AND (repo='' OR repo IN (SELECT value FROM json_each(?)))
+      AND (kind<>'conversation' OR EXISTS (SELECT 1 FROM lead_message m WHERE m.id=CAST(substr(memory_search.ref, 9) AS INTEGER) AND m.pending=0
+        AND (m.text = memory_search.body OR trim(m.text, ' '||char(9)||char(10)||char(13)) = memory_search.body)))
+    ORDER BY bm25(memory_search) LIMIT ?`)
+        .all(match, JSON.stringify(scopes), JSON.stringify(repos), limit * 2);
+    // One hit per entry and place: a message indexed before it waited and again when its turn took it counts once.
+    const seen = new Set();
+    return rows.filter(row => { const key = `${row['kind']}\u0000${row['ref']}\u0000${row['repo']}\u0000${row['scope']}`; return !seen.has(key) && seen.add(key) !== undefined; }).slice(0, limit)
+        .map(row => ({ kind: row['kind'], ref: String(row['ref']), repo: String(row['repo']), title: String(row['title']).slice(0, 200), snippet: String(row['snippet']).slice(0, 400) }));
 }

package/dist/project-tools.d.ts

@@ -1,4 +1,8 @@
 import type { Store, ToolActionInfo } from "./store.js";
+import { type BrokerOptions } from "./tool-broker.js";
+import type { FenceMethod } from "./agent-fence.js";
+import type { ProviderId } from "./contracts/provider.js";
+import { type SecretStoreKind } from "./tool-secret-store.js";
 import { type ToolSecret, type ToolSpec } from "./contracts/integration-metadata.js";
 export type { ToolSecret, ToolSpec };
 export type ToolTest = {
@@ -55,12 +59,36 @@ export declare function toolDigest(spec: ToolSpec): string;
 export declare function validateToolSpec(input: Record<string, unknown>): ToolSpec;
 /** How the tool starts, in one line a person can check. Never a secret value. */
 export declare function toolCommandLine(spec: ToolSpec): string;
-export declare function toolSecretsDir(home?: string): string;
-export declare function readToolSecrets(repo: string, tool: string, home?: string): Record<string, string>;
+/**
+ * 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 declare function legacyToolSecretsDir(home?: string): string | null;
+/** Commands that can start builds or serve the console: Toolroll's folder for secrets is made before any build runs. */
+export declare const SECRETS_FIRST: ReadonlySet<string>;
+/**
+ * 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 declare function startToolSecrets(store: Pick<Store, "toolSecretKeyDigest" | "swapToolSecretKeyDigest" | "toolSecretLegacyDir">, databaseFile: string, clock: () => Date, options: {
+    eager: boolean;
+}): void;
+/** Toolroll's folder for secrets (tool-secret-store.ts): beside the database Toolroll started with, or a test's `state`. */
+export declare function toolSecretsDir(state?: string): string;
+/** A tool's secret values. Read only to test it, change it or start a run: a page reads which are set (secretsSetFor). */
+export declare function readToolSecrets(repo: string, tool: string, state?: string): Record<string, string>;
 /** Set (or, with an empty value, clear) one secret of one tool. */
-export declare function setToolSecret(repo: string, tool: string, name: string, value: string, home?: string): void;
-export declare function setToolSecrets(repo: string, tool: string, values: Record<string, string>, home?: string): void;
-export declare function clearToolSecrets(repo: string, tool: string, home?: string): void;
+export declare function setToolSecret(repo: string, tool: string, name: string, value: string, state?: string): void;
+/** Set (or, with empty values, clear) some secrets of one tool, in one change. */
+export declare function setToolSecrets(repo: string, tool: string, values: Record<string, string>, state?: string): void;
+export declare function clearToolSecrets(repo: string, tool: string, state?: string): void;
+/**
+ * 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 declare function renewingSignIn<T>(repo: string, tool: string, state: string | undefined, work: () => Promise<T>): Promise<T>;
 /** Required secrets with no value yet: the tool is left out of builds until they are set. */
 export declare function missingSecrets(spec: ToolSpec, values: Record<string, string>): string[];
 /** A server already configured on this computer, ready to add to a project (values moved, never shown). */
@@ -123,42 +151,54 @@ export declare function callProjectTool(spec: ToolSpec, values: Record<string, s
     env?: NodeJS.ProcessEnv;
     omitEnv?: readonly string[];
 }): Promise<ToolCall>;
-/** The exact servers one launch gets, and those left out with why. */
+/** The exact servers one launch gets, and those left out with why (`repo`: the project, from the run's record). */
 export type ToolLaunch = {
     tools: ResolvedTool[];
     skipped: {
         name: string;
         reason: string;
     }[];
+    repo?: string;
 };
 /** Everything a provider spawn needs to use exactly these tools, and the
- * cleanup. `privateDir` holds the run's secret launch files: Codex starts
- * tool servers outside its command sandbox, so its agent can be fenced out
- * of that folder while the tools still read it. */
+ * cleanup. `privateDir` holds the run's launch files, which name the broker
+ * and its token, never a tool's secret (tool-broker.ts). */
 export type ToolLaunchArgs = {
     argv: string[];
     env: Record<string, string>;
     omitEnv: string[];
     cleanup: () => void;
     privateDir?: string;
+    serverPids?: () => number[];
+    brokerPort?: number;
+};
+/** How a launch's tools are offered: research steps' servers only their read-only actions. */
+export type ToolLaunchOptions = {
+    broker?: BrokerOptions;
+    enabledTools?: Readonly<Record<string, readonly string[]>>;
 };
-/** Claude: only these servers, written to a private 0600 file removed after the run (the provider adds `--strict-mcp-config`). */
-export declare function claudeToolArgs(launch: ToolLaunch): ToolLaunchArgs;
+/**
+ * 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 declare function claudeToolArgs(launch: ToolLaunch, options?: ToolLaunchOptions): Promise<ToolLaunchArgs>;
 /** Where the tool launcher lives beside this module, built. */
 export declare function toolLauncherPath(): string;
 /**
- * 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 declare function codexToolArgs(launch: ToolLaunch, options?: {
+export declare function codexToolArgs(launch: ToolLaunch, options?: ToolLaunchOptions & {
     launcher?: string;
     node?: string;
-    enabledTools?: Readonly<Record<string, readonly string[]>>;
-}): ToolLaunchArgs;
+}): Promise<ToolLaunchArgs>;
 /** Gemini: no way yet to hand it exactly these servers, so it gets none. */
 export declare const GEMINI_NO_TOOLS_ARGV: readonly string[];
 type ToolRows = Pick<Store, "projectTools">;
@@ -171,24 +211,44 @@ export declare function projectToolsOf(store: ToolRows, repo: string): ProjectTo
  * left out says why, in words the task page can show.
  */
 export declare function toolLaunchFor(store: Pick<Store, "projectTools" | "getRun" | "refById" | "getScope" | "toolSealFor" | "orgPolicy">, runId: number, home?: string): ToolLaunch;
+/** What stops a build reading a local tool server's environment: this computer's platform and the OS fence its run
+ * gets, both fixed by the gateway before any tool is prepared (never from a launch's own files or the checkout). */
+export type ToolContainment = {
+    platform: NodeJS.Platform;
+    fence: FenceMethod;
+};
+/**
+ * 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 declare function secretToolRefusal(provider: ProviderId, containment: ToolContainment): string | 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 declare function prepareRunTools(store: Pick<Store, "projectTools" | "getRun" | "refById" | "getScope" | "toolSealFor" | "recordRunTools" | "orgPolicy">, runId: number, provider: "claude" | "codex" | "openrouter" | "gemini", options: {
+export declare function prepareRunTools(store: Pick<Store, "projectTools" | "getRun" | "refById" | "getScope" | "toolSealFor" | "recordRunTools" | "orgPolicy">, runId: number, provider: ProviderId, options: {
     home?: string;
     now: Date;
+    containment: ToolContainment;
     readOnly?: Readonly<Record<string, readonly string[]>>;
     withheld?: Readonly<Record<string, string>>;
-}): ToolLaunchArgs;
+    broker?: BrokerOptions;
+    fetcher?: typeof fetch;
+}): Promise<ToolLaunchArgs>;
+/** 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 declare class RunSignInError extends Error {
+}
 /** When a launch's tools cannot be prepared, it still gets none of anything else's: the same isolation with an empty list. */
-export declare function noToolsArgs(provider: "claude" | "codex" | "openrouter" | "gemini"): ToolLaunchArgs;
+export declare function noToolsArgs(provider: ProviderId): ToolLaunchArgs;
 type ToolWrites = Pick<Store, "projectTools" | "addProjectTool" | "removeProjectTool" | "recordProjectToolTest">;
 /** Add one tool (and, for an import, the values it brings) to a project's builds. */
 export declare function addToolTo(store: ToolWrites, repo: string, input: ToolSpec, source: string, by: string, now: Date, options?: {
     values?: Record<string, string>;
-    home?: string;
+    home?: string | undefined;
 }): {
     ok: true;
     spec: ToolSpec;
@@ -200,7 +260,7 @@ export declare function addToolTo(store: ToolWrites, repo: string, input: ToolSp
 export declare function removeToolFrom(store: ToolWrites, repo: string, name: string, by: string, now: Date, home?: string): boolean;
 /** Test one tool of a project and keep the answer on it. */
 export declare function testToolOf(store: ToolWrites, repo: string, name: string, now: Date, options?: {
-    home?: string;
+    home?: string | undefined;
     timeoutMs?: number;
     omitEnv?: readonly string[];
 }): Promise<ToolTest | null>;
@@ -209,7 +269,23 @@ export declare function toolStanding(tool: ProjectTool, secretsSet: readonly str
     ready: boolean;
     words: string;
 };
-/** Names of a tool's secrets that have a value (never the values). */
-export declare function secretsSetFor(repo: string, tool: ToolSpec, home?: string): string[];
+/** How a tool's runs get its credentials, in the words Settings and `toolroll integrations` share. */
+export type CredentialMode = {
+    mode: "run-token" | "held-key" | "no-key";
+    words: string;
+    detail: string | null;
+};
+export declare const CREDENTIAL_MODES: Readonly<Record<CredentialMode["mode"], Omit<CredentialMode, "mode">>>;
+/** 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 declare function credentialModeOf(spec: ToolSpec, secretsSet: readonly string[]): CredentialMode | null;
+/** Names of a tool's secrets that have a value, never the values: in the keychain, from the names kept beside them. */
+export declare function secretsSetFor(repo: string, tool: ToolSpec, state?: string): string[];
+/** Where this computer keeps tool secrets, in the words Settings and `toolroll integrations` share; `problem` when they can't be used. */
+export declare function toolSecretStorage(): {
+    kind: SecretStoreKind;
+    words: string;
+    filesOnly: boolean;
+    problem?: string;
+};
 /** A command line split into program and arguments, honouring "double" and 'single' quotes. */
 export declare function splitCommandLine(line: string): string[];