toolroll 0.9.34 → 0.9.37

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 { FINDING_SEVERITIES } from './contracts/review-findings.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';
+/** 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 && FINDING_SEVERITIES.includes(one.severity));
+    const counts = Object.fromEntries(FINDING_SEVERITIES.map(severity => [severity, findings.filter(one => one.severity === severity).length]));
+    const shown = FINDING_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(FINDING_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 FINDING_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/task-sizing.d.ts

@@ -1,5 +1,6 @@
+import { type SizeAnswer } from "./contracts/task-sizing.js";
 import { run, type ExecResult } from "./exec.js";
-import { type TaskSize, type TaskSizing } from "./phase-routing.js";
+import { type TaskSizing } from "./phase-routing.js";
 import type { Store } from "./store.js";
 /** The classifier's whole budget, from asking to answer. */
 export declare const SIZING_BUDGET_MS = 5000;
@@ -11,11 +12,7 @@ export type SizingInput = {
     outOfScope?: string | null | undefined;
     touches?: readonly string[] | undefined;
 };
-export type SizeAnswer = {
-    size: TaskSize;
-    risky: boolean;
-    reason: string;
-};
+export type { SizeAnswer } from "./contracts/task-sizing.js";
 /** One classifier: null (or a throw) is "no answer"; the signal ends at the budget. */
 export type Sizer = (input: SizingInput, signal: AbortSignal) => Promise<SizeAnswer | null>;
 /** Structural or broad work — the description signal planning has always read. */
@@ -27,26 +24,6 @@ export declare function planningSignals(input: SizingInput): boolean;
 export declare function heuristicSizing(input: SizingInput, why?: string | null): TaskSizing;
 /** What the classifier reads: the task as data, bounded, keys blanked. */
 export declare function sizingText(input: SizingInput): string;
-export declare const SIZING_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly size: {
-            readonly type: "string";
-            readonly enum: readonly ["small", "medium", "large"];
-        };
-        readonly risky: {
-            readonly type: "boolean";
-        };
-        readonly reason: {
-            readonly type: "string";
-            readonly maxLength: 160;
-        };
-    };
-    readonly required: readonly ["size", "risky", "reason"];
-    readonly additionalProperties: false;
-};
-/** Read an answer back: only the three sizes, a boolean, and a short reason. */
-export declare function readSizeAnswer(value: unknown): SizeAnswer | null;
 type CommandRunner = (file: string, args: readonly string[], options: Parameters<typeof run>[2]) => Promise<ExecResult>;
 /** A small Claude model on this computer's sign-in: no tools, no MCP servers, no repository, credential keys stripped.
  * The abort ends it: a late answer never keeps a command (or its process) waiting. */
@@ -75,4 +52,3 @@ export declare function filingSizerInstalled(): boolean;
 export declare function refineFiledSizing(store: Store, taskId: string, input: SizingInput, followPlanning: boolean, clock?: () => Date): Promise<void> | null;
 /** Wait for every classification still in flight (each is bounded by the budget). */
 export declare function settleSizings(): Promise<void>;
-export {};

package/dist/task-sizing.js

@@ -20,12 +20,13 @@ import { randomUUID } from "node:crypto";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { readSizeAnswer, SIZING_MODEL_SCHEMA } from "./contracts/task-sizing.js";
 import { strictJsonParse } from "./converse.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { run, terminateOwnedProcesses } from "./exec.js";
 import { JEV_MODEL, JEV_URL } from "./flow-sort.js";
 import { readProviderKey } from "./keys.js";
-import { isTaskSize } from "./phase-routing.js";
+import {} from "./phase-routing.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
 /** The classifier's whole budget, from asking to answer. */
 export const SIZING_BUDGET_MS = 5_000;
