toolroll 0.9.34 → 0.9.36

package/dist/serve.js

@@ -1,3 +1,4 @@
+import { SCREENSHOT_CAPTURE, structuredHandoffView, terminalDiffView } from "./result-evidence-readers.js";
 import { checkLeadIdentity, leadIdentityOf, leadNameOf, LEAD_NAME_MAX, LEAD_PERSONA_MAX } from "./lead-identity.js";
 import { aboutYouOf, checkAboutYou, saveAboutYou, ABOUT_YOU_LINE_MAX, ABOUT_YOU_MAX_LINES } from "./lead-about.js";
 import { withActor } from "./actor.js";
@@ -53,7 +54,7 @@ import { FORM_PATH, flowFormPage, receiveFlowForm, shareFlowButton, stopSharingF
 import { addFlowTriggerTo, checkFlowTriggerNow, HOOK_PATH, pressFlowButton, receiveFlowHook, removeFlowTrigger, renewFlowHook, removeLinearKey, saveHooksBase, saveLinearKey, saveLinearSigningSecret } from "./flow-triggers.js";
 import { addCardToFlow, advanceFlows, cancelFlowCard, crossProjectProblem, decideFlowCard, FLOW_HREF, flowDefinitionOf, moveCardInFlow } from "./flow-engine.js";
 import { chooseFlowCard } from "./flow-send.js";
-import { FLOW_TEMPLATES, validateFlowDefinition } from "./flows.js";
+import { FlowContractError, FLOW_TEMPLATES, validateFlowDefinition, withZoneNames } from "./flows.js";
 import { TOOL_CATALOG, addToolTo, catalogTool, discoverTools, localAppOf, projectToolsOf, removeToolFrom, secretsSetFor, setToolSecret, splitCommandLine, testToolOf } from "./project-tools.js";
 import { changeLearning, learningView } from "./project-learning.js";
 import { applySavedKnowledge, changeKnowledge, knowledgeView, knowledgeVersion, readKnowledgeSnapshot } from "./project-knowledge.js";
@@ -1136,6 +1137,8 @@ export function createDecisionServer(options) {
             response.end(`<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="refresh" content="0;url=${escape(to)}"><title>Toolroll</title>${HANDOFF_STYLE}<p>${escape(words)} <a href="${escape(to)}">Back to Toolroll</a></p>`);
         };
         const state = url.searchParams.get("state") ?? "";
+        // Every arrival is logged (never the code or state): a sign-in that never came back is then visible as an absence.
+        logEvent("info", "connect.callback", { error: url.searchParams.get("error"), known: connectVisits.has(state) });
         if (!startedHere(request, state))
             return done("/settings/tools", "problem", "That sign-in was started in another browser. Connect again from this one.");
         const visit = connectVisits.get(state);
@@ -7179,12 +7182,13 @@ export function createDecisionServer(options) {
                 return redirect(response, "/flows");
             }
             if (action === "save") {
-                let saved;
+                let saved, drawn;
                 try {
-                    saved = validateFlowDefinition(JSON.parse(body.get("definition") ?? "null"));
+                    drawn = JSON.parse(body.get("definition") ?? "null");
+                    saved = validateFlowDefinition(drawn);
                 }
                 catch (error) {
-                    return answer(400, { ok: false, said: error instanceof SyntaxError ? "That flow couldn't be read." : error instanceof Error ? error.message : "That flow isn't valid." });
+                    return answer(400, { ok: false, said: error instanceof SyntaxError ? "That flow couldn't be read." : error instanceof FlowContractError ? withZoneNames(error.lines, drawn) : error instanceof Error ? error.message : "That flow isn't valid." });
                 }
                 const name = (body.get("name") ?? flow.name).replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 80) || flow.name;
                 // The owner (v86) is whom "the owner decides" zones ask: someone who can approve on this project.
@@ -22504,32 +22508,6 @@ function runsPage(chrome, rows, liveIds, nextCursor, verdicts = new Map(), accep
     const older = nextCursor === null ? "" : `<p><a href="/runs?before=${nextCursor}">older →</a></p>`;
     return screen("builds", [`<h1>Builds <a class="badge" href="/peek">Peek at the live ones \u2192</a></h1>`, buildsViews("builds"), `<p class="hint">one build = one attempt by an agent to complete a task, on its own branch</p>`, list, older].join("\n"), { chrome });
 }
-function structuredHandoffView(artifacts, root) {
-    const artifact = [...artifacts].reverse().find(one => one.kind === "handoff");
-    if (artifact === undefined)
-        return null;
-    const read = readVerifiedArtifact(root, artifact);
-    if (!read.ok)
-        return null;
-    try {
-        const parsed = JSON.parse(read.content.toString("utf8"));
-        if (parsed === null || typeof parsed !== "object" || typeof parsed["conclusion"] !== "string")
-            return null;
-        const conclusion = oneLineOf(parsed["conclusion"], 600);
-        if (conclusion === "" || hasForbiddenControls(conclusion))
-            return null;
-        const list = (name) => Array.isArray(parsed[name])
-            ? parsed[name]
-                .filter((one) => typeof one === "string" && one.trim() !== "" && !hasForbiddenControls(one))
-                .slice(0, 8)
-                .map(one => oneLineOf(one, 240))
-            : [];
-        return { conclusion, changes: list("changes"), verification: list("verification"), followUps: list("followUps") };
-    }
-    catch {
-        return null;
-    }
-}
 /** What a scout found, each with its link and picture, then any screenshot no item shows. Every link is the cited
  * http(s) address the report parser admitted; every picture is served from verified evidence. */
 function reportItemsHtml(items, shots, runId) {
@@ -22606,7 +22584,6 @@ function sharedResultFactsOf(run, proof, terminal, handoff, report, publication)
         publicationWords: receiptPublicationWords(publication),
     };
 }
