toolroll 0.9.33 → 0.9.36

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/store.d.ts

@@ -6980,6 +6980,8 @@ export declare class Store {
     /** Remember a project was opened. Upsert keeps added_at; recency always moves.
      * A project added for the first time starts on Quick checks. */
     upsertProject(path: string, name: string, now: Date): void;
+    /** A project removed from the lists (project-admission.ts): only its row goes; its tasks, results and settings stay. */
+    forgetProject(path: string): void;
     /** Most recently opened first — the opener page's order. */
     listProjects(): {
         path: string;

package/dist/store.js

@@ -20463,6 +20463,10 @@ export class Store {
                 stampNewProjectLevel(this, path, now);
         });
     }
+    /** A project removed from the lists (project-admission.ts): only its row goes; its tasks, results and settings stay. */
+    forgetProject(path) {
+        this.db.prepare("DELETE FROM project WHERE path = ?").run(path);
+    }
     /** Most recently opened first — the opener page's order. */
     listProjects() {
         return this.db

package/dist/surface.js

@@ -81,8 +81,14 @@ export const COMMAND_GUIDE = [
     operator('conversation read', 'explicitly record your read position at --message within --conversation'),
     operator('conversation follow', 'enable or pause automatic lead summaries with --conversation and --enabled true|false, within the existing paid chat authorization; passive chat --follow only reads updates'),
     operator('conversation stop', 'request stopping the exact --message in --conversation; retain uncertain work until its owner settles it'),
-    operator("repos add", "connect a repository to the installation"),
-    operator("repos remove", "disconnect a repository"),
+    { invocation: "repos add", synopsis: "add a project: a Git repository, in the console at once; the lead adds with its token", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+        positionals: [{ name: "path", required: false, meaning: "the repository (default: the one you are in)" }],
+        flags: [jsonFlag, { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" }],
+        notableReasons: ["not-git", "unavailable", "refused", "locked"] },
+    { invocation: "repos remove", synopsis: "remove a project from the console and the builder; its tasks and results stay saved", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+        positionals: [{ name: "path", required: true, meaning: "the repository" }],
+        flags: [jsonFlag, { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" }],
+        notableReasons: ["refused", "locked"] },
     operator("repos add-from-github", "preview, clone from GitHub, and connect - the console onboarding ceremony as a CLI verb"),
     { invocation: "contract", synopsis: "the machine contract: envelope version + capability tokens; --commands dumps this guide", audience: "agent", agentMayInvoke: true, mutation: "none",
         flags: [jsonFlag, { name: "commands", takesValue: false, meaning: "dump the declared command guide" }] },
@@ -272,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,11 +16,98 @@ 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. */
     readonly stageOutput: 12000;
+    /** The planner's whole handoff file, in UTF-8 bytes. */
+    readonly planPayloadBytes: number;
+    /** The plan document (markdown), in UTF-8 bytes. */
+    readonly planDocumentBytes: number;
+    /** The plan document's Approach section. */
+    readonly planApproach: 2000;
+    /** One Milestones, Dependencies, Risks or Proof item in the plan document. */
+    readonly planItem: 600;
+    /** One path a plan expects to touch. */
+    readonly planTouch: 200;
+    /** A planner's amendment note: why the filed contract must change. */
+    readonly planAmendment: 1000;
+    /** An acceptance criterion's id, statement and advisory how, in UTF-8 bytes. */
+    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
  * holds, well inside its 28 KB message. */
 export declare const PLATFORM_LIMITS: {

package/dist/text-limits.js

@@ -16,10 +16,96 @@ 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. */
     stageOutput: 12_000,
+    /** The planner's whole handoff file, in UTF-8 bytes. */
+    planPayloadBytes: 64 * 1024,
+    /** The plan document (markdown), in UTF-8 bytes. */
+    planDocumentBytes: 16 * 1024,
+    /** The plan document's Approach section. */
+    planApproach: 2_000,
+    /** One Milestones, Dependencies, Risks or Proof item in the plan document. */
+    planItem: 600,
+    /** One path a plan expects to touch. */
+    planTouch: 200,
+    /** A planner's amendment note: why the filed contract must change. */
+    planAmendment: 1_000,
+    /** An acceptance criterion's id, statement and advisory how, in UTF-8 bytes. */
+    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. */

package/dist/verification-evidence.js

@@ -7,6 +7,7 @@ import { createHash } from "node:crypto";
 import { adjudicate } from "./proof.js";
 import { parseReviewContext, reviewContextCustodyProblem } from "./review-context.js";
 import { readVerifiedArtifact, storeEvidence, scanForSecrets, redactSecretLines } from "./evidence.js";
+import { readVerificationReceipt } from "./contracts/verification-receipt.js";
 import { liveQuickCommand, quickVerifyKey, runCheckLevel } from "./check-levels.js";
 export const VERIFICATION_RECEIPT_CAPTURE = "machine verification receipt v1";
 export const REVIEW_GATE_NAME = "REVIEW-VERIFICATION.json";
@@ -18,11 +19,16 @@ export function sealVerificationReceipt(store, root, runId, head, command, resul
     const log = store.artifactsFor(runId).find(a => a.kind === "check-log");
     if (!log)
         throw new Error("Verification receipt requires its retained log");
-    const raw = JSON.stringify({
+    const receipt = {
         version: reusedFrom === undefined ? 1 : 2, run: runId, head, base: source.baseRevision, scopeDigest: source.scopeDigest,
         ...(reusedFrom === undefined ? {} : { reusedFrom, executedHere: false }),
         command, result, log: binding(log),
-    }, null, 1);
+    };
+    const checked = readVerificationReceipt(receipt);
+    if (!checked.ok)
+        throw new Error(`The verification receipt does not match its contract: ${checked.issues.map(issue => issue.line).join("; ")}`);
+    // Sealed in the writer's own key order, as every receipt before the schema: its bytes and digests stay comparable.
+    const raw = JSON.stringify(receipt, null, 1);
     const hits = scanForSecrets(raw);
     storeEvidence(store, root, runId, "structured-output", "verification-receipt.json", Buffer.from(hits.length ? redactSecretLines(raw, hits) : raw), reusedFrom === undefined ? VERIFICATION_RECEIPT_CAPTURE : "machine verification reuse v1", now, { captureStatus: "ok", redacted: hits.length > 0 });
 }
@@ -73,21 +79,27 @@ export function verificationEvidence(store, root, runId) {
         catch {
             return fail("The verification receipt cannot be read.");
         }
-        if ((receipt?.version !== 1 && receipt?.version !== 2) || receipt.run !== runId || receipt.head !== source.headRevision || receipt.base !== source.baseRevision || receipt.scopeDigest !== source.scopeDigest || JSON.stringify(receipt.command) !== JSON.stringify(command) || JSON.stringify(receipt.log) !== JSON.stringify(binding(log)))
+        // The schema checks the shape; the bindings below check it against the store. The receipt itself stays exactly
+        // as sealed: its bytes are this view's bytes and part of its digest.
+        const read = readVerificationReceipt(receipt);
+        if (!read.ok)
+            return fail(`The verification receipt is malformed: ${read.issues.map(issue => issue.line).join("; ")}`);
+        const checked = read.value;
+        if (checked.run !== runId || checked.head !== source.headRevision || checked.base !== source.baseRevision || checked.scopeDigest !== source.scopeDigest || JSON.stringify(receipt.command) !== JSON.stringify(command) || JSON.stringify(receipt.log) !== JSON.stringify(binding(log)))
             return fail("The candidate, approved command or retained log changed since verification.");
         if (receipt.version === 2) {
             try {
                 const brief = observationBrief(store, root, source.taskRef);
-                const reused = receipt.reusedFrom;
+                const reused = checked.reusedFrom;
                 if (!brief || !readObservationEvidence(store, root, runId) || !reused || reused.run !== brief.sourceRun || reused.run >= runId || reused.digest !== brief.gateDigest ||
-                    source.baseRevision !== brief.head || source.headRevision !== brief.head || receipt.executedHere !== false)
+                    source.baseRevision !== brief.head || source.headRevision !== brief.head || checked.executedHere !== false)
                     return fail("The reused gate is not bound to an unchanged observation follow-up.");
                 const original = verificationEvidence(store, root, reused.run);
                 if (!original.ok || !original.bytes || original.digest !== reused.digest)
                     return fail("The original passing gate no longer verifies.");
                 const previous = JSON.parse(original.bytes);
                 const originalLog = store.getArtifact(previous.log.artifactId);
-                if (previous.head !== source.headRevision || previous.result.exitCode !== 0 || JSON.stringify(previous.command) !== JSON.stringify(command) ||
+                if (previous.head !== source.headRevision || !("exitCode" in previous.result) || previous.result.exitCode !== 0 || JSON.stringify(previous.command) !== JSON.stringify(command) ||
                     JSON.stringify(previous.result) !== JSON.stringify(receipt.result) || originalLog?.sha256 !== log.sha256 ||
                     originalLog.bytesOriginal !== log.bytesOriginal || originalLog.redacted !== log.redacted || originalLog.truncated !== log.truncated)
                     return fail("The reused gate's candidate, command, result or copied log changed.");
@@ -96,10 +108,10 @@ export function verificationEvidence(store, root, runId) {
                 return fail("The reused gate or its observations no longer verify.");
             }
         }
-        else if (receipt.reusedFrom !== undefined)
+        else if (checked.reusedFrom !== undefined || checked.executedHere !== undefined)
             return fail("The gate reuse receipt has an unsupported version.");
-        const result = receipt.result;
-        if (result?.configured !== true || typeof result.ran !== "boolean" || (result.ran ? !Number.isInteger(result.exitCode) || result.exitCode < 0 || result.exitCode > 255 : result.attemptFailed !== true))
+        const result = checked.result;
+        if (!result.configured)
             return fail("The machine verification result is malformed.");
         if (verified && (!result.ran || result.exitCode !== 0))
             return fail("The passing machine verdict disagrees with its verification receipt.");
@@ -142,8 +154,8 @@ function sealedCommandKey(root, receipts) {
     if (!sealed.ok)
         return null;
     try {
-        const repo = JSON.parse(sealed.content.toString("utf8")).command?.repo;
-        return typeof repo === "string" ? repo : null;
+        const read = readVerificationReceipt(JSON.parse(sealed.content.toString("utf8")));
+        return read.ok ? read.value.command.repo : null;
     }
     catch {
         return null;
@@ -244,7 +256,7 @@ export function reuseObservationVerification(store, root, runId, now) {
     if (!original.ok || !original.bytes || original.digest !== brief.gateDigest)
         throw Error("The original passing gate is unavailable or changed.");
     const receipt = JSON.parse(original.bytes), log = store.getArtifact(receipt.log.artifactId);
-    if (!log || receipt.head !== brief.head || receipt.result?.ran !== true || receipt.result.exitCode !== 0)
+    if (!log || receipt.head !== brief.head || !("ran" in receipt.result) || receipt.result.ran !== true || receipt.result.exitCode !== 0)
         throw Error("The source gate did not pass this candidate.");
     const read = readVerifiedArtifact(root, log);
     if (!read.ok)

package/dist/when-html.d.ts

@@ -10,6 +10,8 @@ export declare function deadlineWords(deadline: {
     at: string;
     label: string;
 }, now?: Date, zone?: string): string;
+/** How long ago, in one short mark: "now", "4m", "2h", "3d". A future stamp reads "now"; an unreadable one, "". */
+export declare function shortAge(iso: string, now?: Date): string;
 /** The exact minute in `zone` ("2026-09-30 16:39", with " UTC" when it is UTC): a time's title, one hover away. */
 export declare function fullWhen(iso: string, zone?: string): string;
 /** Every server-rendered stamp (`whenHtml`'s `<time data-when>`) inside `root`, reworded by the one formatter in the