toolroll 0.9.34 → 0.9.37

package/CHANGELOG.md

@@ -1,5 +1,107 @@
 # Changelog
 
+## 0.9.37 — 2026-10-06
+
+- **Zod revamp, waves 1 and 2 finished.** Every handoff between a model and
+  Toolroll, and the context passed between steps, is now one schema each in
+  `src/contracts/`: the lead's 51 tools and the 25 MCP gateway tools, the
+  scout report, task sizing, reviewer findings, decisions, teammate turns and
+  sort answers, the lead's context bundle, project knowledge, memory and
+  skills, chat actions and channel callbacks, and the desktop coding handoff,
+  context and session record. A model gets the schema as `--json-schema`
+  where its harness takes one; a refusal names the field
+  (`steps[0].routes[0].goesTo: required`). Everything that was accepted before
+  is still accepted: tool calls with extra or loose arguments, model answers
+  with nulls or overlong text (clipped as before), saved reports, rows,
+  sessions, chat buttons and proposals. Replayed against real saved data
+  (scout reports, findings, decisions, 410 scopes and 796 routes, 279 chat
+  buttons, every saved flow and card), all of it reads the same.
+- **Research can read PostHog.** A research run gets a connected service's
+  query tool (PostHog's `exec`) only when the access the service actually
+  granted is read-only. Otherwise it skips it and says why on the run and the
+  integration, with a **Reconnect read-only** action. Connecting PostHog as
+  usual is unchanged, and builds keep every tool. Connections made before this
+  release didn't record what was granted, so research skips them until you
+  reconnect read-only.
+- **A question's recommendation can carry its reason.** `connect: because…`
+  now counts as recommending `connect`, instead of failing the question.
+- **A Telegram update Toolroll can't read** is logged and answered OK, so
+  Telegram doesn't keep resending it. A Slack, Discord or Teams message part
+  that can't be read is dropped with its reason instead of retried forever.
+- **Rolling back:** flow cards written by 0.9.37 read as empty in 0.9.36, so a
+  rollback loses the step outputs of cards still in progress.
+- **Scopes, acceptance criteria and sealed routes have one contract.** A task's
+  scope (goal, exclusions, touch paths, rubric) and an acceptance criterion are
+  described once from the plan contract's own fields (`src/contracts/scope.ts`);
+  a sealed agent route, in both versions it has been saved in, with its
+  overrides and task size, is one schema (`src/contracts/route.ts`). The shared
+  rubric input schema is ready for the lead-tool migration. Every saved scope,
+  standing order and sealed route reads and digests exactly as before, so no
+  approval changes.
+  Nothing new is refused: a scope still names up to 50 paths and a criterion
+  still ignores keys it doesn't use. Rubric and route refusals are now
+  field-named lines (`acceptance[0].statement over 1,000 bytes`), and a route
+  made by a newer Toolroll says so.
+- **What a flow's steps hand on has one contract.** A finished zone's
+  `{{stage.…}}` words, a card's saved outputs, and what Send to me and Person
+  chooses send are each described once (`src/contracts/stage-output.ts`,
+  `flow-send.ts`, `flow-card.ts`). Saved cards and sends read exactly as
+  before. A build or research task filed after a step whose output was too
+  long to pass on now gets that output whole, not just a link to it.
+- **Tightened, on purpose.** Saving a flow with a new `{{stage.…}}` that its
+  zone doesn't hand on is refused, naming where:
+  `stages[2].instructions: stage.research.unknown is not available (Research
+  hands on {{stage.research}}, {{stage.research.items}} and
+  {{stage.research.report}})`. This covers the canvas, `toolroll flows
+  create/edit/import`, the lead and templates. A reference a flow already had
+  is never refused, and nothing changes for flows that are only read or run.
+  Card outputs and kept sends are saved with a version; ones a newer Toolroll
+  wrote are refused rather than misread or overwritten.
+
+## 0.9.36 — 2026-10-06
+
+- **Flows have one contract.** Every kind of zone, step, route, answer,
+  option, trigger and the flow file is described once
+  (`src/contracts/flow.ts`), and that description is what the lead's
+  `propose_flow` is told, what `toolroll flows create/edit/import` and the
+  console check, and what `docs/flow-file.schema.json` publishes (now
+  generated, so it includes Send to me, Person chooses and `ifReplied`, which
+  the hand-written one had missed). A refusal names the field and suggests the
+  one meant: `steps[0].routes[0]: unknown key 'to' (did you mean goesTo?)`,
+  `zones[2]: unknown key 'onFail' (did you mean ifFails?)`, instead of
+  "there's no step called ." Every saved flow, template, starter, kit and
+  gallery flow reads exactly as before: the same saved bytes and digests, and
+  the same exported files.
+- **Tightened, on purpose.** A step, flow file zone, trigger setting or
+  `propose_flow` argument with a key its kind doesn't take is refused by name
+  rather than silently ignored: `planning` on a Holding step, `remindAfter` on
+  a Wait step, `ifFails` on a Sort step (use `ifNotSure`, which it meant) or
+  `next` on a Sort or Person chooses step. A sort's `sureAt` is 0.5–99. A flow
+  file's zones keep only the words their kind uses when exported, and a file
+  or drawing made by a newer Toolroll is refused as such. Messages for flows
+  and triggers changed from "Zone Build: …" sentences to path-named lines.
+
+- **Builder handoffs and proofs have one contract.** The handoff a builder
+  leaves, its proof and the verification receipt are versioned schemas. Fifteen
+  real past runs replay with identical verdicts, receipt bytes and digests.
+- **One compact review packet.** `toolroll task review <id> --brief` (or
+  `--json`) shows a build's conclusion, changed files, check result, review
+  findings by severity, screenshot paths and what to do next, in about 40
+  lines and without logs or diffs.
+- **PostHog connects in one short step.** Its sign-in now uses PostHog's own
+  MCP permission preset instead of listing every permission, which showed a
+  75-group permission screen. Sign-in returns are now logged.
+- **Tests can't mistake a real process for a fake one.** Fake process IDs in
+  tests sit above every platform's limit, and a guard refuses new low ones (a
+  Brave tab and a GitHub runner process had made tests fail at random).
+
+## 0.9.35 — 2026-10-05
+
+- **One-click sign-ins ask for every permission a service lists.** Toolroll
+  asked for only the first 20, so a service needing one later in its list
+  issued a token it then refused (PostHog needs `user:read`, its 140th).
+  Reconnect a service that failed its test after signing in.
+
 ## 0.9.34 — 2026-10-05
 
 - **Plans have one contract.** The first step of making every handoff robust:

