toolroll 0.9.63 → 0.9.67

package/dist/webhook-limits.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Webhook floods (docs/plans/webhook-tasks.md §4): how many deliveries a trigger's address may fail in a minute. Held
+ * in memory per store (a restart forgets it, which is harmless: it protects the process and the database's write rate,
+ * not anything durable). It counts only what doesn't prove itself — a bad, missing or stale signature, an address that
+ * isn't set up, an unknown address, and every delivery to an unsigned webhook (nothing proves those) — so a stranger
+ * holding a leaked address can't crowd out the deliveries that are signed.
+ */
+import type { Store } from "./store.js";
+/** At most this many unproven deliveries per address a minute; over it, further ones are answered 429 and do nothing. */
+export declare const UNPROVEN_PER_MINUTE = 60;
+/** Addresses that match no trigger share one count. */
+export declare const UNKNOWN_ADDRESS = "unknown";
+/** Count one unproven delivery to `address` at `now`. Whether it is over the minute's limit, and when to try again. */
+export declare function countUnproven(store: Store, address: string, now: Date): {
+    over: false;
+} | {
+    over: true;
+    retryAfterSeconds: number;
+};
+/** At most this many cards a trigger makes in a rolling hour (counted when each card is made). */
+export declare const CARDS_PER_HOUR = 30;
+/** At most this many signed deliveries a trigger holds while it waits for room; beyond it, deliveries are turned away. */
+export declare const HELD_AT_MOST = 200;

package/dist/webhook-limits.js

@@ -0,0 +1,30 @@
+/** At most this many unproven deliveries per address a minute; over it, further ones are answered 429 and do nothing. */
+export const UNPROVEN_PER_MINUTE = 60;
+const WINDOW_MS = 60_000;
+/** Addresses that match no trigger share one count. */
+export const UNKNOWN_ADDRESS = "unknown";
+const counters = new WeakMap();
+/** Count one unproven delivery to `address` at `now`. Whether it is over the minute's limit, and when to try again. */
+export function countUnproven(store, address, now) {
+    let counter = counters.get(store);
+    if (counter === undefined) {
+        counter = new Map();
+        counters.set(store, counter);
+    }
+    const at = now.getTime();
+    const recent = (counter.get(address) ?? []).filter(one => one > at - WINDOW_MS);
+    recent.push(at);
+    // Keep at most one over the limit: the count only needs to know it is over, and memory stays bounded per address.
+    counter.set(address, recent.slice(-(UNPROVEN_PER_MINUTE + 1)));
+    // Bounded across addresses too: the oldest addresses are forgotten first.
+    if (counter.size > 10_000)
+        counter.delete(counter.keys().next().value);
+    if (recent.length <= UNPROVEN_PER_MINUTE)
+        return { over: false };
+    const oldest = recent[recent.length - UNPROVEN_PER_MINUTE - 1];
+    return { over: true, retryAfterSeconds: Math.max(1, Math.ceil((oldest + WINDOW_MS - at) / 1000)) };
+}
+/** At most this many cards a trigger makes in a rolling hour (counted when each card is made). */
+export const CARDS_PER_HOUR = 30;
+/** At most this many signed deliveries a trigger holds while it waits for room; beyond it, deliveries are turned away. */
+export const HELD_AT_MOST = 200;

package/dist/webhook-readers.d.ts

