toolroll 0.9.36 → 0.9.37

package/dist/contracts/scope.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A task's scope: its goal, what is out of it, the paths it expects to touch and the acceptance rubric an operator
+ * signs. One schema for the terms and one for a criterion, both made from the plan contract's own fields
+ * (src/contracts/plan.ts) rather than restated; a scope may name 50 paths where a plan names 32. The rules JSON Schema
+ * cannot state — UTF-8 byte limits, control characters, duplicate criterion ids and evidence kinds — run in plain code
+ * after parsing, each with a path-named error.
+ *
+ * Reading keeps what every release accepted: a criterion's unknown keys are ignored, a null or empty `how` reads as
+ * null, and an absent or empty rubric reads as none (whether that is allowed is the caller's question). The digest
+ * (scope.ts `digestOf`) reads the parsed values, so a saved scope's digest is what it always was.
+ *
+ * The schemas are built lazily: plan.ts reads the evidence kinds through scope.ts, which reads this module, so in
+ * either load order plan.ts may still be loading when this module is.
+ */
+import { z } from "zod";
+import { type ContractProblem } from "./contract.js";
+/** A criterion as saved and as every reader returns it: the plan's criterion with `how` always present (null for none). */
+export declare const savedCriterionSchema: z.ZodLazy<z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+    how: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>>;
+export type AcceptanceCriterion = z.infer<typeof savedCriterionSchema>;
+/** A rubric as saved: at most twelve criteria (an empty one is a scope filed before rubrics, or by a road with none). */
+export declare const rubricSchema: z.ZodLazy<z.ZodArray<z.ZodLazy<z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+    how: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>>>>;
+/** A rubric as a row stores it: exactly the keys this code writes (`how` may be absent on an older row). */
+export declare const storedRubricSchema: z.ZodLazy<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    how: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+}, z.core.$strict>>>;
+/** What a model drafts as a rubric (the lead's proposals): the plan's criteria, one to twelve. */
+export declare const rubricInputSchema: z.ZodLazy<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    how: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    evidence: z.ZodArray<z.ZodEnum<{
+        "changed-path": "changed-path";
+        check: "check";
+        "manual-review": "manual-review";
+        screenshot: "screenshot";
+    }>>;
+}, z.core.$strict>>>;
+/** A scope's terms as filed: the plan's goal, out-of-scope text and touch paths (up to 50), and its rubric. */
+export declare const scopeTermsSchema: z.ZodLazy<z.ZodObject<{
+    goal: z.ZodString;
+    outOfScope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    touches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    acceptance: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodLazy<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        evidence: z.ZodArray<z.ZodEnum<{
+            "changed-path": "changed-path";
+            check: "check";
+            "manual-review": "manual-review";
+            screenshot: "screenshot";
+        }>>;
+        how: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>>>;
+}, z.core.$strict>>;
+export type ScopeTerms = z.infer<typeof scopeTermsSchema>;
+export type AcceptanceProblem = ContractProblem;
+/**
+ * Read a rubric from already-JSON-parsed input (a console form, the CLI, a routine or template, a model's proposal,
+ * a saved row): every problem at once, each naming its path. Absent or empty is `[]` with no problems. A criterion
+ * that reads cleanly is kept even when another does not, as before; any problem means the rubric is refused.
+ */
+export declare function readAcceptance(value: unknown): {
+    criteria: AcceptanceCriterion[];
+    problems: AcceptanceProblem[];
+};
+export type ScopeTermsResult = {
+    ok: true;
+    terms: Omit<ScopeTerms, "acceptance"> & {
+        acceptance: AcceptanceCriterion[];
+    };
+} | {
+    ok: false;
+    field: "goal" | "outOfScope" | "touches" | "acceptance" | "payload";
+    problems: AcceptanceProblem[];
+};
+/** Read a scope's terms as a person or a model files them; the first field refused names the refusal. */
+export declare function readScopeTerms(input: unknown): ScopeTermsResult;

package/dist/contracts/scope.js