package/README.md

@@ -117,10 +117,17 @@ toolroll project use /path/to/project
 toolroll project show
 toolroll brief
 toolroll assignment show <task>
+toolroll task review <task> --brief
 toolroll task complete <task>
 toolroll task revise <task> --feedback "Keep the filter selected after reload."
 ```
 
+`task review <task> --brief` combines the latest finished build or report's conclusion,
+file counts, checks, review findings, screenshot paths, plan and next actions.
+Use `--run <id>` for an earlier attempt, `--json` for the same fields, and `--all`
+to include LOW findings. Lists stay bounded, with omitted entries counted; missing
+fields say `not recorded`. The lead token works through `--token` or `TOOLROLL_LEAD_TOKEN`.
+
 Completion and revisions use the local sign-in already saved by `up`. Completion
 reports the exact run, commit and check outcome it handled. Agents use a scoped
 credential (`project use /path/to/project --token-file /path/to/credential`) and

package/dist/assignment-adapters.d.ts

@@ -1,87 +1,52 @@
 import { type AssignmentSnapshot } from "./assignment.js";
 import type { Store } from "./store.js";
-export declare const ASSIGNMENT_ACTIONS: readonly ["show", "updates", "claim", "check", "brief", "inbox", "ack"];
-export type AssignmentOperation = typeof ASSIGNMENT_ACTIONS[number];
+import { type AssignmentInput, type AssignmentOperation } from "./contracts/gateway-tools.js";
+export declare const ASSIGNMENT_ACTIONS: AssignmentOperation[];
+export type { AssignmentOperation };
 type Args = Record<string, unknown>;
 type Failure = {
     ok: false;
     reason: string;
     message: string;
 };
+/** The gateway's assignment tools: names and words. Each one's input is ASSIGNMENT_INPUTS[operation]
+ * (src/contracts/gateway-tools.ts), which `toolroll assignment` reads its flags with too. */
 export declare const ASSIGNMENT_TOOLS: readonly [{
     readonly name: "get_assignment";
     readonly operation: "show";
     readonly description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "list_assignment_updates";
     readonly operation: "updates";
     readonly description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "claim_assignment";
     readonly operation: "claim";
     readonly description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "acknowledge_assignment";
     readonly operation: "check";
     readonly description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "get_assignment_brief";
     readonly operation: "brief";
     readonly description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "get_assignment_inbox";
     readonly operation: "inbox";
     readonly description: "Receive a durable batch of your assignments' status changes. Use a stable consumer name. Until acknowledged, the same batch survives reconnects and restarts. Receiving never completes or reruns work.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "acknowledge_assignment_delivery";
     readonly operation: "ack";
     readonly description: "Acknowledge receipt of an inbox batch after handling its updates. This advances only your delivery cursor; it never marks work complete, answers a decision or starts a revision.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }];
-/** The CLI and MCP use the same bounded input contract. MCP also validates its
- * descriptor before dispatch; this check protects direct adapter callers. */
-export declare function assignmentArgumentProblem(operation: AssignmentOperation, args: Args): string | null;
+/** The CLI and MCP read an assignment call with the same schema; MCP reads it before dispatch too, and this protects
+ * direct adapter callers. A refusal is its path-named lines; a ref or project path with control characters, which
+ * JSON Schema can't say, is refused after parsing. */
+export declare function readAssignmentArgs<O extends AssignmentOperation>(operation: O, args: Args): {
+    ok: true;
+    value: AssignmentInput<O>;
+} | Failure;
 /** Every read and mutation authenticates inside the same transaction as its
  * projection. A cached name/allowlist cannot keep a revoked identity alive. */
 export declare function assignmentForCoordinator(store: Store, token: string, operation: AssignmentOperation, args: Args, now: Date, evidenceRoot?: string): Failure | {
@@ -179,4 +144,3 @@ export declare function coordinatorToken(flags: Map<string, string | true>, env:
     token: string | null;
 } | Failure;
 export declare function runAssignmentCommand(positional: readonly string[], flags: Map<string, string | true>, context: AssignmentCliContext): number;
-export {};

package/dist/assignment-adapters.js

@@ -8,47 +8,36 @@ import { assignmentCatchUp } from "./assignment-brief.js";
 import { assignmentInbox, acknowledgeAssignmentDelivery } from "./assignment-delivery.js";
 import { syncAssignmentStatuses } from "./assignment-status.js";
 import { envelopeJson } from "./envelope.js";
-export const ASSIGNMENT_ACTIONS = ["show", "updates", "claim", "check", "brief", "inbox", "ack"];
+import { parseContract } from "./contracts/contract.js";
+import { ASSIGNMENT_INPUTS } from "./contracts/gateway-tools.js";
+export const ASSIGNMENT_ACTIONS = Object.keys(ASSIGNMENT_INPUTS);
 const failure = (reason, message) => ({ ok: false, reason, message });
-const reference = { type: "string", minLength: 1, maxLength: 64 };
-const digest = { type: "string", minLength: 64, maxLength: 64, pattern: "^[a-f0-9]{64}$" };
-const batchId = { type: "string", minLength: 32, maxLength: 32, pattern: "^[a-f0-9]{32}$" };
-const consumer = { type: "string", minLength: 1, maxLength: 64, pattern: "^[a-z0-9][a-z0-9-]{0,63}$" };
-const object = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+/** The gateway's assignment tools: names and words. Each one's input is ASSIGNMENT_INPUTS[operation]
+ * (src/contracts/gateway-tools.ts), which `toolroll assignment` reads its flags with too. */
 export const ASSIGNMENT_TOOLS = [
-    { name: "get_assignment", operation: "show", description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts.", inputSchema: object({ ref: reference }, ["ref"]) },
-    { name: "list_assignment_updates", operation: "updates", description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything.", inputSchema: object({ after: { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER }, limit: { type: "integer", minimum: 1, maximum: 100 } }) },
-    { name: "claim_assignment", operation: "claim", description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority.", inputSchema: object({ ref: reference }, ["ref"]) },
-    { name: "acknowledge_assignment", operation: "check", description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy.", inputSchema: object({ ref: reference, digest }, ["ref", "digest"]) },
-    { name: "get_assignment_brief", operation: "brief", description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation.", inputSchema: object({ repo: { type: "string", minLength: 1, maxLength: 4096 }, limit: { type: "integer", minimum: 1, maximum: 25 } }) },
-    { name: "get_assignment_inbox", operation: "inbox", description: "Receive a durable batch of your assignments' status changes. Use a stable consumer name. Until acknowledged, the same batch survives reconnects and restarts. Receiving never completes or reruns work.", inputSchema: object({ consumer, limit: { type: "integer", minimum: 1, maximum: 100 } }, ["consumer"]) },
-    { name: "acknowledge_assignment_delivery", operation: "ack", description: "Acknowledge receipt of an inbox batch after handling its updates. This advances only your delivery cursor; it never marks work complete, answers a decision or starts a revision.", inputSchema: object({ consumer, batchId }, ["consumer", "batchId"]) },
+    { name: "get_assignment", operation: "show", description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts." },
+    { name: "list_assignment_updates", operation: "updates", description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything." },
+    { name: "claim_assignment", operation: "claim", description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority." },
+    { name: "acknowledge_assignment", operation: "check", description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy." },
+    { name: "get_assignment_brief", operation: "brief", description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation." },
+    { name: "get_assignment_inbox", operation: "inbox", description: "Receive a durable batch of your assignments' status changes. Use a stable consumer name. Until acknowledged, the same batch survives reconnects and restarts. Receiving never completes or reruns work." },
+    { name: "acknowledge_assignment_delivery", operation: "ack", description: "Acknowledge receipt of an inbox batch after handling its updates. This advances only your delivery cursor; it never marks work complete, answers a decision or starts a revision." },
 ];
-/** The CLI and MCP use the same bounded input contract. MCP also validates its
- * descriptor before dispatch; this check protects direct adapter callers. */
-export function assignmentArgumentProblem(operation, args) {
+/** The CLI and MCP read an assignment call with the same schema; MCP reads it before dispatch too, and this protects
+ * direct adapter callers. A refusal is its path-named lines; a ref or project path with control characters, which
+ * JSON Schema can't say, is refused after parsing. */
+export function readAssignmentArgs(operation, args) {
     if (!ASSIGNMENT_ACTIONS.includes(operation))
-        return "Choose show, updates, claim, check, brief, inbox, or ack.";
-    const allowed = operation === "brief" ? ["repo", "limit"] : operation === "inbox" ? ["consumer", "limit"] : operation === "ack" ? ["consumer", "batchId"] : operation === "updates" ? ["after", "limit"] : operation === "check" ? ["ref", "digest"] : ["ref"];
-    for (const key of Object.keys(args))
-        if (!allowed.includes(key))
-            return `Unknown argument: ${key}.`;
-    if (["show", "claim", "check"].includes(operation) && (typeof args["ref"] !== "string" || args["ref"].length < 1 || args["ref"].length > 64 || /[\u0000-\u001f\u007f]/.test(args["ref"])))
-        return "Choose a task id, 1–64 characters without control characters.";
-    if (operation === "check" && (typeof args["digest"] !== "string" || !/^[a-f0-9]{64}$/.test(args["digest"])))
-        return "Use the exact 64-character receipt digest from assignment show.";
-    if ((operation === "inbox" || operation === "ack") && (typeof args["consumer"] !== "string" || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(args["consumer"])))
-        return "Use a stable consumer name with 1–64 lowercase letters, digits or hyphens.";
-    if (operation === "ack" && (typeof args["batchId"] !== "string" || !/^[a-f0-9]{32}$/.test(args["batchId"])))
-        return "Use the exact batchId from assignment inbox.";
-    if (args["repo"] !== undefined && (typeof args["repo"] !== "string" || args["repo"].length < 1 || args["repo"].length > 4096 || /[\u0000-\u001f\u007f]/.test(args["repo"])))
-        return "Choose a project path without control characters.";
-    for (const [name, min, max] of [["after", 0, Number.MAX_SAFE_INTEGER], ["limit", 1, operation === "brief" ? 25 : 100]]) {
-        const value = args[name];
-        if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max))
-            return `${name} must be an integer from ${min} to ${max}.`;
+        return failure("usage", "Choose show, updates, claim, check, brief, inbox, or ack.");
+    const read = parseContract(ASSIGNMENT_INPUTS[operation], args);
+    if (!read.ok)
+        return failure("usage", read.issues.map(one => one.line).join("; "));
+    const value = read.value;
+    for (const field of ["ref", "repo"]) {
+        if (typeof value[field] === "string" && /[\u0000-\u001f\u007f]/.test(value[field]))
+            return failure("usage", `${field}: must not contain control characters`);
     }
-    return null;
+    return { ok: true, value };
 }
 function readAssignment(store, operation, args, now, access, root) {
     if (operation === "brief")
@@ -61,9 +50,10 @@ function readAssignment(store, operation, args, now, access, root) {
 /** Every read and mutation authenticates inside the same transaction as its
  * projection. A cached name/allowlist cannot keep a revoked identity alive. */
 export function assignmentForCoordinator(store, token, operation, args, now, evidenceRoot) {
-    const problem = assignmentArgumentProblem(operation, args);
-    if (problem !== null)
-        return failure("usage", problem);
+    const read = readAssignmentArgs(operation, args);
+    if (!read.ok)
+        return read;
+    args = read.value;
     // Authenticate before maintenance, then authenticate again inside delivery.
     // Reconciliation owns one short transaction per family and cannot sit under
     // the delivery transaction's writer reservation.
@@ -225,11 +215,11 @@ export function runAssignmentCommand(positional, flags, context) {
     for (const flag of operationFlags) {
         const value = flags.get(flag);
         if (value !== undefined)
-            args[flag === "batch" ? "batchId" : flag] = ["after", "limit"].includes(flag) ? typeof value === "string" && /^\d+$/.test(value) ? Number(value) : NaN : value;
+            args[flag === "batch" ? "batchId" : flag] = ["after", "limit"].includes(flag) && typeof value === "string" && /^\d+$/.test(value) ? Number(value) : value;
     }
-    const problem = assignmentArgumentProblem(operation, args);
-    if (problem !== null)
-        return emit(failure("usage", problem));
+    const read = readAssignmentArgs(operation, args);
+    if (!read.ok)
+        return emit(read);
     const credential = coordinatorToken(flags, context.env ?? process.env);
     if ("ok" in credential)
         return emit(credential);

package/dist/assignment.d.ts

@@ -170,6 +170,7 @@ export declare function assignmentBrief(assignment: AssignmentSnapshot | null):
         status: "not-recorded";
     };
 } | null;
+export declare function assignmentChecksForRun(store: Store, root: string | undefined, runId: number, now: Date): AssignmentChecks;
 export declare function assignmentOf(store: Store, taskId: string, now: Date, access: AssignmentAccess, root?: string): AssignmentSnapshot | null;
 type MutationResult = {
     ok: true;

package/dist/assignment.js

@@ -83,7 +83,7 @@ function ownerOf(store, rootId, repo) {
 }
 // Report the recorded check outcome, never turn a model verdict into a check.
 // Follow-up checks on the same commit (Run checks) upgrade a pass and show a failure.
-function nativeChecks(store, root, runId, now) {
+export function assignmentChecksForRun(store, root, runId, now) {
     const own = buildChecks(store, root, runId);
     const run = store.getRun(runId);
     const followUps = followUpChecksOf(store, runId, now, root);
@@ -163,7 +163,7 @@ export function assignmentOf(store, taskId, now, access, root) {
     const reports = artifacts.filter(a => a.kind === "report");
     const unavailable = family.versions.flatMap(version => store.runsFor(version.refId).flatMap(run => store.artifactsFor(run.id).filter(artifact => root === undefined || !readVerifiedArtifact(root, artifact).ok)
         .map(artifact => `Saved ${artifact.kind} #${artifact.id} (run ${run.id}) is unavailable or changed.`)));
