toolroll 0.9.34 → 0.9.36

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 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.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/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

@@ -45,7 +45,7 @@ export declare function readAcceptanceEvidence(store: Store, who: VerifiedApprov
                 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/contracts/contract.d.ts

@@ -29,10 +29,37 @@ export type ContractIssue = {
 };
 /** `["steps", 0, "routes", 0, "goesTo"]` as `steps[0].routes[0].goesTo`. */
 export declare function pathOf(path: readonly PropertyKey[]): string;
-/** A Zod error as path-named issues, in the error's own order. */
-export declare function contractIssues(error: z.ZodError): ContractIssue[];
+/**
+ * How a contract names a key it doesn't know: the keys a person or model often writes for one it does (`onFail` for
+ * `ifFails`, `to` for `goesTo`), tried in order against the keys allowed at that place. Without one that fits, a key
+ * spelled close to an allowed one (a case or a letter or two off) is suggested.
+ */
+export type ContractOptions = {
+    aliases?: Readonly<Record<string, readonly string[]>>;
+};
+type Where = {
+    schema?: z.ZodType;
+    input?: unknown;
+    options?: ContractOptions;
+};
+/**
+ * A Zod error as path-named issues, in the error's own order. Given the schema and input it came from, an unknown key
+ * also says which allowed key it most likely meant (`unknown key 'onFail' (did you mean ifFails?)`).
+ */
+export declare function contractIssues(error: z.ZodError, where?: Where): ContractIssue[];
 /** A Zod error as path-named lines: `steps[0].routes[0].goesTo: required`, `routes[0]: unknown key 'to'`. */
-export declare function contractError(error: z.ZodError): string[];
+export declare function contractError(error: z.ZodError, where?: Where): string[];
+/** A refusal as a reader reports it: a stable reason code, and the path-named line as the message. */
+export type ContractProblem = {
+    reason: string;
+    message: string;
+};
+/**
+ * A contract issue as a problem with a reason code built from its path — `missing-goal`, `criteria[0].how-too-long`,
+ * `checks-too-many`, `payload-unknown-key`, `bad-version`, `newer-version` — so callers that branch on a reason, and
+ * durable outcomes that recorded one, read the same as before the contract.
+ */
+export declare function contractProblemOf(issue: ContractIssue): ContractProblem;
 export type ContractResult<T> = {
     ok: true;
     value: T;
@@ -41,7 +68,7 @@ export type ContractResult<T> = {
     issues: ContractIssue[];
 };
 /** Parse with the input reported, so a missing field reads `required` rather than a wrong type. */
-export declare function parseContract<T>(schema: z.ZodType<T>, input: unknown): ContractResult<T>;
+export declare function parseContract<T>(schema: z.ZodType<T>, input: unknown, options?: ContractOptions): ContractResult<T>;
 /**
  * Read a versioned payload. The current version parses as itself; an older known version (0 for a payload saved
  * before it carried `version`) is upgraded by its adapter and then parsed by the same schema; a newer version is
@@ -51,9 +78,10 @@ export declare function readVersioned<T>(schema: z.ZodType<T> & {
     shape: {
         version: z.ZodLiteral<number>;
     };
-}, input: unknown, upgrades?: Readonly<Record<number, (payload: Record<string, unknown>) => unknown>>): ContractResult<T>;
+}, input: unknown, upgrades?: Readonly<Record<number, (payload: Record<string, unknown>) => unknown>>, options?: ContractOptions): ContractResult<T>;
 /**
  * The JSON Schema a model gets for `schema` (Claude's `--json-schema`). Throws when the schema uses refine,
  * superRefine, transform or preprocess anywhere: what a model is told must be everything the schema checks.
  */
 export declare function toModelSchema(schema: z.ZodType): Record<string, unknown>;
+export {};

package/dist/contracts/contract.js

@@ -41,55 +41,182 @@ function got(input) {
         return "an array";
     return typeof input === "object" ? "an object" : `a ${typeof input}`;
 }
-function issuesOf(issue) {
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The keys an object schema allows at `path` in `input`, following arrays, wrappers and (by its discriminator) a union. */
+function keysAt(schema, input, path) {
+    let node = schema, value = input;
+    for (let at = 0; node !== undefined;) {
+        const def = node._zod.def;
+        if (def.type === "optional" || def.type === "nullable" || def.type === "readonly") {
+            node = def["innerType"];
+            continue;
+        }
+        if (def.type === "lazy") {
+            node = def["getter"]();
+            continue;
+        }
+        if (def.type === "union") {
+            const options = def["options"];
+            const by = def["discriminator"];
+            const wanted = by !== undefined && isRecord(value) ? value[by] : undefined;
+            node = options.find(option => {
+                const shape = option._zod.def["shape"];
+                if (shape === undefined)
+                    return false;
+                if (by === undefined)
+                    return true;
+                const literal = shape[by]?._zod.def;
+                return literal !== undefined && literal["values"]?.includes(wanted) === true;
+            });
+            continue;
+        }
+        if (at === path.length)
+            return def.type === "object" ? Object.keys(def["shape"]) : null;
+        const part = path[at++];
+        if (def.type === "array" && typeof part === "number") {
+            node = def["element"];
+            value = Array.isArray(value) ? value[part] : undefined;
+            continue;
+        }
+        if (def.type === "object" && typeof part === "string") {
+            const shape = def["shape"];
+            node = shape[part] ?? def["catchall"];
+            value = isRecord(value) ? value[part] : undefined;
+            continue;
+        }
+        return null;
+    }
+    return null;
+}
+/** Edit distance, for "did you mean" (short strings only). */
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        let last = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const was = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, last + (a[i - 1] === b[j - 1] ? 0 : 1));
+            last = was;
+        }
+    }
+    return row[b.length];
+}
+/** The allowed key an unknown one most likely meant, or null. */
+function suggestion(key, known, options) {
+    if (known === null || known.length === 0)
+        return null;
+    const alias = options.aliases?.[key]?.find(one => known.includes(one));
+    if (alias !== undefined)
+        return alias;
+    const close = known
+        .map(one => ({ one, far: one.toLowerCase() === key.toLowerCase() ? 0 : distance(one.toLowerCase(), key.toLowerCase()) }))
+        .filter(({ one, far }) => far <= (Math.min(one.length, key.length) >= 6 ? 2 : 1))
+        .sort((a, b) => a.far - b.far);
+    return close[0]?.one ?? null;
+}
+function issuesOf(issue, where = {}) {
     const at = pathOf(issue.path);
     const one = (kind, what) => ({ path: at, kind, line: `${at}: ${what}` });
     switch (issue.code) {
-        case "unrecognized_keys":
-            return issue.keys.map(key => ({ path: at, kind: "unknown-key", line: `${at}: unknown key '${key}'` }));
+        case "unrecognized_keys": {
+            const known = where.schema === undefined ? null : keysAt(where.schema, where.input, issue.path);
+            return issue.keys.map(key => {
+                const meant = suggestion(key, known, where.options ?? {});
+                return { path: at, kind: "unknown-key", line: `${at}: unknown key '${key}'${meant === null ? "" : ` (did you mean ${meant}?)`}` };
+            });
+        }
         case "invalid_type": {
             const missing = "input" in issue ? issue.input === undefined : / received undefined$/.test(issue.message);
-            if (missing)
+            // A null where a value belongs is a value left out.
+            if (missing || ("input" in issue && issue.input === null && issue.expected !== "null"))
                 return [one("required", "required")];
-            return [one("wrong-type", `must be ${issue.expected === "array" ? "an array" : issue.expected === "object" ? "an object" : `a ${issue.expected}`}${"input" in issue ? ` (got ${got(issue.input)})` : ""}`)];
+            const expected = issue.expected === "array" ? "an array" : issue.expected === "object" ? "an object" : issue.expected === "null" ? "null" : `a ${issue.expected}`;
+            return [one("wrong-type", `must be ${expected}${"input" in issue ? ` (got ${got(issue.input)})` : ""}`)];
         }
         case "too_big":
             if (issue.origin === "array" || issue.origin === "set")
                 return [one("too-many", `at most ${String(issue.maximum)} items`)];
+            if (issue.origin === "number" || issue.origin === "int" || issue.origin === "bigint")
+                return [one("bad-value", `at most ${String(issue.maximum)}`)];
             return [one("too-long", issue.origin === "string" && issue.message.startsWith("over ") ? issue.message : `at most ${String(issue.maximum)}${issue.origin === "string" ? " characters" : ""}`)];
         case "too_small":
             if (issue.origin === "string" && Number(issue.minimum) === 1)
                 return [one("empty", "must not be empty")];
             if (issue.origin === "array" || issue.origin === "set")
                 return [one("too-few", `at least ${String(issue.minimum)} item${Number(issue.minimum) === 1 ? "" : "s"}`)];
+            if (issue.origin === "number" || issue.origin === "int" || issue.origin === "bigint")
+                return [one("bad-value", `at least ${String(issue.minimum)}`)];
             return [one("too-few", `at least ${String(issue.minimum)}`)];
         case "invalid_value":
             return [one("bad-value", `must be ${issue.values.length === 1 ? JSON.stringify(issue.values[0]) : `one of ${issue.values.map(value => JSON.stringify(value)).join(", ")}`}`)];
-        case "invalid_union":
+        case "invalid_union": {
+            // A discriminated union names its choices (`steps[0].kind: must be one of "inbox", "task", ...`).
+            const by = issue.discriminator, options = issue.options;
+            if (typeof by === "string" && Array.isArray(options)) {
+                const given = "input" in issue && isRecord(issue.input) ? issue.input[by] : undefined;
+                const path = at === "payload" || issue.path.at(-1) === by ? at : `${at}.${by}`;
+                const line = given === undefined || given === null ? "required" : `must be one of ${options.map(value => JSON.stringify(value)).join(", ")}`;
+                return [{ path, kind: given === undefined || given === null ? "required" : "bad-value", line: `${path}: ${line}` }];
+            }
             return [one("invalid", "does not match any allowed shape")];
+        }
+        case "invalid_format":
+            // A pattern's own words say what it wants (`must be a short id: lowercase letters, numbers and dashes`).
+            return [one("bad-value", issue.message.startsWith("Invalid") ? `must match ${issue.format === "regex" ? issue.pattern ?? "its pattern" : issue.format}` : issue.message)];
         default:
             return [one("invalid", issue.message)];
     }
 }