@@ -0,0 +1,56 @@
+import type { WebhookSender } from "./webhook-signing.js";
+/** A webhook trigger's reading settings (its saved config, defaults filled). */
+export type ReaderSettings = {
+    sender: WebhookSender;
+    title: string;
+    titleField: string | null;
+    bodyField: string | null;
+    idField: string | null;
+    urlField: string | null;
+    project: string | null;
+    team: string | null;
+};
+/** What one delivery is, once read: an item (with the outside thing's identity and link, when it has them), a delivery
+ * whose configured identity couldn't be used (made into nothing, with why), or one that isn't for this flow. */
+export type ReadDelivery = {
+    kind: "item";
+    identity: string | null;
+    url: string | null;
+    title: string;
+    description: string;
+    label: string;
+} | {
+    kind: "skip";
+    why: string;
+} | {
+    kind: "ignored";
+    why: string;
+};
+/** Whether outside words could hold a key or password (the same check cards' words get). */
+export declare const looksSecret: (value: string) => boolean;
+/** Where a sender's links may point: its own host, and (for Sentry) the organisation subdomains under it. */
+export type LinkHosts = readonly {
+    host: string;
+    subdomains: boolean;
+}[];
+export declare const SENTRY_HOSTS: LinkHosts;
+export declare const VERCEL_HOSTS: LinkHosts;
+/**
+ * A link kept from a delivery: absolute https, at most 2,000 characters, no user information, and with its query and
+ * fragment dropped (where tokens travel). `hosts` narrows it to a sender's own site (and its subdomains). Null when it
+ * isn't one, or when what is left could still hold a secret.
+ */
+export declare function safeLink(value: unknown, hosts: LinkHosts | null): string | null;
+/** The identity words a key may carry: at most 120 characters, nothing hidden, and nothing that looks like a secret. */
+export declare function identityOf(value: unknown): {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    why: string;
+};
+/** Whether each provider's reader has read a real, captured delivery (test/fixtures/webhooks/*.captured.json), or only
+ * its sender's documented examples so far: the panel says which until a captured one is in the suite. */
+export declare const READER_CAPTURED: Record<"sentry" | "vercel", boolean>;
+/** What a proven delivery says, by its sender's reader. */
+export declare function readDelivery(body: unknown, settings: ReaderSettings): ReadDelivery;

package/dist/webhook-readers.js