@@ -0,0 +1,114 @@
+/**
+ * A task's scope: its goal, what is out of it, the paths it expects to touch and the acceptance rubric an operator
+ * signs. One schema for the terms and one for a criterion, both made from the plan contract's own fields
+ * (src/contracts/plan.ts) rather than restated; a scope may name 50 paths where a plan names 32. The rules JSON Schema
+ * cannot state — UTF-8 byte limits, control characters, duplicate criterion ids and evidence kinds — run in plain code
+ * after parsing, each with a path-named error.
+ *
+ * Reading keeps what every release accepted: a criterion's unknown keys are ignored, a null or empty `how` reads as
+ * null, and an absent or empty rubric reads as none (whether that is allowed is the caller's question). The digest
+ * (scope.ts `digestOf`) reads the parsed values, so a saved scope's digest is what it always was.
+ *
+ * The schemas are built lazily: plan.ts reads the evidence kinds through scope.ts, which reads this module, so in
+ * either load order plan.ts may still be loading when this module is.
+ */
+import { z } from "zod";
+import { hasForbiddenControls } from "../decision.js";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { ACCEPTANCE_LIMITS } from "./acceptance-terms.js";
+import { contractProblemOf, parseContract } from "./contract.js";
+import { acceptanceCriterionSchema as planCriterionSchema, planSchema } from "./plan.js";
+/** A criterion as saved and as every reader returns it: the plan's criterion with `how` always present (null for none). */
+export const savedCriterionSchema = z.lazy(() => planCriterionSchema.extend({ how: planCriterionSchema.shape.how.unwrap() }));
+/** A rubric as saved: at most twelve criteria (an empty one is a scope filed before rubrics, or by a road with none). */
+export const rubricSchema = z.lazy(() => z.array(savedCriterionSchema).max(ACCEPTANCE_LIMITS.criteria));
+/** A rubric as a row stores it: exactly the keys this code writes (`how` may be absent on an older row). */
+export const storedRubricSchema = z.lazy(() => z.array(planCriterionSchema).max(ACCEPTANCE_LIMITS.criteria));
+/** What a model drafts as a rubric (the lead's proposals): the plan's criteria, one to twelve. */
+export const rubricInputSchema = z.lazy(() => z.array(planCriterionSchema).min(1).max(ACCEPTANCE_LIMITS.criteria));
+/** A scope's terms as filed: the plan's goal, out-of-scope text and touch paths (up to 50), and its rubric. */
+export const scopeTermsSchema = z.lazy(() => z.strictObject({
+    goal: planSchema.shape.goal,
+    outOfScope: planSchema.shape.outOfScope,
+    touches: z.array(planSchema.shape.touches.unwrap().element).max(TEXT_LIMITS.scopeTouches).optional(),
+    acceptance: rubricSchema.optional(),
+}));
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A criterion as the reader takes it: only the fields it knows, a null or empty `how` as null. Anything else as is. */
+function criterionBody(entry) {
+    if (!isRecord(entry))
+        return entry;
+    const out = {};
+    for (const field of ["id", "statement", "evidence"])
+        if (entry[field] !== undefined)
+            out[field] = entry[field];
+    out["how"] = entry["how"] === undefined || entry["how"] === "" ? null : entry["how"];
+    return out;
+}
+/** The plain-code rules for one criterion JSON Schema cannot state: UTF-8 bytes and control characters. */
+function criterionTextProblems(criterion, at) {
+    const out = [];
+    for (const [field, limit] of [["id", ACCEPTANCE_LIMITS.id], ["statement", ACCEPTANCE_LIMITS.statement], ["how", ACCEPTANCE_LIMITS.how]]) {
+        const value = criterion[field];
+        const path = `${at}.${field}`;
+        if (value === null)
+            continue;
+        if (Buffer.byteLength(value, "utf8") > limit)
+            out.push({ reason: `${path}-too-long`, message: `${path}: over ${limit.toLocaleString("en-US")} bytes` });
+        else if (hasForbiddenControls(value))
+            out.push({ reason: `${path}-controls`, message: `${path}: carries control characters that could become terminal escapes` });
+    }
+    return out;
+}
+const named = (problems, path) => problems.some(one => one.message.startsWith(`${path}:`));
+/**
+ * Read a rubric from already-JSON-parsed input (a console form, the CLI, a routine or template, a model's proposal,
+ * a saved row): every problem at once, each naming its path. Absent or empty is `[]` with no problems. A criterion
+ * that reads cleanly is kept even when another does not, as before; any problem means the rubric is refused.
+ */
+export function readAcceptance(value) {
+    if (value === undefined || value === null)
+        return { criteria: [], problems: [] };
+    const body = Array.isArray(value) ? value.map(criterionBody) : value;
+    const parsed = parseContract(z.object({ acceptance: rubricSchema }), { acceptance: body });
+    const issues = parsed.ok ? [] : parsed.issues;
+    // The list itself is wrong (not a list, too long): nothing in it is read.
+    if (!Array.isArray(body) || issues.some(one => one.path === "acceptance"))
+        return { criteria: [], problems: issues.map(contractProblemOf) };
+    const criteria = [];
+    const seen = new Set();
+    const problems = [];
+    body.forEach((entry, index) => {
+        const at = `acceptance[${index}]`;
+        const own = issues.filter(one => one.path === at || one.path.startsWith(`${at}.`) || one.path.startsWith(`${at}[`)).map(contractProblemOf);
+        const read = own.length === 0 ? savedCriterionSchema.safeParse(entry) : null;
+        const text = read?.success === true ? criterionTextProblems(read.data, at) : [];
+        const kinds = read?.success === true ? read.data.evidence : [];
+        const twice = kinds.flatMap((kind, k) => (kinds.indexOf(kind) === k ? [] : [{ reason: `${at}-duplicate-evidence-kind`, message: `${at}.evidence[${k}]: "${kind}" appears twice` }]));
+        problems.push(...own, ...text, ...twice);
+        // A duplicate id is a problem with the rubric, not with either criterion: both stay readable, as before.
+        const id = isRecord(entry) ? entry["id"] : undefined;
+        const idClean = typeof id === "string" && !named(own, `${at}.id`) && !named(text, `${at}.id`);
+        if (idClean && seen.has(id))
+            problems.push({ reason: `${at}-duplicate-id`, message: `${at}.id: "${id}" appears twice` });
+        if (idClean)
+            seen.add(id);
+        if (read?.success === true && text.length === 0 && twice.length === 0)
+            criteria.push(read.data);
+    });
+    return { criteria, problems };
+}
+/** Read a scope's terms as a person or a model files them; the first field refused names the refusal. */
+export function readScopeTerms(input) {
+    if (!isRecord(input))
+        return { ok: false, field: "payload", problems: [{ reason: "bad-payload", message: "payload: must be an object" }] };
+    const acceptance = readAcceptance(input["acceptance"]);
+    const parsed = parseContract(scopeTermsSchema, { ...input, acceptance: acceptance.criteria });
+    if (!parsed.ok) {
+        const first = parsed.issues[0].path.replace(/[[.].*$/, "");
+        return { ok: false, field: first, problems: parsed.issues.filter(one => one.path.replace(/[[.].*$/, "") === first).map(contractProblemOf) };
+    }
+    if (acceptance.problems.length > 0)
+        return { ok: false, field: "acceptance", problems: acceptance.problems };
+    return { ok: true, terms: { ...parsed.value, acceptance: acceptance.criteria } };
+}

package/dist/contracts/scout-report.d.ts

@@ -0,0 +1,234 @@
+/**
+ * The scout's report: one schema for the report a scout writes (its report file, or Claude's structured output), the
+ * JSON Schema a Claude scout is given (`--json-schema`, `SCOUT_OUTPUT_JSON_SCHEMA`) and the reader that takes it back
+ * (`parseReport` in scout-report.ts), which also reads every report already kept as evidence. The rules JSON Schema
+ * cannot state — UTF-8 byte limits, blank text, control characters, one-line titles, a one-paragraph summary, safe
+ * links, duplicate screenshots and items naming them — run in plain code after parsing, each with a path-named error.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** How many follow-ups, items and screenshots a report may carry. */
+export declare const REPORT_COUNTS: {
+    readonly followUps: 5;
+    readonly items: 6;
+    readonly images: 8;
+};
+/** Caps are BYTES of UTF-8 (v4 review, finding 11): a 64 KiB report is 64 KiB whatever script it is written in. They
+ * hold what a scout writes; a stored report is read without them (`storedReportSchema`). */
+export declare const REPORT_LIMITS: {
+    readonly payload: number;
+    readonly title: 200;
+    readonly summary: 2500;
+    readonly document: number;
+    readonly followUps: 5;
+    readonly followUpTitle: 200;
+    /** A follow-up files as a task: its goal is held to the task goal limit, in bytes of the same count. */
+    readonly followUpGoal: 8000;
+    readonly items: 6;
+    readonly itemTitle: 200;
+    readonly itemWhy: 1000;
+    readonly url: 2000;
+    readonly images: 8;
+    readonly caption: 300;
+};
+/** A screenshot's name in the scout's output folder: one plain file name, PNG or JPEG, never a path. */
+export declare const REPORT_IMAGE_FILE: RegExp;
+/** Each text field, the limit it is written within, and whether it is one line or a web address. */
+export declare const REPORT_TEXT_FIELDS: {
+    readonly title: {
+        readonly limit: "reportTitleBytes";
+        readonly oneLine: true;
+    };
+    readonly summary: {
+        readonly limit: "reportSummary";
+    };
+    readonly report: {
+        readonly limit: "reportDocumentBytes";
+    };
+};
+export declare const FOLLOW_UP_TEXT_FIELDS: {
+    readonly title: {
+        readonly limit: "reportTitleBytes";
+        readonly oneLine: true;
+    };
+    readonly goal: {
+        readonly limit: "goal";
+    };
+};
+export declare const ITEM_TEXT_FIELDS: {
+    readonly title: {
+        readonly limit: "reportTitleBytes";
+        readonly oneLine: true;
+    };
+    readonly why: {
+        readonly limit: "reportWhyBytes";
+    };
+    readonly url: {
+        readonly limit: "reportUrlBytes";
+        readonly link: true;
+    };
+};
+export declare const IMAGE_TEXT_FIELDS: {
+    readonly file: {
+        readonly limit: "reportCaptionBytes";
+        readonly oneLine: true;
+    };
+    readonly caption: {
+        readonly limit: "reportCaptionBytes";
+        readonly oneLine: true;
+    };
+    readonly url: {
+        readonly limit: "reportUrlBytes";
+        readonly link: true;
+    };
+};
+export declare const REPORT_VERSION = 1;
+/** A report as a scout writes it now. */
+export declare const scoutReportSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    report: z.ZodString;
+    followUps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        goal: z.ZodString;
+    }, z.core.$strict>>>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        why: z.ZodString;
+        url: z.ZodString;
+        image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        caption: z.ZodString;
+        url: z.ZodString;
+        sha256: z.ZodOptional<z.ZodString>;
+        artifact: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** A report kept as evidence: the same, except text keeps the length it was stored with. */
+export declare const storedReportSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    report: z.ZodString;
+    followUps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        goal: z.ZodString;
+    }, z.core.$strict>>>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        why: z.ZodString;
+        url: z.ZodString;
+        image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        caption: z.ZodString;
+        url: z.ZodString;
+        sha256: z.ZodOptional<z.ZodString>;
+        artifact: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ScoutReportPayload = z.infer<typeof scoutReportSchema>;
+type FollowUp = NonNullable<ScoutReportPayload["followUps"]>[number];
+type Item = NonNullable<ScoutReportPayload["items"]>[number];
+type Image = NonNullable<ScoutReportPayload["images"]>[number];
+/** One finding later steps read: it cites its URL, and may show one of the report's images (null when none). */
+export type ReportItem = Omit<Item, "image"> & {
+    image: string | null;
+};
+/** A screenshot the scout saved. From the scout, `file` names a file in its output folder; once stored, the runner
+ * adds the bytes' sha256 and the evidence row that holds them. */
+export type ReportImage = Image;
+/** A report as read: the payload without its envelope, every list present (empty when the scout gave none). */
+export type ParsedReport = {
+    title: string;
+    summary: string;
+    /** The report document, markdown, rendered fenced-inert everywhere. */
+    report: string;
+    /** Proposed follow-ups: each files as a task in the same repository. */
+    followUps: FollowUp[];
+    items: ReportItem[];
+    images: ReportImage[];
+};
+/** The park mailbox's decision as a scout hands it back: the same fields `parseDecision` reads, which stays its
+ * validator until the decision contract (docs/plans/zod-revamp.md, item 7) gives it one schema. */
+export declare const scoutDecisionSchema: z.ZodObject<{
+    urgency: z.ZodLiteral<"blocking">;
+    recap: z.ZodString;
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        consequence: z.ZodString;
+        reversible: z.ZodBoolean;
+    }, z.core.$strict>>;
+    recommendation: z.ZodString;
+}, z.core.$strict>;
+/**
+ * The scout's handback for Claude's `--json-schema` (run 2334's fix): plan mode only lets a session write its own plan
+ * file, so a Claude scout returns a report — or a question for the operator — as structured output on the terminal
+ * result event. The report branch is the report schema itself; the byte limits and rules JSON Schema cannot state are
+ * `parseReport`'s (and `parseDecision`'s), applied to the branch as handed back.
+ */
+export declare const scoutHandbackSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        question: "question";
+        report: "report";
+    }>;
+    report: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        title: z.ZodString;
+        summary: z.ZodString;
+        report: z.ZodString;
+        followUps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            goal: z.ZodString;
+        }, z.core.$strict>>>;
+        items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            why: z.ZodString;
+            url: z.ZodString;
+            image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>>>;
+        images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            caption: z.ZodString;
+            url: z.ZodString;
+            sha256: z.ZodOptional<z.ZodString>;
+            artifact: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    decision: z.ZodOptional<z.ZodObject<{
+        urgency: z.ZodLiteral<"blocking">;
+        recap: z.ZodString;
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            consequence: z.ZodString;
+            reversible: z.ZodBoolean;
+        }, z.core.$strict>>;
+        recommendation: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const SCOUT_OUTPUT_JSON_SCHEMA: Readonly<Record<string, unknown>>;
+/**
+ * Known reports keep the old parser's field-picking, whether unversioned (including `version: null`) or version 1:
+ * unknown fields in the report, follow-ups, items and images are ignored, and a null list means none. Known field
+ * values are never rewritten, and anything that is not an object is left for the schema to refuse by path.
+ */
+declare function normalizeReportV1(body: Record<string, unknown>): Record<string, unknown>;
+export declare const REPORT_UPGRADES: {
+    readonly 0: typeof normalizeReportV1;
+};
+/** Normalize current and unversioned reports; leave other versions for readVersioned to check. */
+export declare function reportPayloadBody(input: unknown): Record<string, unknown> | null;
+/** Read current and unversioned reports with the same field-picking, then the strict schema; refuse newer versions
+ * plainly. `stored`: one kept as evidence, read without the length limits. */
+export declare function readReportPayload(input: unknown, options?: {
+    stored?: boolean;
+}): ContractResult<ScoutReportPayload>;
+export {};