-/** A Zod error as path-named issues, in the error's own order. */
-export function contractIssues(error) {
-    return error.issues.flatMap(issuesOf);
+/**
+ * A Zod error as path-named issues, in the error's own order. Given the schema and input it came from, an unknown key
+ * also says which allowed key it most likely meant (`unknown key 'onFail' (did you mean ifFails?)`).
+ */
+export function contractIssues(error, where = {}) {
+    return error.issues.flatMap(issue => issuesOf(issue, where));
 }
 /** A Zod error as path-named lines: `steps[0].routes[0].goesTo: required`, `routes[0]: unknown key 'to'`. */
-export function contractError(error) {
-    return contractIssues(error).map(issue => issue.line);
+export function contractError(error, where = {}) {
+    return contractIssues(error, where).map(issue => issue.line);
+}
+/**
+ * A contract issue as a problem with a reason code built from its path — `missing-goal`, `criteria[0].how-too-long`,
+ * `checks-too-many`, `payload-unknown-key`, `bad-version`, `newer-version` — so callers that branch on a reason, and
+ * durable outcomes that recorded one, read the same as before the contract.
+ */
+export function contractProblemOf(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 };
 }
 /** Parse with the input reported, so a missing field reads `required` rather than a wrong type. */
-export function parseContract(schema, input) {
+export function parseContract(schema, input, options = {}) {
     const parsed = schema.safeParse(input, { reportInput: true });
-    return parsed.success ? { ok: true, value: parsed.data } : { ok: false, issues: contractIssues(parsed.error) };
+    return parsed.success ? { ok: true, value: parsed.data } : { ok: false, issues: contractIssues(parsed.error, { schema, input, options }) };
 }
 /**
  * Read a versioned payload. The current version parses as itself; an older known version (0 for a payload saved
  * before it carried `version`) is upgraded by its adapter and then parsed by the same schema; a newer version is
  * refused plainly; anything else is an unknown version.
  */
-export function readVersioned(schema, input, upgrades = {}) {
+export function readVersioned(schema, input, upgrades = {}, options = {}) {
     const current = schema.shape.version.value;
     if (typeof input !== "object" || input === null || Array.isArray(input)) {
         return { ok: false, issues: [{ path: "payload", kind: "wrong-type", line: `payload: must be an object (got ${got(input)})` }] };
@@ -97,7 +224,7 @@ export function readVersioned(schema, input, upgrades = {}) {
     const body = input;
     const version = Object.prototype.hasOwnProperty.call(body, "version") ? body["version"] : 0;
     if (version === current)
-        return parseContract(schema, body);
+        return parseContract(schema, body, options);
     if (typeof version === "number" && Number.isInteger(version) && version > current) {
         return { ok: false, issues: [{ path: "version", kind: "newer-version", line: `version: made by a newer Toolroll (version ${version}; this one reads up to ${current})` }] };
     }
@@ -105,7 +232,7 @@ export function readVersioned(schema, input, upgrades = {}) {
     if (upgrade === undefined) {
         return { ok: false, issues: [{ path: "version", kind: "bad-value", line: `version: unknown version ${JSON.stringify(version)} (this Toolroll reads ${current}${Object.keys(upgrades).length === 0 ? "" : ` and ${Object.keys(upgrades).join(", ")}`})` }] };
     }
-    return parseContract(schema, upgrade(body));
+    return parseContract(schema, upgrade(body), options);
 }
 /** The Zod node kinds a model-facing schema may use: each says exactly what its JSON Schema says. */
 const MODEL_FACING_TYPES = new Set(["string", "number", "int", "boolean", "null", "literal", "enum", "array", "object", "optional", "nullable", "union", "tuple", "record", "lazy", "readonly", "unknown", "any"]);