@@ -0,0 +1,138 @@
+/**
+ * What a proven webhook delivery says, read by its sender's reader (docs/plans/webhook-tasks.md §2). A signature proves
+ * who sent a delivery, not that it belongs in this flow: Sentry's and Vercel's readers check its shape, its action and
+ * the configured scope first, and only then give it an identity. Anything else is ignored, with why, and claims no
+ * identity. The generic senders pick their fields by dot-paths. Every outside value is screened for secrets before it
+ * is used anywhere (a key, a held item, a card, a task), and every link is made safe before it is kept.
+ */
+import { scanForSecrets } from "./evidence.js";
+const HIDDEN = /[\u0000-\u001f\u007f​-‏‪-‮⁦-⁩]/;
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+const pick = (body, path) => path.split(".").reduce((node, part) => record(node)[part], body);
+const text = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+/** A string or a safe integer, as an identity's words exactly as sent; anything else isn't one. */
+const idWords = (value) => typeof value === "string" ? value : typeof value === "number" && Number.isSafeInteger(value) ? String(value) : null;
+/** Whether outside words could hold a key or password (the same check cards' words get). */
+export const looksSecret = (value) => scanForSecrets(value).length > 0;
+export const SENTRY_HOSTS = [{ host: "sentry.io", subdomains: true }];
+export const VERCEL_HOSTS = [{ host: "vercel.com", subdomains: false }];
+/**
+ * A link kept from a delivery: absolute https, at most 2,000 characters, no user information, and with its query and
+ * fragment dropped (where tokens travel). `hosts` narrows it to a sender's own site (and its subdomains). Null when it
+ * isn't one, or when what is left could still hold a secret.
+ */
+export function safeLink(value, hosts) {
+    if (typeof value !== "string" || value.length > 2000 || HIDDEN.test(value))
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" || url.username !== "" || url.password !== "")
+        return null;
+    const host = url.hostname.toLowerCase();
+    if (hosts !== null && !hosts.some(one => host === one.host || (one.subdomains && host.endsWith(`.${one.host}`))))
+        return null;
+    const kept = `${url.origin}${url.pathname}`;
+    // Judged as it will be kept: an address that only normalises past 2,000 characters (escaped non-ASCII) isn't kept.
+    if (kept.length > 2000)
+        return null;
+    // Screened as kept and as read: a token spelled with percent-escapes is the same token. A path that won't decode isn't kept.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(url.pathname);
+    }
+    catch {
+        return null;
+    }
+    return looksSecret(kept) || looksSecret(decoded) || HIDDEN.test(decoded) ? null : kept;
+}
+/** The identity words a key may carry: at most 120 characters, nothing hidden, and nothing that looks like a secret. */
+export function identityOf(value) {
+    const sent = idWords(value);
+    if (sent === null || sent.trim() === "")
+        return { ok: false, why: "its identity is missing" };
+    // Judged as sent, before anything is trimmed: padding, hidden characters or length make it unusable, never another id.
+    if (sent.length > 120 || HIDDEN.test(sent) || sent !== sent.trim())
+        return { ok: false, why: "its identity isn't usable" };
+    if (looksSecret(sent))
+        return { ok: false, why: "it looked like it held a key or password" };
+    return { ok: true, id: sent };
+}
+/** Sentry's API address for an event names its project's slug (…/api/0/projects/<org>/<project>/events/<id>/): read
+ * only from that exact shape on Sentry's own host. */
+function sentrySlugOf(value) {
+    const link = typeof value === "string" ? value : "";
+    const match = /^https:\/\/(?:[a-z0-9-]+\.)?sentry\.io\/api\/0\/projects\/[a-z0-9_-]+\/([a-z0-9_-]+)\/events\/[A-Za-z0-9-]+\/?$/.exec(link);
+    return match?.[1] ?? null;
+}
+/** Sentry: an issue alert (action "triggered", with the event) or a new issue (action "created", with the issue). */
+function readSentry(body, settings) {
+    const action = text(record(body)["action"]);
+    const data = record(record(body)["data"]);
+    const alert = action === "triggered" && Object.keys(record(data["event"])).length > 0;
+    const created = action === "created" && Object.keys(record(data["issue"])).length > 0;
+    // A fixed reason: nothing the sender wrote is kept for an event Toolroll doesn't take.
+    if (!alert && !created)
+        return { kind: "ignored", why: "not an issue alert or a new issue" };
+    const thing = record(alert ? data["event"] : data["issue"]);
+    // Scope from the body alone (the resource header isn't signed): the project's id or slug, as Sentry sends it.
+    if (settings.project !== null) {
+        const project = record(thing["project"]);
+        // An alert's event names its project by number, and by slug only in its API address; a new issue names both.
+        const names = [idWords(thing["project"]), idWords(project["id"]), text(project["slug"]), sentrySlugOf(thing["url"])].filter((one) => one !== null);
+        if (!names.some(one => one.toLowerCase() === settings.project.toLowerCase()))
+            return { kind: "ignored", why: "from another Sentry project" };
+    }
+    const identity = identityOf(alert ? thing["issue_id"] : thing["id"]);
+    if (!identity.ok)
+        return { kind: "skip", why: identity.why };
+    const title = text(thing["title"]) ?? settings.title;
+    const culprit = text(thing["culprit"]);
+    return { kind: "item", identity: identity.id, url: safeLink(thing["web_url"], SENTRY_HOSTS), title, description: culprit === null ? "From a Sentry issue." : `From a Sentry issue, in ${culprit}.`, label: "Sentry issue" };
+}
+/** Vercel: a failed deployment only, from the configured project and team. */
+function readVercel(body, settings) {
+    const type = text(record(body)["type"]);
+    if (type !== "deployment.error")
+        return { kind: "ignored", why: "not a failed deployment" };
+    const payload = record(record(body)["payload"]);
+    if (settings.project !== null && idWords(record(payload["project"])["id"]) !== settings.project)
+        return { kind: "ignored", why: "from another Vercel project" };
+    if (settings.team !== null && idWords(record(payload["team"])["id"]) !== settings.team)
+        return { kind: "ignored", why: "from another Vercel team" };
+    const deployment = record(payload["deployment"]);
+    const identity = identityOf(deployment["id"]);
+    if (!identity.ok)
+        return { kind: "skip", why: identity.why };
+    const name = text(deployment["name"]);
+    return { kind: "item", identity: identity.id, url: safeLink(record(payload["links"])["deployment"], VERCEL_HOSTS), title: name === null ? settings.title : `${name} failed to deploy`,
+        description: "From a failed Vercel deployment.", label: "Vercel deployment" };
+}
+/** Any JSON: the trigger's own paths, then the usual names; shown whole when they find no text. */
+function readGeneric(body, settings) {
+    const at = (path) => path === null ? undefined : pick(body, path);
+    let identity = null;
+    if (settings.idField !== null) {
+        const read = identityOf(at(settings.idField));
+        // A configured identity that can't be used makes nothing: it never falls back to some other identity.
+        if (!read.ok)
+            return { kind: "skip", why: read.why };
+        identity = read.id;
+    }
+    const title = at(settings.titleField ?? "title") ?? at("summary") ?? at("message");
+    const details = at(settings.bodyField ?? "description") ?? at("body") ?? at("text");
+    return { kind: "item", identity, url: settings.urlField === null ? null : safeLink(at(settings.urlField), null),
+        title: typeof title === "string" && title.trim() !== "" ? title : settings.title,
+        description: `From a webhook:\n\n${typeof details === "string" ? details : JSON.stringify(body, null, 2)}`.slice(0, 4000), label: "Webhook" };
+}
+/** Whether each provider's reader has read a real, captured delivery (test/fixtures/webhooks/*.captured.json), or only
+ * its sender's documented examples so far: the panel says which until a captured one is in the suite. */
+export const READER_CAPTURED = { sentry: false, vercel: false };
+/** What a proven delivery says, by its sender's reader. */
+export function readDelivery(body, settings) {
+    return settings.sender === "sentry" ? readSentry(body, settings) : settings.sender === "vercel" ? readVercel(body, settings) : readGeneric(body, settings);
+}

