toolroll 0.9.34 → 0.9.36

package/dist/mate-tools.js

@@ -45,7 +45,10 @@ import { agentChoicesFor, routeOfTask, INSTALLATION_SCOPE } from "./agentconfig.
 import { isNewModel, modelWords, priceWords, runtimeStates, seenModels } from "./model-catalog.js";
 import { agentsSummary, chosenWords, isRiskLevel, isTaskSize, PHASES, postureWords, RISK_CHOICES, riskConsequence, riskTitle, routeProblems, sameSpec, sizeSourceWords, sizeWords, specWords } from "./phase-routing.js";
 import { TOOL_CATALOG, discoverTools, projectToolsOf, secretsSetFor, toolCommandLine, toolStanding } from "./project-tools.js";
-import { deciderOf, durationWords, FLOW_KIND_WORDS, FLOW_STAGE_KINDS, FLOW_TEMPLATES, flowFromSteps, stepsFor } from "./flows.js";
+import { deciderOf, durationWords, FLOW_KIND_WORDS, FLOW_TEMPLATES, flowFromSteps, stepsFor, withKeptSteps } from "./flows.js";
+import { parseContract } from "./contracts/contract.js";
+import { FLOW_ALIASES } from "./contracts/flow.js";
+import { PROPOSE_FLOW_MODEL_SCHEMA, proposeFlowInputSchema } from "./contracts/flow-propose.js";
 import { flowDefinitionOf } from "./flow-engine.js";
 import { flowPersonOf } from "./flow-send.js";
 import { flowInsights } from "./flow-insights.js";
