toolroll 0.9.5 → 0.9.7

package/dist/result-follow-ups.js

@@ -0,0 +1,333 @@
+/** Follow-ups on any result: "Run checks" and "Add tests".
+ *
+ * Run checks runs the project's quick or full check on the result's exact
+ * commit, in a fresh checkout, after the build has finished. A person (or a
+ * pull request opening) asks; the ask is a ledger entry; a worker runs it
+ * once and seals its log and a receipt beside the result. A pass upgrades
+ * what the result's Checks row says; a failure stays visible. Nothing here
+ * rewrites the build's own check or reruns crew work.
+ *
+ * Add tests files a small task, unapproved like any other filing, to write
+ * tests for that change. */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as execRun } from "./exec.js";
+import { approvedCommandShell, SETUP_ENV_ALLOWLIST, SETUP_ENV_DENYLIST } from "./builder.js";
+import { runWithIsolatedDatabase } from "./child-database.js";
+import { boundStreamHeadTail, readVerifiedArtifact, redactSecretLines, scanForSecrets, storeEvidence } from "./evidence.js";
+import { CHECK_LEVEL_WORDS, checkCommandFor, quickVerifyKey, repoClause, repoOfRun, runCheckLevel } from "./check-levels.js";
+import { fileTaskProposal } from "./proposal.js";
+export const CHECKS_REQUESTED = "checks requested";
+export const CHECKS_STARTED = "checks started";
+export const CHECKS_FINISHED = "checks finished";
+export const FOLLOW_UP_LOG = "follow-up check log v1";
+export const FOLLOW_UP_RECEIPT = "follow-up check receipt v1";
+export const ADD_TESTS_ACTION = "tests task filed";
+/** A started check with no result after its time limit and this grace didn't finish. */
+const ABANDONED_GRACE_MS = 10 * 60_000;
+const refuse = (reason, message) => ({ ok: false, reason, message });
+function ledgerFor(store, runId) {
+    const [where, params] = repoClause(repoOfRun(store, runId));
+    return store.handle.prepare(`SELECT id, actor, at, outcome, detail, action FROM action_ledger WHERE ${where} AND run_id = ? AND action IN (?, ?, ?) ORDER BY id`)
+        .all(...params, runId, CHECKS_REQUESTED, CHECKS_STARTED, CHECKS_FINISHED)
+        .map(row => ({ id: Number(row["id"]), actor: String(row["actor"]), at: String(row["at"]), outcome: String(row["outcome"]),
+        detail: row["detail"] === null ? null : String(row["detail"]), action: String(row["action"]) }));
+}
+/** Every follow-up check a result has had, oldest first, as the ledger and its sealed receipts say. */
+export function followUpChecksOf(store, runId, now = new Date(), root) {
+    const rows = ledgerFor(store, runId);
+    const receipts = new Map();
+    if (root !== undefined) {
+        for (const artifact of store.artifactsFor(runId).filter(one => one.kind === "structured-output" && one.capture === FOLLOW_UP_RECEIPT)) {
+            const read = readVerifiedArtifact(root, artifact);
+            if (!read.ok)
+                continue;
+            try {
+                const body = JSON.parse(read.content.toString("utf8"));
+                if (typeof body.request !== "number")
+                    continue;
+                receipts.set(body.request, { ran: body.result?.ran === true, exitCode: typeof body.result?.exitCode === "number" ? body.result.exitCode : null,
+                    log: typeof body.log?.artifactId === "number" ? body.log.artifactId : null });
+            }
+            catch { /* an unreadable receipt upgrades nothing */ }
+        }
+    }
+    return rows.filter(row => row.action === CHECKS_REQUESTED && (row.outcome === "quick" || row.outcome === "full")).map(request => {
+        const [head = "", why = "person", digest = ""] = (request.detail ?? "").split(" · ");
+        const started = rows.find(row => row.action === CHECKS_STARTED && row.outcome === String(request.id)) ?? null;
+        const finished = rows.find(row => row.action === CHECKS_FINISHED && row.outcome.startsWith(`${request.id}:`)) ?? null;
+        const base = { request: request.id, runId, level: request.outcome, head, digest, actor: request.actor, at: request.at,
+            why: why === "pull-request" ? "pull-request" : "person", exitCode: null, logArtifactId: null, note: null };
+        if (finished !== null) {
+            const status = finished.outcome.slice(String(request.id).length + 1);
+            const sealed = receipts.get(request.id) ?? null;
+            // With the evidence at hand, only a sealed receipt can say passed.
+            if (status === "passed" && root !== undefined && (sealed === null || !sealed.ran || sealed.exitCode !== 0)) {
+                return { ...base, state: "not-run", note: "The saved check result could not be verified." };
+            }
+            const exit = /exit (\d+)/.exec(finished.detail ?? "");
+            return { ...base, state: status === "passed" ? "passed" : status === "failed" ? "failed" : "not-run",
+                exitCode: exit === null ? sealed?.exitCode ?? null : Number(exit[1]), logArtifactId: sealed?.log ?? null, note: status === "not-run" ? finished.detail : null };
+        }
+        if (started !== null) {
+            const limit = Number(/limit (\d+)/.exec(started.detail ?? "")?.[1] ?? 3_600_000);
+            if (now.getTime() - Date.parse(started.at) > limit + ABANDONED_GRACE_MS)
+                return { ...base, state: "not-run", note: "The check didn't finish." };
+            return { ...base, state: "running" };
+        }
+        return { ...base, state: "waiting" };
+    });
+}
+/** Whether a result can have checks run on it, and with which command. */
+function checkTarget(store, runId, level) {
+    const run = store.getRun(runId);
+    const ref = run === null ? null : store.refById(run.taskRef);
+    if (run === null || ref === null)
+        return refuse("unknown", "No such result.");
+    if (run.finishedAt === null || run.headRevision === null || !/^[a-f0-9]{40}$/.test(run.headRevision))
+        return refuse("no-commit", "This result has no finished commit to check.");
+    if (ref.repo === null)
+        return refuse("unplaced", "This result isn't in a project, so there is no check to run.");
+    const chosen = checkCommandFor(store, ref.repo, level);
+    if (chosen.command === null)
+        return refuse("no-check", `${ref.repo} has no approved ${level === "quick" ? "quick or full" : "full"} check. Set one in Settings → Projects → Checks.`);
+    return { ok: true, repo: ref.repo, taskId: ref.externalId, head: run.headRevision, level: chosen.level, command: chosen.command };
+}
+/** Ask for checks on a result's exact commit. Asking twice while one is waiting
+ * or running returns the same request; a worker runs it once. */
+export function requestFollowUpChecks(store, input, now) {
+    return store.transact(() => {
+        const target = checkTarget(store, input.runId, input.level);
+        if (!target.ok)
+            return target;
+        const open = followUpChecksOf(store, input.runId, now).find(one => one.level === target.level && one.head === target.head && (one.state === "waiting" || one.state === "running"));
+        if (open !== undefined)
+            return { ok: true, request: open.request, level: target.level, existing: true };
+        const request = store.recordAction({ at: now.toISOString(), actor: input.actor, repo: target.repo, taskId: target.taskId, runId: input.runId,
+            action: CHECKS_REQUESTED, outcome: target.level, source: "work", detail: `${target.head} · ${input.why ?? "person"} · ${target.command.digest}` });
+        store.bumpWake();
+        return { ok: true, request, level: target.level, existing: false };
+    });
+}
+/** Requests nobody has started yet, oldest first. */
+export function waitingCheckRequests(store, now) {
+    const runs = store.handle.prepare(`SELECT DISTINCT r.run_id AS run FROM action_ledger r WHERE r.action = ? AND r.run_id IS NOT NULL
+    AND NOT EXISTS (SELECT 1 FROM action_ledger s WHERE s.run_id = r.run_id AND s.action = ? AND s.outcome = CAST(r.id AS TEXT)) ORDER BY r.id`)
+        .all(CHECKS_REQUESTED, CHECKS_STARTED).map(row => Number(row["run"]));
+    return runs.flatMap(runId => followUpChecksOf(store, runId, now).filter(one => one.state === "waiting"));
+}
+/** Run one waiting request: claim it, check out its commit, run the approved
+ * setup (when the project has one) and the check, seal the log and receipt. */
+export async function runFollowUpCheck(store, root, request, deps = {}) {
+    const now = deps.now ?? (() => new Date());
+    const runner = deps.runner ?? execRun;
+    const git = deps.git ?? execRun;
+    const asked = store.handle.prepare("SELECT run_id FROM action_ledger WHERE id = ? AND action = ?").get(request, CHECKS_REQUESTED);
+    if (asked === undefined)
+        return null;
+    const runId = Number(asked["run_id"]);
+    const wanted = followUpChecksOf(store, runId, now()).find(one => one.request === request);
+    if (wanted === undefined || wanted.state !== "waiting")
+        return wanted ?? null;
+    const target = checkTarget(store, runId, wanted.level);
+    const finish = (status, detail) => {
+        store.recordAction({ at: now().toISOString(), actor: "system", repo: target.ok ? target.repo : null, taskId: target.ok ? target.taskId : null, runId,
+            action: CHECKS_FINISHED, outcome: `${request}:${status}`, source: "work", detail });
+        store.bumpWake();
+    };
+    // The claim: one started entry per request, written only while none exists.
+    const claimed = store.transact(() => {
+        if (store.handle.prepare("SELECT 1 FROM action_ledger WHERE run_id = ? AND action = ? AND outcome = ?").get(runId, CHECKS_STARTED, String(request)) !== undefined)
+            return false;
+        store.recordAction({ at: now().toISOString(), actor: "system", repo: target.ok ? target.repo : null, taskId: target.ok ? target.taskId : null, runId,
+            action: CHECKS_STARTED, outcome: String(request), source: "work", detail: `limit ${target.ok ? target.command.timeoutMs : 0}` });
+        return true;
+    });
+    if (!claimed)
+        return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
+    if (!target.ok) {
+        finish("not-run", target.message);
+        return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
+    }
+    // The commit asked about is the one checked, even if the result changed since.
+    if (target.head !== wanted.head) {
+        finish("not-run", "The result's commit changed after checks were asked for.");
+        return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
+    }
+    const folder = mkdtempSync(join(deps.scratch ?? tmpdir(), "toolroll-checks-"));
+    const checkout = join(folder, "checkout");
+    const log = [];
+    const bound = (text) => { const hits = scanForSecrets(text); return boundStreamHeadTail(hits.length > 0 ? redactSecretLines(text, hits) : text, 24 * 1024); };
+    const note = (label, command, result) => log.push(`=== ${label} ===\n$ ${command}\n(exit ${result.code}${result.notFound ? ", could not start" : ""}${result.timedOut ? ", timed out" : ""})\n\n--- stdout ---\n${bound(result.stdout)}\n\n--- stderr ---\n${bound(result.stderr)}`);
+    let result;
+    try {
+        const added = await git("git", ["-C", target.repo, "worktree", "add", "--detach", checkout, target.head], { timeoutMs: 120_000 });
+        if (added.code !== 0) {
+            note("Checkout", `git worktree add --detach <fresh folder> ${target.head}`, added);
+            result = { ran: false, failure: "The commit couldn't be checked out. It may have been removed from this computer." };
+        }
+        else {
+            const setup = store.liveWorktreeSetup(target.repo);
+            let ready = true;
+            if (setup !== null) {
+                const shell = approvedCommandShell(setup.command);
+                const prepared = await runWithIsolatedDatabase(runner, shell.file, shell.args, { cwd: checkout, timeoutMs: setup.timeoutMs, processGroup: true, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST });
+                note("Approved project setup", setup.command, prepared);
+                if (prepared.code !== 0 || prepared.timedOut || prepared.notFound) {
+                    ready = false;
+                    result = { ran: false, failure: "The project's setup failed, so the check didn't run." };
+                }
+            }
+            if (ready) {
+                // The approval is re-read right before the check starts: a revoked or changed command never runs.
+                const live = store.liveVerifyCommand(target.command.repo);
+                if (live === null || live.digest !== target.command.digest || live.digest !== wanted.digest) {
+                    result = { ran: false, failure: "The approved check changed before it started." };
+                }
+                else {
+                    const shell = approvedCommandShell(live.command);
+                    const ran = await runWithIsolatedDatabase(runner, shell.file, shell.args, { cwd: checkout, timeoutMs: live.timeoutMs, processGroup: true, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST });
+                    note(`${CHECK_LEVEL_WORDS[target.level]} check`, live.command, ran);
+                    result = ran.timedOut ? { ran: false, failure: "The check ran out of time." } : ran.notFound ? { ran: false, failure: "The check couldn't start." } : { ran: true, exitCode: ran.code };
+                }
+            }
+            else
+                result ??= { ran: false, failure: "The project's setup failed, so the check didn't run." };
+        }
+    }
+    finally {
+        await git("git", ["-C", target.repo, "worktree", "remove", "--force", checkout], { timeoutMs: 120_000 }).catch(() => null);
+        rmSync(folder, { recursive: true, force: true });
+    }
+    const at = now();
+    const text = log.length === 0 ? "No command started." : log.join("\n\n");
+    const logId = storeEvidence(store, root, runId, "structured-output", `follow-up-check-${request}.log`, Buffer.from(text, "utf8"), FOLLOW_UP_LOG, at, { captureStatus: "ok" });
+    const logArtifact = store.getArtifact(logId);
+    const receipt = JSON.stringify({ version: 1, request, run: runId, head: target.head, level: target.level,
+        command: { repo: target.command.repo, command: target.command.command, digest: target.command.digest, approvedBy: target.command.approvedBy },
+        result, log: { artifactId: logArtifact.id, sha256: logArtifact.sha256, bytesStored: logArtifact.bytesStored, truncated: logArtifact.truncated } }, null, 1);
+    storeEvidence(store, root, runId, "structured-output", `follow-up-check-${request}.json`, Buffer.from(receipt, "utf8"), FOLLOW_UP_RECEIPT, at, { captureStatus: "ok" });
+    if (result.ran)
+        finish(result.exitCode === 0 ? "passed" : "failed", `${CHECK_LEVEL_WORDS[target.level]} checks on ${target.head.slice(0, 7)} · exit ${result.exitCode}`);
+    else
+        finish("not-run", result.failure);
+    return followUpChecksOf(store, runId, now(), root).find(one => one.request === request) ?? null;
+}
+/** The worker's pass: run every waiting request, one at a time. */
+export async function runWaitingChecks(store, root, deps = {}) {
+    let ran = 0;
+    for (const one of waitingCheckRequests(store, (deps.now ?? (() => new Date()))())) {
+        if (deps.shouldStop?.() === true)
+            break;
+        if ((await runFollowUpCheck(store, root, one.request, deps))?.state !== "waiting")
+            ran++;
+    }
+    return ran;
+}
+/** The build's own check, then each finished follow-up in order on the same
+ * commit: a pass upgrades (a quick pass never replaces a full one), a failure
+ * is shown as it is. A follow-up that couldn't run changes nothing. */
+export function withFollowUps(original, followUps) {
+    let reading = original;
+    for (const one of followUps) {
+        if (original.head !== null && one.head !== "" && one.head !== original.head)
+            continue;
+        if (one.state === "passed") {
+            if (!(reading.status === "passed" && reading.level === "full" && one.level === "quick"))
+                reading = { status: "passed", level: one.level, exitCode: 0, head: one.head };
+        }
+        else if (one.state === "failed")
+            reading = { status: "failed", level: one.level, exitCode: one.exitCode, head: one.head };
+    }
+    const running = followUps.filter(one => one.state === "waiting" || one.state === "running").at(-1)?.level ?? null;
+    return { ...reading, running };
+}
+/** The level a result's checks stand at now: the build's own level, raised by
+ * a follow-up that passed on the same commit. null for results from before levels. */
+export function resultCheckLevel(store, runId, now) {
+    const level = runCheckLevel(store, runId);
+    const run = store.getRun(runId);
+    const follows = followUpChecksOf(store, runId, now);
+    if (follows.length === 0)
+        return level;
+    const read = withFollowUps({ status: level === "off" ? "not-run" : "passed", level, exitCode: null, head: run?.headRevision ?? null }, follows);
+    return read.level;
+}
+/** Whether this result's commit has passed the project's full check, here or in a follow-up. */
+export function fullCheckPassed(reading) {
+    return reading.status === "passed" && (reading.level === "full" || reading.level === null);
+}
+export function fullCheckGate(store, runId, now) {
+    const level = runCheckLevel(store, runId);
+    const repo = repoOfRun(store, runId);
+    const run = store.getRun(runId);
+    if (level === null || level === "full" || repo === null || run === null || store.liveVerifyCommand(repo) === null)
+        return { state: "clear" };
+    const last = followUpChecksOf(store, runId, now).filter(one => one.level === "full" && one.head === run.headRevision).at(-1);
+    if (last === undefined)
+        return { state: "not-requested", message: "The full check hasn't run on this commit yet. Merge once it passes, or merge anyway." };
+    if (last.state === "passed")
+        return { state: "clear" };
+    if (last.state === "failed")
+        return { state: "failed", message: `The full check failed on this commit${last.exitCode === null ? "" : ` (exit ${last.exitCode})`}. Fix it, or merge anyway.` };
+    if (last.state === "not-run")
+        return { state: "not-run", message: `The full check didn't finish on this commit${last.note === null ? "" : `: ${last.note}`} Run it again, or merge anyway.` };
+    return { state: "waiting", message: "The full check is still running on this commit. Merge once it passes, or merge anyway." };
+}
+export const isQuickCommand = (command, repo) => command !== null && command.repo === quickVerifyKey(repo);
+// ---- Add tests --------------------------------------------------------------
+/** File a small task to write tests for a result's change. It is filed like any
+ * other task: nothing runs until a person approves it. */
+export function fileAddTestsTask(store, root, input, now) {
+    const run = store.getRun(input.runId);
+    const ref = run === null ? null : store.refById(run.taskRef);
+    if (run === null || ref === null)
+        return refuse("unknown", "No such result.");
+    if (ref.repo === null)
+        return refuse("unplaced", "This result isn't in a project.");
+    if (run.headRevision === null || !/^[a-f0-9]{40}$/.test(run.headRevision))
+        return refuse("no-commit", "This result has no commit to write tests for.");
+    const earlier = store.handle.prepare("SELECT outcome FROM action_ledger WHERE run_id = ? AND action = ? ORDER BY id DESC LIMIT 1").get(input.runId, ADD_TESTS_ACTION);
+    if (earlier !== undefined && store.getTask(String(earlier["outcome"])) !== null)
+        return { ok: true, id: String(earlier["outcome"]), existing: true };
+    const task = store.getTask(ref.externalId);
+    const files = root === null ? [] : changedFilesOf(store, root, input.runId);
+    const shown = files.slice(0, 12);
+    const title = `Add tests for ${task?.title ?? ref.externalId}`.slice(0, 200);
+    const goal = [
+        `Write tests for the change made by ${ref.externalId} (commit ${run.headRevision.slice(0, 7)}).`,
+        shown.length === 0 ? "" : `Changed files: ${shown.join(", ")}${files.length > shown.length ? `, and ${files.length - shown.length} more` : ""}.`,
+        "Cover the changed behaviour, including its edge cases. Change product code only if a test shows a real bug, and say so.",
+    ].filter(one => one !== "").join(" ");
+    const filed = store.transact(() => {
+        const made = fileTaskProposal(store, {
+            title, repo: ref.repo, goal, planning: "skip", filedVia: input.filedVia,
+            acceptance: [{ id: "c1", statement: "New tests cover the changed behaviour and pass", evidence: ["check"], how: null }],
+            ...(input.admittedRepos === undefined ? {} : { admittedRepos: input.admittedRepos }),
+        }, now);
+        if (!made.ok)
+            return made;
+        store.recordAction({ at: now.toISOString(), actor: input.actor, repo: ref.repo, taskId: ref.externalId, runId: input.runId, action: ADD_TESTS_ACTION, outcome: made.id, source: "request",
+            detail: `Filed ${made.id}` });
+        return made;
+    });
+    if (!filed.ok)
+        return refuse(filed.reason, filed.message);
+    return { ok: true, id: filed.id, existing: false };
+}
+function changedFilesOf(store, root, runId) {
+    const stat = store.artifactsFor(runId).find(one => one.kind === "diff-stat");
+    if (stat === undefined)
+        return [];
+    const read = readVerifiedArtifact(root, stat);
+    if (!read.ok)
+        return [];
+    try {
+        const parsed = JSON.parse(read.content.toString("utf8"));
+        return (parsed.files ?? []).map(one => one.path).filter((one) => typeof one === "string" && one.length < 300);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/scope.js

@@ -2,6 +2,7 @@ import { passwordGuardOf } from "./sign-in-guard.js";
 import { validateScopeText } from "./task-text.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { projectAuthority } from "./project-access.js";
+import { claimActor, currentActor, parseLeadToken } from "./actor.js";
 /**
  * What a task is allowed to become, agreed before anything builds it.
  *
@@ -791,6 +792,14 @@ password) {
 export function authenticateAccount(store, by, secret) {
     if (store.listApprovers().length === 0)
         return { ok: false, reason: "no-approvers" };
+    // A lead token signs in as its owner, only inside a command the lead runs with it (never a console sign-in).
+    const acting = currentActor();
+    if (acting?.lead === true && parseLeadToken(secret) !== null) {
+        const lead = store.leadFor(secret), account = store.accountOf(by);
+        if (lead === null || lead.owner !== by || acting.account !== by || account === null)
+            return { ok: false, reason: "unknown" };
+        return { ok: true, role: account.role, generation: account.generation };
+    }
     // v99: wrong passwords in a row lock the name for a while, whatever road they came by.
     const guard = passwordGuardOf(store), now = Date.now();
     if (guard.lockedFor(by, now) > 0)
@@ -803,6 +812,8 @@ export function authenticateAccount(store, by, secret) {
     guard.succeeded(by);
     if (account.revokedAt !== null)
         return { ok: false, reason: "revoked" };
+    // Inside a command, the person who signed in is who acted (their own acts never ping them).
+    claimActor(by);
     return { ok: true, role: account.role, generation: account.generation };
 }
 /**

package/dist/serve.d.ts

@@ -1,4 +1,6 @@
+import { type BrowserWorkspace, type BrowserSignIn, type BrowserUpdateNotice } from './browser-workspace.js';
 import { CodingWorkspace } from './coding-workspace.js';
+import { type FetchLike } from "./flow-share.js";
 import { type MailSender } from "./flow-actions.js";
 import { type TriggerIo } from "./flow-triggers.js";
 import { type AssignmentSnapshot } from './assignment.js';
@@ -6,14 +8,17 @@ import type { PublishExec } from './publish.js';
 import { type VersionRunner } from "./model-catalog.js";
 import { type Server } from "node:http";
 import { type ProofVerdict, type CriterionMatrixRow } from "./proof.js";
-import { type Run, type Store } from "./store.js";
+import { type Decision, type Run, type Store, type TaskState } from "./store.js";
 import { previewGithubRepo, cloneGithubRepo, listGithubRepos } from "./onboard.js";
 import { run as execRun } from "./exec.js";
+import { type FirstRunStep } from "./first-run.js";
+import { type Gap } from "./gaps.js";
 import { type AgentChoice } from "./agentconfig.js";
 import { type RouteProjection, type RouteOverride, type RouteStamp, type RiskLevel } from "./phase-routing.js";
 import { type Phase } from "./provider.js";
 import { type IntegrationIo } from "./integrations.js";
 import { launchRuntimeUpdate } from "./toolroll-update.js";
+import type { RepairChainRow } from "./store.js";
 import type { RevisionLineage } from "./store.js";
 import type { SubscriptionMateRunner } from "./subscription-chat.js";
 import { type InstallMethod } from "./install-method.js";
@@ -39,8 +44,22 @@ export type ServeOptions = {
     registryPath?: string;
     /** This console fronts an `up` process: onboarding copy says how to watch. */
     upConsole?: boolean;
+    /**
+     * The lead on by default (onboarding): with no lead set up, the agent CLI
+     * signed in on this computer runs it, once. `up` and `serve` turn this on;
+     * tests opt in.
+     */
+    leadByDefault?: boolean;
+    /** Test seam: the operating system the sign-in command is written for. */
+    platform?: NodeJS.Platform;
     /** Extra Host values this server answers as (a Tailscale name, a LAN ip:port). */
     allowedHosts?: readonly string[];
+    /**
+     * This computer's names on its tailnet (onboarding): read at start and every
+     * few minutes; the console answers to each on its own port without an
+     * --allow-host, and the phone card names the address. Absent = none.
+     */
+    tailnetNames?: () => Promise<readonly string[]>;
     /**
      * The first-account road (setup review): while NO approver exists, the
      * login page offers "create the first account", gated by this code —
@@ -107,6 +126,8 @@ export type ServeOptions = {
     toolHome?: string;
     /** v87: sends Send email steps' mail and the settings test (tests inject one). */
     mailSender?: MailSender;
+    /** Injected by tests: how Flows → Import fetches a flow file's address. */
+    flowFetch?: FetchLike;
     /** v89: Google's token endpoint (tests inject a scripted one). */
     googleFetch?: typeof fetch;
     /** Tests: every request a one-click connection makes (discovery, registration, tokens). */
@@ -164,7 +185,14 @@ export type ServeOptions = {
     /** Injected by tests: the git and gh calls pull-request setup and Merge make. */
     publishExec?: PublishExec;
 };
-export declare function createDecisionServer(options: ServeOptions): Server;
+/** Where `up`'s one-time sign-in link points, and how long it works. */
+export declare const SIGN_IN_LINK_PATH = "/login/once/";
+export declare const SIGN_IN_LINK_MS: number;
+/** The console's server, and the one-time sign-in link `up` opens: a path on this server, or null for no such approver. */
+export type DecisionServer = Server & {
+    mintSignInLink(account: string): string | null;
+};
+export declare function createDecisionServer(options: ServeOptions): DecisionServer;
 /**
  * A vscode://file href, or null (arc 6, finding 2): the link exists only
  * when every part is provably tame — an absolute, control-free worktree;
@@ -211,6 +239,79 @@ export type RouteView = {
 };
 /** The page CSS this module writes itself (not the imported modules'), for the stylesheet contract tests. */
 export declare const PAGE_CSS: string;
+/** Everything the sidebar needs to draw itself for one request. */
+type Chrome = {
+    projectScoped?: boolean;
+    active: "code" | "inbox" | "board" | "queue" | "fleet" | "workbench" | "work" | "done" | "activity" | "review" | "system" | "tasks" | "runs" | "caps" | "routines" | "recipes" | "projects" | "flows" | "settings" | "chat" | "people" | "ledger" | "spend" | "mode" | "menu" | "none";
+    project: string | null;
+    /** The surface's scope for the scope bar — which rows this screen can
+     * show. Derived from the ROUTE, not the session: portfolio and fleet are
+     * all-project even while a project is open; the board says which of its
+     * two modes it is in. Absent = the session default (open project, else
+     * all projects). Display only — switching stays POST + CSRF. */
+    scope?: "all" | "project" | "board-all";
+    /** The saturated inbox count — never a sum of unbounded list reads. */
+    inboxCount: number;
+    inboxSaturated: boolean;
+    settings: boolean;
+    /** This database is a demo sandbox: banner every page, spend fenced. */
+    demo?: boolean;
+    /** The active operating mode's banner (M1): rides every page scoped to
+     * a repo with a live mode — a signed posture is never invisible. */
+    modeBanner?: {
+        words: string;
+        name: string;
+    };
+    /** Providers whose sign-in stopped working: every page says so, once. */
+    signIn?: BrowserSignIn[];
+    /** A newer Toolroll: a quiet notice for an operator until they dismiss this version. */
+    update?: BrowserUpdateNotice;
+    /** The chat tab renders only where chat could ever be allowed. */
+    chat?: boolean;
+    code?: boolean;
+    /** A rendered list pane makes the page master-detail. */
+    listPane?: string;
+    /** A compact pulse for the currently open workspace. Null in the
+     * cross-workspace view; absent only when the store could not answer. */
+    projectPeek?: ProjectPeek | null;
+    /** The switcher (board pass): every enrolled project inside the ceiling,
+     * most recently opened first — the one-tap switch on any screen. */
+    projects?: {
+        path: string;
+        name: string;
+    }[];
+    /** The session's csrf token, for the switcher's forms; "" when the
+     * request has no cookie session (bearer), which renders the switcher
+     * inert. */
+    csrf?: string;
+    /** Where a switch made on this screen returns to. */
+    returnTo?: string;
+};
+/**
+ * A page described, not yet rendered (arc 4): every chromed HTML route
+ * returns one of these and ONE helper (sendScreen, inside the server)
+ * owns the nonce, the palette index, the shortcuts overlay, script
+ * composition, and the CSP. Renderers stopped calling shell() themselves
+ * so those five things cannot drift apart per route.
+ */
+type Screen = {
+    title: string;
+    body: string;
+    chrome?: Chrome;
+    /** The page's own executable behavior (a region poller, the push
+     * enrollment script). fetches: true when it calls fetch — connect-src
+     * is granted only then. */
+    functional?: {
+        script: string;
+        fetches?: boolean;
+    };
+    refreshSeconds?: number;
+    /** Render sensitive even when no password field is visible — one-time
+     * secrets and judgment calls the classifier cannot see. */
+    forceSensitive?: boolean;
+    /** Structured conversation; complex guarded forms stay native islands. */
+    workspace?: Partial<Pick<BrowserWorkspace, 'conversation' | 'team' | 'focus' | 'result' | 'catchUpHtml' | 'controlsHtml' | 'notices' | 'pageHtml' | 'view' | 'firstRun' | 'phone' | 'home'>>;
+};
 /**
  * The sensitivity classifier (arc 4, findings 3/17): a body showing a
  * password input renders WITHOUT the chrome additions (palette, overlay,
@@ -232,6 +333,105 @@ export declare function ssoStepUps(html: string, sso: {
     label: string;
     fresh: boolean;
 }, returnTo: string): string;
+/**
+ * The page for an address the console doesn't answer to (onboarding): what was opened, where it answers, and the exact
+ * command that admits this address. It stands alone (styles inline, no script, no font), because every other asset
+ * would be refused at this address too; and it holds nothing a stranger's page doesn't already know.
+ */
+export declare function wrongHostPage(facts: {
+    opened: string | null;
+    served: string;
+    command: string | null;
+}): string;
+/**
+ * The inbox (v3): only things stalling progress without a person, one card
+ * per underlying stall, each with its verb inline or one step away. No
+ * auto-refresh — approval links lead to the step-up screen, and a page
+ * that might hold typed input never re-renders itself.
+ */
+export type InboxTab = "needs-you" | "ready" | "running" | "all";
+export declare function parseInboxTab(raw: string | null): InboxTab | undefined;
+/** What each tab holds, as a short fingerprint: a tab is unread when its
+ * fingerprint differs from the one this browser saw there last. */
+export declare function inboxFingerprints(data: Pick<Parameters<typeof inboxPage>[1], "decisions" | "approvals" | "requeueables" | "cancelledBlockers" | "gaps" | "needsVerification" | "ready" | "running">): Record<InboxTab, string>;
+declare function inboxPage(chrome: Chrome, data: {
+    csrf: string;
+    revision: number;
+    /** No project open in scoped mode: every admitted project at once,
+     * chips on every row, links only — acting means opening the project. */
+    rollup: boolean;
+    /** A project is OPEN: only then do decisions answer on the card. The
+     * legacy unscoped projectless inbox stays links-only too (commit-1
+     * review, finding 4) — the partial belongs to a chosen project. */
+    interactive: boolean;
+    decisions: (Decision & {
+        taskId: string;
+        repo?: string | null;
+    })[];
+    approvals: {
+        taskId: string;
+        title: string;
+        goal: string;
+        proposedAt: string;
+        repo?: string | null; /** v48 authority repair: the closed consent door's title, or null when a yes could bind. */
+        closed?: string | null;
+    }[];
+    requeueables: {
+        taskId: string;
+        title: string;
+        state: TaskState;
+        strikes: number;
+        incidentCount: number;
+        repo?: string | null;
+    }[];
+    cancelledBlockers: {
+        blockerId: string;
+        dependentCount: number;
+        exampleDependent: string;
+        repo?: string | null;
+        blockerRepo?: string | null;
+    }[];
+    gaps: Gap[];
+    /** A completed task whose proof is short or refuted and not yet accepted
+     * (Priority 2) — reads "needs verification" here too, never silently
+     * "done" just because the inbox does not otherwise look at finished work. */
+    needsVerification: {
+        taskId: string;
+        title: string;
+        verdict: "short" | "refuted";
+        repo?: string | null;
+        matrix?: CriterionMatrixRow[];
+        repairChain?: RepairChainRow | null;
+    }[];
+    /** The first-run steps; null once the installation has had its first Ready result. */
+    wizard: FirstRunStep[] | null;
+    /** Whether any worker is answering right now — said at the top when none is. */
+    worker: {
+        answering: number;
+        registered: number;
+        lastHeard: string | null;
+    };
+    now: Date;
+    /** Console v2: the tab shown, results ready to review, work running now,
+     * and the tabs holding something this browser hasn't seen (dots on a phone). */
+    tab?: InboxTab;
+    ready?: {
+        taskId: string;
+        title: string;
+        detail: string;
+        repo: string | null;
+    }[];
+    running?: {
+        taskId: string;
+        title: string;
+        detail: string;
+        repo: string | null;
+    }[];
+    unread?: readonly InboxTab[];
+}): Screen;
+/** The task composer's modes (console v2), as the words the lead reads for that one turn. */
+export type TaskComposerMode = "build" | "plan" | "answer";
+export declare const TASK_COMPOSER_MODES: Record<TaskComposerMode, string>;
 /**
  * The inline-answer enhancement (portfolio arc §2): submits a reversible
  * option's form as the urlencoded POST the forms-only gate expects, follows
@@ -242,6 +442,12 @@ export declare function ssoStepUps(html: string, sso: {
  * Nothing else on the page is touched: typed input elsewhere survives.
  */
 export declare function decisionAnswerScript(): string;
+type ProjectPeek = {
+    waiting: number;
+    queued: number;
+    running: number;
+    doneRecently: number;
+};
 /**
  * Creating work is the product's first verb, so it gets a whole calm page:
  * a title, the goal that becomes the scope draft, and the project it lands
@@ -257,6 +463,8 @@ export declare function decisionAnswerScript(): string;
  */
 /** The person's pinned theme from their own cookie; null follows the device. */
 export declare function pinnedTheme(cookieHeader: string | undefined): "light" | "dark" | null;
+/** A request path fit for a log: the one-time sign-in link's code is left out. */
+export declare function redactedPath(path: string): string;
 /** The /queue page's one nonce'd script: delegated pointer-event drag (it
  * survives every fragment swap — finding 17) plus a poller that re-checks
  * focus, dirty inputs, and an in-flight drag AT SWAP TIME, never only
@@ -339,3 +547,4 @@ export declare function plainConclusionOf(conclusion: string): string;
  * stop marker, so an open tab quits refetching a dead build (round-4
  * finding 15). */
 export declare function runFactsFragment(run: Run, taskId: string, live: boolean, route?: RouteStamp | null): string;
+export {};