package/dist/webhook-signing.d.ts

@@ -0,0 +1,27 @@
+import { WEBHOOK_SENDERS } from "./contracts/flow.js";
+export { WEBHOOK_SENDERS };
+export type WebhookSender = (typeof WEBHOOK_SENDERS)[number];
+/** The senders whose deliveries carry a signature (everything but `none`). */
+export type SigningSender = Exclude<WebhookSender, "none">;
+export declare const SENDER_WORDS: Record<WebhookSender, string>;
+/** Node's `headersDistinct`: every header's values, one per line it arrived on. */
+export type DistinctHeaders = Record<string, string[] | undefined>;
+export type Proof = {
+    ok: true;
+    signedId: string | null;
+} | {
+    ok: false;
+    said: string;
+};
+/** A Standard Webhooks timestamp may be this far from now, either way. */
+export declare const STANDARD_TOLERANCE_MS: number;
+/** A `whsec_` secret's key bytes, or null when it isn't one. */
+export declare function standardKey(secret: string): Buffer | null;
+/** Whether a delivery was signed with this secret by this sender. `none` proves nothing and is never passed here. */
+export declare function proveDelivery(sender: SigningSender, secret: string, headers: DistinctHeaders, body: Buffer, now: Date): Proof;
+/** Whether a pasted secret has its sender's shape (Sentry's and Vercel's come from them; the others can be made here). */
+export declare function secretShapeOk(sender: SigningSender, secret: string): boolean;
+/** A new secret for a sender Toolroll can make one for; Sentry's and Vercel's are pasted from them. */
+export declare function makeSecret(sender: "standard" | "github-style"): string;
+/** Whether Toolroll makes this sender's secret (and shows it once), rather than asking for the sender's own. */
+export declare const makesSecret: (sender: SigningSender) => sender is "standard" | "github-style";

package/dist/webhook-signing.js