package/dist/contracts/scout-report.js

@@ -0,0 +1,141 @@
+/**
+ * The scout's report: one schema for the report a scout writes (its report file, or Claude's structured output), the
+ * JSON Schema a Claude scout is given (`--json-schema`, `SCOUT_OUTPUT_JSON_SCHEMA`) and the reader that takes it back
+ * (`parseReport` in scout-report.ts), which also reads every report already kept as evidence. The rules JSON Schema
+ * cannot state — UTF-8 byte limits, blank text, control characters, one-line titles, a one-paragraph summary, safe
+ * links, duplicate screenshots and items naming them — run in plain code after parsing, each with a path-named error.
+ */
+import { z } from "zod";
+import { limitRule, TEXT_LIMITS } from "../text-limits.js";
+import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
+/** How many follow-ups, items and screenshots a report may carry. */
+export const REPORT_COUNTS = { followUps: 5, items: 6, images: 8 };
+/** Caps are BYTES of UTF-8 (v4 review, finding 11): a 64 KiB report is 64 KiB whatever script it is written in. They
+ * hold what a scout writes; a stored report is read without them (`storedReportSchema`). */
+export const REPORT_LIMITS = {
+    payload: TEXT_LIMITS.reportPayloadBytes,
+    title: TEXT_LIMITS.reportTitleBytes,
+    summary: TEXT_LIMITS.reportSummary,
+    document: TEXT_LIMITS.reportDocumentBytes,
+    followUps: REPORT_COUNTS.followUps,
+    followUpTitle: TEXT_LIMITS.reportTitleBytes,
+    /** A follow-up files as a task: its goal is held to the task goal limit, in bytes of the same count. */
+    followUpGoal: TEXT_LIMITS.goal,
+    items: REPORT_COUNTS.items,
+    itemTitle: TEXT_LIMITS.reportTitleBytes,
+    itemWhy: TEXT_LIMITS.reportWhyBytes,
+    url: TEXT_LIMITS.reportUrlBytes,
+    images: REPORT_COUNTS.images,
+    caption: TEXT_LIMITS.reportCaptionBytes,
+};
+/** A screenshot's name in the scout's output folder: one plain file name, PNG or JPEG, never a path. */
+export const REPORT_IMAGE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\.(?:png|jpe?g)$/i;
+/** Each text field, the limit it is written within, and whether it is one line or a web address. */
+export const REPORT_TEXT_FIELDS = {
+    title: { limit: "reportTitleBytes", oneLine: true },
+    summary: { limit: "reportSummary" },
+    report: { limit: "reportDocumentBytes" },
+};
+export const FOLLOW_UP_TEXT_FIELDS = { title: { limit: "reportTitleBytes", oneLine: true }, goal: { limit: "goal" } };
+export const ITEM_TEXT_FIELDS = { title: { limit: "reportTitleBytes", oneLine: true }, why: { limit: "reportWhyBytes" }, url: { limit: "reportUrlBytes", link: true } };
+// The image's file is any one line here: the runner refuses one that isn't a plain file name in its output folder, not the report.
+export const IMAGE_TEXT_FIELDS = { file: { limit: "reportCaptionBytes", oneLine: true }, caption: { limit: "reportCaptionBytes", oneLine: true }, url: { limit: "reportUrlBytes", link: true } };
+export const REPORT_VERSION = 1;
+function reportSchemaOf(text) {
+    // Limits named without "Bytes" that a report still counts in bytes: the model is told so.
+    const bytes = (field, limit) => text(field, limit).describe(limitRule(field, TEXT_LIMITS[limit], "bytes"));
+    const followUp = z.strictObject({
+        title: text("follow-up title", "reportTitleBytes").min(1),
+        goal: bytes("follow-up goal", "goal").min(1),
+    });
+    const item = z.strictObject({
+        title: text("item title", "reportTitleBytes").min(1),
+        why: text("item why", "reportWhyBytes").min(1),
+        url: text("item url", "reportUrlBytes").min(1),
+        image: z.string().nullable().optional().describe("the file of the one of images this item shows, if any"),
+    });
+    const image = z.strictObject({
+        file: text("image file", "reportCaptionBytes").min(1),
+        caption: text("image caption", "reportCaptionBytes").min(1),
+        url: text("image url", "reportUrlBytes").min(1),
+        /** Added by Toolroll once the screenshot is stored: its bytes' sha256 and the evidence that holds them. */
+        sha256: z.string().regex(/^[0-9a-f]{64}$/, { error: "must be a sha256 hex digest" }).optional().describe("set by Toolroll when it keeps the screenshot; leave out"),
+        artifact: z.int().positive().optional().describe("set by Toolroll when it keeps the screenshot; leave out"),
+    });
+    return versioned(REPORT_VERSION, {
+        title: text("title", "reportTitleBytes").min(1),
+        summary: bytes("summary", "reportSummary").min(1),
+        report: text("report", "reportDocumentBytes").min(1),
+        followUps: z.array(followUp).max(REPORT_COUNTS.followUps).optional(),
+        items: z.array(item).max(REPORT_COUNTS.items).optional(),
+        images: z.array(image).max(REPORT_COUNTS.images).optional(),
+    });
+}
+/** A report as a scout writes it now. */
+export const scoutReportSchema = reportSchemaOf(limited);
+/** A report kept as evidence: the same, except text keeps the length it was stored with. */
+export const storedReportSchema = reportSchemaOf(() => z.string());
+/** The park mailbox's decision as a scout hands it back: the same fields `parseDecision` reads, which stays its
+ * validator until the decision contract (docs/plans/zod-revamp.md, item 7) gives it one schema. */
+export const scoutDecisionSchema = z.strictObject({
+    urgency: z.literal("blocking"),
+    recap: z.string(),
+    question: z.string(),
+    options: z.array(z.strictObject({ id: z.string(), label: z.string(), consequence: z.string(), reversible: z.boolean() })),
+    recommendation: z.string(),
+});
+/**
+ * The scout's handback for Claude's `--json-schema` (run 2334's fix): plan mode only lets a session write its own plan
+ * file, so a Claude scout returns a report — or a question for the operator — as structured output on the terminal
+ * result event. The report branch is the report schema itself; the byte limits and rules JSON Schema cannot state are
+ * `parseReport`'s (and `parseDecision`'s), applied to the branch as handed back.
+ */
+export const scoutHandbackSchema = z.strictObject({
+    kind: z.enum(["report", "question"]),
+    report: scoutReportSchema.optional(),
+    decision: scoutDecisionSchema.optional(),
+});
+export const SCOUT_OUTPUT_JSON_SCHEMA = toModelSchema(scoutHandbackSchema);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function pick(body, fields) {
+    const out = {};
+    for (const field of fields) {
+        if (Object.prototype.hasOwnProperty.call(body, field) && body[field] !== undefined)
+            out[field] = body[field];
+    }
+    return out;
+}
+const ENTRY_FIELDS = {
+    followUps: Object.keys(FOLLOW_UP_TEXT_FIELDS),
+    items: [...Object.keys(ITEM_TEXT_FIELDS), "image"],
+    images: [...Object.keys(IMAGE_TEXT_FIELDS), "sha256", "artifact"],
+};
+/**
+ * Known reports keep the old parser's field-picking, whether unversioned (including `version: null`) or version 1:
+ * unknown fields in the report, follow-ups, items and images are ignored, and a null list means none. Known field
+ * values are never rewritten, and anything that is not an object is left for the schema to refuse by path.
+ */
+function normalizeReportV1(body) {
+    const out = { version: REPORT_VERSION, ...pick(body, [...Object.keys(REPORT_TEXT_FIELDS), "followUps", "items", "images"]) };
+    for (const list of ["followUps", "items", "images"]) {
+        if (out[list] === null)
+            delete out[list];
+        else if (Array.isArray(out[list]))
+            out[list] = out[list].map(entry => (isRecord(entry) ? pick(entry, ENTRY_FIELDS[list]) : entry));
+    }
+    return out;
+}
+export const REPORT_UPGRADES = { 0: normalizeReportV1 };
+/** Normalize current and unversioned reports; leave other versions for readVersioned to check. */
+export function reportPayloadBody(input) {
+    if (!isRecord(input))
+        return null;
+    return !Object.prototype.hasOwnProperty.call(input, "version") || input["version"] === null || input["version"] === REPORT_VERSION
+        ? normalizeReportV1(input)
+        : input;
+}
+/** Read current and unversioned reports with the same field-picking, then the strict schema; refuse newer versions
+ * plainly. `stored`: one kept as evidence, read without the length limits. */
+export function readReportPayload(input, options = {}) {
+    return readVersioned(options.stored === true ? storedReportSchema : scoutReportSchema, reportPayloadBody(input) ?? input, REPORT_UPGRADES);
+}

