toolroll 0.5.0 → 0.7.0

package/dist/dispose.js

@@ -28,6 +28,7 @@ const TICK_FAILURE_REASONS = new Set([
     "agent",
     "agent-reported",
     "no-op",
+    "no-handoff",
     "moved-head",
     "moved-branch",
     "timeout",
@@ -49,6 +50,7 @@ const STANDALONE_BROKE_REASONS = new Set([
     "agent",
     "agent-reported",
     "no-op",
+    "no-handoff",
     "moved-head",
     "timeout",
     "git",
@@ -339,13 +341,15 @@ function disposeBuildOutcomeLocked(context, result) {
         // classification trusts only what the machine itself observed.
         const failureClass = result.reason === "agent-reported"
             ? "agent-reported"
-            : result.reason === "no-op" || result.reason === "moved-head" || result.reason === "moved-branch"
-                ? "no-op"
-                : result.reason === "timeout" || result.reason === "git" || result.reason === "provider-init" || result.reason === "setup" || result.reason === "stopped" || result.reason === "provider-unattested" || result.reason === "provider-protocol"
-                    ? "retryable-infra"
-                    : result.reason === "commit-failure"
-                        ? "commit-failure"
-                        : "unknown";
+            : result.reason === "no-handoff"
+                ? "no-handoff"
+                : result.reason === "no-op" || result.reason === "moved-head" || result.reason === "moved-branch"
+                    ? "no-op"
+                    : result.reason === "timeout" || result.reason === "git" || result.reason === "provider-init" || result.reason === "setup" || result.reason === "stopped" || result.reason === "provider-unattested" || result.reason === "provider-protocol"
+                        ? "retryable-infra"
+                        : result.reason === "commit-failure"
+                            ? "commit-failure"
+                            : "unknown";
         // The attempt's ending, in words, on the run itself: the class is what
         // the strikes count, the message is what a person reads (an agent's
         // own verdict was already recorded by the builder under the same key).

package/dist/exhaustion.d.ts

@@ -20,6 +20,10 @@
  *   class. Exit code, bare rate-limit prose, timeout, notFound, stderr,
  *   and zero tokens NEVER independently establish exhaustion.
  * - Everything unmatched is `unknown` — the ordinary failure road.
+ * - A sign-in that no longer works (`auth-expired`) is recognized FIRST,
+ *   for every provider and version: an expired or revoked login is not a
+ *   property of a CLI version, and retrying it only burns attempts. It is
+ *   never fallback-eligible — a lapsed login must not reach a paid key.
  */
 import type { ProviderId } from "./provider.js";
 export type TerminalClass = 
@@ -29,6 +33,9 @@ export type TerminalClass =
  | "credits-depleted"
 /** Temporary throttling NOT tied to the usage cap — backoff, NEVER paid fallback. */
  | "transient-throttle"
+/** The provider's sign-in or API key no longer works — NO retry, NO
+ * fallback: dispatch for that provider pauses until someone signs in. */
+ | "auth-expired"
 /** A definite non-exhaustion terminal (ordinary failure). */
  | "not-exhausted"
 /** No structural signal matched — the ordinary failure/strike road. */
@@ -82,4 +89,11 @@ export declare function classifyTerminal(args: {
     version: string | null;
     authMode: "subscription" | "api-key";
     terminal: StructuralTerminal | null;
+    /** What a run that failed within seconds, having produced nothing, said
+     * on its way out (stderr and unstructured stdout) — read ONLY for the
+     * sign-in signal: a CLI that is not logged in often exits before its
+     * structured stream begins. */
+    earlyExit?: string | null;
 }): TerminalClass;
+/** Whether a provider's own words say its sign-in or key no longer works. */
+export declare function isAuthFailure(text: string): boolean;

package/dist/exhaustion.js

@@ -20,6 +20,10 @@
  *   class. Exit code, bare rate-limit prose, timeout, notFound, stderr,
  *   and zero tokens NEVER independently establish exhaustion.
  * - Everything unmatched is `unknown` — the ordinary failure road.
+ * - A sign-in that no longer works (`auth-expired`) is recognized FIRST,
+ *   for every provider and version: an expired or revoked login is not a
+ *   property of a CLI version, and retrying it only burns attempts. It is
+ *   never fallback-eligible — a lapsed login must not reach a paid key.
  */
 /** The two classes that may authorize a fallback advance. */
 export const FALLBACK_ELIGIBLE = new Set([
@@ -111,6 +115,12 @@ export function classMatchesAuthMode(cls, authMode) {
  */
 export function classifyTerminal(args) {
     const { provider, version, authMode, terminal } = args;
+    // A sign-in that no longer works, before anything else and for any
+    // provider or version: no fixture is needed to know a login is gone.
+    if (terminal !== null && terminal.failed === true && isAuthFailure(`${terminal.code ?? ""}\n${terminal.text ?? ""}`))
+        return "auth-expired";
+    if (typeof args.earlyExit === "string" && isAuthFailure(args.earlyExit))
+        return "auth-expired";
     if (terminal === null)
         return "unknown";
     // The classifier's contract permits failed:false, but a non-failure
@@ -139,3 +149,28 @@ export function classifyTerminal(args) {
     // unknown above).
     return "not-exhausted";
 }
+/**
+ * The sign-in signals, provider-neutral: Claude's expired or unrefreshable
+ * OAuth session and its "Please run /login", an API key the provider calls
+ * invalid or revoked, Codex's and Gemini's "not logged in", and an HTTP 401
+ * the harness reports as its terminal. Ordinary failures (a test that
+ * failed, a timeout, a usage limit) match none of these.
+ */
+const AUTH_FAILURE = [
+    // Provider-specific phrasings only: a build's own output (a login feature's
+    // tests, an HTTP 401 in a log) must never read as the agent's sign-in.
+    /\bOAuth (?:session|token)\b[^\n]{0,80}\b(?:expired|could not be refreshed|revoked|invalid)/i,
+    /\bFailed to authenticate\b[^\n]{0,40}\b(?:OAuth|token|session|credentials|API key)/i,
+    /\bPlease run \/login\b/i,
+    /\binvalid[ _-](?:x-)?api[ _-]?key\b/i,
+    /\binvalid bearer token\b/i,
+    /\bapi[ _-]?key\b[^\n]{0,40}\b(?:is )?(?:invalid|revoked|expired|not valid)\b/i,
+    /"type"\s*:\s*"authentication_error"/i,
+    /\bMissing bearer (?:or basic )?authentication\b/i,
+    /^Not logged in\b/m,
+];
+/** Whether a provider's own words say its sign-in or key no longer works. */
+export function isAuthFailure(text) {
+    const bounded = text.slice(0, 8192);
+    return AUTH_FAILURE.some(re => re.test(bounded));
+}

package/dist/install-method.d.ts

@@ -0,0 +1,17 @@
+/**
+ * How this Toolroll was installed, read from where its bin really lives, and
+ * the one command that updates it that way. Only the path is read: nothing is
+ * run and nothing leaves the computer.
+ */
+export type InstallKind = "npm" | "pnpm" | "bun" | "yarn" | "homebrew" | "npx" | "source";
+export type InstallMethod = {
+    kind: InstallKind;
+    updateCommand: string;
+};
+export declare const UPDATE_COMMANDS: Record<InstallKind, string>;
+export type InstallProbe = {
+    realpath?: (path: string) => string;
+    exists?: (path: string) => boolean;
+};
+/** The install method of the bin at `bin` (the running one by default). Unknown shapes read as npm, the common case. */
+export declare function installMethod(bin?: string | undefined, probe?: InstallProbe): InstallMethod;

package/dist/install-method.js

@@ -0,0 +1,61 @@
+/**
+ * How this Toolroll was installed, read from where its bin really lives, and
+ * the one command that updates it that way. Only the path is read: nothing is
+ * run and nothing leaves the computer.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const UPDATE_COMMANDS = {
+    npm: "npm install -g toolroll@latest",
+    pnpm: "pnpm add -g toolroll@latest",
+    bun: "bun add -g toolroll@latest",
+    yarn: "yarn global add toolroll@latest",
+    homebrew: "brew upgrade ap9000/toolroll/toolroll",
+    npx: "npx toolroll@latest",
+    source: "git pull && npm install && npm run build",
+};
+/** The install method of the bin at `bin` (the running one by default). Unknown shapes read as npm, the common case. */
+export function installMethod(bin = process.argv[1], probe = {}) {
+    const kind = installKind(bin, probe);
+    return { kind, updateCommand: UPDATE_COMMANDS[kind] };
+}
+function installKind(bin, probe) {
+    if (bin === undefined || bin === "")
+        return "npm";
+    let real = bin;
+    try {
+        real = (probe.realpath ?? realpathSync)(bin);
+    }
+    catch {
+        // A bin that cannot be resolved is judged by the path it was run by.
+    }
+    const path = real.replace(/\\/g, "/");
+    // A plane deployed from a checkout by scripts/deploy-browser.mjs runs from staged-upgrades/browser-*: it updates
+    // by deploying from source, never from npm.
+    if (path.includes("/staged-upgrades/browser-"))
+        return "source";
+    if (/\/Cellar\/toolroll\//i.test(path))
+        return "homebrew";
+    if (path.includes("/_npx/"))
+        return "npx";
+    if (/\/\.bun\/install\/global\//.test(path))
+        return "bun";
+    if (/\/pnpm\/global\//i.test(path))
+        return "pnpm";
+    if (/\/(?:\.config\/yarn|yarn\/data)\/global\//i.test(path))
+        return "yarn";
+    if (path.includes("/node_modules/"))
+        return "npm";
+    // Not inside node_modules: a checkout, when the package's own folder is a git working copy.
+    const exists = probe.exists ?? existsSync;
+    let folder = dirname(real);
+    for (let depth = 0; depth < 4; depth++) {
+        if (exists(join(folder, "package.json")) && exists(join(folder, ".git")))
+            return "source";
+        const parent = dirname(folder);
+        if (parent === folder)
+            break;
+        folder = parent;
+    }
+    return "npm";
+}

package/dist/invoke.js

@@ -19,6 +19,7 @@
 import { adapterFor, auditOf } from "./provider.js";
 import { readProviderKey, readAuthModeStrict, PROVIDER_KEY_ENV, OWN_KEY_ENV } from "./keys.js";
 import { classifyTerminal } from "./exhaustion.js";
+import { liftAuthPause } from "./provider-auth.js";
 import { attestProvider } from "./attest.js";
 import { run as runCommand, runOwnerTag, startClaudeHeldSession } from "./exec.js";
 import { currentContainment } from "./containment.js";
@@ -32,6 +33,9 @@ import { billingOf, claudeBillingFrom, seenBilling } from "./spend.js";
 /** The claude binary name — kept for the legacy quota rows and tests that
  * describe history; new code carries a resolved AgentSpec instead. */
 export const PROVIDER_BINARY = "claude";
+/** "Within seconds": how soon a silent failed run must end for its stderr to
+ * be read for the sign-in signal. */
+const AUTH_EARLY_EXIT_MS = 30_000;
 /**
  * A provider can run the repository's own CLI. In a self-hosting build that
  * must never mean "open the database that launched me": a migration from the
@@ -306,6 +310,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         ? await codexLoginBilling(attested !== null ? attested.executable : adapter.binary, [...(runOptions.omitEnv ?? []), ...adapter.extraOmitEnv, ...ownKeyEnv])
         : null;
     let result;
+    const spawnedAt = Date.now();
     try {
         // Under the stop watch (v52): the run's stop row is re-read while the
         // provider runs, and a stop kills THIS run's process group through the
@@ -438,11 +443,20 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // no version here yet (attested === null), so they classify fail-closed
     // until their exhaustion fixture — and the version proving it needs — is
     // captured and reviewed.
+    // A run that failed within seconds having produced nothing is read for
+    // the sign-in signal too: a CLI that is not logged in often says so on
+    // stderr before its structured stream starts.
+    const quietEarlyExit = result.code !== 0 && !result.timedOut && !result.notFound &&
+        Date.now() - spawnedAt <= AUTH_EARLY_EXIT_MS &&
+        envelope.promptConsumed !== true && (envelope.tokensOut ?? 0) === 0;
     const terminalClass = classifyTerminal({
         provider: spec.provider,
         version: attested === null ? null : attested.version,
         authMode,
         terminal: envelope.structuralTerminal,
+        // stderr and plain stdout only: a JSON event line can carry the agent's
+        // own command output (codex aggregated_output), never its sign-in.
+        earlyExit: quietEarlyExit ? `${result.stderr.slice(-4096)}\n${plainLines(result.stdout).slice(-4096)}` : null,
     });
     store.stampTerminalClass(runId, authMode, terminalClass);
     // Contradictory structural identity is a provider protocol failure, not
@@ -519,6 +533,14 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             finalMessage: envelope.finalMessage,
         };
     }
+    // A run that worked proves its provider's sign-in works: a sign-in pause
+    // on it lifts, and its waiting tasks may start again.
+    if (result.code === 0 && envelope.structuralTerminal === null && envelope.promptConsumed !== false) {
+        try {
+            liftAuthPause(store, spec.provider, "run", `run #${runId}`, clock(), new Date(spawnedAt));
+        }
+        catch { /* the pause stays until the next proof */ }
+    }
     return {
         kind: "ran",
         outcome: {
@@ -778,3 +800,7 @@ async function codexLoginBilling(binary, omitEnv) {
         return null;
     }
 }
+/** The lines of a harness's stdout that are not JSON events. */
+function plainLines(stdout) {
+    return stdout.split("\n").filter(line => !line.trimStart().startsWith("{")).join("\n");
+}

package/dist/lead-status.d.ts

@@ -62,6 +62,13 @@ export type InstallationStatus = {
         plan: string | null;
         observedAt: string;
     })[];
+    /** Providers whose sign-in stopped working: their dispatch is paused. */
+    signIn: {
+        provider: string;
+        reason: string;
+        command: string;
+        since: string;
+    }[];
 };
 /** One indexed observation for `task wait`. `watchedRun` is the attempt the
  * caller first saw. Each poll follows the task's newest attempt from there, so

package/dist/lead-status.js

@@ -2,6 +2,7 @@
  * this module never opens a repository, retained evidence, or a live log. */
 import { COMPLETION_ACTION } from "./result-completion.js";
 import { windowLabel } from "./provider-limits.js";
+import { openAuthPauses, signInCommand, signInReason } from "./provider-auth.js";
 import { BUILT_IN, checkSuitesOf } from "./store.js";
 const maybeNumber = (value) => value === null || value === undefined || !Number.isInteger(Number(value)) ? null : Number(value);
 const CHECK_COLUMNS = "rc.status AS check_status, rc.exit_code AS check_exit_code, rc.suites_json AS check_suites_json";
@@ -192,8 +193,16 @@ export function installationStatus(store, now) {
     WHERE task.state = 'queued'`).all(now.toISOString(), BUILT_IN);
     const reasons = new Map();
     const queuedTasks = [];
+    const pauses = openAuthPauses(store);
     for (const row of queuedRows) {
-        const reason = queueReason(row);
+        let reason = queueReason(row);
+        if (reason === "ready for a worker" && pauses.length > 0) {
+            const scope = store.getScope(String(row["id"]));
+            const provider = scope?.approvedProfile?.provider ?? scope?.profile?.provider;
+            const paused = pauses.find(one => one.provider === provider);
+            if (paused !== undefined)
+                reason = signInReason(paused);
+        }
         reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
         if (queuedTasks.length < 8)
             queuedTasks.push({ task: String(row["id"]), reason });
@@ -243,10 +252,14 @@ export function installationStatus(store, now) {
             reached: Number(row["reached"]) === 1,
             observedAt: String(row["observed_at"]),
         })),
+        signIn: pauses.map(one => ({ provider: one.provider, reason: signInReason(one), command: signInCommand(one), since: one.openedAt })),
     };
 }
 export function renderInstallationStatus(status) {
     const lines = [];
+    // A paused provider comes first: it is the one thing a person must do.
+    for (const one of status.signIn)
+        lines.push(`${one.reason} — run \`${one.command}\`. Its tasks wait until then.`);
     lines.push(status.running.count === 0 ? "Running: none" : `Running: ${status.running.count} — ${status.running.tasks.map(one => `${one.task} (#${one.run}, ${one.phase})`).join(", ")}${status.running.count > status.running.tasks.length ? ", …" : ""}`);
     lines.push(status.queued.count === 0 ? "Queued: none" : `Queued: ${status.queued.count} — ${status.queued.tasks.map(one => `${one.task} (${one.reason})`).join(", ")}${status.queued.count > status.queued.tasks.length ? ", …" : ""}`);
     lines.push(status.waitingForReview.count === 0 ? "Ready for review: none" : `Ready for review: ${status.waitingForReview.count} — ${status.waitingForReview.results.map(one => `${one.task} (#${one.run})`).join(", ")}${status.waitingForReview.count > status.waitingForReview.results.length ? ", …" : ""}`);
@@ -276,7 +289,7 @@ export function renderInstallationStatus(status) {
             lines.push(`Plan windows: ${provider} — ${detail}`);
         }
     }
-    return lines.slice(0, 12);
+    return lines.slice(0, 12 + status.signIn.length);
 }
 export function renderTaskWait(snapshot, outcome = snapshot.outcome) {
     const check = snapshot.check.status === "unknown" ? "checks unknown" : snapshot.check.status === "not-run" ? "checks not run" : `checks ${snapshot.check.status}${snapshot.check.exitCode === null ? "" : ` (exit ${snapshot.check.exitCode})`}`;

package/dist/mate.js

@@ -410,10 +410,13 @@ export async function runMateTurn(input) {
             const outcome = executeMateTool({ store, who, now: clock(), draft, selectEvidence, step: steps, readDecisions, readResults, ...(input.evidenceRoot === undefined ? {} : { evidenceRoot: input.evidenceRoot }), ...(input.mediaDelivery === undefined ? {} : { mediaDelivery: input.mediaDelivery }) }, call.name, call.args, view);
             if (READ_TOOLS.has(call.name))
                 reads++;
-            // Opt-in, local diagnostics for end-to-end runs: what the lead asked of each tool and what came back, keys blanked.
+            // Opt-in, local diagnostics for end-to-end runs: what the lead asked of each tool and what came back (its start), keys
+            // blanked. Each line stays whole JSON so a run can assert on what a tool returned rather than on the model's words.
             if (envValue(process.env, "MATE_TRACE") === "1") {
                 const blanked = (_, value) => typeof value === "string" ? redactSecretAssignments(redactSecretLines(value, scanForSecrets(value))) : value;
-                process.stderr.write(`mate-trace ${JSON.stringify({ turn: turnId, step: steps, tool: call.name, args: call.args, ok: outcome.ok, ...(outcome.ok ? {} : { message: outcome.message }) }, blanked).slice(0, 4000)}\n`);
+                const args = JSON.stringify(call.args, blanked).slice(0, 1500);
+                const result = JSON.stringify(outcome.ok ? outcome.body : null, blanked)?.slice(0, 2000) ?? null;
+                process.stderr.write(`mate-trace ${JSON.stringify({ turn: turnId, step: steps, tool: call.name, args: args.length < 1500 ? call.args : args, ok: outcome.ok, ...(outcome.ok ? { result } : { message: outcome.message }) }, blanked)}\n`);
             }
             history.push({ role: "tool", callId: call.id, name: call.name, result: capped(outcome.ok ? outcome.body : { ok: false, message: outcome.message }) });
         }

package/dist/operate.d.ts

@@ -6,6 +6,7 @@ import { type TelegramTransport } from "./telegram.js";
 import { type MateCliSeams } from "./mate-cli.js";
 import { type PublishExec } from "./publish.js";
 import { type Runner as CommandRunner } from "./builder.js";
+import { type ReleaseIo } from "./releases.js";
 export type Write = (line: string) => void;
 /**
  * 0 done · 1 broke · 2 bad usage · 3 ran fine, the answer is no.
@@ -33,6 +34,10 @@ export type OperateOptions = {
     additionalProjectRepos?: () => readonly string[];
     /** Overridden by tests and by an agent that wants its own queue. */
     databaseFile?: string;
+    /** Injected by tests: how `status` and the console ask for the latest release. */
+    releaseIo?: ReleaseIo;
+    /** Injected by tests: the bin whose real path says how Toolroll was installed. */
+    installBin?: string;
     openDatabase?: (file: string) => Store;
     now?: Date;
     /**