toolroll 0.9.26 → 0.9.28

package/dist/flow-engine.js

@@ -8,14 +8,15 @@
 import { assignmentOf } from "./assignment.js";
 import { filerFor } from "./approval-policy.js";
 import { diagnoseTaskDispatch } from "./dispatch.js";
-import { deciderOf, durationWords, fillFlowText, fitFlowText, flowWorkTemplate, validateFlowDefinition, withinHours } from "./flows.js";
+import { passOn, TEXT_LIMITS } from "./text-limits.js";
+import { deciderOf, durationWords, fillFlowText, flowGoal, flowValueLabel, flowWorkTemplate, validateFlowDefinition, withinHours } from "./flows.js";
 import { reportFillIns, reportSummaryFor } from "./report-summary.js";
 import { fileTaskProposal } from "./proposal.js";
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
 import { readVerifiedReport, scanForSecrets } from "./evidence.js";
 import { cardFollowers, notifyPeople } from "./flow-people.js";
-import { keptDraft } from "./flow-draft.js";
+import { DRAFT_CHARS, keptDraft } from "./flow-draft.js";
 import { chooseStep, flowPersonOf, sendStep } from "./flow-send.js";
 import { parseSoul, teammateLabel } from "./teammates.js";
 /** The flow's drawing, or null when it can't be read (the card then says so and waits). */
@@ -207,7 +208,7 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
                     dedupeKey: `flow-decide:${card.id}:${card.entry}`, kind: "flow-decision", pushClass: "attention", ...(decider === null ? {} : { recipient: decider }),
                     subject: (handoff !== null ? `${handoff.label}: ${card.title} needs ${decider === null ? "a decision" : `${decider}'s decision`}` : `${flow.name}: ${card.title} needs ${decider === null ? "a decision" : `${decider}'s decision`}`).slice(0, 200),
                     body: `${handoff === null ? "" : `${handoff.said}\n\n`}${text === undefined ? `${stage.title}: approve it, or send it back with a note.`
-                        : `${stage.title}: approve this draft to send it as written, edit it, or send it back with a note.\n\n${text}`}`.slice(0, 4000),
+                        : `${stage.title}: approve this draft to send it as written, edit it, or send it back with a note.\n\n${text}`}`,
                     link: flowCardHref(flow.id, card.id), source: { project: flow.repo },
                 }, now);
                 store.updateFlowCard(card.id, { waiting: `Waiting for ${who} to approve or send it back` }, now);
@@ -247,9 +248,9 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
         // Waiting cards try again every pass, so a cause that's fixed (a shorter zone, a freed backlog) files the work then.
         const wait = (why) => { const waiting = `Couldn't file the work: ${why} It tries again on the next pass.`; if (card.waiting !== waiting)
             store.updateFlowCard(card.id, { waiting }, now); };