@@ -0,0 +1,119 @@
+/**
+ * How a webhook proves who sent it (docs/plans/webhook-tasks.md §1). Each sender's check runs over the raw bytes,
+ * before anything is parsed; a security header sent more than once, or not at all, is refused. Nothing here reads or
+ * writes the store: the caller passes the current generation's secret, and a refusal writes nothing.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { WEBHOOK_SENDERS } from "./contracts/flow.js";
+export { WEBHOOK_SENDERS };
+export const SENDER_WORDS = {
+    none: "Unsigned", standard: "Standard Webhooks", "github-style": "GitHub-style signature", sentry: "Sentry", vercel: "Vercel",
+};
+/** A Standard Webhooks timestamp may be this far from now, either way. */
+export const STANDARD_TOLERANCE_MS = 5 * 60_000;
+const HEX = (bytes) => new RegExp(`^[0-9a-f]{${bytes * 2}}$`);
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const HIDDEN = /[\u0000-\u001f\u007f]/;
+/** Exactly one value for a security header, or why not. */
+function single(headers, name) {
+    const values = headers[name] ?? [];
+    if (values.length === 0)
+        return { ok: false, said: `The ${name} header is missing.` };
+    if (values.length > 1)
+        return { ok: false, said: `The ${name} header was sent more than once.` };
+    return { ok: true, value: values[0] };
+}
+function same(expected, given) {
+    return expected.length === given.length && timingSafeEqual(expected, given);
+}
+/** A `whsec_` secret's key bytes, or null when it isn't one. */
+export function standardKey(secret) {
+    if (!secret.startsWith("whsec_"))
+        return null;
+    const encoded = secret.slice("whsec_".length);
+    if (!BASE64.test(encoded) || encoded.length % 4 !== 0)
+        return null;
+    const key = Buffer.from(encoded, "base64");
+    return key.length >= 24 && key.length <= 64 ? key : null;
+}
+/** Whether a delivery was signed with this secret by this sender. `none` proves nothing and is never passed here. */
+export function proveDelivery(sender, secret, headers, body, now) {
+    switch (sender) {
+        case "github-style": {
+            const header = single(headers, "x-hub-signature-256");
+            if (!header.ok)
+                return header;
+            const given = header.value.trim().toLowerCase();
+            if (!given.startsWith("sha256=") || !HEX(32).test(given.slice(7)))
+                return { ok: false, said: "The signature isn't sha256=<hex>." };
+            return same(createHmac("sha256", secret).update(body).digest(), Buffer.from(given.slice(7), "hex")) ? { ok: true, signedId: null } : { ok: false, said: "Signature doesn't match." };
+        }
+        case "sentry": {
+            const header = single(headers, "sentry-hook-signature");
+            if (!header.ok)
+                return { ok: false, said: header.said.includes("missing") ? "Sentry didn't sign this: use an Internal Integration's webhook." : header.said };
+            const given = header.value.trim().toLowerCase();
+            if (!HEX(32).test(given))
+                return { ok: false, said: "The signature isn't a SHA-256 hex digest." };
+            return same(createHmac("sha256", secret).update(body).digest(), Buffer.from(given, "hex")) ? { ok: true, signedId: null } : { ok: false, said: "Signature doesn't match." };
+        }
+        case "vercel": {
+            const header = single(headers, "x-vercel-signature");
+            if (!header.ok)
+                return header;
+            const given = header.value.trim().toLowerCase();
+            if (!HEX(20).test(given))
+                return { ok: false, said: "The signature isn't a SHA-1 hex digest." };
+            return same(createHmac("sha1", secret).update(body).digest(), Buffer.from(given, "hex")) ? { ok: true, signedId: null } : { ok: false, said: "Signature doesn't match." };
+        }
+        case "standard": {
+            const key = standardKey(secret);
+            if (key === null)
+                return { ok: false, said: "The saved secret isn't a whsec_ secret." };
+            const id = single(headers, "webhook-id"), stamp = single(headers, "webhook-timestamp"), signature = single(headers, "webhook-signature");
+            for (const header of [id, stamp, signature])
+                if (!header.ok)
+                    return header;
+            const idText = id.value, stampText = stamp.value, signatureText = signature.value;
+            if (idText === "" || idText.length > 200 || HIDDEN.test(idText))
+                return { ok: false, said: "The webhook-id header isn't usable." };
+            // Unix seconds, as an integer: milliseconds, decimals and signs are refused, not guessed at.
+            if (!/^\d{1,11}$/.test(stampText))
+                return { ok: false, said: "The webhook-timestamp isn't Unix seconds." };
+            if (Math.abs(now.getTime() - Number(stampText) * 1000) > STANDARD_TOLERANCE_MS)
+                return { ok: false, said: "Too old, or from the future." };
+            const expected = createHmac("sha256", key).update(Buffer.concat([Buffer.from(`${idText}.${stampText}.`, "utf8"), body])).digest();
+            // Any well-formed v1 entry may match; a malformed entry is passed over, and none well-formed is a refusal.
+            let wellFormed = 0;
+            for (const entry of signatureText.split(" ")) {
+                if (!entry.startsWith("v1,"))
+                    continue;
+                const encoded = entry.slice(3);
+                if (!BASE64.test(encoded) || encoded.length % 4 !== 0)
+                    continue;
+                const given = Buffer.from(encoded, "base64");
+                if (given.length !== 32)
+                    continue;
+                wellFormed++;
+                if (same(expected, given))
+                    return { ok: true, signedId: idText };
+            }
+            return { ok: false, said: wellFormed === 0 ? "The webhook-signature has no v1 signature." : "Signature doesn't match." };
+        }
+    }
+}
+/** Whether a pasted secret has its sender's shape (Sentry's and Vercel's come from them; the others can be made here). */
+export function secretShapeOk(sender, secret) {
+    switch (sender) {
+        case "sentry": return /^[0-9a-fA-F]{32,128}$/.test(secret);
+        case "vercel": return /^[A-Za-z0-9]{16,200}$/.test(secret);
+        case "standard": return standardKey(secret) !== null;
+        case "github-style": return /^[\x21-\x7e]{16,200}$/.test(secret);
+    }
+}
+/** A new secret for a sender Toolroll can make one for; Sentry's and Vercel's are pasted from them. */
+export function makeSecret(sender) {
+    return sender === "standard" ? `whsec_${randomBytes(32).toString("base64")}` : randomBytes(32).toString("hex");
+}
+/** Whether Toolroll makes this sender's secret (and shows it once), rather than asking for the sender's own. */
+export const makesSecret = (sender) => sender === "standard" || sender === "github-style";

