toolroll 0.9.34 → 0.9.37

package/dist/contracts/route.js

@@ -0,0 +1,128 @@
+/**
+ * A sealed route (phase-routing.ts): which exact agent plans, builds, repairs and reviews a task, as a scope's
+ * `proposed_route_json` / `approved_route_json` and a standing order's route keep it. One schema covering both versions
+ * a route has been saved in — version 1 (sealed before sizing: no `size`, routine and strong tiers) and version 2 —
+ * plus the override list and the task size it carries. The rules JSON Schema cannot state run in plain code after
+ * parsing, each with a path-named error: the legs run plan, build, repair, review in that order; the posture is what
+ * the legs actually run; one override per phase.
+ *
+ * Reading never rewrites: a version 1 route stays version 1 (its digest domain and bytes are its own), and reads with
+ * no size. phase-routing.ts `canonicalRouteJson` / `routeDigestOf` encode the parsed value, so a sealed route's digest
+ * is what it always was.
+ */
+import { z } from "zod";
+import { EVIDENCE_KINDS } from "./acceptance-terms.js";
+import { limited, parseContract, versioned } from "./contract.js";
+/** The phases a route has a leg for, in the order its legs run. */
+export const ROUTE_PHASES = ["plan", "build", "repair", "review"];
+/** provider.ts's provider ids, restated (provider.ts sits above phase-routing.ts in the module graph) and pinned to
+ * them by the test suite. */
+export const ROUTE_PROVIDERS = ["claude", "codex", "openrouter", "gemini"];
+/** provider.ts's MODEL_ID, restated for the same reason: an exact model id is argv-safe — no leading dash, no
+ * whitespace or control bytes. */
+export const MODEL_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+export const RISKS = ["routine", "elevated", "high"];
+export const TASK_SIZE_WORDS = ["small", "medium", "large"];
+/** The route version this code seals; version 1 (before sizing) still reads. */
+export const ROUTE_VERSION = 2;
+const phase = z.enum(ROUTE_PHASES);
+const provider = z.enum(ROUTE_PROVIDERS);
+const model = z.string().regex(MODEL_ID_SHAPE, { error: "must be an exact model id: letters, digits and . _ : / -, not starting with a dash" });
+const text = z.string().min(1);
+/** How big a change the task is, as it was sized (by the classifier, the description, or a person). */
+export const taskSizingSchema = z.strictObject({
+    size: z.enum(TASK_SIZE_WORDS),
+    risky: z.boolean(),
+    source: z.enum(["classifier", "heuristic", "person"]),
+    reason: limited("size reason", "sizeReason"),
+});
+/** An approver's explicit per-phase choice, recorded with attribution. */
+export const routeOverrideSchema = z.strictObject({ phase, provider, model, by: text, at: text });
+function legSchema(tiers) {
+    const tier = z.enum(tiers);
+    return z.strictObject({
+        phase,
+        provider,
+        model,
+        tier,
+        chosen: z.enum(["recommended", "override", "pinned"]),
+        recommended: z.strictObject({ provider, model, tier }),
+        reasons: z.array(z.string()),
+        problem: text.nullable(),
+    });
+}
+/** One leg of a version 2 route: the light tier exists. */
+export const routeLegSchema = legSchema(["light", "routine", "strong"]);
+const terms = {
+    risk: z.enum(RISKS),
+    qualityMode: z.enum(["default", "strict"]),
+    publication: z.enum(["none", "notify", "automerge"]),
+    evidence: z.array(z.enum(EVIDENCE_KINDS)),
+    posture: z.enum(["economy", "strong"]),
+    demands: z.array(z.string()),
+};
+export const sealedRouteV1Schema = versioned(1, {
+    ...terms,
+    legs: z.array(legSchema(["routine", "strong"])).length(ROUTE_PHASES.length),
+    overrides: z.array(routeOverrideSchema),
+});
+export const sealedRouteV2Schema = versioned(ROUTE_VERSION, {
+    ...terms,
+    legs: z.array(routeLegSchema).length(ROUTE_PHASES.length),
+    overrides: z.array(routeOverrideSchema),
+    size: taskSizingSchema.nullable(),
+});
+/** A sealed route as saved, in either version. */
+export const sealedRouteSchema = z.discriminatedUnion("version", [sealedRouteV1Schema, sealedRouteV2Schema]);
+/** The posture legs actually run under: strong only when a leg runs a configured strong agent as recommended. */
+export function postureOf(legs) {
+    return legs.some(leg => leg.chosen === "recommended" && leg.tier === "strong") ? "strong" : "economy";
+}
+const issue = (path, what) => ({ path, kind: "bad-value", line: `${path}: ${what}` });
+/** Overrides as read: one per phase (a second is named by path), in phase order. */
+function overridesOf(overrides, at) {
+    const issues = overrides.flatMap((one, index) => overrides.findIndex(other => other.phase === one.phase) === index ? [] : [issue(`${at}[${index}].phase`, `${JSON.stringify(one.phase)} appears twice`)]);
+    if (issues.length > 0)
+        return { ok: false, issues };
+    return { ok: true, value: [...overrides].sort((a, b) => ROUTE_PHASES.indexOf(a.phase) - ROUTE_PHASES.indexOf(b.phase)) };
+}
+/** Read a task's recorded override list (a list on its own, as `route_overrides_json` keeps it). */
+export function readRouteOverrides(input) {
+    const parsed = parseContract(z.object({ overrides: z.array(routeOverrideSchema) }), { overrides: input });
+    return parsed.ok ? overridesOf(parsed.value.overrides, "overrides") : parsed;
+}
+/** Read a sealed route: either version as itself, every leg, override and the size proved, nothing unknown. */
+export function readSealedRoute(input) {
+    const version = typeof input === "object" && input !== null ? input["version"] : undefined;
+    if (typeof version === "number" && Number.isInteger(version) && version > ROUTE_VERSION) {
+        return { ok: false, issues: [{ path: "version", kind: "newer-version", line: `version: made by a newer Toolroll (version ${version}; this one reads up to ${ROUTE_VERSION})` }] };
+    }
+    const parsed = parseContract(sealedRouteSchema, input);
+    if (!parsed.ok)
+        return parsed;
+    const route = parsed.value;
+    const issues = route.legs.flatMap((leg, index) => (leg.phase === ROUTE_PHASES[index] ? [] : [issue(`legs[${index}].phase`, `must be ${JSON.stringify(ROUTE_PHASES[index])} (legs run plan, build, repair, review)`)]));
+    const posture = postureOf(route.legs);
+    if (posture !== route.posture)
+        issues.push(issue("posture", `must be ${JSON.stringify(posture)}: that is what its legs run`));
+    const overrides = overridesOf(route.overrides, "overrides");
+    if (!overrides.ok)
+        issues.push(...overrides.issues);
+    if (issues.length > 0 || !overrides.ok)
+        return { ok: false, issues };
+    return {
+        ok: true,
+        value: {
+            version: route.version,
+            risk: route.risk,
+            qualityMode: route.qualityMode,
+            publication: route.publication,
+            evidence: [...route.evidence].sort(),
+            posture: route.posture,
+            demands: route.demands,
+            legs: route.legs,
+            overrides: overrides.value,
+            size: route.version === 1 ? null : route.size,
+        },
+    };
+}

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 {};