@@ -890,49 +893,16 @@ export const MATE_TOOLS = [
     {
         name: "propose_flow",
         description: "Draft a flow change as a card the operator confirms. To make a flow, create with a template or the steps in plain names; leave instructions out unless the operator gave them, and use decider 'me' when they decide. To change one, edit with the whole step list, keeping existing steps by id. For cards use add_card, move_card, approve, send_back with the operator's note, or cancel_card; find the card by what it is about; comment (with @name to ping someone), assign and follow here too. For triage, spam, lead, effort or exception routing, start from the matching template, with the sort as the first step. Use remindAfter and thenMoveTo for follow-ups and decisions that stall. The Issues to PRs template runs GitHub issues labelled toolroll through build, approval, pull request and a comment on the issue. When the operator asks for something to happen every time (fix CI when it fails, turn labelled issues into tasks, queue work overnight, review what went wrong every morning), offer the matching starter; each is one yes, and none merges without a person. When someone new wants a support desk, bug triage, sales follow-up or requests handled, a kit sets up the teammate and its flow in one card. Teammates: propose_teammate adds one (from a template: support, sales, ops, triage), changes one rule section (edit_section), pauses, resumes or removes it, passes it a note, or answers its question for the operator; put it to work with a flow here. When the operator says something like 'Maya can approve refunds up to $100 now', change that section of her soul file; when it's for this week or a one-off, pass it as a note. Teammates use the project's tools under a rule per action (do it, ask first: the operator approves each exact call, never, or up to a limit on a number); propose_teammate use_tool, stop_tool and tool_rule change them, and when a rule has a limit also change the soul file so its words agree. forget or edit_memory when the operator says a teammate has something wrong; a rule change it suggests is a question for the operator, answered only as they say. propose_teammate add_routine puts a card on its desk on a schedule; propose_teammate undo undoes a tool call only when its action has an undo set (tool_rule undoWith). Actions: starter: switch on a starter flow in a project (repo, starter: ci-fix files a fix task when CI fails on the main branch, issue-task makes a task of each GitHub issue labelled toolroll, overnight holds cards added in the day until 22:00 and leaves results for the morning, plane-review reviews the plane's last 24 hours every morning and turns each problem worth fixing into a researched fix and a pull request) — its zones and trigger in one card; offer the matching one when the operator says to do something every time. kit: set up a starter kit in a project (repo, kit: support-desk, bug-triage, sales-follow-up or ops-requests) — a teammate, the flow it works and its buttons, in one card; prefer it when the operator wants a support desk, bug triage, sales follow-up or requests handled. create: a template, or the steps in order (each leads to the next; Done is added; instructions may be left out). 'request' calls a web address (method, url with its host written out, headers — {{secret.NAME}} uses a secret the operator saved on the step, never in chat — and body); 'email' sends mail (to, subject, body; {{card.email}} is the card's email address); 'tool' calls one of the project's tools (server: the tool's name from get_project_tools, tool: its function, args: an object). Put a decision before any of these when they send what a model wrote or what an outsider sent. A 'draft' step has Claude write something from the card (instructions: what to write); follow it with an approval step (decider 'owner' asks the flow's owner in their chat app, where they can approve, edit or send it back), then an 'update' or 'notify' step whose message is '{{stage.<draft id>}}'. A 'sort' step has Jev pick one of its answers; make it the first step (never a holding step before it, or new cards wait unsorted): question, answers (answer, means: a few words Jev reads, goesTo: a step), sureAt (percent, default 80), ifNotSure (a step; otherwise the card waits for a person), and up to 3 alsoNote (score with levels lowest first, or yes-no); a sort has no next, so give each branch's last step its own next. A 'pull-request' step opens a pull request for the card's built result and waits for CI: next when it passes, ifFails when it fails (only this step defaults it: to the build before it, as a revision carrying the failing check); merge ('squash', 'merge' or 'rebase') merges once checks pass, and needs an approval step before it on every path. waitFor 'hours' with from and until (like '22:00' and '06:00') holds cards until the clock is inside those hours. A 'wait' step, after an 'email' step, waits for a reply to that email from someone it went to (waitFor 'reply', the default): next is where a reply goes (the reply is {{stage.<wait id>}}), ifNoReply where the card goes when none comes within wait (like '3 days', up to 30 days); waitFor 'time' just waits, then next. Any step but wait and done can have remindAfter (like '2 days': whoever it waits on is reminded once; 'none' removes it) and, on holding and approval steps, thenMoveTo (a step the card moves to then). AI teammates (get_teammates): an approval step with teammate (its short name) is decided by that teammate within its rules, and it hands hard ones to the step's decider; a 'teammate' step (teammate, instructions, routes of answer and goesTo) has it read the card, pick where it goes and write what the next steps send (the email body is then {{stage.<id>}}), asking the flow's owner when its rules say to. edit: the full step list, keeping existing steps by id — what a kept step leaves out carries over. add_card (starts in the first zone unless zone is named), move_card, approve, send_back (needs a note), cancel_card, comment (note; @name pings that person), assign (owner: a name, 'me', or 'nobody'), follow, unfollow, save_script (repo, and script: name, about, language python|node|shell, and either body (short) or file (a path in the project, like scripts/enrich.py), and timeoutMinutes; scripts belong to the project, so no flow is needed; a 'check' step in any of its flows names it). A 'check' step runs its script with the card as JSON on stdin (and in $FLOW_INPUT); what it prints is its result for later steps ({{stage.<id>}}); runIn 'folder' (an empty folder: for scripts that work on data) or 'copy' (a copy of the card's work, after setup: for tests on code; the default); routes (answer, goesTo) that a last printed line 'goto: <answer>' picks; ifFails is where a failing script sends the card, such as back to the build (it has no default: without it the card waits there); secrets (names of saved secrets it gets as variables). add_trigger with settings (kind button: label, questions; schedule: schedule like 'daily 09:00 Europe/London', and title, or script (a saved script whose printed items — one per line, a title or JSON with title, description, key — each become a card, once) with secrets; github: repo owner/name, watch issues|pulls|checks, label, branch, from team|anyone; linear: team, state, label; flow: follow (another flow's id), when (its zone); email: folder (default INBOX), sender (addresses or domains), subject (words it must contain); plane-review: at (HH:MM, default 07:30), timeZone — every day it reads the plane's last 24 hours and makes one card per problem worth fixing, a returning problem joining its card); pause_trigger, resume_trigger, remove_trigger with trigger. A 'send' step ('Send to me') sends the card's owner what the step before produced (summary, links, screenshots) in their chat apps, then moves on; a 'choose' step sends the same with 2 to 4 options (label, goesTo: a step, or 'end' to ignore the card) as buttons, ifReplied (where a reply goes as {{note}}; the build before by default), and remindAfter with ifNoReply. choose (card, and choice by number or a note to reply) answers one for the operator. A 'task' step may build in another project: repo (from list_repos). Read get_flows first except to create.",
-        inputSchema: schema({
-            operation: { type: "string", enum: ["create", "edit", "add_card", "move_card", "approve", "send_back", "choose", "cancel_card", "comment", "assign", "follow", "unfollow", "save_script", "add_trigger", "pause_trigger", "resume_trigger", "remove_trigger", "kit", "starter"] },
-            repo: REPO_ARG, flow: { type: "integer", minimum: 1 }, card: { type: "integer", minimum: 1 }, kit: { type: "string", enum: KITS.map(one => one.id) },
-            starter: { type: "string", enum: [...STARTER_IDS] },
-            name: { type: "string", maxLength: 80 }, template: { type: "string", enum: FLOW_TEMPLATES.map(one => one.id) },
-            steps: { type: "array", minItems: 1, maxItems: 24, items: { type: "object", additionalProperties: false, properties: {
-                        id: { type: "string", maxLength: 32 }, title: { type: "string", maxLength: 60 }, kind: { type: "string", enum: [...FLOW_STAGE_KINDS] },
-                        instructions: { type: "string", maxLength: TEXT_LIMITS.flowInstructions }, planning: { type: "string", enum: ["auto", "required", "skip"] },
-                        decider: { type: "string", maxLength: 64 }, message: { type: "string", maxLength: 1000 },
-                        script: { type: "string", maxLength: 40 }, close: { type: "boolean" },
-                        question: { type: "string", maxLength: 300 }, sureAt: { type: "integer", minimum: 50, maximum: 99 },
-                        answers: { type: "array", minItems: 2, maxItems: 12, items: { type: "object", additionalProperties: false, properties: { answer: { type: "string", maxLength: 40 }, means: { type: "string", maxLength: 200 }, goesTo: { type: "string", maxLength: 60 } } } },
-                        alsoNote: { type: "array", maxItems: 3, items: { type: "object", additionalProperties: false, properties: { question: { type: "string", maxLength: 300 }, kind: { type: "string", enum: ["score", "yes-no"] }, levels: { type: "array", minItems: 2, maxItems: 10, items: { type: "string", maxLength: 120 } } } } },
-                        method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"] }, url: { type: "string", maxLength: 2000 },
-                        headers: { type: "object", additionalProperties: { type: "string", maxLength: 500 } }, body: { type: "string", maxLength: 8000 },
-                        to: { type: "string", maxLength: 500 }, subject: { type: "string", maxLength: 200 },
-                        server: { type: "string", maxLength: 64 }, tool: { type: "string", maxLength: 100 }, args: { type: "object" },
-                        runIn: { type: "string", enum: ["folder", "copy"] }, routes: { type: "array", maxItems: 12, items: { type: "object", additionalProperties: false, properties: { answer: { type: "string", maxLength: 40 }, goesTo: { type: "string", maxLength: 60 } } } },
-                        secrets: { type: "array", maxItems: 10, items: { type: "string", maxLength: 40 } },
-                        waitFor: { type: "string", enum: ["reply", "time", "hours"] }, wait: { type: "string", maxLength: 40 }, ifNoReply: { type: "string", maxLength: 60 },
-                        from: { type: "string", maxLength: 5 }, until: { type: "string", maxLength: 5 }, merge: { type: "string", enum: ["squash", "merge", "rebase"] },
-                        remindAfter: { type: "string", maxLength: 40 }, thenMoveTo: { type: "string", maxLength: 60 }, teammate: { type: "string", maxLength: 40 },
-                        options: { type: "array", minItems: 2, maxItems: 4, items: { type: "object", additionalProperties: false, properties: { label: { type: "string", maxLength: 40 }, goesTo: { type: "string", maxLength: 60 } } } },
-                        ifReplied: { type: "string", maxLength: 60 }, repo: REPO_ARG,
-                        next: { type: "string", maxLength: 60 }, ifFails: { type: "string", maxLength: 60 }, ifNotSure: { type: "string", maxLength: 60 },
-                    } } },
-            title: { type: "string", maxLength: 200 }, description: { type: "string", maxLength: 4000 }, zone: { type: "string", maxLength: 60 }, note: { type: "string", maxLength: LIMITS.note, description: `At most ${LIMITS.note} characters; longer is refused with its length, not cut.` },
-            choice: { type: "integer", minimum: 1, maximum: 4 },
-            trigger: { type: "integer", minimum: 1 }, owner: { type: "string", maxLength: 64 },
-            script: { type: "object", additionalProperties: false, properties: { name: { type: "string", maxLength: 40 }, about: { type: "string", maxLength: 160 }, body: { type: "string", maxLength: 1600 }, timeoutMinutes: { type: "integer", minimum: 1, maximum: 60 },
-                    language: { type: "string", enum: ["python", "node", "shell"] }, file: { type: "string", maxLength: 200 } } },
-            settings: { type: "object", additionalProperties: false, properties: {
-                    kind: { type: "string", enum: FLOW_TRIGGER_KINDS.filter(one => one !== "webhook" && one !== "chat") }, zone: { type: "string", maxLength: 60 },
-                    label: { type: "string", maxLength: 50 }, questions: { type: "array", maxItems: 6, items: { type: "string", maxLength: 80 } },
-                    schedule: { type: "string", maxLength: 80 }, title: { type: "string", maxLength: 200 }, description: { type: "string", maxLength: 2000 },
-                    repo: { type: "string", maxLength: 140 }, watch: { type: "string", enum: ["issues", "pulls", "checks"] }, branch: { type: "string", maxLength: 100 }, from: { type: "string", enum: ["team", "anyone"] },
-                    team: { type: "string", maxLength: 12 }, state: { type: "string", maxLength: 40 }, follow: { type: "integer", minimum: 1 }, when: { type: "string", maxLength: 60 },
-                    folder: { type: "string", maxLength: 100 }, sender: { type: "string", maxLength: 300 }, subject: { type: "string", maxLength: 100 },
-                    script: { type: "string", maxLength: 40 }, secrets: { type: "array", maxItems: 10, items: { type: "string", maxLength: 40 } },
-                    at: { type: "string", maxLength: 5 }, timeZone: { type: "string", maxLength: 60 },
-                } },
-        }, ["operation"]),
-        handle: (ctx, args) => {
+        inputSchema: { ...PROPOSE_FLOW_MODEL_SCHEMA },
+        handle: (ctx, given) => {
+            // The call is read by the schema the lead was given: a refusal names each path (`steps[0].routes[0].goesTo: required`).
+            // An edit's kept steps may leave their kind and name to the zone they keep.
+            const editing = given["operation"] === "edit" && Number.isSafeInteger(given["flow"]) ? ctx.store.getFlow(Number(given["flow"])) : null;
+            const kept = editing !== null && ctx.who.repos.includes(editing.repo) ? flowDefinitionOf(editing) : null;
+            const read = parseContract(proposeFlowInputSchema, given["steps"] === undefined ? given : { ...given, steps: withKeptSteps(given["steps"], kept) }, FLOW_ALIASES);
+            if (!read.ok)
+                return { ok: false, message: read.issues.map(one => one.line).join("\n") };
+            const args = read.value;
             const pick = (keys) => Object.fromEntries(keys.filter(key => args[key] !== undefined).map(key => [key, args[key]]));
             // "me" in a step means the operator; the drawing stores their name.
             // A build step in another project names it as list_repos does (r2); the drawing keeps its path.

package/dist/mcp-connect.d.ts

@@ -11,6 +11,9 @@ export type OneClick = {
     url: string;
     about: string;
     reads?: readonly string[];
+    /** Send no scope: the server applies its own preset for this resource (PostHog's MCP preset). Naming scopes there
+     * shows a 75-group permission grid instead, and the person can stop on it without ever coming back. */
+    serverScopes?: true;
 };
 /**
  * Services that connect this way: their servers speak streamable HTTP and

package/dist/mcp-connect.js

@@ -52,7 +52,7 @@ export const ONE_CLICK = [
     // Mobbin's sign-in is its Supabase auth server, on another origin: its protected-resource metadata names it.
     { id: "mobbin", label: "Mobbin", url: "https://api.mobbin.com/mcp", about: "Real app screens and flows to learn from.",
         reads: ["screen", "flow", "app", "site", "element", "pattern", "ui", "ios", "android", "web"] },
-    { id: "posthog", label: "PostHog", url: "https://mcp.posthog.com/mcp", about: "Product analytics, funnels and events.",
+    { id: "posthog", label: "PostHog", url: "https://mcp.posthog.com/mcp", about: "Product analytics, funnels and events.", serverScopes: true,
         reads: ["insight", "run", "event", "definition", "property", "properties"] },
     { id: "betterstack", label: "Better Stack", url: "https://mcp.betterstack.com", about: "Uptime checks and incidents.",
         reads: ["uptime", "monitor", "incident", "availability", "response", "time"] },
@@ -147,6 +147,9 @@ const ACCESS = "OAUTH_ACCESS_TOKEN", REFRESH = "OAUTH_REFRESH_TOKEN", CLIENT = "
 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}$/;
+const SCOPE_PARAM_LIMIT = 6_000;
 const json = async (fetcher, url) => {
     try {
         const answer = await fetcher(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
@@ -195,10 +198,19 @@ export async function discoverSignIn(mcpUrl, fetcher = fetch) {
     const methods = Array.isArray(meta["code_challenge_methods_supported"]) ? meta["code_challenge_methods_supported"] : ["S256"];
     if (!methods.includes("S256"))
         return null;
-    const scopes = Array.isArray(resource?.["scopes_supported"]) ? resource["scopes_supported"].filter((one) => typeof one === "string") : [];
+    // 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 scopes = [];
+    for (const one of listed) {
+        if (scopes.join(" ").length + one.length + 1 > SCOPE_PARAM_LIMIT)
+            break;
+        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: scopes.slice(0, 20), resource: https(named) ? named : null };
+    return { authorize: meta["authorization_endpoint"], token: meta["token_endpoint"], register: meta["registration_endpoint"], scopes, resource: https(named) ? named : null };
 }
 /**
  * Start connecting a service: find its sign-in, register this console as a
@@ -240,7 +252,7 @@ export async function startConnect(input, fetcher = fetch, now = Date.now()) {
     go.searchParams.set("code_challenge_method", "S256");
     go.searchParams.set("state", state);
     go.searchParams.set("resource", resource);
-    if (server.scopes.length > 0)
+    if (server.scopes.length > 0 && service.serverScopes !== true)
         go.searchParams.set("scope", server.scopes.join(" "));
     return { ok: true, go: go.toString(), state, visit: { service: service.id, repo: input.repo, by: input.by, kit: input.kit ?? null, template: input.template ?? null, verifier, clientId, clientSecret, token: server.token, resource, redirect, expires: now + VISIT_MS } };
 }

package/dist/operate.js

@@ -53,6 +53,7 @@ import { FLOWS_VALUE_FLAGS, runFlowsCommand } from "./flows-cli.js";
 import { runAssignmentCommand } from "./assignment-adapters.js";
 import { applyProjectProfile, runProjectCommand } from "./project-cli.js";
 import { pullRequestLines, runTaskMergeCommand, runTaskOutcomeCommand } from "./task-outcome-cli.js";
+import { taskReviewBrief, renderReviewBrief } from "./task-review-brief.js";
 /**
  * The commands that actually move work: authoring tasks, and the claim loop.
  *
@@ -261,6 +262,7 @@ export const OPERATE_HELP = `toolroll — operating the queue
   toolroll backup now|list          back the database up now; list backups and how the last ones went
   toolroll restore <file> [--dry-run]  put a backup back (Toolroll stopped; the current database is kept)
   toolroll review show|on|off --repo <path>  one automatic review of each finished build; only HIGH findings send it back
+  toolroll task review <id> --brief   compact saved result, checks and findings; --run <id>, --all, --json
   toolroll policy show|set          the organisation policy; an instance operator sets it with --providers claude,codex|any,
                                         --models <m,…>|any, --tools <t,…>|any, --ceiling safe|standard|escalated
   toolroll ledger verify             check the action ledger's hash chain (--checkpoint <n:hash> to compare a copied head)
@@ -665,7 +667,7 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "task",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
-    "json", "yes", "all", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
+    "json", "yes", "all", "brief", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
     "clear", "follow", "ready", "all-tasks", "inbound-only", "help", "undo", "anyone", "allow-dispatch", "allow-merge", "merge-delete-branch",
     "no-open", "remove", "no-verify", "no-follow", "end", "report", "off", "tmux",
     "self-heal", "plan-auto", "chat-approve", "repair-auto", "review-retry-auto", "no-local",
@@ -5171,9 +5173,36 @@ async function planTaskCommand(positional, flags, context) {
         autoPlan ? "An unchanged, verified plan can auto-approve under your signed mode. Amendments and questions still wait for you." : "Its questions reach you like any decision; its plan lands as a scope for you to edit and approve.",
     ]);
 }
-/** The retired command is a typed refusal, never a new provider request. */
+/** Read saved work; neither form requests a new provider review. */
 async function reviewTaskCommand(positional, flags, context) {
     const { store, write, json } = context;
+    if (flags.has("brief")) {
+        const allowed = new Set(["brief", "all", "run", "json", "db", "as", "token"]);
+        for (const name of flags.keys())
+            if (!allowed.has(name))
+                return fail(write, json, "task review", "usage", `--${name} is not a task review --brief option.`, EXIT.usage);
+        const task = positional[0], selected = flags.get("run");
+        if (positional.length !== 1 || !task || task.length > 64 || /[\x00-\x1f\x7f]/.test(task) ||
+            selected !== undefined && (typeof selected !== "string" || !/^[1-9]\d*$/.test(selected) || !Number.isSafeInteger(Number(selected)))) {
+            return fail(write, json, "task review", "usage", "Use toolroll task review <task> --brief [--run <id>] [--all] [--json].", EXIT.usage);
+        }
+        // The normal CLI entry has already authenticated lead tokens. Local reads
+        // stay available; a signed-in lead sees only its owner's admitted projects.
+        let viewer = currentActor()?.account ?? null;
+        if (viewer === null && (flags.has("as") || flags.has("token"))) {
+            const acting = await askCredentials(flags, context);
+            if (acting === null || !authenticateApprover(store, acting.name, acting.token).ok)
+                return fail(write, json, "task review", "unauthenticated", "That sign-in is not valid.", EXIT.refused);
+            viewer = acting.name;
+        }
+        const repos = viewer === null ? null : store.knownRepos().filter(repo => store.accountCanAccess(viewer, repo));
+        const result = taskReviewBrief(store, task, context.evidenceRoot, context.now, { principal: "operator", repos, includeUnplaced: viewer === null }, { ...(selected === undefined ? {} : { run: Number(selected) }), all: flags.has("all"), secrets: [context.leadToken ?? "", text(flags, "token") ?? ""] });
+        if (!result.ok)
+            return fail(write, json, "task review", result.reason, result.message, EXIT.refused);
+        return succeed(write, json, "task review", { brief: result.brief }, () => renderReviewBrief(result.brief));
+    }
+    if (flags.has("run") || flags.has("all"))
+        return fail(write, json, "task review", "usage", "--run and --all require --brief.", EXIT.usage);
     const [runText] = positional;
     const runId = Number(runText ?? "");
     if (runText === undefined || !Number.isInteger(runId) || runId < 1) {

package/dist/plan.d.ts

@@ -6,7 +6,7 @@
  * the scope proposal is authority-bearing, so it gets the park discipline).
  */
 import { type AcceptanceCriterion } from "./scope.js";
-import type { ContractIssue } from "./contracts/contract.js";
+import { type ContractIssue } from "./contracts/contract.js";
 export type PlanProblem = {
     reason: string;
     message: string;
@@ -71,11 +71,11 @@ export type PlanParseResult = {
     problems: PlanProblem[];
 };
 /**
- * A contract issue as a plan problem: the path-named line is the message, and the reason keeps the codes the rest of
- * the code relies on — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` —
- * so repair eligibility (document-only problems) and durable outcomes read the same as before the contract.
+ * A contract issue as a plan problem (`contractProblemOf`): the reason keeps the codes the rest of the code relies on
+ * — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` — so repair eligibility
+ * (document-only problems) and durable outcomes read the same as before the contract.
  */
-export declare function planProblemOf(issue: ContractIssue): PlanProblem;
+export declare const planProblemOf: (issue: ContractIssue) => PlanProblem;
 /**
  * The planner's handoff, read against the plan contract (src/contracts/plan.ts): fail closed, every problem at once,
  * each one naming its path (`acceptance[0].evidence[0]: must be one of ...`). A plan saved before plans carried

package/dist/plan.js

@@ -9,6 +9,7 @@ import { createHash } from "node:crypto";
 import { hasForbiddenControls } from "./decision.js";
 import { parseAcceptanceCriteria } from "./scope.js";
 import { TEXT_LIMITS } from "./text-limits.js";
+import { contractProblemOf } from "./contracts/contract.js";
 import { planPayloadBody, readPlanPayload } from "./contracts/plan.js";
 const EXECUTION_PLAN_SECTIONS = ["approach", "milestones", "dependencies", "risks", "proof"];
 const EXECUTION_PLAN_LIST_CAP = 12;
@@ -163,32 +164,11 @@ function prose(value, field, cap, required, problems) {
     return value;
 }
 /**
- * A contract issue as a plan problem: the path-named line is the message, and the reason keeps the codes the rest of
- * the code relies on — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` —
- * so repair eligibility (document-only problems) and durable outcomes read the same as before the contract.
+ * A contract issue as a plan problem (`contractProblemOf`): the reason keeps the codes the rest of the code relies on
+ * — `missing-goal`, `bad-touches`, `plan-too-long`, `amendment-too-long`, `acceptance-too-many` — so repair eligibility
+ * (document-only problems) and durable outcomes read the same as before the contract.
  */
-export function planProblemOf(issue) {
-    const at = issue.path;
-    const reason = (() => {
-        switch (issue.kind) {
-            case "required":
-            case "empty":
-            case "too-few":
-                return `missing-${at}`;
-            case "too-long":
-                return `${at}-too-long`;
-            case "too-many":
-                return `${at}-too-many`;
-            case "unknown-key":
-                return `${at}-unknown-key`;
-            case "newer-version":
-                return "newer-version";
-            default:
-                return `bad-${at}`;
-        }
-    })();
-    return { reason, message: issue.line };
-}
+export const planProblemOf = contractProblemOf;
 /** scope.ts's rubric problem as a path-named line: `acceptance[0].id: is over 40 bytes`. */
 function acceptanceLine(problem) {
     const named = /^(acceptance(?:\[\d+\])?(?:\.[A-Za-z]+)?) (.*)$/.exec(problem.message);

package/dist/process-recovery-eligibility.d.ts

@@ -37,7 +37,7 @@ export declare function preparedCandidateObserverGapEligibility(store: Store, in
             leaseId: string;
             role: "builder";
             outcome: "built" | "no-change";
-            committed: boolean | null;
+            committed: boolean;
             startedAt: string;
             finishedAt: string;
             branch: string;
@@ -81,7 +81,7 @@ export declare function preparedCandidateObserverGapEligibility(store: Store, in
                 readonly state: import("./proof.js").CriterionMatrixState;
                 readonly detail: readonly string[];
                 readonly answered: readonly {
-                    readonly kind: import("./scope.js").EvidenceKind;
+                    readonly kind: "changed-path" | "check" | "manual-review" | "screenshot";
                     readonly ref: string;
                 }[];
                 readonly review: {

package/dist/process-recovery-eligibility.js

@@ -8,6 +8,8 @@
 import { createHash } from "node:crypto";
 import { normalizeBootId } from "./boot-identity.js";
 import { scopeApprovedForDispatch } from "./dispatch.js";
+import { parseHandoffArtifact } from "./contracts/handoff.js";
+import { readVerificationReceipt } from "./contracts/verification-receipt.js";
 import { readVerifiedArtifact } from "./evidence.js";
 import { ownedProcessCount, runOwnerTag } from "./exec.js";
 import { scopeAuthorityOf } from "./scope.js";
@@ -97,11 +99,11 @@ export function preparedCandidateObserverGapEligibility(store, input) {
             const gate = verificationEvidence(store, evidenceRoot, runId);
             if (!gate.ok || gate.bytes === null)
                 return refuse("verification-evidence-unavailable");
-            const receipt = JSON.parse(gate.bytes);
-            if (receipt.version !== 1 || receipt.source !== undefined || receipt.reusedFrom !== undefined || receipt.executedHere !== undefined ||
-                receipt.result?.configured !== true || receipt.result.ran !== true || receipt.result.exitCode !== 0 ||
-                Object.keys(receipt.result).some(key => !["configured", "ran", "exitCode", "setupReplayed"].includes(key)) ||
-                (receipt.result.setupReplayed !== undefined && receipt.result.setupReplayed !== true) ||
+            // A legacy log-header view is not a sealed receipt: the strict schema refuses its extra keys.
+            const view = JSON.parse(gate.bytes);
+            const receipt = readVerificationReceipt(view);
+            if (!receipt.ok || view.version !== 1 || receipt.value.reusedFrom !== undefined || receipt.value.executedHere !== undefined ||
+                receipt.value.result.configured !== true || receipt.value.result.ran !== true || receipt.value.result.exitCode !== 0 ||
                 !instant(gateArtifact.createdAt) || Date.parse(gateArtifact.createdAt) < Date.parse(run.startedAt) ||
                 Date.parse(gateArtifact.createdAt) > Date.parse(machine.decidedAt) ||
                 Date.parse(gateArtifact.createdAt) > Date.parse(run.finishedAt))
@@ -115,12 +117,15 @@ export function preparedCandidateObserverGapEligibility(store, input) {
             const saved = readVerifiedArtifact(evidenceRoot, artifact);
             if (!saved.ok)
                 return refuse("machine-prepared-handoff-unavailable");
-            const handoff = JSON.parse(saved.content.toString("utf8"));
+            const read = parseHandoffArtifact(saved.content.toString("utf8"));
+            if (!read.ok)
+                return refuse("machine-prepared-handoff-mismatch");
+            const handoff = read.value;
             const conclusion = `Prepared candidate ${scope.candidate} was checked out by the machine; no agent ran. ${run.outcome === "no-change" ? "The branch already matched it." : "The sealed diff spans this task's base to that candidate."}`;
-            if (handoff.schema !== 1 || handoff.runId !== runId || handoff.taskId !== ref.externalId || handoff.sessionId !== null ||
+            if (handoff.runId !== runId || handoff.taskId !== ref.externalId || handoff.sessionId !== null ||
                 handoff.provider !== run.provider || handoff.branch !== run.branch || handoff.worktree !== run.worktree ||
                 handoff.base !== run.baseRevision || handoff.head !== run.headRevision || handoff.outcome !== run.outcome ||
-                handoff.committed !== run.committed || handoff.freshness?.currentAsOf !== run.headRevision ||
+                handoff.committed !== run.committed || handoff.freshness.currentAsOf !== run.headRevision ||
                 handoff.conclusion !== conclusion || run.handoff !== conclusion ||
                 !instant(artifact.createdAt) || Date.parse(artifact.createdAt) < Date.parse(run.startedAt) ||
                 Date.parse(artifact.createdAt) > Date.parse(gateArtifact.createdAt))

package/dist/proof.d.ts

@@ -18,31 +18,12 @@
  * returned — is gathered by the caller (`builder.ts`) and handed in as data,
  * so the review itself stays testable without a filesystem or a database.
  */
-import { type EvidenceKind } from "./scope.js";
+import type { EvidenceKind } from "./scope.js";
+import { type ContractProblem } from "./contracts/contract.js";
+import type { VerifyCommandFacts } from "./contracts/verification-receipt.js";
+import { type CriterionEvidenceRef, type ParsedProof } from "./contracts/proof.js";
+export { PROOF_LIMITS, type CriterionEvidenceRef, type ParsedCheck, type ParsedCriterion, type ParsedProof, type ParsedScreenshot } from "./contracts/proof.js";
 export type ProofVerdict = "verified" | "attested" | "short" | "refuted";
-/** One typed reference the proof cites to answer a criterion's required
- * evidence: `ref` names an existing check's command, an existing
- * screenshot's path, a path inside `changed`, or (kind `manual-review`)
- * free-text pointing at nothing machine-checkable. Additive (v39): a
- * criterion with no `evidence` array parses the same as one that always
- * had none — legacy proofs, and every proof against a rubric-less scope,
- * are untouched. */
-export type CriterionEvidenceRef = {
-    kind: EvidenceKind;
-    ref: string;
-};
-export type ParsedCriterion = {
-    id: string;
-    statement: string;
-    /** pending-verification asserts all agent-owned work is met; only the
-     * machine-owned final check remains. It never upgrades a legacy failure. */
-    verdict: "met" | "not-met" | "not-checked" | "pending-verification";
-    how: string;
-    /** v39: typed references answering a SIGNED criterion by exact id.
-     * `[]` for a criterion the agent added beyond the rubric, or for any
-     * proof written before this migration. */
-    evidence: CriterionEvidenceRef[];
-};
 /** v39: the rubric side of a criterion, as `adjudicate` reads it — the
  * SIGNED id, statement, and required evidence kinds. Never `how` (never
  * signed). Empty = nothing signed: `adjudicate` runs the v1 rules,
@@ -54,31 +35,7 @@ export type ApprovedCriterion = {
 };
 /** Only submission defects. A truthful not-met answer is not malformed. */
 export declare function proofSubmissionProblems(proof: ParsedProof, rubric: readonly ApprovedCriterion[]): string[];
-export type ParsedCheck = {
-    command: string;
-    exitCode: number;
-    summary: string;
-};
-/** A screenshot the agent claims proves UI-facing work. `path` is the
- * repository-relative path the file lived at in the worktree when the
- * agent wrote the proof — validated as a path shape here; validated as an
- * actual bounded PNG/JPEG, and read, by the caller. */
-export type ParsedScreenshot = {
-    path: string;
-    caption: string;
-};
-export type ParsedProof = {
-    version: 1;
-    criteria: ParsedCriterion[];
-    checks: ParsedCheck[];
-    changed: string[];
-    caveats: string[];
-    screenshots: ParsedScreenshot[];
-};
-export type ProofProblem = {
-    reason: string;
-    message: string;
-};
+export type ProofProblem = ContractProblem;
 export type ProofParseResult = {
     ok: true;
     proof: ParsedProof;
@@ -86,31 +43,14 @@ export type ProofParseResult = {
     ok: false;
     problems: ProofProblem[];
 };
-/** Caps are BYTES of UTF-8, matching the scout report's rule: a payload is
- * the same size whatever script it is written in. */
-export declare const PROOF_LIMITS: {
-    readonly payload: number;
-    readonly criteria: 12;
-    readonly criterionId: 40;
-    readonly criterionStatement: 300;
-    readonly criterionHow: 500;
-    readonly evidencePerCriterion: 4;
-    readonly evidenceRef: 300;
-    readonly checks: 12;
-    readonly checkCommand: 300;
-    readonly checkSummary: 300;
-    readonly changed: 64;
-    readonly changedPath: 300;
-    readonly caveats: 8;
-    readonly caveat: 300;
-    readonly screenshots: 8;
-    readonly screenshotPath: 300;
-    readonly screenshotCaption: 300;
-};
+/**
+ * Read a proof: the payload byte cap and JSON first, then the proof schema (version 2 as itself, the version 1 a
+ * builder writes upgraded, a newer one refused plainly), then the plain-code rules. Every problem names its path and
+ * is reported at once; fail closed.
+ */
 export declare function parseProof(raw: string): ProofParseResult;
-/** Re-serialize the validated shape, never the agent's raw bytes (the
- * scout report's rule, `scout.ts`): what is stored and later hash-verified
- * is exactly what this parser admitted, key order and all. */
+/** Serialize the validated shape, never the agent's raw bytes (the scout report's rule, `scout.ts`): what is stored
+ * and later hash-verified is exactly what the schema admitted, in its key order. */
 export declare function serializeProof(proof: ParsedProof): string;
 /** One caveat that admits an exception to a criterion the same proof marks
  * `met` — the proof's own verdict disagreeing with its own words (atomic
@@ -255,24 +195,8 @@ export declare function frozenCriterionProblems(submitted: ParsedProof, correcte
  * correction and re-reads it after that correction and after the final
  * gate; a reading that differs is never adjudicated from the cached one. */
 export declare function sameDiffStatFacts(a: DiffStatFacts | null, b: DiffStatFacts | null): boolean;
-/** The plane's own re-run of the repository's approved verification
- * command, when one is configured. `ran: false` covers both "none
- * configured" and "configured but the run could not attempt it" — the
- * latter is distinguished by `attemptFailed`, which downgrades to `short`
- * rather than `refuted`: "we could not check" is not "the claim is false". */
-export type VerifyCommandFacts = {
-    configured: false;
-} | {
-    configured: true;
-    ran: false;
-    attemptFailed: true;
-    failure?: "spawn-failed" | "timed-out" | "dependency-missing" | "setup-stale" | "setup-failed" | "own-install-failed" | "tracked-files-changed" | "setup-changed-files" | "checkout-moved" | "cleanliness-unavailable" | "dependency-still-missing" | "retry-spawn-failed" | "retry-timed-out" | "custody-lost";
-} | {
-    configured: true;
-    ran: true;
-    exitCode: number;
-    setupReplayed?: true;
-};
+/** What the approved verification command did (the receipt's `result`); its schema lives with the receipt. */
+export type { VerifyCommandFacts } from "./contracts/verification-receipt.js";
 export type AdjudicateInput = {
     /** New captures may assess the signed goal directly when the builder wrote
      * no optional proof. Historical calls retain their original contract. */