toolroll 0.5.0 → 0.7.0

package/dist/operate.js

@@ -10,6 +10,8 @@ import { billingOf, budgetHoldWords, budgetLabel, budgetStates, monthNamed, mont
 import { spendCsv } from "./spend-ui.js";
 import { buildExport, exportSummary, exportZip, writeExportFolder } from "./export.js";
 import { startBudgetAlerts } from "./budget-alerts.js";
+import { liftAuthPause, openAuthPauses, signInGate, signInWords, startSignInProbes } from "./provider-auth.js";
+import { createConnectionChecker } from "./provider-connection.js";
 import { backupFiles, backupFolderOf, backupOwner, backupNow, restoreDatabase, startBackups } from "./backup.js";
 import { pushLimitSink } from "./provider-limits.js";
 import { limitsView } from "./limits-ui.js";
@@ -121,7 +123,7 @@ import { verdictWords as proofVerdictWords, matrixWords, semanticCoverage, cover
 import { probeRepo, isVerified } from "./probe.js";
 import { diagnoseTaskDispatch, diagnosisIsDispatchable, scopeApprovedForDispatch, } from "./dispatch.js";
 import { createDecisionServer } from "./serve.js";
-import { daemonLaunchCommand, daemonStatus, installDaemon, installedLegacyDaemon, planDaemon, uninstallDaemon, awaitFreshHeartbeat, } from "./daemon.js";
+import { daemonLaunchCommand, daemonStatus, installReplacingLegacy, installedLegacyDaemon, planDaemon, uninstallDaemon, awaitFreshHeartbeat, } from "./daemon.js";
 import { bridgePass, clearBotToken, createTransport, followBridge, hashPairingCode, loadBotToken, mintPairingCode, redactToken, saveBotToken, PAIRING_TTL_MS, TOKEN_ENV, telegramHookSecret, telegramPushUrl, } from "./telegram.js";
 import { scanRepo } from "./capscan.js";
 import { computeGaps, describeCapability } from "./gaps.js";
@@ -179,6 +181,9 @@ import { updateAdmissionPaused, UPDATE_PAUSED } from "./desktop-update-gate.js";
 import { beads } from "./beads.js";
 import { githubIssues } from "./issues.js";
 import { installationStatus, renderInstallationStatus, renderTaskWait, taskWaitSnapshot } from "./lead-status.js";
+import { latestRelease, newerRelease, notifySecurityRelease, recordRunnerVersion, startUpdateChecks, updateLine } from "./releases.js";
+import { installMethod } from "./install-method.js";
+import { PACKAGE_VERSION } from "./version.js";
 /**
  * 0 done · 1 broke · 2 bad usage · 3 ran fine, the answer is no.
  *
@@ -405,6 +410,8 @@ Agents — which provider and model each phase runs on
   toolroll providers --report --runner <name> --token <t>
                                         record this machine's readiness per
                                         provider under its runner name
+  toolroll providers resume <provider> after signing in again, start its
+                                        paused tasks now
   toolroll config set chat --provider claude-subscription|codex-subscription|anthropic-api|openrouter-api
       [--model <m>] [--weekly-usd <n>] [--daily-turns <n>] --as <you> --token <t>
       membership providers reuse a logged-in local harness with no dollar
@@ -716,6 +723,8 @@ export async function runOperate(command, argv, write, options = {}) {
             ...(options.mateSeams === undefined ? {} : { mateSeams: options.mateSeams }),
             ...(options.heldCoordinator === undefined ? {} : { heldCoordinator: options.heldCoordinator }),
             ...(options.waitSleep === undefined ? {} : { waitSleep: options.waitSleep }),
+            ...(options.releaseIo === undefined ? {} : { releaseIo: options.releaseIo }),
+            ...(options.installBin === undefined ? {} : { installBin: options.installBin }),
         });
     }
     catch (error) {
@@ -913,6 +922,8 @@ async function dispatch(command, positional, flags, context) {
         case "intake":
             return intakeCommand(positional, flags, context);
         case "providers":
+            if (positional[0] === "resume")
+                return resumeProviderCommand(positional.slice(1), flags, context);
             return providersCommand(flags, context);
         case "template":
             return templateCommand(positional, flags, context);
@@ -1007,6 +1018,7 @@ async function readyCommand(flags, context) {
     const ready = store.listReady(now);
     const described = ready.map(ref => describeRef(store, ref, now));
     const dispatchableCount = described.filter(one => diagnosisIsDispatchable(one.dispatch)).length;
+    const pauses = openAuthPauses(store);
     if (json) {
         write(envelopeJson({
             ok: ready.length > 0,
@@ -1014,10 +1026,14 @@ async function readyCommand(flags, context) {
             ...(ready.length > 0 ? {} : { reason: "empty", message: "nothing is task-locally ready" }),
             count: ready.length,
             dispatchableCount,
+            signIn: pauses.map(one => ({ provider: one.provider, message: signInWords(one), since: one.openedAt })),
             tasks: described,
         }));
         return ready.length > 0 ? EXIT.ok : EXIT.refused;
     }
+    // A paused provider first: nothing on it runs until someone signs in.
+    for (const one of pauses)
+        write(signInWords(one));
     if (ready.length === 0) {
         write("Nothing is ready to dispatch.");
         return EXIT.refused;
@@ -1026,7 +1042,7 @@ async function readyCommand(flags, context) {
     for (const ref of ready) {
         const task = store.getTask(ref.externalId);
         const diagnosis = diagnoseTaskDispatch(store, ref.externalId, now);
-        write(`  ${ref.externalId}  ${task === null ? "" : task.title}${ref.assignedRunner === null ? "" : `  (reserved for ${ref.assignedRunner})`}${diagnosis === null ? "" : ` — ${diagnosis.summary.toLowerCase()}`}`);
+        write(`  ${ref.externalId}  ${task === null ? "" : task.title}${ref.assignedRunner === null ? "" : `  (reserved for ${ref.assignedRunner})`}${diagnosis === null ? "" : ` — ${diagnosis.code === "signed-out" ? diagnosis.summary : diagnosis.summary.toLowerCase()}`}`);
     }
     return EXIT.ok;
 }
@@ -1826,6 +1842,7 @@ async function buildCommand(positional, flags, context) {
         const broke = result.reason === "agent" ||
             result.reason === "agent-reported" ||
             result.reason === "no-op" ||
+            result.reason === "no-handoff" ||
             result.reason === "moved-head" ||
             result.reason === "timeout" ||
             result.reason === "git" ||
@@ -2114,12 +2131,20 @@ async function tickCommand(flags, context) {
                 resumed.push({ id: taskId, outcome: "skipped", reason: "budget", detail: budgetWords(laneBudget) });
                 continue;
             }
+            // The sign-in pause holds a resumed lane too: it waits, parked, instead of failing.
+            const laneGate = signInGate(store, [racer.provider], clock());
+            if (laneGate.waiting !== null) {
+                backToParked();
+                resumed.push({ id: taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(laneGate.waiting) });
+                continue;
+            }
             // Legacy comparison lanes carried an absolute clock. New profiles use
             // a progress watchdog and may remain alive indefinitely while useful
             // work is observable; only legacy approvals retain their cumulative
             // wall-clock contract.
             const remaining = waiting.kind === "comparison" ? null : racer.budgetMicrousd - racer.accountedMicrousd;
             if (remaining !== null && remaining <= 0) {
+                laneGate.giveBack();
                 const current = store.getContestant(racer.id);
                 if (current !== null)
                     store.casContestantState(racer.id, ["ready"], "stopped", current.generation);
@@ -2131,6 +2156,7 @@ async function tickCommand(flags, context) {
                 const laneProfile = racer.profile ?? contestantProfileOf(racer.provider, racer.model, racer.repairModel);
                 const clockCapMs = 3 * laneProfile.timeoutSeconds * 1000;
                 if (laneProfile.timeoutKind !== "idle" && store.contestantCumulativeMs(racer.id) >= clockCapMs) {
+                    laneGate.giveBack();
                     const current = store.getContestant(racer.id);
                     if (current !== null)
                         store.casContestantState(racer.id, ["ready"], "stopped", current.generation);
@@ -2141,12 +2167,14 @@ async function tickCommand(flags, context) {
             }
             const reclaimed = acquire(store, waiting.taskRef, runner, { now: clock(), token, ttlMs: leaseTtlMs });
             if (!reclaimed.ok) {
+                laneGate.giveBack();
                 backToParked();
                 continue;
             }
             const freshContest = store.getContest(waiting.id);
             if (freshContest === null || !store.casContestState(waiting.id, ["decision-wait", "racing"], "racing", freshContest.generation)) {
                 release(store, reclaimed.claim.leaseId, clock());
+                laneGate.giveBack();
                 backToParked();
                 continue;
             }
@@ -2365,7 +2393,10 @@ async function tickCommand(flags, context) {
     // gateway re-checks freshly at spawn; this cache only keeps a skipped
     // queue from probing once per task.
     const attestedThisPass = new Map();
+    let untakenTrial = null;
     for (const ref of ready) {
+        untakenTrial?.giveBack();
+        untakenTrial = null;
         // The build budget governs UNATTENDED admissions (round-1 finding 4):
         // once it is spent, the pass keeps SCANNING for attended
         // authorizations — operator-invoked sessions launch regardless —
@@ -2575,6 +2606,21 @@ async function tickCommand(flags, context) {
             dispatched.push({ id, outcome: "skipped", reason: "auth-mode", detail: brokenMode.problem });
             continue;
         }
+        // THE SIGN-IN PAUSE: a provider whose sign-in stopped working takes no
+        // new work — no claim, no run, never a substitute (a lapsed login must not
+        // reach a paid fallback) — until a run or check on it works again or a
+        // person resumes it. Other providers keep working.
+        // One task every AUTH_TRIAL_MS goes ahead as the trial: a sign-in check
+        // can say "logged in" for a session that cannot refresh, so a real run
+        // decides — it lifts the pause, or fails into the same incident.
+        const gate = signInGate(store, modeProviders, clock(), ref.id);
+        if (gate.waiting !== null) {
+            dispatched.push({ id, outcome: "skipped", reason: "signed-out", detail: signInWords(gate.waiting) });
+            continue;
+        }
+        // A trial whose task is skipped before its claim succeeds is given back
+        // at the next task (or after the pass), so the next pass may take it.
+        untakenTrial = gate;
         // The leg is the authority: what resolved must BE the leg, exactly —
         // the sealed build leg, or the parked fallback entry's own pair.
         const governingLeg = wantsPlan ? planLeg : parkedEntry !== null ? { provider: parkedEntry.provider, model: parkedEntry.model, chosen: "fallback" } : sealedBuildLeg;
@@ -2741,6 +2787,8 @@ async function tickCommand(flags, context) {
                 ? {}
                 : { maxOpenDecisions: Number(text(flags, "max-open-decisions")) }),
         });
+        if (claimed.ok)
+            untakenTrial = null;
         if (!claimed.ok) {
             // Losing a race, finding the task no longer ready, and a machine that
             // lacks what the task needs are all the system working. None fails the
@@ -3678,7 +3726,9 @@ async function tickCommand(flags, context) {
                     id,
                     outcome: "failed",
                     reason: disposition.sealed
-                        ? `${disposition.failureClass}${disposition.disposition === "backoff" ? ` — retry ${disposition.strikes}/3` : disposition.disposition === "stalled" ? " — stalled" : ""}`
+                        ? disposition.disposition === "auth-expired"
+                            ? "auth-expired — requeued, sign-in needed"
+                            : `${disposition.failureClass}${disposition.disposition === "backoff" ? ` — retry ${disposition.strikes}/3` : disposition.disposition === "stalled" ? " — stalled" : ""}`
                         : "fenced",
                     ...(result.ok ? {} : { detail: result.message.slice(0, 200) }),
                     worktree: leased.worktree.path,
@@ -3699,6 +3749,7 @@ async function tickCommand(flags, context) {
                 break;
         }
     }
+    untakenTrial?.giveBack();
     // THE CHAIN ADMISSION PASS (E3d): cycles a recognized exhaustion advanced
     // to pending-admission dispatch their NEXT approved entry here — the ONLY
     // road that runs a fallback entry. Every authority is re-derived inside
@@ -3745,6 +3796,12 @@ async function tickCommand(flags, context) {
             dispatched.push({ id: pending.taskId, outcome: "skipped", reason: "budget-unenforceable" });
             continue;
         }
+        // The sign-in pause holds a fallback entry too: the admission stays pending until its provider works.
+        const entryGate = signInGate(store, [peek.profile.provider], clock(), pending.taskRef);
+        if (entryGate.waiting !== null) {
+            dispatched.push({ id: pending.taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(entryGate.waiting) });
+            continue;
+        }
         // The FALLBACK claim (finding 4): every acquireIfReady gate — task
         // state, non-backoff holds, blockers, approved scope + mode belt,
         // capability, capacity, and quota keyed by the PINNED credential —
@@ -3767,6 +3824,7 @@ async function tickCommand(flags, context) {
                 : { maxOpenDecisions: Number(text(flags, "max-open-decisions")) }),
         });
         if (!claimed.ok) {
+            entryGate.giveBack();
             dispatched.push({ id: pending.taskId, outcome: "skipped", reason: claimed.reason });
             continue;
         }
@@ -3934,8 +3992,15 @@ async function tickCommand(flags, context) {
                 dispatched.push({ id: taskId, outcome: "skipped", reason: "budget", detail: budgetWords(continuationBudget) });
                 continue;
             }
+            // The sign-in pause holds a continuation too: its authorization stays open and it starts once the sign-in works.
+            const continuationGate = signInGate(store, [pinned.provider], clock(), parent.taskRef);
+            if (continuationGate.waiting !== null) {
+                dispatched.push({ id: taskId, outcome: "skipped", reason: "signed-out", detail: signInWords(continuationGate.waiting) });
+                continue;
+            }
             const claimed = acquireContinuation(store, continuation, runner, { now: clock(), token, ttlMs: leaseTtlMs });
             if (!claimed.ok) {
+                continuationGate.giveBack();
                 dispatched.push({ id: taskId, outcome: "skipped", reason: claimed.reason, ...("message" in claimed ? { detail: claimed.message } : {}) });
                 continue;
             }
@@ -4633,9 +4698,13 @@ async function startConsole(options) {
     server.on("close", stopMonitoring);
     // v105: budget alerts at 50/80/100 %, a pass a minute.
     server.on("close", startBudgetAlerts(context.store));
+    // A paused provider's sign-in is checked every two minutes (no model, nothing spent); the pause lifts when it works.
+    server.on("close", startSignInProbes(context.store, createConnectionChecker()));
     // Sprint 8: scheduled backups, a pass a minute; its lease also tells a restore that the console is running.
     server.on("close", startBackups(context.store, context.databaseFile));
     server.on("close", startCodexLimits(context.store));
+    // At most one anonymous look a day for a newer Toolroll (Settings → Updates can switch it off).
+    server.on("close", startUpdateChecks(context.store, dirname(context.databaseFile), PACKAGE_VERSION, installMethod(context.installBin).updateCommand, context.releaseIo ?? {}));
     const bound = server.address();
     const port = typeof bound === "object" && bound !== null ? bound.port : options.port;
     // A bind-everywhere address is not a place a browser can go: the URL
@@ -5009,6 +5078,27 @@ async function webhookCommand(positional, flags, context) {
         `Send yourself a proof: toolroll webhook test`,
     ]);
 }
+/**
+ * `toolroll providers resume <provider>` — a person says the sign-in works
+ * again (after `claude /login`, say): the provider's sign-in pause lifts, its
+ * tasks may start, and one short message says how many resumed. A pause that
+ * lifted by itself answers so; nothing is paused twice.
+ */
+function resumeProviderCommand(positional, flags, context) {
+    const { store, write, json } = context;
+    const command = "providers resume";
+    const provider = positional[0];
+    if (provider === undefined || !isProviderId(provider) || positional.length > 1) {
+        return fail(write, json, command, "usage", `Use \`toolroll providers resume <${PROVIDER_IDS.join("|")}>\`.`, EXIT.usage);
+    }
+    const who = text(flags, "as") ?? process.env["USER"] ?? "operator";
+    const lifted = liftAuthPause(store, provider, "person", who, context.clock());
+    if (lifted === null)
+        return succeed(write, json, command, { provider, resumed: 0, paused: false }, () => [`${provider} is not paused.`]);
+    return succeed(write, json, command, { provider, resumed: lifted.resumed, paused: false }, () => [
+        `${provider} resumed — ${lifted.resumed} ${lifted.resumed === 1 ? "task" : "tasks"} can start again.`,
+    ]);
+}
 /**
  * `toolroll providers` — identification, never integration theater.
  *
@@ -6884,18 +6974,12 @@ async function daemonCommand(positional, flags, context) {
             write("Nothing was written. Re-run without --dry-run to install.");
             return EXIT.ok;
         }
-        if (legacy !== null) {
-            try {
-                await uninstallDaemon(legacy, supervise);
-            }
-            catch (error) {
-                return fail(write, json, "daemon install", "supervisor", `could not stop ${legacy.label}, the same watch under its older name: ${error.message}`, EXIT.failed);
-            }
-        }
-        const installed = await installDaemon(plan, token, supervise);
+        const installed = await installReplacingLegacy(plan, token, legacy, supervise);
         if (!installed.ok) {
             return fail(write, json, "daemon install", "supervisor", installed.message, EXIT.failed);
         }
+        // The legacy watch beat for this runner until it stopped: only a beat after that proves the new one.
+        const readySince = legacy === null ? heartbeatBefore : store.getRunner(runnerName)?.runner.heartbeatAt ?? null;
         const started = await daemonStatus(plan, supervise);
         if (started.state !== "running") {
             return fail(write, json, "daemon install", "not-running", `the service was installed but did not stay running (${started.detail}) — read ${plan.logPath}; no work will be claimed until this is fixed`, EXIT.failed);
@@ -6906,7 +6990,7 @@ async function daemonCommand(positional, flags, context) {
         // readiness receipt that proves this service reached the work loop —
         // a FRESH one when the service was (re)started; the one already
         // standing when a healthy running service was left alone.
-        const fresh = await awaitFreshHeartbeat(store, runnerName, installed.action === "running" ? null : heartbeatBefore);
+        const fresh = await awaitFreshHeartbeat(store, runnerName, installed.action === "running" && legacy === null ? null : readySince);
         const liveRunner = fresh.ok ? store.getRunner(runnerName)?.runner ?? null : null;
         if (liveRunner === null) {
             const macHint = process.platform === "darwin" && repo.startsWith(join(homedir(), "Documents"))
@@ -7013,6 +7097,7 @@ async function runWatchLoop(args) {
     // attributes to this episode by runner and window, and `brief
     // --latest-watch` bounds itself to exactly it.
     store.startWatchEpisode({ repo, runner, incarnation }, new Date());
+    recordRunnerVersion(dirname(context.databaseFile), runner, PACKAGE_VERSION, new Date());
     args.onReady?.();
     // A false renewal is FATAL (arc 2 finding 15): the lease or the
     // credential is gone, and admitting one more pass would be work done for
@@ -8002,6 +8087,7 @@ async function upCommand(flags, context) {
         });
     };
     observeReadiness();
+    recordRunnerVersion(dirname(context.databaseFile), runnerName, PACKAGE_VERSION, clock());
     const runnerHeartbeat = setInterval(() => {
         const beat = heartbeatRunner(store, runnerName, runnerToken, clock());
         if (!beat.ok && !stopping) {
@@ -8887,7 +8973,7 @@ function readPaths(flags, backend) {
     return backend === BUILT_IN ? [BUILT_IN] : [];
 }
 // ---- authoring ------------------------------------------------------------
-function statusCommand(positional, flags, context) {
+async function statusCommand(positional, flags, context) {
     const command = "status";
     const allowed = new Set(["db", "json"]);
     for (const name of flags.keys()) {
@@ -8897,7 +8983,15 @@ function statusCommand(positional, flags, context) {
     if (positional.length > 0)
         return fail(context.write, context.json, command, "usage", "Use `toolroll status [--json]`.", EXIT.usage);
     const status = installationStatus(context.store, context.clock());
-    return succeed(context.write, context.json, command, { ...status }, () => renderInstallationStatus(status));
+    // One line, only when a newer Toolroll exists; offline or switched off says nothing.
+    const current = PACKAGE_VERSION;
+    const method = installMethod(context.installBin);
+    const release = newerRelease(await latestRelease(dirname(context.databaseFile), { now: context.clock, ...context.releaseIo }), current);
+    if (release !== null)
+        notifySecurityRelease(context.store, release, current, method.updateCommand, context.clock());
+    const line = updateLine(release, current, method.updateCommand);
+    const update = release === null ? {} : { update: { current, latest: release.version, security: release.security, updateCommand: method.updateCommand, url: release.url } };
+    return succeed(context.write, context.json, command, { ...status, ...update }, () => [...renderInstallationStatus(status), ...(line === null ? [] : [line])]);
 }
 async function waitTask(positional, flags, context) {
     const command = "task wait";

package/dist/provider-auth.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Sign-in pauses: when a provider's sign-in (or API key) stops working, its
+ * runs fail in seconds and every retry fails the same way. So an
+ * `auth-expired` run takes no strike and no retry: its task goes back to the
+ * queue, dispatch for THAT provider pauses (the others keep working), and a
+ * person is told once per incident, on every connected messaging channel, what
+ * to run. The pause lifts when a run or a sign-in probe on that provider
+ * succeeds, or when a person resumes it; one short message says so.
+ *
+ * One row per incident. At most one open incident per provider (a partial
+ * unique index), so however many runs hit it, one notification goes out:
+ * its key is `signin:auth-expired:<provider>:<ordinal>:<person>`, the ordinal
+ * being the incident's own number for that provider.
+ */
+import type { Store } from "./store.js";
+import { type ProviderId } from "./provider.js";
+/** Every sign-in message's dedupe key starts here: `signin:<kind>:<provider>:<ordinal>:<person>`.
+ * Not a lifecycle (`life:`) key: those are progress chatter, and an undelivered
+ * one stays out of the attention list — this one needs a person. */
+export declare const SIGN_IN_KEY_PREFIX = "signin:";
+export declare const PROVIDER_AUTH_SCHEMA = "\nCREATE TABLE IF NOT EXISTS provider_auth_pause (\n  id          INTEGER PRIMARY KEY AUTOINCREMENT,\n  provider    TEXT NOT NULL,\n  ordinal     INTEGER NOT NULL,\n  auth_mode   TEXT NOT NULL DEFAULT 'subscription' CHECK (auth_mode IN ('subscription', 'api-key')),\n  opened_at   TEXT NOT NULL,\n  first_run   INTEGER,\n  task_ref    INTEGER,\n  runs        INTEGER NOT NULL DEFAULT 1,\n  -- 1 once a sign-in probe during this pause said the provider is signed out:\n  -- only a probe that then sees it signed in again may lift the pause.\n  probe_saw_out INTEGER NOT NULL DEFAULT 0,\n  lifted_at   TEXT,\n  lifted_by   TEXT,\n  lifted_how  TEXT CHECK (lifted_how IS NULL OR lifted_how IN ('run', 'probe', 'person')),\n  resumed     INTEGER,\n  -- The last task let through as a trial while paused: a sign-in check can\n  -- say \"logged in\" for a session that no longer works, so a real run decides.\n  last_trial_at TEXT,\n  UNIQUE (provider, ordinal)\n);\nCREATE UNIQUE INDEX IF NOT EXISTS provider_auth_pause_open ON provider_auth_pause (provider) WHERE lifted_at IS NULL;\n";
+export type AuthPause = {
+    id: number;
+    provider: ProviderId;
+    ordinal: number;
+    authMode: "subscription" | "api-key";
+    openedAt: string;
+    firstRun: number | null;
+    taskRef: number | null;
+    runs: number;
+};
+export declare function providerName(provider: string): string;
+/** The plain reason: "Claude needs you to sign in again". */
+export declare function signInReason(pause: Pick<AuthPause, "provider" | "authMode">): string;
+/** What to run, as a command. */
+export declare function signInCommand(pause: Pick<AuthPause, "provider" | "authMode">): string;
+/** One line for status, ready and the console. */
+export declare function signInWords(pause: AuthPause): string;
+/** The open pause for a provider, or null. */
+export declare function authPauseOf(store: Store, provider: string): AuthPause | null;
+/**
+ * SQL: whether the pause `pause` (a provider_auth_pause alias) is on one of
+ * the task_ref `taskRef`'s current providers — its pins, its working profile,
+ * route legs and fallback entries — so a task re-routed to another provider
+ * stops saying it waits on the old one. A task that names none yet (an
+ * unpinned planner, whose agent comes from configuration) keeps what the gate
+ * found.
+ */
+export declare function pauseOnTaskProviders(pause: string, taskRef: string): string;
+/** The open pause the dispatch gate last left this task waiting on, while it
+ * is still on one of the task's providers; or null. */
+export declare function authWaitOf(store: Store, taskRef: number): AuthPause | null;
+/** Every open pause, oldest first. */
+export declare function openAuthPauses(store: Store): AuthPause[];
+/**
+ * Record an auth-expired run against its provider's pause, opening the
+ * incident (and its one notification) when none is open. Called inside the
+ * run's own failure transaction. Returns whether this run opened it.
+ */
+export declare function pauseForAuth(store: Store, args: {
+    provider: string;
+    authMode: "subscription" | "api-key" | null;
+    runId: number;
+    taskRef: number;
+    now: Date;
+}): {
+    opened: boolean;
+    pause: AuthPause;
+};
+/**
+ * Lift a provider's open pause — a run or probe on it succeeded, or a person
+ * resumed it — and send the one short "signed in again" message. Returns the
+ * number of tasks its incident sent back to the queue, or null when nothing
+ * was paused.
+ */
+export declare function liftAuthPause(store: Store, provider: string, how: "run" | "probe" | "person", by: string, now: Date, 
+/** For a run: when it started. A run that began before the pause opened proves nothing about the sign-in now. */
+runStartedAt?: Date): {
+    resumed: number;
+    pause: AuthPause;
+} | null;
+/**
+ * What a non-spending sign-in probe said. A probe lifts the pause only after
+ * one during the same pause saw the provider signed out: a CLI that reports
+ * "logged in" while its session cannot refresh must not lift and re-open the
+ * pause over and over.
+ */
+export declare function noteSignInProbe(store: Store, provider: string, state: string, now: Date): {
+    resumed: number;
+} | null;
+/** How often a paused provider lets one task through as a trial. */
+export declare const AUTH_TRIAL_MS: number;
+/** A trial taken: the pause, when it was taken, and the trial time it replaced. */
+export type AuthTrial = {
+    pauseId: number;
+    takenAt: string;
+    previous: string | null;
+};
+/**
+ * Whether this task may go ahead as the paused provider's trial: at most one
+ * every AUTH_TRIAL_MS. A trial that works lifts the pause (its run proves the
+ * sign-in); one that fails the same way only counts against the open
+ * incident, so nobody is told twice. Null when no trial is due.
+ */
+export declare function claimAuthTrial(store: Store, pause: AuthPause, now: Date): AuthTrial | null;
+/** Give a trial back when its task never started (its claim failed), so the next pass may take it. */
+export declare function giveBackAuthTrial(store: Store, trial: AuthTrial): void;
+/** What the sign-in gate decided: the open pause the work waits on, or null
+ * when it may go ahead; and, when it goes ahead as a pause's trial, how to
+ * give that trial back if its claim then fails. */
+export type SignInGate = {
+    waiting: AuthPause | null;
+    giveBack: () => void;
+};
+/**
+ * The sign-in gate every road that starts an agent asks before it claims
+ * anything: the tick's queue, and the roads beside it (fallback entries,
+ * attended continuations, contest resumes). Waits when a provider is paused,
+ * unless this is the pause's one trial. A waiting task is noted on its
+ * task_ref, so the work index says exactly what the gate decided; a task let
+ * through is un-noted. A road whose claim fails after a trial calls giveBack.
+ */
+export declare function signInGate(store: Store, providers: readonly string[], now: Date, taskRef?: number): SignInGate;
+/** The loop beside the console: every two minutes, probe each paused
+ * provider's sign-in (no model, nothing spent) and lift the pause when it
+ * works again. Nothing is probed while nothing is paused. */
+export declare function startSignInProbes(store: Store, check: (provider: ProviderId, fresh?: boolean) => Promise<{
+    state: string;
+}>, everyMs?: number): () => void;
+/** The console's view of every open pause: title, command, one action. */
+export declare function signInNotices(store: Store): {
+    provider: string;
+    title: string;
+    command: string;
+    detail: string;
+    resumeLabel: string;
+    resumeHref: string;
+}[];