-    const checks = result === null ? null : nativeChecks(store, root, result.id, now);
+    const checks = result === null ? null : assignmentChecksForRun(store, root, result.id, now);
     const finishedBuild = result?.role === "builder" && (result.outcome === "built" || result.outcome === "no-change") &&
         result.finishedAt !== null && /^[a-f0-9]{40}$/.test(result.headRevision ?? "");
     // Finished work returns to its lead or user. Strict terms and previous model

package/dist/browser-workspace.d.ts

@@ -802,9 +802,9 @@ export type BrowserFlowStage = {
     wait?: {
         for: "reply" | "time" | "hours";
         minutes: number;
-        from?: string;
-        to?: string;
-        timeZone?: string;
+        from?: string | undefined;
+        to?: string | undefined;
+        timeZone?: string | undefined;
     };
     /** A Pull request zone merges once checks pass (after a person approved), this way. */
     merge?: "squash" | "merge" | "rebase" | undefined;

package/dist/build-review.d.ts

@@ -1,6 +1,6 @@
 import type { Store } from "./store.js";
 import type { Runner } from "./builder.js";
-import type { BuildFinding } from "./review-switch.js";
+import { type BuildFinding } from "./contracts/review-findings.js";
 export { buildReviewOf, buildReviewHeadline, buildReviewLines, findingWords, type BuildReviewView } from "./review-switch.js";
 export declare const AUTOMATIC_REVIEWER = "automatic review";
 /**

package/dist/build-review.js

@@ -29,6 +29,7 @@ import { runCheckLevel } from "./check-levels.js";
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
 import { parseBuildFindings, REVIEW_PATCH_NAME } from "./reviewer.js";
+import { FINDINGS_VERSION } from "./contracts/review-findings.js";
 import { heartbeat as runnerHeartbeat } from "./runner.js";
 import { TELEGRAM_TOKEN_ENVS } from "./names.js";
 import { CLAUDE_LIMITS } from "./scope.js";
@@ -90,7 +91,7 @@ function queueLocked(store, repo, runId, root, now) {
 }
 function settle(store, runId, state, fields, now) {
     store.handle.prepare("UPDATE build_review SET state = ?, findings_json = ?, reason = ?, sent_back_as = ?, finished_at = ? WHERE run = ? AND state = 'pending'")
-        .run(state, fields.findings === undefined ? null : JSON.stringify({ version: 1, findings: fields.findings }), fields.reason ?? null, fields.sentBackAs ?? null, now.toISOString(), runId);
+        .run(state, fields.findings === undefined ? null : JSON.stringify({ version: FINDINGS_VERSION, findings: fields.findings }), fields.reason ?? null, fields.sentBackAs ?? null, now.toISOString(), runId);
     store.bumpWake();
 }
 /** Only the first automatic send-back in a task family: its revision's HIGH goes to the person. */

package/dist/builder.js

@@ -63,6 +63,7 @@ import { openLiveLog } from "./live.js";
 import { CheckProgressTracker } from "./check-progress.js";
 import { captureParkEvidence, captureTerminalDiff, captureBaseTree, evidenceRoot, handoffName, isImagePath, WORKTREE_EVIDENCE_DIR, storeHandoffArtifact, looksLikeProtocolFile, mailboxName, progressFileName, proofFileName, rubricFileName, proposalFileName, quarantineMailboxes, readMailbox, readVerifiedArtifact, scanForSecrets, redactSecretLines, storeEvidence, validateScreenshotBytes, imageDimensions, SCREENSHOT_BYTE_CAP, boundStreamHeadTail } from "./evidence.js";
 import { PROOF_LIMITS, parseProof, serializeProof, adjudicate, artifactManifestOnly, sameDiffStatFacts } from "./proof.js";
+import { parseHandoffArtifact } from "./contracts/handoff.js";
 import { captureReviewContext } from "./review-context.js";
 import { authoritySnapshotDigest, classifyRevisionAuthority, isMilestoneRegression, milestonesOf, parseExecutionPlanDocument, parsePlanRevisionProposal, parseProgressSnapshot, renderExecutionPlanDocument, PROGRESS_LIMITS, REVISION_LIMITS, } from "./plan.js";
 import { maybeSettleRepairChain } from "./dispose.js";
@@ -1115,11 +1116,9 @@ export async function build(store, request) {
             try {
                 const verified = readVerifiedArtifact(root, handoffArtifact);
                 if (verified.ok) {
-                    const parsed = JSON.parse(verified.content.toString("utf8"));
-                    if (parsed.branch === branch &&
-                        typeof parsed.conclusion === "string" &&
-                        parsed.freshness?.currentAsOf === baseRevision) {
-                        previousHandoff = `A previous attempt (${String(parsed.outcome ?? "finished")}) left the branch exactly where it now stands and concluded: ${parsed.conclusion}`;
+                    const parsed = parseHandoffArtifact(verified.content.toString("utf8"));
+                    if (parsed.ok && parsed.value.branch === branch && parsed.value.freshness.currentAsOf === baseRevision) {
+                        previousHandoff = `A previous attempt (${parsed.value.outcome}) left the branch exactly where it now stands and concluded: ${parsed.value.conclusion}`;
                     }
                 }
             }
@@ -1740,7 +1739,6 @@ export async function settleProviderOutcome(captured, result) {
         store.setRunPhase(request.runId, "capturing-evidence");
         const diffEvidence = await captureTerminalDiff(store, git, worktree, pinnedBase, baseRevision, root, request.runId, clock());
         storeHandoffArtifact(store, root, {
-            schema: 1,
             taskId,
             runId: request.runId,
             provider,
@@ -1835,7 +1833,6 @@ export async function settleProviderOutcome(captured, result) {
             store.setRunPhase(request.runId, "capturing-evidence");
             const diffEvidence = await captureTerminalDiff(store, git, worktree, pinnedBase, head, root, request.runId, clock());
             storeHandoffArtifact(store, root, {
-                schema: 1,
                 taskId,
                 runId: request.runId,
                 provider,

package/dist/chat-acceptance.d.ts

@@ -39,13 +39,13 @@ export declare function readAcceptanceEvidence(store: Store, who: VerifiedApprov
             requirement: string | null;
             state: string;
             details: (string | null)[];
-            requiredEvidence: readonly import("./scope.js").EvidenceKind[];
+            requiredEvidence: readonly ("changed-path" | "check" | "manual-review" | "screenshot")[];
             reviewer: {
                 judgement: import("./proof.js").CriterionJudgementWord;
                 note: string | null;
             } | null;
             evidence: {
-                kind: import("./scope.js").EvidenceKind;
+                kind: "changed-path" | "check" | "manual-review" | "screenshot";
                 reference: string | null;
             }[];
             coverageGaps: (string | null)[];

package/dist/chat-actions.d.ts

@@ -1,5 +1,7 @@
 import { type Store } from "./store.js";
 import { type VerifiedApprover } from "./principal.js";
+import { CHAT_ACTION_FIELDS, type SharedAction } from "./contracts/chat-actions.js";
+export { CHAT_ACTION_FIELDS, type SharedAction };
 export declare const CHAT_ACTIONS: {
     readonly skill_import: {
         readonly label: "Add skill";
@@ -235,20 +237,11 @@ export declare const CHALLENGE_ACTIONS: ReadonlySet<ChatAction>;
 /** Actions about the person themselves, in no project: their card carries no project (repo ""). */
 export declare const OWNER_ACTIONS: ReadonlySet<ChatAction>;
 export declare function isChatAction(value: unknown): value is ChatAction;
-export type SharedAction = {
-    operation: ChatAction;
-    request: Record<string, unknown>;
-    repo: string;
-    title: string;
-    terms: string[];
-    stamp: string;
-    state: Record<string, unknown>;
-};
-export declare const CHAT_ACTION_FIELDS: Record<ChatAction, readonly string[]>;
 /** No writes, including at preview. Store-derived snapshots are never accepted
  * from a model. Rebuilding the same request before execution catches changes. */
 export declare function prepareSharedAction(store: Store, who: VerifiedApprover, operation: ChatAction, input: Record<string, unknown>, root?: string, now?: Date): SharedAction;
-export declare function sharedActionPayload(value: Record<string, unknown>): SharedAction | null;
+/** A saved proposal's action, read by its schema (contracts/chat-actions.ts); null when it can't be read. */
+export declare function sharedActionPayload(value: unknown): SharedAction | null;
 export declare function sharedActionNeedsReview(action: SharedAction): boolean;
 /** Whether a paired phone may confirm this protected action behind its own
  * explicit challenge: the action is on the challenge list, needs no
@@ -256,7 +249,20 @@ export declare function sharedActionNeedsReview(action: SharedAction): boolean;
 export declare function sharedActionAllowsChallenge(action: SharedAction): boolean;
 export declare function sharedActionReviewPath(id: number): string;
 export declare function mintSharedActionReview(store: Store, who: VerifiedApprover, id: number, root: string, now: Date): {
-    payload: SharedAction;
+    payload: {
+        version: 1;
+        operation: "decision_record" | "decision_retire" | "flow_card_add" | "flow_card_approve" | "flow_card_assign" | "flow_card_cancel" | "flow_card_choose" | "flow_card_comment" | "flow_card_move" | "flow_card_send_back" | "flow_card_watch" | "flow_create" | "flow_edit" | "flow_script_save" | "flow_starter" | "flow_trigger_add" | "flow_trigger_pause" | "flow_trigger_remove" | "flow_trigger_resume" | "kit_setup" | "knowledge_instructions" | "knowledge_remove" | "knowledge_restore" | "knowledge_save" | "lead_about_you" | "result_accept" | "scope_approve" | "skill_disable" | "skill_enable" | "skill_import" | "skill_restore" | "skill_test" | "task_cancel" | "task_resume" | "teammate_answer" | "teammate_create" | "teammate_memory" | "teammate_note" | "teammate_routine" | "teammate_soul" | "teammate_state" | "teammate_tools" | "teammate_undo" | "tool_add" | "tool_remove";
+        request: {
+            [x: string]: unknown;
+        };
+        repo: string;
+        title: string;
+        terms: string[];
+        stamp: string;
+        state: {
+            [x: string]: unknown;
+        };
+    };
     nonce: string;
 };
 export type SharedActionOptions = {