package/dist/contracts/slack-callback.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A Slack button tap (slack-chat.ts `receiveSlack`): the `block_actions` interaction Slack sends, and the button data
+ * Toolroll put on it. The interaction is Slack's, so fields Toolroll doesn't read are ignored; the button (its
+ * `action_id` and one-time token `value`) is Toolroll's. A tap from the paired person whose button can't be read is
+ * answered with why (`actions[0].value: must be a Toolroll button token`), and nothing is done.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** Toolroll's buttons: toolroll_* since the rename; standing_orders_* buttons on older messages still work. */
+export declare const SLACK_BUTTON_ACTION: RegExp;
+/** A link button opens its page in Slack's own client; Slack still reports the tap, and there is nothing to do. */
+export declare const SLACK_LINK_ACTION: RegExp;
+/** The interaction around a tap: who, and the message the button is on. */
+export declare const slackBlockActionsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"block_actions">;
+    user: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    container: z.ZodObject<{
+        type: z.ZodString;
+        channel_id: z.ZodOptional<z.ZodString>;
+        message_ts: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    message: z.ZodOptional<z.ZodObject<{
+        thread_ts: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    actions: z.ZodArray<z.ZodObject<{
+        action_id: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        action_ts: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SlackBlockActions = z.infer<typeof slackBlockActionsSchema>;
+/** The one tapped button, as Toolroll made it. */
+export declare const slackButtonSchema: z.ZodObject<{
+    action_id: z.ZodString;
+    value: z.ZodString;
+    action_ts: z.ZodString;
+}, z.core.$strip>;
+export type SlackButton = z.infer<typeof slackButtonSchema>;
+export declare function readSlackBlockActions(body: unknown): ContractResult<SlackBlockActions>;
+/** The tapped button: exactly one, Toolroll's (`actions[0].action_id: not a Toolroll button`). */
+export declare function readSlackButton(interaction: SlackBlockActions): ContractResult<SlackButton>;