-const SCREENSHOT_CAPTURE = /^agent-claimed screenshot at (.+) \(validated (?:png|jpeg)\)/;
 function proofBundleView(store, run, artifacts, root) {
     const verdictRow = store.proofVerdictFor(run.id);
     const acceptanceRow = store.proofAcceptance(run.id);
@@ -22722,74 +22699,6 @@ function completionReceiptView(store, run, artifacts, root, review = null) {
         facts: sharedResultFactsOf(run, proof, terminal, handoff, report, publication),
     };
 }
-const CAPTURE_EXIT = /\(exit ([0-9]{1,4})\)\s*$/;
-/**
- * Assemble the terminal-diff card's facts. Every branch names its state:
- * a failed capture (nonzero exit recorded in the capture string) reads as
- * the failure it is, unverifiable bytes read as their problem, and absence
- * returns null so old runs simply show nothing rather than a broken card.
- */
-function terminalDiffView(artifacts, root) {
-    const patchArtifact = artifacts.find(one => one.kind === "terminal-diff");
-    const statArtifact = artifacts.find(one => one.kind === "diff-stat");
-    if (patchArtifact === undefined && statArtifact === undefined)
-        return null;
-    const view = { patch: null, stat: null };
-    if (patchArtifact !== undefined) {
-        const exit = CAPTURE_EXIT.exec(patchArtifact.capture);
-        if (exit !== null && exit[1] !== "0") {
-            view.patch = { problem: `capture failed — ${patchArtifact.capture}` };
-        }
-        else {
-            const read = readVerifiedArtifact(root, patchArtifact);
-            view.patch = read.ok
-                ? { text: read.content.toString("utf8"), truncated: patchArtifact.truncated, artifactId: patchArtifact.id }
-                : { problem: `stored but unverifiable — ${read.problem}` };
-        }
-    }
-    if (statArtifact !== undefined) {
-        const exit = CAPTURE_EXIT.exec(statArtifact.capture);
-        if (exit !== null && exit[1] !== "0") {
-            view.stat = { problem: `capture failed — ${statArtifact.capture}` };
-        }
-        else {
-            const read = readVerifiedArtifact(root, statArtifact);
-            if (!read.ok) {
-                view.stat = { problem: `stored but unverifiable — ${read.problem}` };
-            }
-            else {
-                try {
-                    const parsed = JSON.parse(read.content.toString("utf8"));
-                    // Every field this page renders is type-proved (arc 6, finding 7):
-                    // "an object with a base key" was accepting any shape at all.
-                    const count = (value) => typeof value === "number" && Number.isFinite(value);
-                    const wellFormed = parsed !== null &&
-                        typeof parsed === "object" &&
-                        typeof parsed["base"] === "string" &&
-                        typeof parsed["head"] === "string" &&
-                        count(parsed["fileCount"]) &&
-                        count(parsed["additions"]) &&
-                        count(parsed["deletions"]) &&
-                        count(parsed["binaryCount"]) &&
-                        typeof parsed["filesTruncated"] === "boolean" &&
-                        Array.isArray(parsed["files"]) &&
-                        parsed["files"].every(one => one !== null &&
-                            typeof one === "object" &&
-                            typeof one["path"] === "string" &&
-                            (count(one["additions"]) || one["additions"] === null) &&
-                            (count(one["deletions"]) || one["deletions"] === null));
-                    view.stat = wellFormed
-                        ? parsed
-                        : { problem: "stat is not the shape this page knows" };
-                }
-                catch {
-                    view.stat = { problem: "stat did not parse as JSON" };
-                }
-            }
-        }
-    }
-    return view;
-}
 const REVIEW_DIFF_LINE_CAP = 4_000;
 /** Parse only the stable structure Git's unified patch format guarantees.
  * Unknown metadata remains visible, and a patch that cannot be structured

package/dist/setup-guide.d.ts

@@ -15,10 +15,10 @@ export declare function detectPreparation(repo: string): {
 } | null;
 /** Browser installation may write only this known file inside its project. */
 export declare function previewProjectInstructions(repo: string): {
+    content?: never;
     ok: false;
     message: string;
     plan?: never;
-    content?: never;
     fingerprint?: never;
     installed?: never;
 } | {
@@ -30,10 +30,10 @@ export declare function previewProjectInstructions(repo: string): {
     installed: boolean;
 };
 export declare function addProjectInstructions(repo: string, fingerprint: string): {
+    content?: never;
     ok: false;
     message: string;
     plan?: never;
-    content?: never;
     fingerprint?: never;
     installed?: never;
 } | import("./skills.js").InstallResult;

package/dist/surface.js

@@ -278,7 +278,14 @@ export const COMMAND_GUIDE = [
     operator("task approve", "the yes — nothing builds without one; binds to the scope digest"),
     operator("task requeue", "exit a stall: incidents resolved, strikes cleared, queued again"),
     operator("task regate", "explicitly rerun the approved check on the last exact commit — no agent or automatic retry"),
-    operator("task review", "show a run's automatic review: HIGH findings, suggested follow-ups, or why it was not reviewed"),
+    { invocation: "task review", synopsis: "read a task's compact result packet with --brief, or a run's automatic findings without it", audience: "agent", agentMayInvoke: true, mutation: "none",
+        positionals: [{ name: "id", required: true, meaning: "task id with --brief; run id otherwise" }],
+        flags: [jsonFlag, dbFlag,
+            { name: "brief", takesValue: false, meaning: "saved conclusion, changed files, checks, findings, screenshots, plan and next actions; missing fields say not recorded" },
+            { name: "run", takesValue: true, meaning: "with --brief, select an exact finished attempt instead of the latest" },
+            { name: "all", takesValue: false, meaning: "include LOW findings within the compact packet's limit; extra findings are counted" },
+            { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" }],
+        notableReasons: ["usage", "unauthenticated", "not-found"] },
     operator("task accept", "record an explicit acceptance with limitations; does not change checks or prove deployment"),
     operator("task repair", "inspect or approve an existing historical repair draft; use task revise for new feedback"),
     operator("task route", "which configured agents plan, build and repair this task; phase and risk changes require renewed approval"),

package/dist/task-review-brief.d.ts

@@ -0,0 +1,75 @@
+/** A read-only packet of saved result facts. Never opens a worktree or emits logs, patches or saved shell commands. */
+import type { Store } from './store.js';
+import { type AssignmentAccess } from './assignment.js';
+import { type FindingSeverity } from './review-switch.js';
+declare const MISSING: 'not recorded';
+type Missing = typeof MISSING;
+type Finding = {
+    severity: FindingSeverity;
+    file: string;
+    line: number;
+    scenario: string;
+};
+export type ReviewBrief = {
+    header: {
+        task: string;
+        run: number | Missing;
+        provider: string;
+        model: string;
+        minutes: number | Missing;
+        outcome: string;
+        base: string;
+        head: string;
+        state: string;
+    };
+    conclusion: string;
+    changedFiles: {
+        files: {
+            path: string;
+            additions: number | Missing;
+            deletions: number | Missing;
+        }[];
+        total: number;
+        omitted: number;
+    } | Missing;
+    check: {
+        status: string;
+        exit: number | Missing;
+        failed: string[] | Missing;
+    };
+    review: {
+        state: string;
+        reason: string;
+        findings: Finding[];
+        counts: Record<FindingSeverity, number>;
+        omitted: Record<FindingSeverity, number>;
+    } | Missing;
+    screenshots: {
+        files: {
+            path: string;
+            bytes: number | Missing;
+        }[];
+        omitted: number;
+    } | Missing;
+    plan: {
+        titles: string[];
+        omitted: number;
+    } | Missing;
+    nextActions: string[];
+};
+/** Select only finished build/report attempts in the admitted family. An explicit run never crosses that boundary. */
+export declare function taskReviewBrief(store: Store, task: string, root: string, now: Date, access: AssignmentAccess, options?: {
+    run?: number;
+    all?: boolean;
+    secrets?: readonly string[];
+}): {
+    ok: true;
+    brief: ReviewBrief;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+/** Text and JSON share this bounded projection; --all includes LOW details within the same line budget. */
+export declare function renderReviewBrief(brief: ReviewBrief): string[];
+export {};

package/dist/task-review-brief.js

@@ -0,0 +1,179 @@
+import { assignmentChecksForRun, assignmentOf } from './assignment.js';
+import { assignmentPresentationOf } from './assignment-presentation.js';
+import { readVerifiedArtifact, readVerifiedProofForRun, reportShotsOf, scanForSecrets } from './evidence.js';
+import { SCREENSHOT_CAPTURE, structuredHandoffView, terminalDiffView } from './result-evidence-readers.js';
+import { buildReviewOf } from './review-switch.js';
+import { parseReport } from './scout-report.js';
+import { sanitizeTranscriptLine } from './live.js';
+import { redactSecretAssignments } from './builder.js';
+import { parseExecutionPlanDocument } from './plan.js';
+const MISSING = 'not recorded';
+const SEVERITIES = ['HIGH', 'MEDIUM', 'LOW'];
+/** Redact before shortening so a clipped credential cannot escape recognition. Apply to every data string in both formats. */
+function safeText(value, secrets, cap = 300) {
+    if (typeof value !== 'string' || !value.trim())
+        return MISSING;
+    const flat = value.replace(/\s+/g, ' ').trim();
+    const cleaned = sanitizeTranscriptLine(flat);
+    if (secrets.some(secret => secret !== '' && value.includes(secret)) ||
+        /\blt_[a-f0-9]{12}_[A-Za-z0-9_-]{43}\b|\bBearer\s+\S+/i.test(flat) ||
+        scanForSecrets(flat).length || redactSecretAssignments(flat) !== flat || cleaned.startsWith('[a credential-shaped'))
+        return '[redacted]';
+    return cleaned.length <= cap ? cleaned : `${cleaned.slice(0, cap - 1)}…`;
+}
+function verifiedText(root, artifact) {
+    if (!artifact || artifact.truncated || artifact.captureStatus === 'failed')
+        return null;
+    const read = readVerifiedArtifact(root, artifact);
+    return read.ok ? read.content.toString('utf8') : null;
+}
+/** Select only finished build/report attempts in the admitted family. An explicit run never crosses that boundary. */
+export function taskReviewBrief(store, task, root, now, access, options = {}) {
+    const family = store.taskFamilyOf(task, access.repos, access.principal === 'operator' && access.includeUnplaced === true);
+    if (family === null)
+        return { ok: false, reason: 'not-found', message: 'That task is unavailable in your projects.' };
+    const runs = family.versions.flatMap(version => store.runsFor(version.refId))
+        .filter(run => (run.role === 'builder' || run.role === 'scout') && run.finishedAt !== null && run.outcome !== null)
+        .sort((a, b) => b.id - a.id);
+    const run = options.run === undefined ? runs[0] ?? null : runs.find(one => one.id === options.run) ?? null;
+    if (options.run !== undefined && run === null)
+        return { ok: false, reason: 'not-found', message: 'That finished build or report is unavailable for this task.' };
+    const assignment = assignmentOf(store, task, now, access, root);
+    const safe = (value, cap) => safeText(value, options.secrets ?? [], cap);
+    const sha = (value) => /^[a-f0-9]{40,64}$/.test(value ?? '') ? value.slice(0, 12) : MISSING;
+    const artifacts = run === null ? [] : store.artifactsFor(run.id);
+    // Pass only the inventory: this reader does not need to open the patch for a brief.
+    const statView = terminalDiffView(artifacts.filter(one => one.kind === 'diff-stat' && one.captureStatus !== 'failed'), root)?.stat;
+    const stat = statView && !('problem' in statView) ? statView : null;
+    const handoff = structuredHandoffView(artifacts, root, value => safe(value, 600));
+    const reportText = run?.role === 'scout' ? verifiedText(root, artifacts.find(one => one.kind === 'report')) : null;
+    const report = reportText === null ? null : parseReport(reportText, { stored: true });
+    const conclusion = handoff?.conclusion ?? (report?.ok ? report.report.summary : run?.handoff);
+    const duration = run?.finishedAt ? (Date.parse(run.finishedAt) - Date.parse(run.startedAt)) / 60_000 : NaN;
+    const recordedCheck = run === null ? null : store.runCheckFor(run.id);
+    const receipt = assignment?.receipt?.runId === run?.id ? assignment?.receipt : null;
+    // The shared assignment reader includes later checks on the same candidate. Its result wins;
+    // old named failures must not ride a newer passing (or differently failed) check.
+    const checks = receipt?.checks ?? (run === null ? null : assignmentChecksForRun(store, root, run.id, now));
+    const status = checks && checks.status !== 'unavailable' && checks.status !== 'not-run' ? checks.status : recordedCheck?.status ?? checks?.status ?? MISSING;
+    const exit = checks && checks.status === status ? checks.exitCode : recordedCheck?.exitCode;
+    const sameCheck = recordedCheck?.status === status && recordedCheck.exitCode === exit &&
+        (!checks?.logArtifactId || artifacts.some(one => one.id === checks.logArtifactId && one.kind === 'check-log'));
+    const progress = run === null ? null : store.checkProgress(run.id);
+    const failed = sameCheck ? [...new Set([
+            ...recordedCheck.suites.filter(one => one.status === 'failed').map(one => safe(one.name)),
+            ...Object.entries(progress?.suites ?? {}).filter(([, suite]) => suite.state === 'failed').map(([name, suite]) => `${name}: ${suite.failed} failed`),
+        ])] : [];
+    const review = run === null ? null : buildReviewOf(store, run.id);
+    const findings = review === null ? [] : [...review.high, ...review.followUps].filter(one => one && SEVERITIES.includes(one.severity));
+    const counts = Object.fromEntries(SEVERITIES.map(severity => [severity, findings.filter(one => one.severity === severity).length]));
+    const shown = SEVERITIES.flatMap(severity => severity === 'LOW' && !options.all ? [] : findings.filter(one => one.severity === severity))
+        .slice(0, 12).map(one => ({ severity: one.severity, file: safe(one.file), line: Number.isSafeInteger(one.line) ? one.line : 0, scenario: safe(one.scenario) }));
+    const omitted = Object.fromEntries(SEVERITIES.map(severity => [severity, counts[severity] - shown.filter(one => one.severity === severity).length]));
+    const proof = run === null ? null : readVerifiedProofForRun(store, root, run.id);
+    const shots = artifacts.filter(one => one.kind === 'screenshot');
+    const reportShots = report?.ok && run !== null ? reportShotsOf(artifacts, root, run.id, report.report.images) : [];
+    const pathOf = (artifact) => SCREENSHOT_CAPTURE.exec(artifact.capture)?.[1] ??
+        (reportShots.some(one => one.artifactId === artifact.id) ? `evidence/${artifact.key}` : null);
+    const declared = proof?.ok ? proof.proof.screenshots.map(one => one.path) : [];
+    const paths = [...new Set([...declared, ...shots.flatMap(one => pathOf(one) ?? [])])];
+    const screenshots = paths.map(path => {
+        const artifact = shots.find(one => pathOf(one) === path);
+        return { path: safe(path), bytes: artifact && artifact.captureStatus !== 'failed' && readVerifiedArtifact(root, artifact).ok ? artifact.bytesStored : MISSING };
+    });
+    const plan = run === null ? null : planTitles(store, root, run);
+    const current = run !== null && receipt !== null && family.current.refId === run.taskRef;
+    const nextActions = [];
+    if (!run)
+        nextActions.push('Open the task to inspect its progress.');
+    else if (!current)
+        nextActions.push('Open the current result before completing or requesting a revision.');
+    else {
+        if (assignment?.state === 'ready-to-check')
+            nextActions.push(`Complete: toolroll task complete ${safe(family.root.id)} --digest ${receipt.digest}`);
+        const diff = artifacts.find(one => one.kind === 'terminal-diff');
+        if (run.role === 'builder' && diff && readVerifiedArtifact(root, diff).ok) {
+            nextActions.push(`Revise: toolroll task revise ${safe(family.root.id)} --run ${run.id} --feedback "requested change"`);
+        }
+        else if (run.role === 'builder')
+            nextActions.push('Revision unavailable: saved changes are not recorded or cannot be read.');
+        if (assignment?.state === 'ready-to-check' || assignment?.state === 'complete') {
+            if (run.role === 'builder' && run.outcome === 'built')
+                nextActions.push(assignment.state === 'complete'
+                    ? 'Merge into a release through the normal release approval and check process.'
+                    : 'After completion, merge into a release through the normal release approval and check process.');
+        }
+        else
+            nextActions.push(`Open the task: ${safe(assignment?.detail)}`);
+    }
+    return { ok: true, brief: {
+            header: { task: safe(run === null ? task : store.externalIdFor(run.taskRef)), run: run?.id ?? MISSING,
+                provider: safe(run?.provider), model: safe(run?.model), minutes: Number.isFinite(duration) && duration >= 0 ? Math.round(duration * 10) / 10 : MISSING,
+                outcome: safe(run?.outcome), base: sha(run?.baseRevision), head: sha(run?.headRevision), state: run !== null && !current ? 'Earlier result' : assignment === null ? MISSING : assignmentPresentationOf(assignment).status.label },
+            conclusion: safe(conclusion, 600),
+            changedFiles: stat === null ? MISSING : { files: [...stat.files].sort((a, b) => ((b.additions ?? 0) + (b.deletions ?? 0)) - ((a.additions ?? 0) + (a.deletions ?? 0)))
+                    .slice(0, 15).map(one => ({ path: safe(one.path), additions: one.additions ?? MISSING, deletions: one.deletions ?? MISSING })), total: stat.fileCount, omitted: Math.max(0, stat.fileCount - Math.min(15, stat.files.length)) },
+            check: { status: status === 'unavailable' ? MISSING : status, exit: exit ?? MISSING, failed: status !== 'failed' ? [] : failed.length ? failed : MISSING },
+            review: review === null ? MISSING : { state: review.state, reason: safe(review.reason), findings: shown, counts, omitted },
+            screenshots: screenshots.length ? { files: screenshots.slice(0, 8), omitted: Math.max(0, screenshots.length - 8) } : MISSING,
+            plan: plan === null || plan.length === 0 ? MISSING : { titles: plan.slice(0, 5).map(one => safe(one)), omitted: Math.max(0, plan.length - 5) },
+            nextActions,
+        } };
+}
+function planTitles(store, root, run) {
+    const revision = run.planRevision == null ? null : store.getPlanRevision(run.planRevision);
+    // Historical runs cannot borrow a plan written after they started.
+    const artifact = revision === null ? store.runsFor(run.taskRef).filter(one => one.role === 'planner' && one.id < run.id)
+        .sort((a, b) => b.id - a.id).flatMap(one => store.artifactsFor(one.id)).find(one => one.kind === 'plan') : store.getArtifact(revision.artifact);
+    const text = verifiedText(root, artifact);
+    if (text === null)
+        return null;
+    const parsed = parseExecutionPlanDocument(text);
+    return parsed.ok ? parsed.document.milestones : text.split(/\r?\n/).filter(line => /^#{1,6}\s+\S/.test(line)).map(line => line.replace(/^#{1,6}\s+/, ''));
+}
+/** Text and JSON share this bounded projection; --all includes LOW details within the same line budget. */
+export function renderReviewBrief(brief) {
+    const h = brief.header;
+    const lines = [`${h.task} · run ${h.run} · ${h.provider}/${h.model} · ${h.minutes} min · ${h.outcome} · ${h.base} → ${h.head} · ${h.state}`,
+        `Conclusion: ${brief.conclusion}`, 'Changed files:'];
+    if (brief.changedFiles === MISSING)
+        lines.push(`  ${MISSING}`);
+    else {
+        lines.push(...brief.changedFiles.files.map(one => `  ${one.path} +${one.additions} / -${one.deletions}`));
+        if (brief.changedFiles.total === 0)
+            lines.push('  none');
+        if (brief.changedFiles.omitted)
+            lines.push(`  and ${brief.changedFiles.omitted} more`);
+    }
+    const check = brief.check;
+    lines.push(`Check: ${check.status} · exit ${check.exit}${check.failed === MISSING ? ` · failed parts: ${MISSING}` : check.failed.length ? ` · failed: ${check.failed.join('; ')}` : ''}`);
+    if (brief.review === MISSING)
+        lines.push(`Automatic review: ${MISSING}`);
+    else {
+        lines.push(`Automatic review: ${brief.review.state}${brief.review.reason === MISSING ? '' : ` · ${brief.review.reason}`}`);
+        lines.push(...brief.review.findings.map(one => `  ${one.severity} ${one.file}:${one.line} — ${one.scenario}`));
+        for (const severity of SEVERITIES)
+            if (brief.review.omitted[severity])
+                lines.push(`  ${severity}: ${brief.review.omitted[severity]} more (${brief.review.counts[severity]} total)`);
+        if (Object.values(brief.review.counts).every(count => count === 0) && brief.review.state === 'reviewed')
+            lines.push('  no findings');
+    }
+    lines.push('Screenshots:');
+    if (brief.screenshots === MISSING)
+        lines.push(`  ${MISSING}`);
+    else {
+        lines.push(...brief.screenshots.files.map(one => `  ${one.path} (${one.bytes}${typeof one.bytes === 'number' ? ' bytes' : ''})`));
+        if (brief.screenshots.omitted)
+            lines.push(`  and ${brief.screenshots.omitted} more`);
+    }
+    lines.push('Plan:');
+    if (brief.plan === MISSING)
+        lines.push(`  ${MISSING}`);
+    else {
+        lines.push(...brief.plan.titles.map(one => `  ${one}`));
+        if (brief.plan.omitted)
+            lines.push(`  and ${brief.plan.omitted} more`);
+    }
+    lines.push('Next:', ...brief.nextActions.map(one => `  ${one}`));
+    return lines;
+}

package/dist/text-limits.d.ts

@@ -16,6 +16,67 @@ export declare const TEXT_LIMITS: {
     readonly noteBytes: 16000;
     /** A flow work zone's instructions; nothing is held back for the card's details (they are attached when long). */
     readonly flowInstructions: 8000;
+    /** A flow's zones and steps (src/contracts/flow.ts): a zone's name, a step's id as written, and a reference to another step. */
+    readonly flowTitle: 60;
+    readonly flowStepId: 32;
+    readonly flowRef: 60;
+    /** A Message zone's message, or the comment an Update zone leaves. */
+    readonly flowMessage: 1000;
+    /** Who decides a "Person decides" zone (a sign-in name), and the AI teammate who works a zone, as written. */
+    readonly flowDecider: 64;
+    readonly flowTeammate: 40;
+    /** A Build zone's other project: its path. */
+    readonly flowRepo: 1000;
+    /** A script's or teammate's answer, a choice's button, a Sort zone's answer and what it means, its question, and a score's level. */
+    readonly flowAnswer: 40;
+    readonly flowChoice: 40;
+    readonly flowSortMeans: 200;
+    readonly flowSortQuestion: 300;
+    readonly flowSortLevel: 120;
+    /** A Web request zone's address, one header's value and the body it sends (an email's body too). */
+    readonly flowUrl: 2000;
+    readonly flowHeader: 500;
+    readonly flowBody: 8000;
+    /** An email's recipients and subject. */
+    readonly flowEmailTo: 500;
+    readonly flowEmailSubject: 200;
+    /** A tool zone's tool (MCP server), its function, and the arguments as JSON. */
+    readonly flowToolServer: 64;
+    readonly flowToolName: 100;
+    readonly flowToolArgs: 4000;
+    /** A wait or reminder said in words ("3 days"), and a time zone's name. */
+    readonly flowDuration: 40;
+    readonly flowTimeZone: 60;
+    /** A flow's name, and a flow file's about line, needs, parameter questions and answers, and scripts. */
+    readonly flowName: 80;
+    readonly flowFileAbout: 600;
+    readonly flowFileNeed: 80;
+    readonly flowParameter: 200;
+    readonly flowScriptAbout: 160;
+    readonly flowScriptBody: 20000;
+    readonly flowScriptFile: 200;
+    /** A trigger's settings: a button's label and questions, a schedule and the card it makes, GitHub, Linear, webhook and email terms. */
+    readonly triggerButton: 40;
+    readonly triggerQuestion: 80;
+    readonly triggerSchedule: 80;
+    readonly triggerTitle: 200;
+    readonly triggerDescription: 2000;
+    readonly triggerGithubRepo: 140;
+    readonly triggerLabel: 50;
+    readonly triggerBranch: 100;
+    readonly triggerTeam: 12;
+    readonly triggerState: 40;
+    readonly triggerWebhookTitle: 120;
+    readonly triggerWebhookField: 80;
+    readonly triggerFolder: 100;
+    readonly triggerSender: 300;
+    readonly triggerSubject: 100;
+    /** A schedule's secrets written as one line ("API_KEY, CRM_TOKEN"). */
+    readonly triggerSecrets: 500;
+    /** A card the lead adds to a flow: its title and description; a script it saves inline. */
+    readonly flowCardTitle: 200;
+    readonly flowCardDescription: 4000;
+    readonly flowScriptInline: 1600;
     /** A research report's summary, in UTF-8 bytes. */
     readonly reportSummary: 2500;
     /** What one flow step passes on to the steps after it. */
@@ -36,6 +97,15 @@ export declare const TEXT_LIMITS: {
     readonly acceptanceIdBytes: 40;
     readonly acceptanceStatementBytes: 1000;
     readonly acceptanceHowBytes: 500;
+    /** A builder's whole proof file, in UTF-8 bytes. */
+    readonly proofPayloadBytes: number;
+    /** A proof criterion's id, in UTF-8 bytes. */
+    readonly proofCriterionIdBytes: 40;
+    /** How a proof criterion was met, in UTF-8 bytes. */
+    readonly proofHowBytes: 500;
+    /** One proof line — a criterion statement, evidence ref, check command or summary, changed path, caveat, or
+     * screenshot path or caption — in UTF-8 bytes. */
+    readonly proofLineBytes: 300;
 };
 export type TextLimitKey = keyof typeof TEXT_LIMITS;
 /** One chat message on each platform. Longer text is split across messages, never cut. Teams: the text one Adaptive Card

package/dist/text-limits.js

@@ -16,6 +16,67 @@ export const TEXT_LIMITS = {
     noteBytes: 16_000,
     /** A flow work zone's instructions; nothing is held back for the card's details (they are attached when long). */
     flowInstructions: 8_000,
+    /** A flow's zones and steps (src/contracts/flow.ts): a zone's name, a step's id as written, and a reference to another step. */
+    flowTitle: 60,
+    flowStepId: 32,
+    flowRef: 60,
+    /** A Message zone's message, or the comment an Update zone leaves. */
+    flowMessage: 1_000,
+    /** Who decides a "Person decides" zone (a sign-in name), and the AI teammate who works a zone, as written. */
+    flowDecider: 64,
+    flowTeammate: 40,
+    /** A Build zone's other project: its path. */
+    flowRepo: 1_000,
+    /** A script's or teammate's answer, a choice's button, a Sort zone's answer and what it means, its question, and a score's level. */
+    flowAnswer: 40,
+    flowChoice: 40,
+    flowSortMeans: 200,
+    flowSortQuestion: 300,
+    flowSortLevel: 120,
+    /** A Web request zone's address, one header's value and the body it sends (an email's body too). */
+    flowUrl: 2_000,
+    flowHeader: 500,
+    flowBody: 8_000,
+    /** An email's recipients and subject. */
+    flowEmailTo: 500,
+    flowEmailSubject: 200,
+    /** A tool zone's tool (MCP server), its function, and the arguments as JSON. */
+    flowToolServer: 64,
+    flowToolName: 100,
+    flowToolArgs: 4_000,
+    /** A wait or reminder said in words ("3 days"), and a time zone's name. */
+    flowDuration: 40,
+    flowTimeZone: 60,
+    /** A flow's name, and a flow file's about line, needs, parameter questions and answers, and scripts. */
+    flowName: 80,
+    flowFileAbout: 600,
+    flowFileNeed: 80,
+    flowParameter: 200,
+    flowScriptAbout: 160,
+    flowScriptBody: 20_000,
+    flowScriptFile: 200,
+    /** A trigger's settings: a button's label and questions, a schedule and the card it makes, GitHub, Linear, webhook and email terms. */
+    triggerButton: 40,
+    triggerQuestion: 80,
+    triggerSchedule: 80,
+    triggerTitle: 200,
+    triggerDescription: 2_000,
+    triggerGithubRepo: 140,
+    triggerLabel: 50,
+    triggerBranch: 100,
+    triggerTeam: 12,
+    triggerState: 40,
+    triggerWebhookTitle: 120,
+    triggerWebhookField: 80,
+    triggerFolder: 100,
+    triggerSender: 300,
+    triggerSubject: 100,
+    /** A schedule's secrets written as one line ("API_KEY, CRM_TOKEN"). */
+    triggerSecrets: 500,
+    /** A card the lead adds to a flow: its title and description; a script it saves inline. */
+    flowCardTitle: 200,
+    flowCardDescription: 4_000,
+    flowScriptInline: 1_600,
     /** A research report's summary, in UTF-8 bytes. */
     reportSummary: 2_500,
     /** What one flow step passes on to the steps after it. */
@@ -36,6 +97,15 @@ export const TEXT_LIMITS = {
     acceptanceIdBytes: 40,
     acceptanceStatementBytes: 1_000,
     acceptanceHowBytes: 500,
+    /** A builder's whole proof file, in UTF-8 bytes. */
+    proofPayloadBytes: 64 * 1024,
+    /** A proof criterion's id, in UTF-8 bytes. */
+    proofCriterionIdBytes: 40,
+    /** How a proof criterion was met, in UTF-8 bytes. */
+    proofHowBytes: 500,
+    /** One proof line — a criterion statement, evidence ref, check command or summary, changed path, caveat, or
+     * screenshot path or caption — in UTF-8 bytes. */
+    proofLineBytes: 300,
 };
 /** One chat message on each platform. Longer text is split across messages, never cut. Teams: the text one Adaptive Card
  * holds, well inside its 28 KB message. */