toolroll 0.9.40 → 0.9.42

package/dist/desktop-update.js

@@ -12,6 +12,7 @@ import { activeUpdateWork, freezeUpdateGate, installUpdateGate, removeUpdateGate
 import { currentDesktopAccess } from "./desktop-access.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, releaseStaleCodingOwner } from "./coding-update.js";
 import { processMayBeAlive } from "./process-liveness.js";
+import { readDesktopRecoveryView, readDesktopUpdateJournal, supervisorPidsOf, updateRequestIs } from "./contracts/update-journal.js";
 /** Loaded on first use (as backup.ts and store.ts do), so modules that only import this one (the console,
  * and tests that load it in a browser-like environment) never need `node:sqlite` itself. */
 function sqlite() {
@@ -60,13 +61,40 @@ function privateFile(file) {
     if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== "win32" && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())))
         throw Error("The update record must be an owner-only regular file.");
 }
+/** The refusal the hand-written reader gave for the field a saved journal first gets wrong, so callers and people read
+ * the same words; fields it never checked read as an invalid record. */
+function journalRefusal(issue) {
+    const [field, inner] = issue.path.split(/[.[]/);
+    switch (field) {
+        case "old":
+            if (inner === undefined || inner === "path")
+                return "The saved update record is invalid. Preserve it and the app backups; nothing was changed.";
+            return "The saved update paths or build identities are invalid. Nothing was changed.";
+        case "next":
+        case "databaseFile":
+        case "configHash":
+        case "wasRunning":
+        case "backupPath":
+        case "backupHash":
+            return "The saved update paths or build identities are invalid. Nothing was changed.";
+        case "replacementOccurred": return "The recorded replacement state is invalid. Nothing was changed.";
+        case "codingCatalogExpected": return "The recorded coding catalog presence is invalid. Nothing was changed.";
+        case "stoppedPids": return "The recorded service processes are invalid. Nothing was changed.";
+        case "codingBackupPath":
+        case "codingBackupHash": return "The retained coding backup paths or identity are invalid. Nothing was changed.";
+        default: return "The saved update record is invalid. Preserve it and the app backups; nothing was changed.";
+    }
+}
 export function readUpdateJournal(stateDir, retainedReceipt) {
     const file = retainedReceipt ?? journalPath(stateDir);
     if (!existsSync(file))
         return null;
     privateFile(file);
-    const j = JSON.parse(readFileSync(file, "utf8"));
-    if (j.version !== 1 || !/^[a-f0-9-]{36}$/.test(j.id) || j.stateDir !== resolve(stateDir) || !isAbsolute(j.old?.path ?? "") || j.workDir !== join(dirname(j.old.path), ".standing-orders-updates", j.id) || !/^[a-zA-Z0-9.-]+$/.test(j.label) || !["install", "restore"].includes(j.intended) || !["prepared", "draining", "backing-up", "stopping", "installing", "verifying", "rolling-back", "releasing", "complete", "restored", "cancelled", "needs-attention"].includes(j.phase))
+    const read = readDesktopUpdateJournal(JSON.parse(readFileSync(file, "utf8")));
+    if (!read.ok)
+        throw Error(`${journalRefusal(read.issues[0])} (${read.issues.map(issue => issue.line).join("; ")})`);
+    const j = read.value;
+    if (!/^[a-f0-9-]{36}$/.test(j.id) || j.stateDir !== resolve(stateDir) || !isAbsolute(j.old?.path ?? "") || j.workDir !== join(dirname(j.old.path), ".standing-orders-updates", j.id) || !/^[a-zA-Z0-9.-]+$/.test(j.label) || !["install", "restore"].includes(j.intended) || !["prepared", "draining", "backing-up", "stopping", "installing", "verifying", "rolling-back", "releasing", "complete", "restored", "cancelled", "needs-attention"].includes(j.phase))
         throw Error("The saved update record is invalid. Preserve it and the app backups; nothing was changed.");
     if (retainedReceipt && retainedReceipt !== join(j.workDir, "receipt.json"))
         throw Error("The retained recovery receipt is at the wrong path.");
@@ -374,7 +402,7 @@ export function desktopUpdateStatus(stateDir) {
     let recovery = null;
     try {
         privateFile(join(j.workDir, "recovery.json"));
-        recovery = JSON.parse(readFileSync(join(j.workDir, "recovery.json"), "utf8"));
+        recovery = readDesktopRecoveryView(JSON.parse(readFileSync(join(j.workDir, "recovery.json"), "utf8")));
     }
     catch { /* A legacy/manual update has no guardian. */ }
     const wantsAutomatic = recovery?.id === j.id && ["armed", "running", "backoff"].includes(recovery.state ?? "") && !terminal(j.phase);
@@ -389,8 +417,7 @@ export function updateStopRequested(j) {
     if (!existsSync(file))
         return false;
     privateFile(file);
-    const request = JSON.parse(readFileSync(file, "utf8"));
-    if (request.id !== j.id || request.action !== "stop")
+    if (!updateRequestIs(JSON.parse(readFileSync(file, "utf8")), j.id, "stop"))
         throw Error("The saved stop request is invalid. Automatic starts are refused.");
     return true;
 }
@@ -410,7 +437,9 @@ export function requestUpdateRestore(stateDir) {
 function restoreRequested(j) {
     try {
         const request = JSON.parse(readFileSync(join(j.workDir, "request.json"), "utf8"));
-        return request.id === j.id && request.action === "restore";
+        if (request === null)
+            throw Error("The saved restore request is invalid.");
+        return updateRequestIs(request, j.id, "restore");
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -543,8 +572,7 @@ function assertDesktopCodingStopped(j, db) {
 /** The service's own processes, from its supervisor's status file: read before the stop, never after. */
 function servicePids(stateDir) {
     try {
-        const status = JSON.parse(readFileSync(join(stateDir, "controller-supervisor.json"), "utf8"));
-        return [status.supervisorPid, status.controllerPid].filter((pid) => Number.isSafeInteger(pid) && Number(pid) > 1);
+        return supervisorPidsOf(JSON.parse(readFileSync(join(stateDir, "controller-supervisor.json"), "utf8")));
     }
     catch {
         return [];

package/dist/evidence.d.ts

@@ -16,6 +16,7 @@
 import { type ParsedReport, type ReportImage } from "./scout-report.js";
 import { type ParsedProof } from "./proof.js";
 import { type HandoffArtifact } from "./contracts/handoff.js";
+import type { DiffStat } from "./contracts/diff-stat.js";
 export type { HandoffArtifact } from "./contracts/handoff.js";
 import type { Artifact, Store } from "./store.js";
 import type { ExecResult } from "./exec.js";
@@ -229,25 +230,8 @@ export declare function quarantineMailboxes(worktree: string, root: string | nul
 export declare function captureParkEvidence(store: Store, git: (file: string, args: readonly string[], options?: {
     cwd?: string;
 }) => Promise<ExecResult>, worktree: string, baseRevision: string | null, root: string, runId: number, now: Date): Promise<number[]>;
-/** One file's row in the terminal diff-stat. null adds/dels = binary. */
-export type DiffStatFile = {
-    path: string;
-    additions: number | null;
-    deletions: number | null;
-    renamedFrom?: string;
-};
-export type DiffStat = {
-    schema: 1;
-    base: string;
-    head: string;
-    fileCount: number;
-    additions: number;
-    deletions: number;
-    binaryCount: number;
-    files: DiffStatFile[];
-    /** True when the file list was cut to fit the cap — counts stay complete. */
-    filesTruncated: boolean;
-};
+/** The terminal diff-stat and its file rows: src/contracts/diff-stat.ts. */
+export type { DiffStat, DiffStatFile } from "./contracts/diff-stat.js";
 /**
  * Parse `git diff --numstat -z` output. NUL-delimited, so filenames are never
  * guessed out of patch headers (Codex roadmap review, scope cut A.3): plain

package/dist/flow-triggers.js

@@ -42,6 +42,7 @@ import { mailboxAccess, mailCursorOf, mailCursorText, readThroughImap } from "./
 import { readFlowSecrets } from "./flow-secrets.js";
 import { tmpdir } from "node:os";
 import { envValue } from "./names.js";
+import { linearLabelNames, readFormSubmission, readGithubEvent, readGithubIssue, readGithubIssueEventList, readGithubIssueList, readGithubRun, readGithubRunList, readInboundMail, readLinearAnswer, readLinearEvent, readLinearIssue, readWebhookPayload } from "./contracts/trigger-payloads.js";
 export { FLOW_TRIGGER_KINDS };
 export const CHAT_APP_NAMES = { slack: "Slack", discord: "Discord", teams: "Teams", telegram: "Telegram" };
 /** What each kind is called on the canvas. */
@@ -771,7 +772,7 @@ async function fetchMail(store, config, trigger, io, now) {
     if (!read.ok)
         return { ok: false, problem: read.said };
     const own = signed.address.toLowerCase();
-    const items = read.mails.filter(mail => mailMatches(config, mail)).map(mail => {
+    const items = read.mails.map(readInboundMail).filter(mail => mailMatches(config, mail)).map(mail => {
         const key = `mail:${read.at.validity}:${mail.uid}`, at = mailCursorText({ validity: read.at.validity, uid: mail.uid });
         const label = `Email from ${mail.from || "an unknown sender"}`.slice(0, 120);
         // Machines and this account itself never start cards: a flow that answers mail mustn't answer them.
@@ -793,44 +794,42 @@ async function fetchMail(store, config, trigger, io, now) {
         : read.renumbered ? "The mail server renumbered this folder; watching it from now." : undefined;
     return { ok: true, items, cursor: mailCursorText(read.at), more: read.more, ...(said === undefined ? {} : { said }) };
 }
-const text = (value) => typeof value === "string" ? value : "";
-const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 /** A GitHub issue or pull request as a card, or why it is left out; null when it doesn't match. */
 export function githubItem(config, raw, what) {
-    const item = record(raw);
-    const number = Number(item["number"]);
+    const item = readGithubIssue(raw);
+    const number = Number(item.number);
     if (!Number.isSafeInteger(number))
         return null;
-    if (what === "issue" && item["pull_request"] !== undefined)
+    if (what === "issue" && item.pull_request !== undefined)
         return null;
-    if (what === "pull" && item["draft"] === true)
+    if (what === "pull" && item.draft === true)
         return null;
-    const labels = Array.isArray(item["labels"]) ? item["labels"].map(one => text(record(one)["name"]).toLowerCase()) : [];
+    const labels = (item.labels ?? []).map(one => (one.name ?? "").toLowerCase());
     if (config.label !== null && !labels.includes(config.label.toLowerCase()))
         return null;
     const label = what === "issue" ? `GitHub issue #${number}` : `Pull request #${number}`;
-    const key = `${what}:${number}`, at = text(item["updated_at"]) || null;
-    if (config.from === "team" && !TEAM.has(text(item["author_association"])))
+    const key = `${what}:${number}`, at = item.updated_at || null;
+    if (config.from === "team" && !TEAM.has(item.author_association ?? ""))
         return { key, skip: "opened by someone without write access", label, at };
-    const login = text(record(item["user"])["login"]) || "someone";
-    const branches = what === "pull" ? ` (${text(record(item["head"])["ref"])} → ${text(record(item["base"])["ref"])})` : "";
-    return { key, at, title: text(item["title"]) || label,
-        description: `From ${what === "issue" ? "GitHub issue" : "pull request"} #${number} by @${login}${branches}:\n\n${text(item["body"])}`.trim().slice(0, 4000),
-        source: { kind: "github", label, url: text(item["html_url"]) || null } };
+    const login = item.user?.login || "someone";
+    const branches = what === "pull" ? ` (${item.head?.ref ?? ""} → ${item.base?.ref ?? ""})` : "";
+    return { key, at, title: item.title || label,
+        description: `From ${what === "issue" ? "GitHub issue" : "pull request"} #${number} by @${login}${branches}:\n\n${item.body ?? ""}`.trim().slice(0, 4000),
+        source: { kind: "github", label, url: item.html_url || null } };
 }
 /** A failed workflow run as a card: one card per failing commit on the watched branch. */
 export function githubRunItem(config, raw) {
-    const run = record(raw);
-    if (text(run["conclusion"]) !== "failure" || (config.branch !== null && text(run["head_branch"]) !== config.branch))
+    const run = readGithubRun(raw);
+    if (run.conclusion !== "failure" || (config.branch !== null && (run.head_branch ?? "") !== config.branch))
         return null;
-    const sha = text(run["head_sha"]);
+    const sha = run.head_sha ?? "";
     if (sha === "")
         return null;
-    const name = text(run["name"]) || "Checks";
-    const commit = text(run["display_title"]);
-    return { key: `checks:${sha}`, at: text(run["created_at"]) || null, title: `Checks failed on ${config.branch}: ${name}`,
-        description: `From GitHub: “${name}” failed on ${config.branch} at ${sha.slice(0, 7)}${commit === "" ? "" : ` (${commit})`}.\nRun: ${text(run["html_url"])}`,
-        source: { kind: "github", label: `Failed check on ${config.branch}`, url: text(run["html_url"]) || null } };
+    const name = run.name || "Checks";
+    const commit = run.display_title ?? "";
+    return { key: `checks:${sha}`, at: run.created_at || null, title: `Checks failed on ${config.branch}: ${name}`,
+        description: `From GitHub: “${name}” failed on ${config.branch} at ${sha.slice(0, 7)}${commit === "" ? "" : ` (${commit})`}.\nRun: ${run.html_url ?? ""}`,
+        source: { kind: "github", label: `Failed check on ${config.branch}`, url: run.html_url || null } };
 }
 async function fetchGitHub(config, trigger, gh) {
     const since = trigger.cursor ?? trigger.createdAt;
@@ -861,20 +860,19 @@ async function fetchGitHub(config, trigger, gh) {
     }
     const created = Date.parse(trigger.createdAt);
     if (config.watch === "checks") {
-        const runs = (Array.isArray(record(body)["workflow_runs"]) ? record(body)["workflow_runs"] : []).filter(one => Date.parse(text(record(one)["created_at"])) > created);
+        const runs = (readGithubRunList(body).workflow_runs ?? []).filter(one => Date.parse(one.created_at ?? "") > created);
         const items = runs.reverse().map(one => githubRunItem(config, one)).filter((one) => one !== null);
         return { ok: true, items: unique(items), cursor: trigger.cursor };
     }
-    const list = Array.isArray(body) ? body : [];
     if (labelEvents) {
-        const labeled = list.filter(one => text(record(one)["event"]) === "labeled" && text(record(record(one)["label"])["name"]).toLowerCase() === config.label.toLowerCase()
-            && Date.parse(text(record(one)["created_at"])) > Date.parse(since)).reverse();
-        const items = labeled.map(one => { const item = githubItem(config, record(one)["issue"], "issue"); return item === null ? null : { ...item, at: text(record(one)["created_at"]) || null }; }).filter((one) => one !== null);
-        return { ok: true, items: unique(items), cursor: labeled.map(one => text(record(one)["created_at"])).at(-1) ?? trigger.cursor };
+        const labeled = readGithubIssueEventList(body).filter(one => one.event === "labeled" && (one.label?.name ?? "").toLowerCase() === config.label.toLowerCase()
+            && Date.parse(one.created_at ?? "") > Date.parse(since)).reverse();
+        const items = labeled.map(one => { const item = githubItem(config, one.issue, "issue"); return item === null ? null : { ...item, at: one.created_at || null }; }).filter((one) => one !== null);
+        return { ok: true, items: unique(items), cursor: labeled.map(one => one.created_at ?? "").at(-1) ?? trigger.cursor };
     }
     // New issues and pull requests: opened after the trigger was added, oldest first; the key keeps each to one card.
     const what = config.watch === "pulls" ? "pull" : "issue";
-    const items = list.filter(one => Date.parse(text(record(one)["created_at"])) > created).reverse().map(one => githubItem(config, one, what)).filter((one) => one !== null);
+    const items = readGithubIssueList(body).filter(one => Date.parse(one.created_at ?? "") > created).reverse().map(one => githubItem(config, one, what)).filter((one) => one !== null);
     return { ok: true, items, cursor: trigger.cursor };
 }
 const unique = (items) => items.filter((item, index) => items.findIndex(one => one.key === item.key) === index);
@@ -882,21 +880,20 @@ export const LINEAR_URL = "https://api.linear.app/graphql";
 export const LINEAR_QUERY = "query FlowTrigger($filter: IssueFilter) { issues(filter: $filter, first: 50, orderBy: updatedAt) { nodes { identifier title description url updatedAt state { name } team { key } labels { nodes { name } } } } }";
 /** A Linear issue as a card; null when it doesn't match the trigger. */
 export function linearItem(config, raw) {
-    const issue = record(raw);
-    const identifier = text(issue["identifier"]);
+    const issue = readLinearIssue(raw);
+    const identifier = issue.identifier ?? "";
     if (identifier === "")
         return null;
-    const labelNodes = Array.isArray(issue["labels"]) ? issue["labels"] : Array.isArray(record(issue["labels"])["nodes"]) ? record(issue["labels"])["nodes"] : [];
-    const labels = labelNodes.map(one => text(record(one)["name"]).toLowerCase());
-    if (config.team !== null && text(record(issue["team"])["key"]).toUpperCase() !== config.team)
+    const labels = linearLabelNames(issue).map(one => one.toLowerCase());
+    if (config.team !== null && (issue.team?.key ?? "").toUpperCase() !== config.team)
         return null;
-    if (config.state !== null && text(record(issue["state"])["name"]).toLowerCase() !== config.state.toLowerCase())
+    if (config.state !== null && (issue.state?.name ?? "").toLowerCase() !== config.state.toLowerCase())
         return null;
     if (config.label !== null && !labels.includes(config.label.toLowerCase()))
         return null;
-    return { key: `linear:${identifier}`, at: text(issue["updatedAt"]) || null, title: text(issue["title"]) || identifier,
-        description: `From Linear ${identifier}:\n\n${text(issue["description"])}`.trim().slice(0, 4000),
-        source: { kind: "linear", label: `Linear ${identifier}`, url: text(issue["url"]) || null } };
+    return { key: `linear:${identifier}`, at: issue.updatedAt || null, title: issue.title || identifier,
+        description: `From Linear ${identifier}:\n\n${issue.description ?? ""}`.trim().slice(0, 4000),
+        source: { kind: "linear", label: `Linear ${identifier}`, url: issue.url || null } };
 }
 async function fetchLinear(config, trigger, io) {
     const key = readLinearKey(io.dir);
@@ -917,22 +914,22 @@ async function fetchLinear(config, trigger, io) {
     catch {
         return { ok: false, problem: "Couldn't reach Linear." };
     }
-    let body;
+    let raw;
     try {
-        body = record(await response.json());
+        raw = await response.json();
     }
     catch {
         return { ok: false, problem: `Linear answered ${response.status} and it couldn't be read.` };
     }
-    const errors = Array.isArray(body["errors"]) ? body["errors"].map(one => text(record(one)["message"])) : [];
+    const body = readLinearAnswer(raw);
+    const errors = (body.errors ?? []).map(one => one.message ?? "");
     if (response.status === 401 || errors.some(one => /authenticat|api key/i.test(one)))
         return { ok: false, problem: "Linear didn't accept the key. Add a new one on this flow's Triggers panel." };
     if (!response.ok || errors.length > 0)
         return { ok: false, problem: `Linear said: ${(errors[0] ?? `status ${response.status}`).slice(0, 160)}` };
-    const nodes = record(record(record(body["data"])["issues"]))["nodes"];
-    const issues = (Array.isArray(nodes) ? nodes : []).sort((a, b) => text(record(a)["updatedAt"]).localeCompare(text(record(b)["updatedAt"])));
+    const issues = (body.data?.issues?.nodes ?? []).sort((a, b) => (a.updatedAt ?? "").localeCompare(b.updatedAt ?? ""));
     const items = issues.map(one => linearItem(config, one)).filter((one) => one !== null);
-    return { ok: true, items, cursor: issues.map(one => text(record(one)["updatedAt"])).filter(one => one !== "").at(-1) ?? trigger.cursor };
+    return { ok: true, items, cursor: issues.map(one => one.updatedAt ?? "").filter(one => one !== "").at(-1) ?? trigger.cursor };
 }
 const header = (delivery, name) => { const value = delivery.headers[name]; return Array.isArray(value) ? value[0] ?? "" : value ?? ""; };
 function sameHex(expected, given) {
@@ -963,8 +960,8 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
         const signature = header(delivery, "x-hub-signature-256");
         if (secret === null || !sameHex(`sha256=${createHmac("sha256", secret).update(delivery.body).digest("hex")}`, signature))
             return { status: 401, said: "Signature doesn't match." };
-        const event = header(delivery, "x-github-event"), body = record(payload), action = text(body["action"]);
-        const repository = text(record(body["repository"])["full_name"]);
+        const event = header(delivery, "x-github-event"), body = readGithubEvent(payload), action = body.action ?? "";
+        const repository = body.repository?.full_name ?? "";
         if (event === "ping") {
             note("GitHub connected.");
             return { status: 200, said: "Connected." };
@@ -972,10 +969,10 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
         if (repository.toLowerCase() !== config.repo.toLowerCase())
             return { status: 202, said: "Not this repository." };
         // A label trigger takes the moment its label is added (or an issue opened with it); a plain one takes new issues.
-        const labeledNow = action === "labeled" && config.label !== null && text(record(body["label"])["name"]).toLowerCase() === config.label.toLowerCase();
-        const found = config.watch === "issues" && event === "issues" && (action === "opened" || labeledNow) ? githubItem(config, body["issue"], "issue")
-            : config.watch === "pulls" && event === "pull_request" && ["opened", "ready_for_review", "labeled", "reopened"].includes(action) ? githubItem(config, body["pull_request"], "pull")
-                : config.watch === "checks" && event === "workflow_run" && action === "completed" ? githubRunItem(config, body["workflow_run"]) : null;
+        const labeledNow = action === "labeled" && config.label !== null && (body.label?.name ?? "").toLowerCase() === config.label.toLowerCase();
+        const found = config.watch === "issues" && event === "issues" && (action === "opened" || labeledNow) ? githubItem(config, body.issue, "issue")
+            : config.watch === "pulls" && event === "pull_request" && ["opened", "ready_for_review", "labeled", "reopened"].includes(action) ? githubItem(config, body.pull_request, "pull")
+                : config.watch === "checks" && event === "workflow_run" && action === "completed" ? githubRunItem(config, body.workflow_run) : null;
         items = found === null ? [] : [found];
     }
     else if (config.kind === "linear") {
@@ -984,23 +981,26 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
             return { status: 401, said: "Paste Linear's signing secret on the flow's Triggers panel first." };
         if (!sameHex(createHmac("sha256", secret).update(delivery.body).digest("hex"), header(delivery, "linear-signature")))
             return { status: 401, said: "Signature doesn't match." };
-        const body = record(payload), sent = Number(body["webhookTimestamp"]);
+        const body = readLinearEvent(payload), sent = Number(body.webhookTimestamp);
         if (!Number.isFinite(sent) || Math.abs(now.getTime() - sent) > 5 * 60_000)
             return { status: 401, said: "Too old." };
-        if (text(body["type"]) !== "Issue" || !["create", "update"].includes(text(body["action"])))
+        if (body.type !== "Issue" || !["create", "update"].includes(body.action ?? ""))
             return { status: 202, said: "Ignored." };
         // A state trigger fires when the issue arrives in that state, not on every later edit there.
-        const moved = text(body["action"]) === "create" || record(body["updatedFrom"])["stateId"] !== undefined || config.state === null;
-        const found = moved ? linearItem(config, body["data"]) : null;
+        const moved = body.action === "create" || body.updatedFrom?.stateId !== undefined || config.state === null;
+        const found = moved ? linearItem(config, body.data) : null;
         items = found === null ? [] : [found];
     }
     else if (config.kind === "webhook") {
-        const pick = (path) => path === null ? null : path.split(".").reduce((node, part) => record(node)[part], payload);
+        // Any JSON, kept as sent: the trigger's own paths are picked from it, and it is shown whole when they find no text.
+        const body = readWebhookPayload(payload);
+        const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+        const pick = (path) => path === null ? null : path.split(".").reduce((node, part) => record(node)[part], body);
         const title = pick(config.titleField ?? "title") ?? pick("summary") ?? pick("message");
         const bodyText = pick(config.bodyField ?? "description") ?? pick("body") ?? pick("text");
         const id = header(delivery, "x-request-id") || header(delivery, "x-delivery-id") || header(delivery, "idempotency-key") || createHash("sha256").update(delivery.body).digest("hex");
         items = [{ key: `hook:${id.slice(0, 120)}`, at: null, title: typeof title === "string" && title.trim() !== "" ? title : config.title,
-                description: `From a webhook:\n\n${typeof bodyText === "string" ? bodyText : JSON.stringify(payload, null, 2)}`.slice(0, 4000),
+                description: `From a webhook:\n\n${typeof bodyText === "string" ? bodyText : JSON.stringify(body, null, 2)}`.slice(0, 4000),
                 source: { kind: "webhook", label: "Webhook", url: null } }];
     }
     if (items.length === 0)
@@ -1081,13 +1081,14 @@ export function receiveFlowForm(store, token, fields, now) {
     const again = `<p><a href="${esc(FORM_PATH + token)}">Send another</a></p>`;
     const thanks = formHtml(config.label, `<p>Thanks — it's been sent.</p>${again}`);
     // A filled trap, or a page posted faster than a person could, gets thanks and makes nothing.
-    const shown = Number(fields.get("t"));
-    if ((fields.get("website") ?? "") !== "" || !Number.isFinite(shown) || now.getTime() - shown < 2000 || now.getTime() - shown > 86_400_000)
+    const form = readFormSubmission(fields, config.questions.length);
+    const shown = Number(form.t);
+    if ((form.website ?? "") !== "" || !Number.isFinite(shown) || now.getTime() - shown < 2000 || now.getTime() - shown > 86_400_000)
         return { status: 200, html: thanks };
     const recent = store.handle.prepare("SELECT COUNT(*) AS n FROM flow_trigger_event WHERE trigger = ? AND key LIKE 'form:%' AND at > ?").get(trigger.id, new Date(now.getTime() - 3_600_000).toISOString());
     if (Number(recent?.["n"] ?? 0) >= FORM_CARDS_PER_HOUR)
         return { status: 429, html: formHtml(config.label, `<p>Too many sent in the last hour. Try again later.</p>`) };
-    const answers = config.questions.map((_question, index) => (fields.get(`a${index}`) ?? "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim().slice(0, index === 0 ? 200 : 3000));
+    const answers = form.answers.map((answer, index) => (answer ?? "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim().slice(0, index === 0 ? 200 : 3000));
     if (answers[0] === "")
         return { status: 400, html: formHtml(config.label, `<p>Answer “${esc(config.questions[0])}” first.</p>${again}`) };
     const details = config.questions.slice(1).map((question, index) => answers[index + 1] === "" ? null : `${question}\n${answers[index + 1]}`).filter(one => one !== null).join("\n\n");

package/dist/mcp-connect.d.ts

@@ -64,7 +64,6 @@ export declare function connectionsOf(store: Store, repo: string, home?: string)
  */
 export declare function readsOnly(action: string, subjects: readonly string[]): boolean;
 export declare const readScope: (scope: string) => boolean;
-/** Whether a saved grant only reads: it names at least one scope and every one is a read or identity scope. Unknown (null) never is. */
 export declare const readOnlyGrant: (grant: readonly string[] | null) => boolean;
 /** An OAuth `scope` value as scope tokens (RFC 6749), sorted and deduplicated; null when absent, empty or malformed. */
 export declare function scopeList(value: unknown): string[] | null;

package/dist/mcp-connect.js

@@ -16,6 +16,7 @@ import { homedir } from "node:os";
 import { basename } from "node:path";
 import { LOCAL_APPS, addToolTo, catalogTool, localAppOf, projectToolsOf, readToolSecrets, setToolSecrets, testToolOf } from "./project-tools.js";
 import { envValue } from "./names.js";
+import { SCOPE_TOKEN, readAuthorizationServer, readProtectedResource, readRegistration, readTokenResponse } from "./contracts/integration-metadata.js";
 /**
  * Services that connect this way: their servers speak streamable HTTP and
  * advertise registering clients on the spot. Advertising isn't accepting:
@@ -133,7 +134,10 @@ const IDENTITY_SCOPES = new Set(["openid", "profile", "email"]);
 const READ_SCOPE = /^[a-z][a-z0-9_]{0,63}:read$/;
 export const readScope = (scope) => IDENTITY_SCOPES.has(scope) || READ_SCOPE.test(scope);
 /** Whether a saved grant only reads: it names at least one scope and every one is a read or identity scope. Unknown (null) never is. */
-export const readOnlyGrant = (grant) => grant !== null && grant.length > 0 && grant.every(readScope);
+// A scope a server adds to every token without being asked, that grants no access to data. PostHog adds
+// `introspection` (its ALWAYS_ALLOWED_SCOPES): it lets the token be checked, and has no write form. Never requested.
+const GRANTED_ANYWAY = new Set(["introspection"]);
+export const readOnlyGrant = (grant) => grant !== null && grant.some(readScope) && grant.every(scope => readScope(scope) || GRANTED_ANYWAY.has(scope));
 /** An OAuth `scope` value as scope tokens (RFC 6749), sorted and deduplicated; null when absent, empty or malformed. */
 export function scopeList(value) {
     if (typeof value !== "string")
@@ -199,8 +203,7 @@ const GRANTED = "OAUTH_GRANTED_SCOPE";
 export const CONNECT_CALLBACK = "/settings/tools/connected";
 const VISIT_MS = 15 * 60_000, RENEW_RETRY_MS = 5 * 60_000;
 const renewTried = new Map();
-/** RFC 6749 scope tokens; and the most scope text a sign-in address carries (addresses stay well under 8 KB). */
-const SCOPE_TOKEN = /^[\x21\x23-\x5b\x5d-\x7e]{1,128}$/;
+/** The most scope text a sign-in address carries (addresses stay well under 8 KB). */
 const SCOPE_PARAM_LIMIT = 6_000;
 const json = async (fetcher, url) => {
     try {
@@ -235,25 +238,29 @@ export async function discoverSignIn(mcpUrl, fetcher = fetch) {
     catch {
         pointer = null;
     }
-    const resource = (pointer !== null && https(pointer) ? await json(fetcher, pointer) : null)
+    const found = (pointer !== null && https(pointer) ? await json(fetcher, pointer) : null)
         ?? await json(fetcher, `${mcp.origin}/.well-known/oauth-protected-resource${mcp.pathname === "/" ? "" : mcp.pathname}`)
         ?? await json(fetcher, `${mcp.origin}/.well-known/oauth-protected-resource`);
-    const issuers = Array.isArray(resource?.["authorization_servers"]) ? resource["authorization_servers"].filter(https) : [];
+    const resource = found === null ? {} : readProtectedResource(found);
+    const issuers = (resource.authorization_servers ?? []).filter(https);
     const issuer = new URL(issuers[0] ?? mcp.origin);
     const path = issuer.pathname === "/" ? "" : issuer.pathname.replace(/\/$/, "");
-    const meta = await json(fetcher, `${issuer.origin}/.well-known/oauth-authorization-server${path}`)
+    const answered = await json(fetcher, `${issuer.origin}/.well-known/oauth-authorization-server${path}`)
         ?? await json(fetcher, `${issuer.origin}/.well-known/oauth-authorization-server`)
         ?? (path === "" ? null : await json(fetcher, `${issuer.origin}${path}/.well-known/openid-configuration`))
         ?? await json(fetcher, `${issuer.origin}/.well-known/openid-configuration`);
-    if (meta === null || !https(meta["authorization_endpoint"]) || !https(meta["token_endpoint"]) || !https(meta["registration_endpoint"]))
+    if (answered === null)
         return null;
-    const methods = Array.isArray(meta["code_challenge_methods_supported"]) ? meta["code_challenge_methods_supported"] : ["S256"];
-    if (!methods.includes("S256"))
+    const meta = readAuthorizationServer(answered);
+    const { authorization_endpoint: authorize, token_endpoint: token, registration_endpoint: register } = meta;
+    if (!https(authorize) || !https(token) || !https(register))
+        return null;
+    if (!(meta.code_challenge_methods_supported ?? ["S256"]).includes("S256"))
         return null;
     // Ask for every scope the server lists for this resource: a token missing one the server itself requires is
     // refused after a successful sign-in (PostHog lists 155 and needs user:read, the 140th). Only well-formed scope
     // tokens, and at most what fits a sign-in address.
-    const listed = Array.isArray(resource?.["scopes_supported"]) ? resource["scopes_supported"].filter((one) => typeof one === "string" && SCOPE_TOKEN.test(one)) : [];
+    const listed = resource.scopes_supported ?? [];
     const scopes = [];
     for (const one of listed) {
         if (scopes.join(" ").length + one.length + 1 > SCOPE_PARAM_LIMIT)
@@ -261,8 +268,8 @@ export async function discoverSignIn(mcpUrl, fetcher = fetch) {
         scopes.push(one);
     }
     // A token is for the resource the server names (Stripe's has no trailing slash), when it names one.
-    const named = resource?.["resource"];
-    return { authorize: meta["authorization_endpoint"], token: meta["token_endpoint"], register: meta["registration_endpoint"], scopes, resource: https(named) ? named : null };
+    const named = resource.resource;
+    return { authorize, token, register, scopes, resource: https(named) ? named : null };
 }
 /**
  * Start connecting a service: find its sign-in, register this console as a
@@ -284,11 +291,14 @@ export async function startConnect(input, fetcher = fetch, now = Date.now()) {
         // Figma's answer (Oct 2026): it registers only apps it has approved. Said before reading a body that may not be JSON.
         if (registered.status === 401 || registered.status === 403)
             return { ok: false, said: `${service.label} doesn't let other apps sign in this way yet.${INSTEAD[service.id] === undefined ? "" : ` ${INSTEAD[service.id]}`}` };
-        const body = await registered.json();
-        if (!registered.ok || typeof body.client_id !== "string")
+        const body = readRegistration(await registered.json());
+        // A `null` answer that says it registered is no answer, as it always read.
+        if (registered.ok && body === null)
+            return { ok: false, said: `${service.label} couldn't be reached.` };
+        if (!registered.ok || body?.client_id === undefined)
             return { ok: false, said: `${service.label} didn't let Toolroll register (HTTP ${registered.status}).` };
         clientId = body.client_id;
-        clientSecret = typeof body.client_secret === "string" ? body.client_secret : null;
+        clientSecret = body.client_secret ?? null;
     }
     catch {
         return { ok: false, said: `${service.label} couldn't be reached.` };
@@ -324,9 +334,9 @@ export function connectedSpec(serviceId) {
         secrets: [ACCESS, REFRESH, CLIENT, CLIENT_SECRET, TOKEN_URL, EXPIRES, RESOURCE].map(name => ({ name, optional: name !== ACCESS })), about: `${service.label}: ${service.about} Connected by signing in.` };
 }
 const tokensFrom = (body, now) => ({
-    access: typeof body["access_token"] === "string" ? body["access_token"] : null,
-    refresh: typeof body["refresh_token"] === "string" ? body["refresh_token"] : null,
-    expires: typeof body["expires_in"] === "number" && body["expires_in"] > 0 ? new Date(now + body["expires_in"] * 1000).toISOString() : null,
+    access: body.access_token ?? null,
+    refresh: body.refresh_token ?? null,
+    expires: body.expires_in === undefined ? null : new Date(now + body.expires_in * 1000).toISOString(),
 });
 /**
  * Finish connecting: trade the code for tokens, add the tool to the project
@@ -344,9 +354,13 @@ export async function finishConnect(store, visit, code, now, options = {}) {
     try {
         const answer = await fetcher(visit.token, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, signal: AbortSignal.timeout(15_000),
             body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: visit.redirect, client_id: visit.clientId, code_verifier: visit.verifier, resource: visit.resource, ...(visit.clientSecret === null ? {} : { client_secret: visit.clientSecret }) }) });
-        body = await answer.json();
+        const read = readTokenResponse(await answer.json());
+        // An answer of `null` reads as none, like one that isn't JSON.
+        if (read === null)
+            return { ok: false, said: `${service.label} couldn't be reached to finish the sign-in.` };
+        body = read;
         if (!answer.ok)
-            return { ok: false, said: `${service.label} didn't finish the sign-in (${typeof body["error"] === "string" ? body["error"] : `HTTP ${answer.status}`}).` };
+            return { ok: false, said: `${service.label} didn't finish the sign-in (${body.error ?? `HTTP ${answer.status}`}).` };
     }
     catch {
         return { ok: false, said: `${service.label} couldn't be reached to finish the sign-in.` };
@@ -360,7 +374,7 @@ export async function finishConnect(store, visit, code, now, options = {}) {
             return { ok: false, said: added.message };
     }
     // The grant: what the answer says, or what was asked for when it says nothing; never one from an earlier sign-in.
-    const granted = "scope" in body ? scopeList(body["scope"]) : scopeList(visit.scope ?? null);
+    const granted = body.scopeSaid ? scopeList(body.scope) : scopeList(visit.scope ?? null);
     setToolSecrets(visit.repo, spec.name, { [ACCESS]: tokens.access, [CLIENT]: visit.clientId, [TOKEN_URL]: visit.token, [RESOURCE]: visit.resource, [GRANTED]: granted?.join(" ") ?? "",
         ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }), ...(visit.clientSecret === null ? {} : { [CLIENT_SECRET]: visit.clientSecret }) }, home);
     // The success line names the project it went to: the page and chat may be looking at another.
@@ -391,7 +405,11 @@ export async function refreshConnections(store, repos, now, options = {}) {
             try {
                 const answer = await fetcher(values[TOKEN_URL], { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, signal: AbortSignal.timeout(15_000),
                     body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: values[REFRESH], client_id: values[CLIENT], ...(values[CLIENT_SECRET] === undefined ? {} : { client_secret: values[CLIENT_SECRET] }), ...(values[RESOURCE] === undefined ? {} : { resource: values[RESOURCE] }) }) });
-                const body = await answer.json();
+                const body = readTokenResponse(await answer.json());
+                if (body === null) {
+                    report.problems.push(`${tool.name}: couldn't reach it to renew its sign-in`);
+                    continue;
+                }
                 const tokens = tokensFrom(body, now.getTime());
                 if (!answer.ok || tokens.access === null) {
                     report.problems.push(`${tool.name}: its sign-in ran out; connect it again on the Tools page`);
@@ -399,7 +417,7 @@ export async function refreshConnections(store, repos, now, options = {}) {
                 }
                 // A refresh carries the same grant or a narrower one, and says so when it changes; said badly, it is unknown.
                 setToolSecrets(repo, tool.name, { [ACCESS]: tokens.access, ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }),
-                    ...("scope" in body ? { [GRANTED]: scopeList(body["scope"])?.join(" ") ?? "" } : {}) }, home);
+                    ...(body.scopeSaid ? { [GRANTED]: scopeList(body.scope)?.join(" ") ?? "" } : {}) }, home);
                 renewTried.delete(key);
                 report.refreshed++;
             }

package/dist/model-catalog.js

@@ -11,6 +11,7 @@ import { accessSync, constants, lstatSync, readFileSync, realpathSync } from "no
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { fetchOpenRouterModels } from "./openrouter-models.js";
+import { codexModelSchema, codexModelsCacheSchema, npmLatestSchema } from "./contracts/model-catalog.js";
 import { readCappedBody } from "./converse.js";
 import { validModelId } from "./provider.js";
 import { activeUpdateWork } from "./desktop-update-gate.js";
@@ -73,10 +74,11 @@ export function codexCatalog(home = homedir()) {
         const path = join(home, ".codex", "models_cache.json");
         if (lstatSync(path).size >= 2_000_000)
             return [];
-        const data = JSON.parse(readFileSync(path, "utf8"));
-        return (Array.isArray(data.models) ? data.models : [])
-            .filter(one => one != null && one.visibility === "list" && typeof one.slug === "string" && validModelId(one.slug))
-            .slice(0, 30).map(one => ({ id: one.slug, name: typeof one.display_name === "string" ? one.display_name.slice(0, 80) : one.slug }));
+        const data = codexModelsCacheSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
+        return (data.success ? data.data.models : []).flatMap(entry => {
+            const one = codexModelSchema.safeParse(entry);
+            return one.success ? [one.data] : [];
+        }).slice(0, 30).map(one => ({ id: one.slug, name: typeof one.display_name === "string" ? one.display_name.slice(0, 80) : one.slug }));
     }
     catch {
         return [];
@@ -255,8 +257,8 @@ async function latestVersion(pkg, fetcher) {
         const body = await readCappedBody(response, 2_000_000);
         if (body === null)
             return null;
-        const version = JSON.parse(new TextDecoder().decode(body)).version;
-        return typeof version === "string" && /^\d+\.\d+\.\d+/.test(version) ? version : null;
+        const latest = npmLatestSchema.safeParse(JSON.parse(new TextDecoder().decode(body)));
+        return latest.success ? latest.data.version : null;
     }
     catch {
         return null;

package/dist/observations.d.ts

@@ -1,5 +1,6 @@
 import type { Runner } from "./builder.js";
 import type { Store } from "./store.js";
+import { type ObservationCase } from "./contracts/observation-request.js";
 export declare const OBSERVATION_MAILBOX = "STANDING-ORDERS-OBSERVATIONS.json";
 export declare const OBSERVATION_CAPTURE = "machine focused observations v1";
 export declare const OBSERVATION_FILE = "REVIEW-OBSERVATIONS.json";
@@ -18,12 +19,7 @@ export type ObservationBrief = {
     gateDigest: string;
 };
 export declare function focusedTestCommandSupported(command: string): boolean;
-export type ObservationCase = {
-    criterion: string;
-    at: "base" | "head";
-    testPath: string;
-    testName: string;
-};
+export type { ObservationCase };
 export declare function originalTaskBase(store: Store, taskId: string): string | null;
 /** The existing sealed revision brief identifies this narrower kind of work.
  * A title, agent-authored mailbox, or handoff can never elect gate reuse. */