package/dist/work-index.d.ts

@@ -47,6 +47,8 @@ export type WorkIndexOptions = {
     state?: TaskState;
     leadId?: string;
     root?: string;
+    /** Only these families (by root task id): the sidebar reads its rows' own words this way. */
+    roots?: readonly string[];
 };
 /** How the list is grouped: the Needs you rows by their ask, then building, then the rest. */
 export type WorkIndexGroup = Ask | 'building' | 'rest';
@@ -85,6 +87,33 @@ export declare function workIndexPage(store: Store, now: Date, access: WorkSumma
  * permission-bound and bypasses pagination, never action-time verification. */
 export declare function workIndexTask(store: Store, taskId: string, now: Date, access: WorkSummaryAccess, root?: string): WorkIndexItem | null;
 export declare function workCountsByProject(store: Store, now: Date, access: WorkSummaryAccess): WorkProjectCounts[];
+/** One row per task family the person may see (the Tasks list's own projection: current version, admission, unplaced
+ * work and the ceiling as the list applies them), with what the cockpit's states read (agent-state.ts): its code, whether
+ * it waits on a person, whether a lead took it on, and its live, unfinished and result runs. Every family, no page. */
+export type WorkStateRow = {
+    repo: string | null;
+    rootId: string;
+    code: string;
+    needs: boolean;
+    personNeed: boolean;
+    leadClaim: boolean;
+    liveRun: number | null;
+    unfinished: number | null;
+    resultRun: number | null;
+    /** The Tasks list ranks it as waiting its turn (custody confirmations from another computer included). */
+    waits: boolean;
+    /** What it needs now, as an identity: its code and the question, hold, result or stop it is about. A new one of
+     * these — or a changed plan or approval terms (its digests) — is a new thing to need a person, even on the same task. */
+    version: string;
+    /** When what it needs now began: the newest of its plan's proposal, its question, its hold, its result and its stop
+     * (each fixed once written, so an unrelated edit never moves it). Newer asks are named first. */
+    at: string;
+    /** The agent its ask is about: the live one, or the one whose question or decision it parked on. */
+    askRun: number | null;
+    /** Every task_ref of the family (its versions), for counting each of its live attempts. */
+    members: number[];
+};
+export declare function workStateRows(store: Store, now: Date, access: WorkSummaryAccess): WorkStateRow[];
 /** Families whose headline is Ready for review, newest first: the Tasks
  * list's own rows, so a completed family (root or any revision), a failed
  * check and a superseded version never count. */

package/dist/work-index.js

@@ -388,7 +388,7 @@ function readWorkIndexPage(store, now, access, options, taskId = null) {
     const scope = cursorScope(access, options, view), cursor = readCursor(options.cursor, scope);
     const filter = view === 'needs-you' ? 'needs=1' : view === 'running' ? 'family_running=1' : view === 'completed' ? "code='complete'" : '1';
     const rows = prepared(store, `${projection}, selected_page AS MATERIALIZED (
-    SELECT * FROM ranked WHERE ${filter} AND ($taskId IS NULL OR root_ref IN (SELECT root_ref FROM members WHERE id=$taskId)) AND ($cursorRoot=0 OR
+    SELECT * FROM ranked WHERE ${filter} AND ($taskId IS NULL OR root_ref IN (SELECT root_ref FROM members WHERE id=$taskId)) AND ($roots IS NULL OR root_id IN (SELECT value FROM json_each($roots))) AND ($cursorRoot=0 OR
       ${ORDER}>$cursorRank OR (${ORDER}=$cursorRank AND (sort_at<$cursorAt OR (sort_at=$cursorAt AND root_ref<$cursorRoot))))
     ORDER BY ${ORDER},sort_at DESC,root_ref DESC LIMIT $limit
   ), page AS (SELECT p.*,COALESCE(p.result_id,(SELECT id FROM run WHERE task_ref=p.ref_id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1)) page_result_id FROM selected_page p), totals AS (SELECT ${TOTALS},${GROUP_TOTALS} FROM ranked), project_totals AS (
@@ -415,7 +415,7 @@ function readWorkIndexPage(store, now, access, options, taskId = null) {
     'agent_ask_run',(SELECT run FROM agent_question WHERE id=page.agent_ask),'agent_ask_text',(SELECT substr(question,1,300) FROM agent_question WHERE id=page.agent_ask),'replaced_by',(SELECT successor FROM task_replacement WHERE task_ref=page.ref_id),
     'completed_by_lead',(SELECT lead FROM task_act WHERE task_ref=page.root_ref AND act='completed' ORDER BY id DESC LIMIT 1),
     'question_task',(SELECT r.external_id FROM decision d JOIN run ON run.id=d.run JOIN task_ref r ON r.id=run.task_ref WHERE d.id=page.question_id)) FROM page`)
-        .all({ ...parameters(now, access, options, custody), $taskId: taskId, $cursorRoot: cursor?.root ?? 0, $cursorRank: cursor?.rank ?? 0, $cursorAt: cursor?.at ?? '', $limit: limit + 1, $recent: new Date(now.getTime() - 86_400_000).toISOString() });
+        .all({ ...parameters(now, access, options, custody), $taskId: taskId, $roots: options.roots === undefined ? null : JSON.stringify(options.roots), $cursorRoot: cursor?.root ?? 0, $cursorRank: cursor?.rank ?? 0, $cursorAt: cursor?.at ?? '', $limit: limit + 1, $recent: new Date(now.getTime() - 86_400_000).toISOString() });
     const selected = rows.slice(1).map(row => JSON.parse(String(row['row_json'])));
     const page = selected.slice(0, limit), last = page.at(-1);
     const nextCursor = selected.length > limit && last !== undefined ? Buffer.from(JSON.stringify({ version: 2, scope,
@@ -442,6 +442,20 @@ export function workCountsByProject(store, now, access) {
         .all({ ...parameters(now, access, {}, custodyReadings(store)), $recent: new Date(now.getTime() - 86_400_000).toISOString() })
         .map(row => ({ repo: s(row, 'repo'), totals: counts(row), queued: n(row, 'queued'), doneRecently: n(row, 'done_recently') }));
 }
+export function workStateRows(store, now, access) {
+    const projection = registerValidators(store);
+    return store.handle.prepare(`${projection} SELECT repo,root_id,code,needs,person_need,lead_claim,live_run,unfinished,result_id,rank,
+      code||':'||COALESCE(question_id,'')||':'||COALESCE(agent_ask,'')||':'||COALESCE(hold_id,'')||':'||COALESCE(result_id,'')||':'||COALESCE(stop_run,'')||':'||COALESCE(digest,'')||':'||COALESCE(scope_digest,'') version,
+      COALESCE(NULLIF(MAX(COALESCE(proposed_at,''),COALESCE(finished_at,''),
+        COALESCE((SELECT created_at FROM decision WHERE id=question_id),''),COALESCE((SELECT asked_at FROM agent_question WHERE id=agent_ask),''),
+        COALESCE((SELECT held_at FROM hold WHERE id=hold_id),''),COALESCE((SELECT requested_at FROM run_stop WHERE run=stop_run),'')),''),sort_at) ask_at,
+      COALESCE(live_run,(SELECT run FROM decision WHERE id=question_id),(SELECT run FROM agent_question WHERE id=agent_ask)) ask_run,
+      (SELECT json_group_array(m.ref_id) FROM members m WHERE m.root_ref=ranked.root_ref) members FROM ranked`)
+        .all(parameters(now, access, {}, custodyReadings(store)))
+        .map(row => ({ repo: s(row, 'repo'), rootId: String(row['root_id']), code: String(row['code']), needs: n(row, 'needs') === 1, personNeed: n(row, 'person_need') === 1,
+        leadClaim: n(row, 'lead_claim') === 1, liveRun: row['live_run'] == null ? null : n(row, 'live_run'), unfinished: row['unfinished'] == null ? null : n(row, 'unfinished'),
+        resultRun: row['result_id'] == null ? null : n(row, 'result_id'), waits: Number(row['rank']) === 2, version: String(row['version']), at: String(row['ask_at'] ?? ''), askRun: row['ask_run'] == null ? null : n(row, 'ask_run'), members: JSON.parse(String(row['members'] ?? '[]')).map(Number) }));
+}
 /** Families whose headline is Ready for review, newest first: the Tasks
  * list's own rows, so a completed family (root or any revision), a failed
  * check and a superseded version never count. */

package/dist/workspace-revision.js

@@ -6,7 +6,9 @@ const MAX_AGE_MS = 60_000;
 const OMIT = new Set(['schema_version', 'service_cursor', 'wake', 'notification_delivery', 'sqlite_sequence',
     'team_read', 'team_request', 'push_delivery', 'chat_message_ref',
     // Who is watching an agent right now: renewed by every open page's keep-alive, never news.
-    'agent_view']);
+    'agent_view',
+    // A run's How it ran, derived from its own records on first view (run-efficiency.ts): a cache, never news.
+    'run_efficiency']);
 const QUIET = {
     runner: ['heartbeat_at'], claim: ['heartbeat_at', 'expires_at'], watch_lease: ['heartbeat_at', 'expires_at'],
     watch_episode: ['ticks'], provider_readiness: ['observed_at'],

package/dist/writes-mode.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Where a build may write (docs/plans/agent-baseline-hardening.md arc 2). `workspace`: only its allowlist (agent-fence.ts
+ * WriteAllowlist), whatever its permission mode; `anywhere`: anywhere its fence doesn't deny, as builds did before.
+ */
+export type WritesMode = "workspace" | "anywhere";
+export declare const WRITES_DEFAULT: WritesMode;
+export declare const isWritesMode: (value: unknown) => value is WritesMode;
+/** What an approval card and the CLI say of where a build may write (absent: sealed before write allowlists). */
+export declare function writesWords(writes: WritesMode | undefined): string;

package/dist/writes-mode.js

@@ -0,0 +1,8 @@
+export const WRITES_DEFAULT = "workspace";
+export const isWritesMode = (value) => value === "workspace" || value === "anywhere";
+/** What an approval card and the CLI say of where a build may write (absent: sealed before write allowlists). */
+export function writesWords(writes) {
+    return writes === "workspace" ? "only its checkout, its caches and its temp folder"
+        : writes === "anywhere" ? "anywhere outside Toolroll's fenced folders (an approver's choice)"
+            : "anywhere outside Toolroll's fenced folders (approved before write limits)";
+}

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "toolroll",
-  "version": "0.9.63",
+  "version": "0.9.67",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/browser-build.mjs && node scripts/postbuild.mjs",
-    "test": "vitest run",
+    "test": "vitest run --exclude '**/*.slow.test.ts'",
+    "test:slow": "vitest run .slow.test",
+    "test:all": "vitest run",
     "test:attacks": "vitest run --config test/attacks/vitest.config.ts",
     "check:quick": "node scripts/quick-check.mjs",
     "dev": "tsx src/cli.ts",
@@ -80,6 +82,11 @@
     "@types/node": "26.6.4",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
+    "@types/ws": "8.18.2",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/addon-unicode11": "0.9.0",
+    "@xterm/addon-webgl": "0.19.0",
+    "@xterm/xterm": "6.0.0",
     "@xyflow/react": "12.12.0",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
@@ -119,12 +126,18 @@
   },
   "dependencies": {
     "@slack/socket-mode": "3.1.0",
+    "@xterm/addon-serialize": "0.14.0",
+    "@xterm/headless": "6.0.0",
     "discord.js": "14.27.0",
     "imapflow": "2.2.5",
     "mailparser": "3.9.36",
     "nodemailer": "10.0.15",
     "typescript-parser": "npm:typescript@6.0.3",
+    "ws": "8.22.0",
     "yaml": "2.9.1",
     "zod": "^4.6.5"
+  },
+  "optionalDependencies": {
+    "@lydell/node-pty": "1.2.0-beta.15"
   }
 }