-        // The goal fits a task: the zone's words whole, long filled-in values (a script's output) cut in the middle.
-        // The agent is given them in full (flowGoalCuts).
-        const goal = fitFlowText(flowWorkTemplate(stage.instructions ?? card.title, card), card);
+        // The goal fits a task: the zone's words whole and the card's details whole; a value too long for the goal (a
+        // script's output) is attached instead, and the agent is given it in full (flowGoalCuts). Nothing is cut.
+        const goal = flowGoal(stage.instructions ?? card.title, card, id => titleIn(definition, id));
         if (goal === null) {
             wait(`${stage.title}'s instructions are too long for a task. Open the flow and shorten them.`);
             return;
@@ -313,7 +314,8 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
         if (stage.kind === "report") {
             const ref = store.lookupRef(current);
             const summary = ref === null ? null : reportSummaryFor(store, options.evidenceRoot, ref.id);
-            outputs[stage.id] = summary !== null && "summary" in summary ? summary.summary.slice(0, 6000) : "The report is ready on its task.";
+            // The summary whole (a report's summary is within TEXT_LIMITS.reportSummary bytes; an older, longer one is linked).
+            outputs[stage.id] = summary !== null && "summary" in summary ? passOn(summary.summary, TEXT_LIMITS.stageOutput, { label: `task ${current}`, href: null }).text : "The report is ready on its task.";
             // {{stage.<id>.items}} and {{stage.<id>.report}}: what it found and the whole report, for the zones after it.
             // A visit's report replaces the last visit's, so nothing stale is left behind.
             const view = ref === null || options.evidenceRoot === undefined ? null : readVerifiedReport(store, options.evidenceRoot, ref.id);
@@ -353,6 +355,9 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
 /** What a flow task's goal had to cut, whole, for the agent doing it: each value its zone fills in from the card that the
  * goal doesn't hold in full. Empty when the task didn't come from a flow card or nothing was cut. Script output and
  * card text can come from outside, so the brief quotes these as untrusted data. */
+/** The most of one attached value the agent's brief carries: more than any card value holds (a whole report is at most
+ * 64 KiB), so in practice an attachment is never shortened. */
+const FLOW_ATTACHED_LIMIT = 128_000;
 export function flowGoalCuts(store, taskId, goal) {
     try {
         return goalCuts(store, taskId, goal);
@@ -369,7 +374,6 @@ function goalCuts(store, taskId, goal) {
     const stage = definition?.stages.find(one => one.id === card.stage);
     if (card === null || definition == null || stage === undefined || (stage.kind !== "task" && stage.kind !== "report"))
         return [];
-    const labels = { "card.title": "The card's title", "card.description": "The card's description", note: "The note it was sent back with" };
     const cuts = [];
     const seen = new Set();
     for (const match of flowWorkTemplate(stage.instructions ?? card.title, card).matchAll(/\{\{\s*(card\.title|card\.description|note|stage\.([a-z0-9-]+)(?:\.(items|report))?)\s*\}\}/g)) {
@@ -379,8 +383,7 @@ function goalCuts(store, taskId, goal) {
         const text = fillFlowText(`{{${match[1]}}}`, card);
         if (text === "" || goal.includes(text))
             continue;
-        const part = match[3] === "items" ? "listed" : match[3] === "report" ? "reported in full" : "found";
-        cuts.push({ label: labels[match[1]] ?? `What ${titleIn(definition, match[2])} ${part}`, text: text.slice(0, 50_000) });
+        cuts.push({ label: flowValueLabel(match[1], id => titleIn(definition, id)), text: text.slice(0, FLOW_ATTACHED_LIMIT) });
     }
     return cuts;
 }
@@ -488,6 +491,10 @@ export function decideFlowCard(store, input, now) {
     if (input.decision === "approve") {
         // An edited draft replaces the one Claude wrote, so the steps after this send what the person approved.
         const draft = draftFor(definition, stage);
+        // A person's edit over the draft limit is refused with it, never cut. (A teammate's was asked once to shorten and is kept whole.)
+        if (draft !== null && input.teammate === undefined && typeof input.draft === "string" && input.draft.trim().length > DRAFT_CHARS) {
+            return { ok: false, message: `Keep the draft to ${DRAFT_CHARS.toLocaleString("en-US")} characters; this is ${input.draft.trim().length.toLocaleString("en-US")}.` };
+        }
         if (draft !== null && typeof input.draft === "string" && input.draft.trim() !== "" && input.draft.trim() !== card.outputs[draft.id]?.trim()) {
             store.updateFlowCard(card.id, { outputs: { ...card.outputs, [draft.id]: keptDraft(input.draft) } }, now);
             store.addFlowComment({ card: card.id, author: input.actor, body: "Edited the draft before approving it.", mentions: [] }, now);

package/dist/flow-items.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A research report's items in a flow's message (flow-send.ts): after a report step, each item is listed under the
+ * summary, numbered — its title in bold, its why in plain lines, and its link named by its source ("Mobbin", or the
+ * site's name). Each screenshot of an item is captioned with the same number, its title and how it plugs in
+ * (result-shots.ts), so "2." in the album is item 2 in the text.
+ *
+ * The message is written in reply-shape.ts's canonical form (`**bold**`, `[label](url)`), which every channel renders
+ * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
+ * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
+ */
+export type FlowSendItem = {
+    title: string;
+    why: string;
+    url: string;
+    /** Where the link goes, by name: "Mobbin", "Linear", "Apple". */
+    source: string;
+    /** One line: how it plugs in (from the why, else the image's own caption). */
+    plug: string;
+    /** The item's screenshot (its evidence id in the report's run), when it has one. */
+    shot: number | null;
+};
+/** A link's source by name: a few known sites as they write themselves, else the site's own name from its address. */
+export declare function itemSource(url: string): string;
+/** A why as plain lines: its own lines, or "the pattern; why it fits us; how it plugs in" one to a line. */
+export declare function whyLines(why: string): string[];
+/** How an item plugs in, in one line: the why's last line when it has several, else the image's caption, else the why. */
+export declare function itemPlug(why: string, imageCaption: string | null): string;
+/** A screenshot's caption: its item's number, title and how it plugs in. */
+export declare function itemCaption(number: number, item: Pick<FlowSendItem, "title" | "plug">): string;
+export type FlowMessage = {
+    head: string;
+    summary: string;
+    items: readonly FlowSendItem[];
+    tail: readonly string[];
+};
+/** The message's own words through a channel's cleaner — head, summary, each title and why, and tail — before it is fitted. */
+export declare function cleanFlowMessage(message: FlowMessage, clean: (text: string) => string): FlowMessage;
+/**
+ * The message in canonical form, as parts within `limit` as `measure` counts each once the channel renders it: one
+ * whole part when it fits; else every why shortened to the same length; then the summary; then the titles. When the
+ * head, links and tail alone are over the limit, the whole message goes in several parts instead, split between
+ * blocks (else between lines). Every link stays.
+ */
+export declare function fitFlowMessage(message: FlowMessage, limit: number, measure: (shaped: string) => number): string[];
+/** Items read back from a kept content; anything malformed is left out. */
+export declare function readFlowItems(raw: unknown): FlowSendItem[];

package/dist/flow-items.js

@@ -0,0 +1,152 @@
+/**
+ * A research report's items in a flow's message (flow-send.ts): after a report step, each item is listed under the
+ * summary, numbered — its title in bold, its why in plain lines, and its link named by its source ("Mobbin", or the
+ * site's name). Each screenshot of an item is captioned with the same number, its title and how it plugs in
+ * (result-shots.ts), so "2." in the album is item 2 in the text.
+ *
+ * The message is written in reply-shape.ts's canonical form (`**bold**`, `[label](url)`), which every channel renders
+ * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
+ * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
+ */
+const PLUG_CHARS = 160;
+const NAMES = {
+    "mobbin.com": "Mobbin", "github.com": "GitHub", "figma.com": "Figma", "dribbble.com": "Dribbble", "behance.net": "Behance",
+    "youtube.com": "YouTube", "linkedin.com": "LinkedIn", "producthunt.com": "Product Hunt", "pageflows.com": "Page Flows",
+};
+const cutTo = (text, cap) => cap <= 0 ? "" : text.length <= cap ? text : `${text.slice(0, Math.max(0, cap - 1)).trimEnd()}…`;
+const oneLine = (text) => text.replace(/\s+/g, " ").trim();
+/** A link's source by name: a few known sites as they write themselves, else the site's own name from its address. */
+export function itemSource(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase().replace(/^www\./, "");
+    }
+    catch {
+        return "Link";
+    }
+    for (const [site, name] of Object.entries(NAMES))
+        if (host === site || host.endsWith(`.${site}`))
+            return name;
+    const labels = host.split(".");
+    if (labels.length < 2 || /^[0-9.]+$/.test(host) || host.includes(":"))
+        return host;
+    // "bbc.co.uk" is the BBC's; "developer.apple.com" is Apple's.
+    const short = labels.length >= 3 && labels[labels.length - 1].length === 2 && labels[labels.length - 2].length <= 3;
+    const name = labels[labels.length - (short ? 3 : 2)];
+    return name === "" ? host : `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+}
+/** A why as plain lines: its own lines, or "the pattern; why it fits us; how it plugs in" one to a line. */
+export function whyLines(why) {
+    const lines = why.split(/\n+/).map(one => one.trim()).filter(one => one !== "");
+    if (lines.length !== 1)
+        return lines;
+    const parts = lines[0].split(/;\s+/).map(one => one.trim()).filter(one => one !== "");
+    return parts.length >= 2 && parts.length <= 4 ? parts.map(one => `${one.charAt(0).toUpperCase()}${one.slice(1)}`) : lines;
+}
+/** How an item plugs in, in one line: the why's last line when it has several, else the image's caption, else the why. */
+export function itemPlug(why, imageCaption) {
+    const lines = whyLines(why);
+    const words = lines.length >= 2 ? lines[lines.length - 1] : imageCaption !== null && imageCaption.trim() !== "" ? imageCaption : lines.join(" ");
+    return cutTo(oneLine(words), PLUG_CHARS);
+}
+/** A screenshot's caption: its item's number, title and how it plugs in. */
+export function itemCaption(number, item) {
+    return item.plug === "" ? `${number}. ${item.title}` : `${number}. ${item.title} · ${item.plug}`;
+}
+/** Plain words can't become bold or a link by accident. */
+const inert = (text) => text.replace(/\*\*/g, "*").replace(/\]\(/g, "] (");
+/** A link the canonical form keeps whole: the characters it stops at are written percent-encoded, as browsers read them. */
+const linkable = (url) => url.replace(/[()[\]<>"'`\s]/g, char => `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+/** The message's own words through a channel's cleaner — head, summary, each title and why, and tail — before it is fitted. */
+export function cleanFlowMessage(message, clean) {
+    return { head: clean(message.head), summary: clean(message.summary), items: message.items.map(item => ({ ...item, title: clean(item.title), why: clean(item.why) })),
+        tail: message.tail.map(clean) };
+}
+function blocks(message, whyCap, summaryCap, titleCap) {
+    const items = message.items.map((item, index) => {
+        const title = cutTo(oneLine(item.title).replace(/\*/g, ""), titleCap);
+        const why = cutTo(whyLines(item.why).join("\n"), whyCap);
+        return [`${index + 1}. ${title === "" ? "" : `**${title}**`}`.trimEnd(), ...(why === "" ? [] : [inert(why)]), `[${item.source.replace(/[[\]]/g, "")}](${linkable(item.url)})`].join("\n");
+    });
+    return [inert(message.head), inert(cutTo(message.summary, summaryCap)), ...items, ...message.tail.map(inert)].filter(one => one.trim() !== "");
+}
+const compose = (message, whyCap, summaryCap, titleCap) => blocks(message, whyCap, summaryCap, titleCap).join("\n\n");
+/** The largest n in [0, high] that fits, or -1. */
+function largest(high, fits) {
+    if (!fits(0))
+        return -1;
+    let low = 0;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (fits(mid))
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low;
+}
+/** Whole pieces packed into as few parts as fit, joined by `glue`; a piece too long alone is broken by `smaller`. */
+function pack(pieces, glue, fits, smaller) {
+    const parts = [];
+    let open = "";
+    for (const piece of pieces.flatMap(one => fits(one) ? [one] : smaller(one))) {
+        const joined = open === "" ? piece : `${open}${glue}${piece}`;
+        if (open === "" || fits(joined))
+            open = joined;
+        else {
+            parts.push(open);
+            open = piece;
+        }
+    }
+    return open === "" ? parts : [...parts, open];
+}
+/** A line longer than a whole part, in the longest prefixes that fit (never splitting a surrogate pair). */
+function chop(line, fits) {
+    const out = [];
+    for (let rest = line; rest !== "";) {
+        let at = Math.max(1, largest(rest.length, n => fits(rest.slice(0, n))));
+        if (at < rest.length && /[\uD800-\uDBFF]/.test(rest[at - 1]))
+            at = at > 1 ? at - 1 : at + 1;
+        out.push(rest.slice(0, at));
+        rest = rest.slice(at);
+    }
+    return out;
+}
+/**
+ * The message in canonical form, as parts within `limit` as `measure` counts each once the channel renders it: one
+ * whole part when it fits; else every why shortened to the same length; then the summary; then the titles. When the
+ * head, links and tail alone are over the limit, the whole message goes in several parts instead, split between
+ * blocks (else between lines). Every link stays.
+ */
+export function fitFlowMessage(message, limit, measure) {
+    const fits = (text) => measure(text) <= limit;
+    const full = compose(message, Infinity, Infinity, Infinity);
+    if (fits(full))
+        return [full];
+    const longest = Math.max(0, ...message.items.map(one => whyLines(one.why).join("\n").length));
+    const why = largest(longest, n => fits(compose(message, n, Infinity, Infinity)));
+    if (why >= 0)
+        return [compose(message, why, Infinity, Infinity)];
+    const summary = largest(message.summary.length, n => fits(compose(message, 0, n, Infinity)));
+    if (summary >= 0)
+        return [compose(message, 0, summary, Infinity)];
+    const title = largest(Math.max(0, ...message.items.map(one => one.title.length)), n => fits(compose(message, 0, 0, n)));
+    if (title >= 0)
+        return [compose(message, 0, 0, title)];
+    return pack(blocks(message, Infinity, Infinity, Infinity), "\n\n", fits, block => pack(block.split("\n"), "\n", fits, line => chop(line, fits)));
+}
+/** Items read back from a kept content; anything malformed is left out. */
+export function readFlowItems(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((one) => {
+        if (typeof one !== "object" || one === null)
+            return [];
+        const item = one;
+        const text = (key) => typeof item[key] === "string" ? item[key] : null;
+        const [title, why, url, source, plug] = [text("title"), text("why"), text("url"), text("source"), text("plug")];
+        if (title === null || why === null || url === null || source === null || plug === null || !/^https?:\/\//.test(url))
+            return [];
+        return [{ title, why, url, source, plug, shot: typeof item["shot"] === "number" && Number.isSafeInteger(item["shot"]) ? item["shot"] : null }];
+    });
+}

package/dist/flow-people.d.ts

@@ -10,7 +10,6 @@ type CardEvent = {
     body: string;
     attention?: boolean;
 };
-/** One notification per person, to that person only. The actor never notifies themself. */
 export declare function notifyPeople(store: Store, card: FlowCardRow, people: Iterable<string>, actor: string | null, event: CardEvent, now: Date): string[];
 /** Who follows a card: its owner and its watchers. */
 export declare function cardFollowers(store: Store, card: FlowCardRow): string[];

package/dist/flow-people.js

@@ -22,6 +22,14 @@ export function mentionsIn(body, people) {
     return found;
 }
 /** One notification per person, to that person only. The actor never notifies themself. */
+/** A notice's body: whole up to 2,000 characters; longer, its start and a line saying the rest is on the card it links. */
+const NOTICE_CHARS = 2000;
+function noticeBody(body) {
+    if (body.length <= NOTICE_CHARS)
+        return body;
+    const mark = "\n… (the rest is on the card)";
+    return `${body.slice(0, NOTICE_CHARS - mark.length)}${mark}`;
+}
 export function notifyPeople(store, card, people, actor, event, now) {
     const flow = store.getFlow(card.flow);
     if (flow === null)
@@ -33,7 +41,7 @@ export function notifyPeople(store, card, people, actor, event, now) {
         const queued = store.enqueueNotification({
             dedupeKey: `flow-card:${card.id}:${event.key}:${person}`, kind: "flow-card", recipient: person,
             ...(event.attention === true ? { pushClass: "attention" } : {}),
-            subject: `${flow.name}: ${event.subject}`.slice(0, 200), body: event.body.slice(0, 2000), link: flowCardHref(flow.id, card.id), source: { project: flow.repo },
+            subject: `${flow.name}: ${event.subject}`.slice(0, 200), body: noticeBody(event.body), link: flowCardHref(flow.id, card.id), source: { project: flow.repo },
         }, now);
         if (queued)
             sent.push(person);

package/dist/flow-send.d.ts

@@ -1,4 +1,5 @@
 import { type FlowDecision } from "./flow-engine.js";
+import { type FlowSendItem } from "./flow-items.js";
 import { type FlowDefinition, type FlowStage } from "./flows.js";
 import { type FlowCardRow, type FlowRow, type Store } from "./store.js";
 /** The notice a "Send to me" visit sends: `flow-send:<card>:<entry>`. */
@@ -26,6 +27,8 @@ export type FlowSendContent = {
         taskId: string;
         run: number;
     } | null;
+    /** After research: the report's items, numbered in this order in every message and screenshot caption (flow-items.ts). */
+    items?: FlowSendItem[];
     /** choose: the options as they were offered, and whether a reply is taken. */
     options?: {
         choice: number;
@@ -52,6 +55,8 @@ export declare function sendStep(store: Store, flow: FlowRow, definition: FlowDe
 export declare function chooseStep(store: Store, flow: FlowRow, definition: FlowDefinition, stage: FlowStage, card: FlowCardRow, now: Date, evidenceRoot?: string): void;
 /** The words above a choice's buttons: what was done, then what to do. */
 export declare function flowChooseBody(content: FlowSendContent): string;
+/** What a sent visit's message ends with, after its summary (and items): its pull request, and for a choice what to do. */
+export declare function flowSendTail(content: FlowSendContent): string[];
 export type FlowChoiceVisit = {
     card: FlowCardRow;
     flow: FlowRow;

package/dist/flow-send.js

@@ -14,9 +14,12 @@
  * Deterministic and model-free, in the worker's flow pass.
  */
 import { assignmentOf } from "./assignment.js";
+import { TEXT_LIMITS } from "./text-limits.js";
 import { withActor } from "./actor.js";
 import { flowCardHref, flowDefinitionOf, revisionWithNote } from "./flow-engine.js";
+import { itemPlug, itemSource, readFlowItems } from "./flow-items.js";
 import { notifyPeople } from "./flow-people.js";
+import { readVerifiedReport } from "./evidence.js";
 import { FLOW_END, replyTarget } from "./flows.js";
 import { FLOW_SHOTS_KIND } from "./store.js";
 /** The notice a "Send to me" visit sends: `flow-send:<card>:<entry>`. */
@@ -63,6 +66,18 @@ function reportShotsOf(store, taskId) {
     const run = store.runsFor(ref.id).find(one => one.finishedAt !== null && one.role === "scout");
     return run !== undefined && run.outcome === "built" && store.artifactsFor(run.id).some(one => one.kind === "screenshot") ? { taskId, run: run.id } : null;
 }
+/** A research task's report items, each with its source, how it plugs in, and its screenshot from that run. */
+function reportItemsOf(store, taskId, shots, evidenceRoot) {
+    const ref = store.lookupRef(taskId);
+    const view = ref === null || evidenceRoot === undefined ? null : readVerifiedReport(store, evidenceRoot, ref.id);
+    if (view === null || !view.ok)
+        return [];
+    return view.report.items.map(item => {
+        const image = item.image === null ? undefined : view.report.images.find(one => one.file === item.image);
+        const shot = item.image === null || shots?.run !== view.run ? null : view.shots.find(one => one.file === item.image)?.artifactId ?? null;
+        return { title: plain(item.title), why: plain(item.why), url: item.url, source: itemSource(item.url), plug: plain(itemPlug(item.why, image?.caption ?? null)), shot };
+    });
+}
 /** What a visit sends its person, worked out from the card as it is now. */
 export function flowSendContent(store, flow, definition, stage, card, now, evidenceRoot) {
     const before = stepBefore(store, definition, card);
@@ -96,10 +111,12 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
         links.push({ label: "Report", path: `/t/${encodeURIComponent(report)}` });
     links.push({ label: "Card", path: flowCardHref(flow.id, card.id) });
     const options = stage.kind === "choose" ? (stage.options ?? []).map((one, choice) => ({ choice, label: one.label })) : undefined;
+    // After research, its own screenshots are what that step produced; otherwise the build's.
+    const shots = (report === null ? null : reportShotsOf(store, report)) ?? result?.shots ?? null;
+    const items = report === null ? [] : reportItemsOf(store, report, shots?.taskId === report ? shots : null, evidenceRoot);
     return {
         title: cut(plain(before === null ? card.title : `${card.title} · ${before.title}`), 200), ...(before === null ? {} : { from: before.title }),
-        // After research, its own screenshots are what that step produced; otherwise the build's.
-        summary: plain(lines.join("\n\n")), links, shots: (report === null ? null : reportShotsOf(store, report)) ?? result?.shots ?? null,
+        summary: plain(lines.join("\n\n")), links, shots, ...(items.length === 0 ? {} : { items }),
         ...(options === undefined ? {} : { options, reply: replyTarget(stage) !== null }),
     };
 }
@@ -107,7 +124,13 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
 export function readFlowSend(json) {
     try {
         const raw = JSON.parse(json);
-        return typeof raw.title === "string" && typeof raw.summary === "string" && Array.isArray(raw.links) ? raw : null;
+        if (typeof raw.title !== "string" || typeof raw.summary !== "string" || !Array.isArray(raw.links))
+            return null;
+        if (raw.items === undefined)
+            return raw;
+        const items = readFlowItems(raw.items);
+        const { items: _, ...rest } = raw;
+        return items.length === 0 ? rest : { ...rest, items };
     }
     catch {
         return null;
@@ -168,8 +191,12 @@ export function chooseStep(store, flow, definition, stage, card, now, evidenceRo
 }
 /** The words above a choice's buttons: what was done, then what to do. */
 export function flowChooseBody(content) {
+    return [content.summary, ...flowSendTail(content)].join("\n\n");
+}
+/** What a sent visit's message ends with, after its summary (and items): its pull request, and for a choice what to do. */
+export function flowSendTail(content) {
     const pull = content.links.find((one) => "url" in one);
-    return [content.summary, ...(pull === undefined ? [] : [`${pull.label}: ${pull.url}`]), content.reply === true ? `Choose one. ${REPLY_ASK}` : "Choose one."].join("\n\n");
+    return [...(pull === undefined ? [] : [`${pull.label}: ${pull.url}`]), ...(content.options === undefined ? [] : [content.reply === true ? `Choose one. ${REPLY_ASK}` : "Choose one."])];
 }
 /** The card, if it is still at that visit, waiting for its person's choice. */
 export function flowChoiceAt(store, cardId, entry) {
@@ -240,8 +267,8 @@ export function chooseFlowCard(store, input, now) {
         return { ok: false, message: "Where replies go changed since; nothing was changed." };
     if (note === "")
         return { ok: false, message: "Say what you'd change." };
-    if (note.length > 2000)
-        return { ok: false, message: "Keep it under 2,000 characters." };
+    if (note.length > TEXT_LIMITS.note)
+        return { ok: false, message: `Keep it to ${TEXT_LIMITS.note.toLocaleString("en-US")} characters; this is ${note.length.toLocaleString("en-US")}.` };
     const revision = revisionWithNote(store, card, definition.stages.find(one => one.id === target), note, input.actor, input.repos, input.evidenceRoot, now);
     const moved = store.transact(() => {
         if (!store.moveFlowCard(card.id, { to: target, outcome: "sent-back", actor: input.actor, note, ...(revision === null ? {} : { task: revision }), expectEntry: card.entry }, now))

package/dist/flow-steps.js

@@ -27,12 +27,13 @@ import { join } from "node:path";
 import { approvedCommandShell, redactSecretAssignments, SETUP_ENV_ALLOWLIST, SETUP_ENV_DENYLIST } from "./builder.js";
 import { assignmentOf } from "./assignment.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
-import { flowDefinitionOf } from "./flow-engine.js";
+import { flowCardHref, flowDefinitionOf } from "./flow-engine.js";
 import { cardFollowers, notifyPeople } from "./flow-people.js";
 import { LINEAR_URL, readLinearKey } from "./flow-triggers.js";
 import { cardEmailOf, fillFlowText } from "./flows.js";
 import { JEV_MODEL, askJev, readJevAnswers, sortLog, sortRequest, sortState, sortWords } from "./flow-sort.js";
-import { claudeDraftRunner, DRAFT_TIMEOUT, draftPrompt, keptDraft } from "./flow-draft.js";
+import { claudeDraftRunner, DRAFT_CHARS, DRAFT_TIMEOUT, draftPrompt, wholeDraft } from "./flow-draft.js";
+import { overruns, passOn, TEXT_LIMITS, writeWithin } from "./text-limits.js";
 import { readFlowSecrets, sendingReady, runRequest, sendEmail, toolWaiting, useTool } from "./flow-actions.js";
 import { cleanFolder, runCode } from "./flow-code.js";
 import { agentFence } from "./agent-fence.js";
@@ -246,7 +247,13 @@ function settle(store, definition, stage, card, outcome, now, durationMs) {
         outcome = { state: "failed", said: `${outcome.said} It didn't work after three tries.` };
     }
     store.finishFlowStep(card.id, card.entry, { state: outcome.state === "passed" ? "passed" : "failed", result: outcome.said, ...kept }, now);
-    store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: outcome.output ?? outcome.said }, waiting: null }, now);
+    // What the steps after it read: whole up to TEXT_LIMITS.stageOutput; longer is attached whole to the card's discussion,
+    // and they read a link to it. Never cut.
+    const whole = outcome.output ?? outcome.said;
+    const passed = passOn(whole, TEXT_LIMITS.stageOutput, { label: "the card's discussion", href: flowCardHref(card.flow, card.id) });
+    if (passed.kept)
+        store.addFlowComment({ card: card.id, author: "flow", body: `What ${stage.title} produced, in full (${whole.length.toLocaleString("en-US")} characters):\n\n${whole}`, mentions: [] }, now);
+    store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: passed.text }, waiting: null }, now);
     const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? "another zone";
     if (outcome.state === "passed") {
         // A sort names where the card goes; one it isn't sure about is a person's to place.
@@ -289,16 +296,32 @@ function draftModel(store) {
 /** A draft: Claude writes what the zone asks, from the card, with the lead chat's Claude model; the text stays on the card. */
 async function draftCard(store, definition, stage, card, io, repo, now) {
     const model = draftModel(store);
-    const answer = await (io.draft ?? claudeDraftRunner())({ model, prompt: draftPrompt(stage, card, definition), timeoutMs: DRAFT_TIMEOUT });
+    const runner = io.draft ?? claudeDraftRunner();
+    // Claude is told the limit before it writes; a draft over it is asked once to shorten, and one still over is kept whole
+    // in the step's log and attached to the card's discussion, linked from what the next steps read (settle): never cut.
+    let first = null;
+    const written = await writeWithin(async (shorten) => {
+        const answer = await runner({ model, prompt: draftPrompt(stage, card, definition, shorten === null || first === null ? null : { draft: first, ask: shorten }), timeoutMs: DRAFT_TIMEOUT });
+        // v105: what it cost, billed as this computer's Claude does (a plan's is $0).
+        if (answer.ok) {
+            store.recordDraftSpend({ repo, model: model === "default" ? null : model, costUsd: answer.costUsd ?? null }, now);
+            first ??= wholeDraft(answer.text);
+        }
+        return answer;
+    }, answer => answer.ok ? overruns({ draft: wholeDraft(answer.text) }, { draft: DRAFT_CHARS }) : []);
+    const answer = written.answer;
     if (!answer.ok)
-        return { state: "retry", said: answer.said };
-    // v105: what it cost, billed as this computer's Claude does (a plan's is $0).
-    store.recordDraftSpend({ repo, model: model === "default" ? null : model, costUsd: answer.costUsd ?? null }, now);
-    const text = keptDraft(answer.text);
+        return written.repaired && first !== null ? draftOutcome(first, model, null, true) : { state: "retry", said: answer.said };
+    const text = wholeDraft(answer.text);
     if (text === "")
-        return { state: "retry", said: "Claude's draft came back empty." };
+        return written.repaired && first !== null ? draftOutcome(first, model, answer.ms, true) : { state: "retry", said: "Claude's draft came back empty." };
+    return draftOutcome(text, model, answer.ms, written.repaired);
+}
+/** A draft step's result: the draft whole, on the card and in its log. */
+function draftOutcome(text, model, ms, shortened) {
     const words = text.split(/\s+/).filter(Boolean).length;
-    return { state: "passed", said: `Drafted ${words} word${words === 1 ? "" : "s"}.`, output: text, log: `Claude (${model}) · ${(answer.ms / 1000).toFixed(1)} s\n\n${text}` };
+    const over = text.length > DRAFT_CHARS ? ` It is still over the ${DRAFT_CHARS.toLocaleString("en-US")}-character limit after one ask to shorten, so it is kept whole.` : shortened ? " Shortened once to fit." : "";
+    return { state: "passed", said: `Drafted ${words} word${words === 1 ? "" : "s"}.${over}`, output: text, log: `Claude (${model})${ms === null ? "" : ` · ${(ms / 1000).toFixed(1)} s`}\n\n${text}` };
 }
 /** A sort: Jev picks one of the zone's answers for the card; the answer (or the not-sure path) says where it goes. */
 async function sortCard(definition, stage, card, key, io) {

package/dist/flows-ui.js

@@ -7,6 +7,7 @@ import { flowSecretNames, readEmailSettings, sendingReady } from "./flow-actions
 import { projectToolsOf, secretsSetFor, toolStanding } from "./project-tools.js";
 import { flowFingerprint } from "./flow-live.js";
 import { flowChoiceAt, readFlowSend } from "./flow-send.js";
+import { itemCaption, whyLines } from "./flow-items.js";
 import { FLOW_FILE_MAX_BYTES } from "./flow-share.js";
 import { googleConnected } from "./google-mail.js";
 import { mailboxReady } from "./mailbox.js";
@@ -130,7 +131,10 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         // On the card itself: where it came from (the card's title is right above), and only the links the panel doesn't already have.
         const own = new Set([`/flows/${flow.id}?card=${card.id}`, ...(task === null ? [] : [`/t/${encodeURIComponent(task)}`])]);
         const sentView = (content) => ({ title: content.from === undefined ? "What was done" : `From ${content.from}`, summary: content.summary,
-            links: content.links.map(one => ({ label: one.label, href: "url" in one ? one.url : one.path })).filter(one => !own.has(one.href)) });
+            links: content.links.map(one => ({ label: one.label, href: "url" in one ? one.url : one.path })).filter(one => !own.has(one.href)),
+            // After research: the same numbered items the message carried, each beside its screenshot.
+            ...(content.items === undefined ? {} : { items: content.items.map((item, index) => ({ number: index + 1, title: item.title, lines: whyLines(item.why), source: item.source, url: item.url,
+                    image: item.shot === null || content.shots === null ? null : { src: `/r/${content.shots.run}/evidence/${item.shot}`, caption: itemCaption(index + 1, item) } })) }) });
         return {
             id: card.id, title: card.title, description: card.description, stage: card.stage, state: card.state, waiting: card.waiting,
             task: task === null ? null : { id: task, href: `/t/${encodeURIComponent(task)}` },

package/dist/flows.d.ts

@@ -167,6 +167,14 @@ export declare function deciderOf(stage: Pick<FlowStage, "approver" | "toOwner">
 export declare function validateFlowDefinition(input: unknown, options?: {
     stored?: boolean;
 }): FlowDefinition;
+/** The instructions 0.9.26 and earlier read from a saved zone: they re-check this length on every read, and a flow with a
+ * longer one won't load. A saved zone keeps its first part under it, and the rest in `instructionsMore`, which they ignore. */
+export declare const FLOW_INSTRUCTIONS_STORED = 4000;
+/** A flow's definition as the store saves it: any zone's instructions over FLOW_INSTRUCTIONS_STORED are split, so a
+ * person who goes back a version still opens the flow (with its instructions' first part). Unchanged otherwise. */
+export declare function flowDefinitionForStore(json: string): string;
+/** A saved flow's definition with every zone's instructions whole again (flowDefinitionForStore). */
+export declare function flowDefinitionFromStore(json: string): string;
 /** The zones a card can reach from `start` without passing through a zone `stop` picks (those zones aren't included). */
 export declare function reachableWithout(stages: readonly FlowStage[], start: string, stop: (stage: FlowStage) => boolean): Set<string>;
 /** The zones a choose zone's options lead to (an option that ends the card leads to none). */
@@ -183,20 +191,27 @@ type FlowFillCard = {
 };
 /** Fill a zone's text from the card: title, description, the latest note and earlier zones' reports. */
 export declare function fillFlowText(template: string, card: FlowFillCard, encode?: (value: string) => string): string;
-/** The task door's goal limit (task-text.ts). A work zone's goal is kept under it. */
-export declare const FLOW_GOAL_LIMIT = 2000;
-/** What stands in for the middle of a filled-in value the goal had no room for. */
-export declare const FLOW_CUT = "\u2026 (cut; the full text is on the card)";
+/** The task door's goal limit (task-text.ts). A work zone's goal is kept within it. */
+export declare const FLOW_GOAL_LIMIT: 8000;
+/** What stands in a goal for a filled-in value too long to hold whole: the agent is given it whole, attached (flowGoalCuts). */
+export declare const flowAttachedMark: (label: string) => string;
 /** A work zone's words, plus the card and any send-back note when the words leave them out. "Fix the bug on the card"
  * says nothing on its own (found in the real e2e: the builder saw only the branch name). */
 export declare function flowWorkTemplate(instructions: string, card: {
     description: string | null;
     note: string | null;
 }): string;
-/** A work zone's goal, filled from the card and kept under FLOW_GOAL_LIMIT: the zone's own words stay whole, and only the
- * filled-in values are shortened (the longest first), each keeping its start and end. Null when the words alone leave no
- * room, which a saved flow can't have (validateFlowDefinition). */
-export declare function fitFlowText(template: string, card: FlowFillCard, limit?: number): string | null;
+/** How a filled-in value is named where it is attached: the same words flowGoalCuts labels it with. */
+export declare function flowValueLabel(key: string, stageTitle?: (id: string) => string): string;
+/** A work zone's goal, filled from the card and kept within `limit`: the zone's own words stay whole, and every filled-in
+ * value goes in whole. When they don't all fit, the longest values are attached instead (each named in the goal by
+ * flowAttachedMark, and given to the agent whole by flowGoalCuts) until the rest fits: nothing is cut. Words that fill
+ * the limit to the last character leave attached values a shorter mark, then none (they are still attached). Null only
+ * when the template's own words are over the limit: the caller then files the zone's words alone (flowGoal). */
+export declare function fitFlowText(template: string, card: FlowFillCard, limit?: 8000, stageTitle?: (id: string) => string): string | null;
+/** A work zone's goal for a card: its words, the card and any note, fitted (fitFlowText); when the zone's words leave no
+ * room for the card's own lines, its words alone, with the card attached. Null only for words over the limit. */
+export declare function flowGoal(instructions: string, card: FlowFillCard, stageTitle?: (id: string) => string): string | null;
 /** The first email address a card mentions, or "" — what {{card.email}} holds. */
 export declare function cardEmailOf(card: {
     title: string;