@@ -49,8 +50,11 @@ export function heuristicSizing(input, why = null) {
 const clip = (text, cap) => (text.length <= cap ? text : `${text.slice(0, cap - 1)}…`);
 /** Key-shaped lines never leave the machine. */
 const blank = (text) => redactSecretLines(text, scanForSecrets(text));
-/** One plain line, bounded. */
-const oneLine = (text) => clip(text.replace(/\s+/g, " ").trim(), 160);
+/** An answer read through the contract (src/contracts/task-sizing.ts), its reason on one line; null when it isn't one. */
+function answerOf(value) {
+    const read = readSizeAnswer(value);
+    return read.ok ? read.value : null;
+}
 const SIZE_MEANS = {
     small: "a contained change a fast model can make directly: copy, a style, a config value, one small function, one or two files",
     medium: "ordinary feature or fix work across a few files that benefits from the everyday model",
@@ -66,25 +70,6 @@ export function sizingText(input) {
         ...(input.touches === undefined || input.touches.length === 0 ? [] : [`Paths: ${clip(input.touches.slice(0, 40).join(", "), 1500)}`]),
     ].join("\n");
 }
-export const SIZING_SCHEMA = {
-    type: "object",
-    properties: {
-        size: { type: "string", enum: ["small", "medium", "large"] },
-        risky: { type: "boolean" },
-        reason: { type: "string", maxLength: 160 },
-    },
-    required: ["size", "risky", "reason"],
-    additionalProperties: false,
-};
-/** Read an answer back: only the three sizes, a boolean, and a short reason. */
-export function readSizeAnswer(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return null;
-    const v = value;
-    if (!isTaskSize(v["size"]) || typeof v["risky"] !== "boolean")
-        return null;
-    return { size: v["size"], risky: v["risky"], reason: typeof v["reason"] === "string" ? oneLine(v["reason"]) : "" };
-}
 /** A small Claude model on this computer's sign-in: no tools, no MCP servers, no repository, credential keys stripped.
  * The abort ends it: a late answer never keeps a command (or its process) waiting. */
 export function claudeSizer(runner = run, model = SIZING_CLAUDE_MODEL, budgetMs = SIZING_BUDGET_MS) {
@@ -108,7 +93,7 @@ export function claudeSizer(runner = run, model = SIZING_CLAUDE_MODEL, budgetMs
                 sizingText(input),
             ].join("\n");
             const result = await runner("claude", [
-                "-p", "--output-format", "json", "--json-schema", JSON.stringify(SIZING_SCHEMA), "--safe-mode", "--no-session-persistence", "--tools", "", "--permission-mode", "dontAsk",
+                "-p", "--output-format", "json", "--json-schema", JSON.stringify(SIZING_MODEL_SCHEMA), "--safe-mode", "--no-session-persistence", "--tools", "", "--permission-mode", "dontAsk",
                 "--permission-prompts", "none", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--model", model,
             ], { cwd: dir, stdin: prompt, timeoutMs: budgetMs, maxBuffer: 256 * 1024, omitEnv: ALL_CREDENTIAL_ENV, processGroup: true, owner, beforeSpawn: () => !signal.aborted });
             if (signal.aborted || result.notFound || result.timedOut || result.code !== 0)
@@ -117,7 +102,7 @@ export function claudeSizer(runner = run, model = SIZING_CLAUDE_MODEL, budgetMs
             const body = parsed.ok && typeof parsed.value === "object" && parsed.value !== null && !Array.isArray(parsed.value) ? parsed.value : null;
             if (body === null || body["is_error"] === true || body["subtype"] !== "success")
                 return null;
-            return readSizeAnswer(body["structured_output"]);
+            return answerOf(body["structured_output"]);
         }
         finally {
             signal.removeEventListener("abort", stop);
@@ -149,10 +134,10 @@ export function jevSizer(fetcher, key) {
         const answers = (body["answers"] ?? {});
         const size = answers["size"]?.["choice"];
         const risky = answers["risky"]?.["noul"];
-        if (!isTaskSize(size) || typeof risky !== "number" || !Number.isFinite(risky))
+        if (typeof risky !== "number" || !Number.isFinite(risky))
             return null;
         const sure = answers["size"]?.["confidence"];
-        return { size, risky: risky >= 0.5, reason: typeof sure === "number" && Number.isFinite(sure) ? `Jev is ${Math.round(Math.min(1, Math.max(0, sure)) * 100)}% sure` : "" };
+        return answerOf({ size, risky: risky >= 0.5, reason: typeof sure === "number" && Number.isFinite(sure) ? `Jev is ${Math.round(Math.min(1, Math.max(0, sure)) * 100)}% sure` : "" });
     };
 }
 /** The owner's own classifier: Jev when an OpenRouter key is set up, otherwise Claude on this computer's sign-in. */

package/dist/task-text.d.ts

@@ -3,11 +3,6 @@ export declare const TASK_TEXT_LIMITS: {
     readonly text: 8000;
     readonly textBytes: 32000;
 };
-export declare const TASK_SCOPE_TEXT_SCHEMA: {
-    readonly type: "string";
-    readonly maxLength: 8000;
-    readonly description: `At most ${string} characters (UTF-16 code units) and ${string} UTF-8 bytes; no control or disguised text. Longer text is refused with its length, not cut: shorten it and call again.`;
-};
 export type TaskTextRefusal = {
     ok: false;
     reason: "bad-title" | "bad-goal";

package/dist/task-text.js

@@ -6,10 +6,8 @@
  * runtime with lower limits. */
 import { hasForbiddenControls, hasDisguisedText } from "./decision.js";
 import { TEXT_LIMITS } from "./text-limits.js";
-export const TASK_TEXT_LIMITS = { title: 200, text: TEXT_LIMITS.goal, textBytes: TEXT_LIMITS.goalBytes };
+export const TASK_TEXT_LIMITS = { title: TEXT_LIMITS.taskTitle, text: TEXT_LIMITS.goal, textBytes: TEXT_LIMITS.goalBytes };
 const n = (value) => value.toLocaleString("en-US");
-export const TASK_SCOPE_TEXT_SCHEMA = { type: "string", maxLength: TASK_TEXT_LIMITS.text,
-    description: `At most ${n(TASK_TEXT_LIMITS.text)} characters (UTF-16 code units) and ${n(TASK_TEXT_LIMITS.textBytes)} UTF-8 bytes; no control or disguised text. Longer text is refused with its length, not cut: shorten it and call again.` };
 const dishonest = (text) => hasForbiddenControls(text) || hasDisguisedText(text);
 const overBytes = (text, cap) => Buffer.byteLength(text, "utf8") > cap;
 const BYTE_CAPS = { title: 800, text: TASK_TEXT_LIMITS.textBytes, path: 800 };

package/dist/teammate-question.js

@@ -11,8 +11,10 @@
  * the person it was asked of. Answered anywhere, every button retires.
  */
 import { randomBytes } from "node:crypto";
+import { partContent, savedChatPart } from "./chat-delivery-state.js";
 import { answerTeammateQuestion } from "./teammate-work.js";
 import { labelOf } from "./teammate-admin.js";
+import { telegramButton } from "./contracts/telegram-callback.js";
 /** The key notifyPeople gives a teammate's question: flow-card:<card>:teammate-q:<question>:<person>. */
 export const TEAMMATE_Q_KEY = /^flow-card:[1-9][0-9]{0,14}:teammate-q:([1-9][0-9]{0,14}):/;
 export const IN_WORDS = "Answer in words";
@@ -41,8 +43,8 @@ export function telegramQuestionButtons(store, binding, question, now) {
     const rows = [];
     const options = choices.filter(one => one.choice !== null);
     for (let at = 0; at < options.length; at += 2)
-        rows.push(options.slice(at, at + 2).map(one => ({ text: one.label.slice(0, 60), callback_data: one.token })));
-    rows.push([{ text: choices.at(-1).label, callback_data: choices.at(-1).token }]);
+        rows.push(options.slice(at, at + 2).map(one => telegramButton(one.label.slice(0, 60), one.token)));
+    rows.push([telegramButton(choices.at(-1).label, choices.at(-1).token)]);
     return { keyboard: rows, tokens: choices.map(one => one.token) };
 }
 /** A tapped question button, inside the update's transaction. */
@@ -90,7 +92,7 @@ export function questionParts(store, notification, binding) {
 /** The live buttons on one part, in the order they were minted. */
 export function chatQuestionButtons(state, part, now) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE id=?").get(part);
-    const content = row === undefined ? null : JSON.parse(String(row["payload"]));
+    const content = row === undefined ? null : partContent(String(row["payload"]));
     const labels = new Map((content?.question?.choices ?? []).map(one => [one.choice ?? "", one.label]));
     return state.prepare("SELECT token,choice FROM chat_question_action WHERE part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(part, now.toISOString())
         .map(one => ({ token: String(one.token), label: (labels.get(one.choice ?? "") ?? IN_WORDS).slice(0, 75), words: one.choice === null }));
@@ -98,9 +100,9 @@ export function chatQuestionButtons(state, part, now) {
 /** Show the tapped notice again with the answer, and without its buttons. */
 function repaint(state, part, event, line) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE id=?").get(part);
-    const before = row === undefined ? { text: "" } : JSON.parse(String(row["payload"]));
+    const before = row === undefined ? { text: "" } : partContent(String(row["payload"]));
     const content = { text: `${before.text}\n\n${line}`.slice(0, 3400), edit: event.ts, ...(before.link === undefined ? {} : { link: before.link }), ...(before.channel === undefined ? {} : { channel: before.channel }) };
-    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(JSON.stringify(content), part);
+    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(savedChatPart(content), part);
 }
 /** A tapped question button, inside the action's transaction; false when the token isn't one. */
 export function applyChatQuestionTap(options, event, binding, token, now) {

package/dist/teammate-work.js

@@ -111,9 +111,10 @@ export async function teammateTurn(store, flow, definition, stage, card, mate, n
         store.addTeammateTurn({ teammate: mate.id, card: card.id, model, ok: reply.ok, ms: reply.ok ? reply.ms : Date.now() - asked, costUsd: reply.costUsd ?? null, tokensIn: reply.tokensIn ?? null, tokensOut: reply.tokensOut ?? null }, now);
         if (!reply.ok)
             return { state: "retry", said: reply.said, ...(log.length === 0 ? {} : { log: log.join("\n\n") }) };
-        const answer = readTurn(reply.value, context);
-        if (answer === null)
-            return { state: "retry", said: `${context.name}'s answer wasn't one this zone allows.`, log: [...log, JSON.stringify(reply.value).slice(0, 4000)].join("\n\n") };
+        const read = readTurn(reply.value, context);
+        if (!read.ok)
+            return { state: "retry", said: `${context.name}'s answer wasn't one this zone allows.`, log: [...log, read.issues.map(issue => issue.line).join("\n"), JSON.stringify(reply.value).slice(0, 4000)].join("\n\n") };
+        const answer = read.value;
         const header = `${context.name} (${model}) · ${(reply.ms / 1000).toFixed(1)} s`;
         const over = turnOverruns(answer);
         if (over.length > 0 && !shortened) {
@@ -243,8 +244,11 @@ function carryOut(store, flow, definition, stage, card, mate, context, answer, n
     // route: the answer names where the card goes; its text is what the next zones use.
     const picked = handleAnswers(stage).find(one => one.answer.toLowerCase() === answer.answer.toLowerCase());
     // What the next zones read: whole up to what a step passes on; longer is attached whole to the card, and they read a link to it.
-    if (answer.text !== "")
-        store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: keptWhole(store, flow, card, actor, wholeDraft(answer.text), TEXT_LIMITS.stageOutput, "a step passes on", `What ${label} wrote for the next zones`, now) } }, now);
+    if (answer.text !== "") {
+        const whole = wholeDraft(answer.text);
+        const text = keptWhole(store, flow, card, actor, whole, TEXT_LIMITS.stageOutput, "a step passes on", `What ${label} wrote for the next zones`, now);
+        store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: text }, ...(text === whole ? {} : { attached: { [stage.id]: whole } }) }, now);
+    }
     const said = `Sent “${card.title}” to ${titleOf(picked.to)}${picked.answer === CARRY_ON ? "" : ` (${picked.answer})`}${answer.reason === "" ? "" : `: ${answer.reason}`}`;
     event("handled", said);
     // v96: a zone that answers whoever asked sends what it wrote back to them, under its name.

package/dist/teammates.d.ts

@@ -1,4 +1,6 @@
 import { run, type ExecResult } from "./exec.js";
+import type { ContractResult } from "./contracts/contract.js";
+import { type TurnAnswer } from "./contracts/teammate-turn.js";
 import { type Overrun } from "./text-limits.js";
 export declare const SOUL_CHARS = 12000;
 export type Soul = {
@@ -29,25 +31,11 @@ export declare const TEAMMATE_TEMPLATES: readonly {
     about: string;
     soul: string;
 }[];
-/** What a teammate may do on one turn. A decision zone: approve, send back, or hand it to a person. A work zone: pick where it goes, ask its person, or say it can't. */
-export type TurnAction = "approve" | "send_back" | "hand_off" | "route" | "ask" | "cant" | "use_tool";
-/** v94: "use_tool" asks for one tool call (`tool`: its name, `input`: a JSON object as text); the turn goes on with its answer. */
-export type TurnAnswer = {
-    action: TurnAction;
-    answer: string;
-    text: string;
-    note: string;
-    question: string;
-    options: string[];
-    reason: string;
-    tool: string;
-    input: string;
-    /** v95: one short fact worth keeping for later cards ("": none). */
-    remember: string;
-};
+export type { TurnAction, TurnAnswer } from "./contracts/teammate-turn.js";
 /** Each field's limit, in characters: stated in the prompt before it answers (turnPrompt), and an answer over one is
  * asked once to shorten (teammateTurn); one still over is kept whole, never cut. "text" is what the next zones read;
- * "note" is a decision or send-back note. */
+ * "note" is a decision or send-back note. Not in the turn's schema (src/contracts/teammate-turn.ts): the CLI would
+ * refuse an answer a few characters over one whole. */
 export declare const TURN_LIMITS: {
     readonly answer: 60;
     readonly text: 12000;
@@ -58,49 +46,6 @@ export declare const TURN_LIMITS: {
 };
 /** The fields of an answer over their limits. */
 export declare function turnOverruns(answer: TurnAnswer): Overrun[];
-/** The shape Claude answers in: one flat object (a root union is refused). No length limits here: an answer
- * a few characters over one is refused whole by the CLI, so the limits are TURN_LIMITS, checked after. */
-export declare const TURN_SCHEMA: {
-    readonly type: "object";
-    readonly additionalProperties: false;
-    readonly required: readonly ["action", "answer", "text", "note", "question", "options", "reason", "tool", "input", "remember"];
-    readonly properties: {
-        readonly action: {
-            readonly type: "string";
-            readonly enum: readonly ["approve", "send_back", "hand_off", "route", "ask", "cant", "use_tool"];
-        };
-        readonly answer: {
-            readonly type: "string";
-        };
-        readonly text: {
-            readonly type: "string";
-        };
-        readonly note: {
-            readonly type: "string";
-        };
-        readonly question: {
-            readonly type: "string";
-        };
-        readonly options: {
-            readonly type: "array";
-            readonly items: {
-                readonly type: "string";
-            };
-        };
-        readonly reason: {
-            readonly type: "string";
-        };
-        readonly tool: {
-            readonly type: "string";
-        };
-        readonly input: {
-            readonly type: "string";
-        };
-        readonly remember: {
-            readonly type: "string";
-        };
-    };
-};
 /** Everything one turn is told: the zone, the card as data, and what its people said. */
 export type TurnContext = {
     soul: string;
@@ -165,8 +110,13 @@ export type TurnContext = {
     };
 };
 export declare function turnPrompt(context: TurnContext): string;
-/** A turn's answer, checked against what this zone allows; null when it isn't one. */
-export declare function readTurn(value: unknown, context: Pick<TurnContext, "kind" | "canSendBack" | "answers" | "tools">): TurnAnswer | null;
+/**
+ * A turn's answer, read through its contract (src/contracts/teammate-turn.ts) and then checked against what this zone
+ * allows, each refusal naming its path (`action: "route" isn't one this zone allows`). Text is trimmed and kept whole
+ * (a field over its limit is asked to shorten, turnOverruns); blank options are dropped, and an ask offers at most 4,
+ * each cut to an answer's length, and a tool name is cut to 140, as they always were.
+ */
+export declare function readTurn(value: unknown, context: Pick<TurnContext, "kind" | "canSendBack" | "answers" | "tools">): ContractResult<TurnAnswer>;
 export type TurnRequest = {
     model: string;
     prompt: string;
@@ -190,10 +140,9 @@ export type TurnReply = ({
 export type TurnRunner = (request: TurnRequest) => Promise<TurnReply>;
 export declare const TURN_TIMEOUT_MS = 180000;
 type CommandRunner = (file: string, args: readonly string[], options: Parameters<typeof run>[2]) => Promise<ExecResult>;
-/** The production runner: Claude through this computer's sign-in, answering in TURN_SCHEMA, with no tools, no MCP servers and no repository. */
+/** The production runner: Claude through this computer's sign-in, answering in the turn schema (TURN_MODEL_SCHEMA), with no tools, no MCP servers and no repository. */
 export declare function claudeTurnRunner(runner?: CommandRunner): TurnRunner;
 /** How a teammate is named to people: "Maya · Support". */
 export declare const teammateLabel: (soul: Pick<Soul, "name" | "role">) => string;
 /** How its acts read in a card's history: "Maya (AI)". */
 export declare const teammateActor: (soul: Pick<Soul, "name">) => string;
-export {};