toolroll 0.9.94 → 0.9.95

package/dist/surface.js

@@ -1,5 +1,6 @@
 import { KNOWLEDGE_DESCRIPTORS } from "./knowledge-cli.js";
 import { MEMORY_DESCRIPTORS } from "./memory-cli.js";
+import { CARD_DESCRIPTOR } from "./card-cli.js";
 import { FLAKY_DESCRIPTORS } from "./flaky-cli.js";
 import { MODELS_DESCRIPTORS } from "./models-cli.js";
 import { MAP_DESCRIPTORS } from "./code-map-cli.js";
@@ -119,6 +120,7 @@ const GUIDE_ROWS = [
     operator("demo", "a seeded throwaway sandbox"),
     ...KNOWLEDGE_DESCRIPTORS.map(spec => ({ invocation: `knowledge ${spec.action}`, synopsis: spec.synopsis, audience: "audience" in spec ? spec.audience : "agent", agentMayInvoke: !("audience" in spec), mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text or source file for impact" }] } : {}) })),
     ...MEMORY_DESCRIPTORS.map(spec => ({ invocation: `memory ${spec.action}`, synopsis: spec.synopsis, audience: "audience" in spec ? spec.audience : "agent", agentMayInvoke: !("audience" in spec), mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text, a decision id, or the decision sentence" }] } : {}) })),
+    { invocation: CARD_DESCRIPTOR.invocation, synopsis: CARD_DESCRIPTOR.synopsis, audience: "agent", agentMayInvoke: true, mutation: "none", flags: CARD_DESCRIPTOR.flags, positionals: [{ name: "source", required: true, meaning: "which data to show" }] },
     ...FLAKY_DESCRIPTORS.map(spec => ({ invocation: `flaky ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "identity", required: true, meaning: "a row's key from flaky list" }] } : {}) })),
     // Flow writes carry an approver's credential: an agent runs them only as the person asked, after showing the preview.
     // Letting a flow run on its own raises authority: the owner's own password ceremony, never an agent's act.
@@ -327,7 +329,19 @@ const GUIDE_ROWS = [
             { name: "digest", takesValue: true, meaning: "the exact receipt from assignment show; accepts and finishes exactly that result" },
             { name: "despite", takesValue: true, meaning: "accept with this reason, without finishing; never combines with --finish or --digest (--note is its alias)" }],
         notableReasons: ["usage", "unknown-task", "no-run", "not-ready"] },
-    operator("task repair", "inspect or approve an existing historical repair draft; use task revise for new feedback"),
+    operator("task repair", "inspect or approve a repair draft; --yes starts the repair a failed check is waiting for, under the normal plan approval"),
+    operatorRead("task handover", "where a task stands, from Toolroll's records: revision, decisions, rejected approaches, open findings, checks and the next action"),
+    operator("task before-after", "before-and-after evidence: read it, save a failing result, or rerun the same check on the latest commit with no agent"),
+    operator("task failing-first", "ask a bug fix's next attempt to write a failing test first (on|off); shown in the result as the agent's report"),
+    operatorRead("finding list", "findings still waiting on someone, or every finding of --task <id>"),
+    operatorRead("finding show", "one finding: its text, evidence and how it stands"),
+    operator("finding send", "send a finding to the task that owns the code; the owner must accept it or reject it with a reason"),
+    operator("finding resend", "send an answered finding back, one more round; past the limit it goes to a person"),
+    operator("finding close", "a person's decision on a finding"),
+    operatorRead("captures list", "what providers said when attempts failed, the ones mentioning limits first; nothing routes on these"),
+    operatorRead("captures show", "one saved provider failure"),
+    operatorRead("captures export", "one saved provider failure as a fixture"),
+    operator("captures mark", "a person's reading of a capture: exhausted or not-exhausted"),
     operator("task route", "which configured agents plan, build and repair this task; phase and size changes require renewed approval"),
     operator("task reopen", "resume external work its tracker closed and has been SEEN open again"),
     operator("task stop", "stop ONE exact live attempt (--run <id>): durable before any process is signalled, answers 'stopping' until its own processes are established gone; work, branch, and evidence preserved; no strike, no retry"),
@@ -509,6 +523,11 @@ const REMOTE_NO = [
     // Reads this machine owner's own Claude and Codex session files (~/.claude, ~/.codex).
     "memory propose",
 ];
+const REMOTE_FOLLOW_THROUGH = [
+    // On the server's machine or in the console: each writes through a verified person, and they read saved model text.
+    "task handover", "task before-after", "task failing-first", "finding list", "finding show", "finding send", "finding resend", "finding close",
+    "captures list", "captures show", "captures export", "captures mark",
+];
 const REMOTE_STEP_UP = [
     "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle",
     // Putting tasks away and restoring them: a person's act, in the console or on the server's machine.
@@ -533,7 +552,7 @@ const REMOTE_YES = [
     "knowledge search", "knowledge impact", "knowledge refresh",
     "map", "map area", "map file", "map search", "map refresh",
     "memory search", "memory decisions", "memory show", "memory review", "memory status",
-    "flaky list", "flaky show",
+    "flaky list", "flaky show", "card",
     "flows list", "flows show", "flows export", "flows create", "flows edit", "flows trigger add", "flows trigger pause", "flows trigger resume",
     "flows trigger remove", "flows card add", "flows archive",
     "models status", "models list",
@@ -541,11 +560,12 @@ const REMOTE_YES = [
 /** Every row's remote policy, by invocation. Exported for the contract test, which holds it to the guide exactly. */
 export const REMOTE_POLICY = new Map([
     ...REMOTE_NO.map(invocation => [invocation, "no"]),
+    ...REMOTE_FOLLOW_THROUGH.map(invocation => [invocation, "no"]),
     ...REMOTE_STEP_UP.map(invocation => [invocation, "step-up"]),
     ...REMOTE_YES.map(invocation => [invocation, "yes"]),
 ]);
 /** How many times each invocation was classified — the contract test refuses a row stated twice. */
-export const REMOTE_POLICY_COUNT = REMOTE_NO.length + REMOTE_STEP_UP.length + REMOTE_YES.length;
+export const REMOTE_POLICY_COUNT = REMOTE_NO.length + REMOTE_FOLLOW_THROUGH.length + REMOTE_STEP_UP.length + REMOTE_YES.length;
 /**
  * Easy-start C3: the commands a laptop's local owner may run through the terminal UI (local-owner.ts runAsLocalOwner),
  * each with the act it is; every other row (and every command with no row) is refused to the local owner before any
@@ -554,7 +574,7 @@ export const REMOTE_POLICY_COUNT = REMOTE_NO.length + REMOTE_STEP_UP.length + RE
 const LOCAL_ALLOW = {
     // Reads.
     pulls: "read", graph: "read", repos: "read", map: "read", "map area": "read", "map file": "read", "map search": "read", status: "read", ready: "read", gaps: "read", contract: "read", "skills list": "read", "skills get": "read",
-    "flaky list": "read", "flaky show": "read", "memory review": "read", "memory status": "read", "memory decisions": "read", "memory show": "read",
+    "flaky list": "read", "flaky show": "read", card: "read", "memory review": "read", "memory status": "read", "memory decisions": "read", "memory show": "read",
     // Learning loops (D3): a lesson note or a clean-up, decided by a person at the laptop (the writers check the act).
     "memory apply": "memory-review", "memory tidy": "memory-review", "memory restore": "memory-review", "memory unmerge": "memory-review",
     "task list": "read", "task show": "read", "task state": "read", "task wait": "read", "check-progress": "read", "review show": "read", welcome: "read",

package/dist/task-control.d.ts

@@ -19,6 +19,7 @@
  * hold, recovery, and invocation-gateway machinery. This
  * module only names the door and the fence.
  */
+import type { StopVia } from "./store.js";
 import { type DispatchDiagnosis } from "./dispatch.js";
 import type { Run, RunStop, Store } from "./store.js";
 /** How often a running attempt re-reads its stop row while a child runs.
@@ -86,7 +87,7 @@ export type ResumeRequest = {
     taskId: string;
     runId: number;
     by: string;
-    via: "cli" | "web";
+    via: StopVia;
     /** The workspace occupancy probe (the worktree pool's `inUse`): a
      * checkout some process still holds is not quiescent, whatever the
      * rows say — the concrete gate names the pid. */

package/dist/task-status.js

@@ -385,6 +385,9 @@ export function pullRequestFactOf(publication) {
 /** The assignment's stage. The work status, when the caller read one, names
  * the exact reason (a running planner, a pause, a failed attempt, a sign-in). */
 export function assignmentStageOf(assignment, work, planning = false) {
+    // A finding held for a person outlives the stage the work is in, a saved result included: only a person closes it.
+    if (work?.token === "finding-held" && assignment.state !== "cancelled")
+        return { stage: "needs-you", need: "finding" };
     // The assignment's own reading (a build Toolroll can't confirm stopped) comes first.
     const own = assignment.need ?? null;
     if (own !== null && (assignment.state === "working" || assignment.state === "needs-decision"))
@@ -407,6 +410,8 @@ export function assignmentStageOf(assignment, work, planning = false) {
                 return { stage: "needs-you", need: "answer" };
             if (action === "inspect-decisions")
                 return { stage: "needs-you", need: "questions" };
+            if (action === "inspect-findings")
+                return { stage: "needs-you", need: "finding" };
             const token = work?.token ?? "";
             // A failed attempt is Failed. A saved result that still needs a decision
             // (its scope, a hold, a process exit) is Needs you, even if its checks

package/dist/teardown-git.d.ts

@@ -50,6 +50,8 @@ export type GitBinding = {
  * real `.git` folder, holding no `commondir`. No pointer file or `commondir` an agent can write decides it, and no git
  * runs (a page visit reads this). Throws with the reason otherwise. */
 export declare function recordedCommonDir(repo: string): string;
+/** Where git incidents are recorded: beside the fenced views folder (git-incident.ts). */
+export declare function gitIncidentRecord(): string;
 /** Settings fixed on every write through a view: `worktree add` records absolute paths (relative ones would need a
  * config write, which a view keeps); no transport at all (a caller that fetches allows its one protocol by name, as the
  * nightly check's local fetch does with protocol.file.allow); and no split index (its shared index files would be

package/dist/teardown-git.js

@@ -191,7 +191,7 @@ function nestedRepository(path) {
  * repository (boundDirs; `binding.repo` when the caller has the project's), is refused; so is a command whose
  * repository changed under it while git ran.
  */
-async function inView(cwd, binding, work, after = true, lockTimeoutMs, gitFile = "git") {
+async function inView(cwd, binding, work, after = true, lockTimeoutMs, doing, gitFile = "git") {
     const root = checkoutRootOf(cwd);
     if (root === null)
         return NOT_A_REPOSITORY;
@@ -207,7 +207,7 @@ async function inView(cwd, binding, work, after = true, lockTimeoutMs, gitFile =
         return await withCheckoutLock(realpathSync(homedir()), key, async () => {
             let view;
             try {
-                view = gitView(root, "write", binding, gitFile);
+                view = gitView(root, "write", binding, gitFile, undefined, doing);
             }
             catch (error) {
                 return refused(error instanceof Error ? error.message : "the checkout couldn't be read");
@@ -255,6 +255,7 @@ export function teardownGit(runner = run, binding = {}, lockTimeoutMs, gitFile =
         const forced = removal && args.includes("--force");
         const inspection = args.includes("status") || args.includes("diff");
         const target = removal ? resolve(cwd, args.at(-1)) : cwd;
+        const doing = teardownDoing(args);
         const safeArgs = [...args];
         if (inspection && !safeArgs.includes("--ignore-submodules=all")) {
             const command = safeArgs.findIndex(arg => arg === "status" || arg === "diff");
@@ -288,8 +289,22 @@ export function teardownGit(runner = run, binding = {}, lockTimeoutMs, gitFile =
             // the target's view, inspected above, so it judges the target by the target's own settings.
             return ran(removal && !forced ? { ...view.env, GIT_COMMON_DIR: targetView.env["GIT_COMMON_DIR"] } : view.env);
             // A removed target has no git directory left to prove: the folder it was removed from is proven instead.
-        }, !removal, lockTimeoutMs, gitFile);
-    }, true, lockTimeoutMs, gitFile);
+        }, !removal, lockTimeoutMs, doing, gitFile);
+    }, true, lockTimeoutMs, teardownDoing(args), gitFile);
+}
+/** What teardown git is doing, for an incident's notice: removing a checkout, or looking one over to tidy it. */
+function teardownDoing(args) {
+    return args.includes("worktree") && args.includes("remove") ? "removing an old checkout" : "tidying an old checkout";
+}
+/** What a build's git is doing, for an incident's notice. */
+function checkoutDoing(args) {
+    if (args.includes("worktree"))
+        return args.includes("remove") ? "removing a checkout" : args.includes("add") ? "making a checkout" : "listing checkouts";
+    if (args.some(arg => arg === "commit" || arg === "add" || arg === "merge" || arg === "rebase" || arg === "reset" || arg === "checkout" || arg === "switch"))
+        return "saving a build's work";
+    if (args.some(arg => arg === "fetch" || arg === "push"))
+        return "updating a repository";
+    return "reading a build's checkout";
 }
 /** A setup call's time limit: its own five seconds, or less when a caller's deadline leaves less (never below 1 ms;
  * a caller checks the deadline itself before calling). */
@@ -330,7 +345,7 @@ function regularFile(path) {
 }
 /** A checkout's git directory and common directory, as git finds them from its `.git` (a folder, or a one-line
  * `gitdir: ` file); null when the pointer isn't one git would read the same way. */
-function gitDirsOf(checkout) {
+function gitDirsOf(checkout, vouched = NO_VOUCHED) {
     let gitdir = join(checkout, ".git");
     try {
         if (!lstatSync(gitdir).isDirectory()) {
@@ -350,11 +365,14 @@ function gitDirsOf(checkout) {
     // Where the checkout's own files point (a build can write both): read, in the console, only while that folder
     // answered a look lately, and never vouched for by the checkout pool's spelling (folder-gate.ts). Held back: not one
     // git would read the same way, so every caller refuses.
-    if (gitdir !== join(checkout, ".git") && !folderAnswers(gitdir, true))
+    // `vouched`: the very folders this view was made from, read again after git ran (settle). They answered moments ago
+    // and git just ran in them; the gate's staleness is no evidence about them. Anything they now point elsewhere is
+    // gated as ever, so a re-pointed `.git` or `commondir` is never read on the console's thread on its say.
+    if (gitdir !== join(checkout, ".git") && !vouched.has(gitdir) && !folderAnswers(gitdir, true))
         return null;
     const named = regularFile(join(gitdir, "commondir"))?.trim();
     const common = named === undefined || named === "" ? gitdir : resolve(gitdir, named);
-    if (common !== gitdir && !folderAnswers(common, true))
+    if (common !== gitdir && !vouched.has(common) && !folderAnswers(common, true))
         return null;
     return { gitdir, common };
 }
@@ -382,7 +400,8 @@ function includeIn(path, gitFile = "git", limit) {
         return named.toLowerCase();
     return /^\s*\[\s*include(if)?\b/im.test(text) ? "include" : null;
 }
-function boundDirs(checkout, binding = {}) {
+const NO_VOUCHED = new Set();
+function boundDirs(checkout, binding = {}, vouched = NO_VOUCHED) {
     const fail = (why) => { throw new Error(`the checkout's .git ${why}`); };
     let top;
     try {
@@ -403,12 +422,12 @@ function boundDirs(checkout, binding = {}) {
     if (held.isDirectory()) {
         if (existsSync(join(dotgit, "commondir")))
             fail("names another repository (commondir)");
-        dirs = { checkout: top, gitdir: dotgit, common: dotgit, linked: false };
+        dirs = { checkout: top, gitdir: dotgit, common: dotgit, linked: false, spelled: [dotgit] };
     }
     else {
         if (!held.isFile())
             fail("is a link");
-        const named = gitDirsOf(top);
+        const named = gitDirsOf(top, vouched);
         if (named === null)
             return fail("couldn't be read as git reads it");
         let gitdir;
@@ -444,7 +463,7 @@ function boundDirs(checkout, binding = {}) {
         }
         if (backReal !== dotgit)
             fail("belongs to a git directory that names another checkout");
-        dirs = { checkout: top, gitdir, common, linked: true };
+        dirs = { checkout: top, gitdir, common, linked: true, spelled: [named.gitdir, named.common, gitdir, common] };
     }
     // The common folder is a main checkout's own `.git` folder, a real one.
     if (basename(dirs.common) !== ".git")
@@ -490,7 +509,12 @@ export function recordedCommonDir(repo) {
 const ADMIN_LINKED = ["index", "logs", "refs", "reftable"];
 /** What git keeps in a common directory (its path.c common_list, and reftable), linked whether or not it exists yet. */
 const COMMON_NAMES = ["branches", "gc.pid", "logs", "lost-found", "modules", "objects", "packed-refs", "reftable", "refs", "remotes", "rr-cache", "shallow", "svn", "worktrees"];
-function gitView(checkout, kind, binding = {}, gitFile = "git", limit) {
+/** Where git incidents are recorded: beside the fenced views folder (git-incident.ts). */
+export function gitIncidentRecord() {
+    return join(dirname(ensureGitViewsRoot(realpathSync(homedir()))), "git-incidents.jsonl");
+}
+/** `doing`: what the plane was doing, in a person's words ("tidying an old checkout"), for an incident's notice. */
+function gitView(checkout, kind, binding = {}, gitFile = "git", limit, doing) {
     const dirs = boundDirs(checkout, binding);
     const root = ensureGitViewsRoot(realpathSync(homedir()));
     const view = realpathSync(mkdtempSync(join(root, `${kind}-`)));
@@ -658,8 +682,10 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit) {
     const settle = () => {
         const now = pinned(dirs);
         let bound = false;
+        // The same proof as before git ran, of the same folders: re-read past the console's folder gate only where they are
+        // the very ones this view was made from (vouched), so a gate whose answer went stale mid-run is never read as a swap.
         try {
-            const again = boundDirs(checkout, binding);
+            const again = boundDirs(checkout, binding, new Set(dirs.spelled));
             bound = again.gitdir === dirs.gitdir && again.common === dirs.common;
         }
         catch {
@@ -669,7 +695,7 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit) {
             // Too late to prevent: recorded and told (git-incident.ts), never rolled back where the swap leads.
             if (kind === "write") {
                 gitIncident({ checkout: dirs.checkout, repository: dirs.common, swapped: now.swapped.length > 0 ? now.swapped.map(({ path, leadsTo }) => ({ path, leadsTo })) : [{ path: join(dirs.checkout, ".git"), leadsTo: null }],
-                    record: join(dirname(ensureGitViewsRoot(realpathSync(homedir()))), "git-incidents.jsonl") });
+                    cause: now.swapped.length > 0 ? "swapped" : "rebound", ...(doing === undefined ? {} : { doing }), record: gitIncidentRecord() });
             }
             return "the checkout's repository changed while git ran";
         }
@@ -683,7 +709,7 @@ function gitView(checkout, kind, binding = {}, gitFile = "git", limit) {
             catch (error) {
                 if (!(error instanceof AnchorMoved))
                     return "the checkout's git state couldn't be carried back after git ran";
-                gitIncident({ checkout: dirs.checkout, repository: dirs.common, swapped: [{ path: error.message, leadsTo: null }], record: join(dirname(ensureGitViewsRoot(realpathSync(homedir()))), "git-incidents.jsonl") });
+                gitIncident({ checkout: dirs.checkout, repository: dirs.common, swapped: [{ path: error.message, leadsTo: null }], cause: "moved", ...(doing === undefined ? {} : { doing }), record: gitIncidentRecord() });
                 return "the checkout's repository changed while git ran";
             }
             if (left.length > 0)
@@ -1110,7 +1136,7 @@ export function checkoutGit(inner = run, mode = "build", binding = {}) {
         const once = async () => {
             let view;
             try {
-                view = gitView(cwd, mode === "read" ? "read" : "write", binding);
+                view = gitView(cwd, mode === "read" ? "read" : "write", binding, "git", undefined, checkoutDoing(args));
             }
             catch (error) {
                 return refused(error instanceof Error ? error.message : "the checkout couldn't be read");

package/dist/telegram-lead.js

@@ -1,5 +1,7 @@
+import { telegramCardMessage } from "./card-render.js";
+import { cardOfProposal, cardPlainOf, cardsFirst, cardWithin, isCardProposal } from "./chat-card.js";
 import { CHAT_ACTIONS, sharedActionAllowsChallenge, sharedActionPayload } from "./chat-actions.js";
-import { taskInCeiling, mirrorToTaskChat, couldNotAnswerText, channelRepos as telegramConversationRepos, resolveChannelLead as resolveTelegramLead, NO_PHONE_LINK, NO_TASK_LINK, phoneProposalLink, confirmedLink, phoneProposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText } from "./chat-channel.js";
+import { armedQuestion, taskInCeiling, mirrorToTaskChat, couldNotAnswerText, channelRepos as telegramConversationRepos, resolveChannelLead as resolveTelegramLead, NO_PHONE_LINK, NO_TASK_LINK, phoneProposalLink, confirmedLink, phoneProposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText } from "./chat-channel.js";
 export { channelRepos as telegramConversationRepos, resolveChannelLead as resolveTelegramLead, tooLongText, whichTaskText, replyContextFor, NO_PHONE_LINK, NO_TASK_LINK, proposalLink, confirmedLink, proposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText, CHAT_ACTION_PARITY as TELEGRAM_ACTION_PARITY, parityGaps } from "./chat-channel.js";
 /**
  * The paired phone as one more way to use the same assistant.
@@ -260,7 +262,7 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         const body = preview.text.split("\n\nConfirm or Dismiss below")[0];
         if (challenged) {
             ack("confirm it");
-            edit(`${body}\n\nThis records that you handled this exact result. Confirm?`, [
+            edit(`${body}\n\n${armedQuestion(proposal)}`, [
                 [telegramButton(`✓ Yes, ${CHAT_ACTIONS[sharedAction.operation].label.toLowerCase()}`, yes)],
                 [telegramButton("Cancel", cancel)],
             ]);
@@ -288,6 +290,7 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         // The paired phone speaks for its account's full authority (pairing is a full session's act).
         authority: "full",
         via: "telegram",
+        binding: binding.id,
         evidenceRoot: options.evidenceRoot,
         confirm: action.phase === "yes",
         deferSignal: signal => effects.push({ kind: "signal", run: signal }),
@@ -549,17 +552,26 @@ async function runTelegramConversation(row, args) {
                 const origin = proposal === null ? null : options.phoneOrigin?.() ?? null;
                 const wanted = proposal === null ? null : phoneProposalLink(store, proposal, repos);
                 const keyboard = keyboardWith(part.keyboard, phoneLinkButton(origin, wanted));
+                // A Toolroll card: read again now, shown only where every project behind it is still reachable. An unreadable
+                // one goes out as its saved plain words.
+                const isCard = proposal !== null && isCardProposal(proposal);
+                const rich = isCard ? cardOfProposal(proposal) : null;
+                const shown = rich !== null && cardWithin(rich, repos) ? telegramCardMessage(rich) : null;
+                const links = rich === null ? [] : rich.buttons.flatMap(one => phoneLinkButton(origin, one) ?? []).map(one => [one]);
                 // The lead's own words carry their bold anchors and labelled links as entities, never as Markdown characters.
                 const voiced = part.kind === "reply" ? telegramReply(part.text) : null;
-                const text = proposal !== null && part.keyboard === null ? handoffCardText(part.text, linkNote(origin, wanted)) : voiced?.text ?? part.text;
+                const text = isCard ? shown?.text ?? (rich === null ? part.text : "This card's projects changed, so it wasn't sent.")
+                    : proposal !== null && part.keyboard === null ? handoffCardText(part.text, linkNote(origin, wanted)) : voiced?.text ?? part.text;
+                const entities = isCard ? shown?.entities ?? [] : voiced?.entities ?? [];
+                const buttons = isCard ? (shown === null || links.length === 0 ? undefined : links) : keyboard;
                 method = "sendMessage";
                 send = () => transport("sendMessage", {
                     chat_id: chatId,
                     text,
-                    ...(voiced === null || voiced.entities.length === 0 ? {} : { entities: voiced.entities }),
+                    ...(entities.length === 0 ? {} : { entities }),
                     link_preview_options: { is_disabled: true },
                     ...(part.replyTo === null ? {} : { reply_parameters: { message_id: Number(part.replyTo) } }),
-                    ...(keyboard === undefined ? {} : { reply_markup: { inline_keyboard: keyboard } }),
+                    ...(buttons === undefined ? {} : { reply_markup: { inline_keyboard: buttons } }),
                 });
             }
             // The first time the answer itself fails to go out, the person hears so once,
@@ -626,7 +638,12 @@ async function runTelegramConversation(row, args) {
                 const selected = store.getLeadTurn(turn)?.state === "answered" ? store.listLeadTurnEvidence(turn) : [];
                 for (const image of selected)
                     parts.push({ kind: "image", text: image.caption, taskId: image.taskId, run: image.run, artifact: image.artifact, sha256: image.sha256 });
-                for (const proposal of proposals) {
+                // Cards first, so what a card leads to sits right under it. A card mints no tokens: it confirms nothing.
+                for (const proposal of cardsFirst(proposals)) {
+                    if (isCardProposal(proposal)) {
+                        parts.push({ kind: "card", text: cardPlainOf(proposal), proposal: proposal.id, keyboard: null });
+                        continue;
+                    }
                     const preview = phoneProposalPreview(store, proposal, repos);
                     const keyboard = preview.buttons ? mintCardTokens(store, binding, proposal.id, now).keyboard : null;
                     parts.push({ kind: "card", text: preview.text, proposal: proposal.id, keyboard });

package/dist/telegram.js

@@ -18,6 +18,8 @@
  * BotFather token plus `bridge telegram unpair` is the recovery, and both
  * are one command.
  */
+import { telegramCardMessage } from "./card-render.js";
+import { flowDoneCard } from "./flow-result-card.js";
 import { applyTelegramQuestionReply, applyTelegramQuestionTap, openQuestionOf, telegramQuestionButtons } from "./subagent-question.js";
 import { acceptanceEvidenceText } from "./chat-acceptance.js";
 import { verifyApproverStanding } from "./principal.js";
@@ -1288,6 +1290,15 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             parts = voiced.map(one => one.text);
             entities = voiced.map(one => one.entities);
         }
+        // A flow's result as a card (flow-result-card.ts): one more message, its tables as monospaced text.
+        const resultCard = offer === null ? sent?.card ?? flowDoneCard(store, notification, clock()) : null;
+        if (resultCard != null) {
+            const message = telegramCardMessage(resultCard);
+            entities = [...parts.map((_, at) => entities[at] ?? []), message.entities];
+            parts = [...parts, message.text];
+        }
+        // Its links stay on the words: the card follows them.
+        const keyedPart = parts.length - (resultCard != null ? 2 : 1);
         // A subagent's question (v93): its options and "Answer in words", for the person it asks.
         const asked = flowKeys === null && choiceKeys === null ? openQuestionOf(store, notification.dedupeKey) : null;
         const questionKeys = asked === null ? null : telegramQuestionButtons(store, binding, asked, clock());
@@ -1301,7 +1312,7 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             }
         }
         for (const [index, part] of parts.entries()) {
-            const final = index === parts.length - 1;
+            const final = index === keyedPart;
             const decideKeys = decided === null ? [] : decideKeyboard(phoneOrigin, decided.rows);
             const keyboard = !final ? undefined : keys !== null ? [...keys.keyboard, ...(button === null ? [] : [button])] : decideKeys.length > 0 ? decideKeys : button !== null ? [button] : undefined;
             const sent = await sender(part, keyboard, undefined, entities[index]?.length ? entities[index] : undefined);

package/dist/toolroll-update.js

@@ -427,6 +427,8 @@ const HISTORY_RULES = {
     // v152: a saved project's code map reads on, with no enrollment yet; the code map's tables are new.
     // v153: a saved task reads no fast start and a saved project no fast-start setting (NULL); its tables are new.
     // v154 adds a table only (check_stamp): no saved row changes, so no rule is needed for it.
+    // v155 adds tables only (fleet-schema.ts): no saved row changes, so no rule is needed for it.
+    // v156 adds tables only (fallback chains): likewise.
     ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS, V148_ADDED_COLUMNS, V150_ADDED_COLUMNS, V151_ADDED_COLUMNS, V152_ADDED_COLUMNS, V153_ADDED_COLUMNS))
         .map(([table, rule]) => [table, { ...EARLIER_RULES[table], ...rule }])),
 };

package/dist/work-index.js

@@ -19,7 +19,7 @@ import { isCheckLevel, requiredCheckCommandFor } from './check-levels.js';
 import { MARKER } from './worktree.js';
 import { withFollowUps } from './result-follow-ups.js';
 import { LANDED_ACTOR, landedReasonOf } from './result-completion.js';
-import { ASKS, CODE_READING, NEED_ASK, NEEDS, askChipOf, failedAttemptSentence, isWaitCode, processNeedOf, resultHoldUpSentence } from './needs-you.js';
+import { ASKS, CODE_READING, STORAGE_HOLD_PREFIX, NEED_ASK, NEEDS, askChipOf, failedAttemptSentence, isWaitCode, processNeedOf, resultHoldUpSentence } from './needs-you.js';
 import { retryWhenWords } from './dispatch.js';
 import { LEAD_CLAIM_SQL, LEAD_IDLE_MS } from './lead-voice.js';
 export const WORK_INDEX_PAGE_LIMIT = 40;
@@ -45,9 +45,11 @@ const GATE_PAUSE_ON_TASK = pauseOnTaskProviders('p', 'c.ref_id');
 const INDEX_NEED = Object.fromEntries(['earlier-active', 'process-needs-attention', 'invalid-scope', 'decision-queue', 'history-problem']
     .map(code => [code, CODE_READING[code].need]));
 /** Every index code that can wait on a person. A wait (stopping, waiting its turn, a retry later) is never one. */
-const PERSON_CODES = ['history-problem', 'earlier-active', 'ready-to-check', 'waiting-decision', 'decision-queue', 'result-needs-attention',
+const PERSON_CODES = ['finding-held', 'history-problem', 'earlier-active', 'ready-to-check', 'waiting-decision', 'decision-queue', 'result-needs-attention',
     'process-needs-attention', 'failed', 'vanished-run', 'stopped', 'held', 'waiting-incident', 'terminal-dependency', 'needs-project',
-    'needs-scope', 'invalid-scope', 'needs-agent-profile', 'needs-approval', 'missing-requirement', 'no-worker-registered', 'no-worker-online', 'signed-out'];
+    'needs-scope', 'invalid-scope', 'needs-agent-profile', 'needs-approval', 'missing-requirement', 'no-worker-registered', 'no-worker-online', 'signed-out', 'storage-blocked'];
+/** A family's findings held for a person (findings.ts). A database not yet at v155 has no such table: see registerValidators. */
+const HELD_FINDINGS = `(SELECT COUNT(*) FROM finding fd WHERE fd.family_root=root.id AND fd.state='with-person')`;
 /** The index codes that wait on nobody: finished or running work, and every wait (needs-you.ts CODE_READING). */
 export const WAITING_CODES = ['cancelled', 'complete', 'running', 'queued',
     ...['stopping', 'updating', 'retry-scheduled', 'waiting-dependency', 'worker-at-capacity', 'planning-ready', 'scouting-ready'].filter(code => isWaitCode(code))];
@@ -179,6 +181,7 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
     (SELECT run FROM run_stop WHERE task_ref=c.ref_id AND resumed_at IS NULL ORDER BY requested_at DESC LIMIT 1) stop_run,
     (SELECT settled_at FROM run_stop WHERE task_ref=c.ref_id AND resumed_at IS NULL ORDER BY requested_at DESC LIMIT 1) stop_settled,
     COALESCE((SELECT substr(actor,13) FROM action_ledger WHERE task_id=root.id AND action='assignment claimed' AND source='work' ORDER BY id DESC LIMIT 1),root.coordinator_cid) owner_id,
+    ${HELD_FINDINGS} held_findings,
     pub.pr_url publication_url
   FROM ordered c JOIN families f USING(root_ref) JOIN admitted root ON root.ref_id=c.root_ref
   LEFT JOIN run result INDEXED BY work_result ON result.task_ref=c.ref_id AND result.id=c.result_id
@@ -216,6 +219,7 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
     WHEN state='cancelled' THEN 'cancelled'
     WHEN earlier_active>0 AND state='done' THEN 'earlier-active'
     WHEN stop_run IS NOT NULL THEN CASE WHEN stop_settled IS NULL THEN 'stopping' ELSE 'stopped' END
+    WHEN held_findings>0 AND state<>'failed' THEN 'finding-held'
     WHEN ready THEN CASE WHEN checked_id IS NULL THEN 'ready-to-check' ELSE 'complete' END
     WHEN state='done' AND question_id IS NOT NULL AND hold_id IS NULL THEN 'waiting-decision'
     WHEN state='done' THEN 'result-needs-attention'
@@ -224,6 +228,7 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
     WHEN live_lease IS NOT NULL THEN CASE WHEN question_id IS NOT NULL OR agent_ask IS NOT NULL THEN 'waiting-decision' ELSE 'running' END
     WHEN state='running' OR unfinished IS NOT NULL THEN 'vanished-run'
     WHEN EXISTS(SELECT 1 FROM sqlite_master WHERE type='trigger' AND name GLOB 'so_desktop_update_*') THEN 'updating'
+    WHEN hold_kind='backoff' AND substr(hold_reason,1,${STORAGE_HOLD_PREFIX.length})='${STORAGE_HOLD_PREFIX}' THEN 'storage-blocked'
     WHEN hold_kind='backoff' THEN 'retry-scheduled'
     WHEN hold_kind='decision' THEN 'waiting-decision'
     WHEN hold_kind='incident' THEN 'waiting-incident'
@@ -304,8 +309,11 @@ function registerValidators(store) {
     const asks = db.prepare("SELECT 1 AS hit FROM sqlite_master WHERE type='table' AND name='agent_question'").get() !== undefined;
     const projection = asks ? indexed : indexed.replace(AGENT_ASK, 'NULL')
         .replace(`'agent_ask_run',(SELECT run FROM agent_question WHERE id=page.agent_ask),'agent_ask_text',(SELECT substr(question,1,300) FROM agent_question WHERE id=page.agent_ask),`, '');
-    registered.set(db, projection);
-    return projection;
+    // Nor, before v155, any held findings: readingFleet's rule for a list read.
+    const findings = db.prepare("SELECT 1 AS hit FROM sqlite_master WHERE type='table' AND name='finding'").get() !== undefined;
+    const read = findings ? projection : projection.replace(HELD_FINDINGS, '0');
+    registered.set(db, read);
+    return read;
 }
 /** The list can't see processes: each task whose build Toolroll can't yet
  * confirm stopped, as the store reads it now (the task page's own reading).
@@ -430,7 +438,7 @@ function readWorkIndexPage(store, now, access, options, taskId = null) {
     'proof_verdict',(SELECT COALESCE(machine_verdict,verdict) FROM proof_verdict WHERE run=page_result_id),
     'proof_failed_check',(SELECT verdict='refuted' AND reasons_json LIKE '%approved verification command exited%' FROM proof_verdict WHERE run=page_result_id),'code',code,'needs',needs,'person_need',person_need,'lead_claim',lead_claim,'family_running',family_running,'rank',rank,'ask_rank',ask_rank,'list_order',${ORDER},'sort_at',sort_at,
     'checked_actor',checked_actor,'checked_at',checked_at,'checked_digest',checked_digest,'checked_detail',checked_detail,'question_id',question_id,
-    'dependency_id',dependency_id,'dependency_state',dependency_state,'hold_until',hold_until,'attempt_run',(SELECT id FROM run WHERE task_ref IN (SELECT ref_id FROM members WHERE root_ref=page.root_ref) AND (finished_at IS NOT NULL OR outcome IS NOT NULL) AND role NOT IN ('planner','reviewer') ORDER BY id DESC LIMIT 1),'custody_unresolved',custody_unresolved,'hold_kind',hold_kind,'hold_reason',substr(hold_reason,1,300),'hold_id',hold_id,'live_lease',live_lease IS NOT NULL,'approved',COALESCE(approved,0),
+    'dependency_id',dependency_id,'dependency_state',dependency_state,'hold_until',hold_until,'attempt_run',(SELECT id FROM run WHERE task_ref IN (SELECT ref_id FROM members WHERE root_ref=page.root_ref) AND (finished_at IS NOT NULL OR outcome IS NOT NULL) AND role NOT IN ('planner','reviewer') ORDER BY id DESC LIMIT 1),'custody_unresolved',custody_unresolved,'hold_kind',hold_kind,'hold_reason',substr(hold_reason,1,600),'hold_id',hold_id,'live_lease',live_lease IS NOT NULL,'approved',COALESCE(approved,0),
     'plan_changed',scope_digest IS NOT NULL AND digest IS NOT scope_digest,'head_ok',length(head_revision)=40 AND head_revision NOT GLOB '*[^a-f0-9]*','stop_run',stop_run,'unfinished',unfinished,'signed_out',signed_out,
     'question_run',(SELECT run FROM decision WHERE id=page.question_id),'agent_ask',page.agent_ask,
     'agent_ask_run',(SELECT run FROM agent_question WHERE id=page.agent_ask),'agent_ask_text',(SELECT substr(question,1,300) FROM agent_question WHERE id=page.agent_ask),'replaced_by',(SELECT successor FROM task_replacement WHERE task_ref=page.ref_id),
@@ -612,6 +620,13 @@ function itemOf(row, principal, probe, leadName, readiness, readable = false, no
     }
     if (code === 'stopped')
         detail = 'Paused by a person. The work so far is kept.';
+    // The storage check couldn't finish (dispose.ts holdForStorage): its own words, when it retries, and Try again.
+    if (code === 'storage-blocked') {
+        const until = s(row, 'hold_until');
+        detail = `${(s(row, 'hold_reason') ?? '').slice(STORAGE_HOLD_PREFIX.length)}${until === null ? '' : ` It tries again on its own ${retryWhenWords(until, now)}.`}`;
+        actionCode = 'unhold';
+        actionLabel = NEEDS.storage.action.label;
+    }
     if (code === 'cancelled')
         detail = 'This task was cancelled.';
     // The same failure again and again: what failed, and the two ways on.
@@ -671,7 +686,7 @@ function itemOf(row, principal, probe, leadName, readiness, readable = false, no
         actionCode = code === 'running' ? 'inspect-run' : 'inspect-task';
         actionLabel = code === 'running' ? 'Watch the build' : 'View task details';
     }
-    const read = actionCode !== null && ['inspect-task', 'inspect-run', 'inspect-stop', 'inspect-decisions', 'open-result'].includes(actionCode);
+    const read = actionCode !== null && ['inspect-task', 'inspect-findings', 'inspect-run', 'inspect-stop', 'inspect-decisions', 'open-result'].includes(actionCode);
     const primaryAction = actionCode === null ? null : { code: actionCode, label: actionLabel,
         target: { taskId: successor ?? (code === 'earlier-active' ? s(row, 'earlier_id') ?? id : actionCode === 'answer-decision' ? s(row, 'question_task') ?? id : id),
             runId: actionCode === 'answer-decision' ? n(row, 'question_run') || null : actionCode === 'answer-agent' ? n(row, 'agent_ask_run') || null : actionCode === 'inspect-run' && code === 'running' ? n(row, 'live_run') || null : actionCode === 'open-result' || actionCode === 'inspect-run' ? n(row, 'result_id') || null

package/dist/work-summary.d.ts

@@ -10,7 +10,7 @@ export type WorkTarget = {
 export type WorkAction = {
     /** `recheck-stopped`: Toolroll looks again whether a finished build stopped (nobody vouches for it);
      * `sign-in`: the agent's sign-in, in Settings; `answer-agent`: Reply to a running agent's question on the Agents board. */
-    code: DispatchAction | "inspect-task" | "inspect-run" | "inspect-stop" | "inspect-decisions" | "reconcile-run" | "open-pr" | "recheck-stopped" | "sign-in" | "answer-agent";
+    code: DispatchAction | "inspect-task" | "inspect-findings" | "inspect-run" | "inspect-stop" | "inspect-decisions" | "reconcile-run" | "open-pr" | "recheck-stopped" | "sign-in" | "answer-agent";
     label: string;
     target: WorkTarget;
     access: "read" | "operator-control" | "proposal-only" | "operator-handoff";

package/dist/work-summary.js

@@ -2,6 +2,7 @@
  * State, decisions, approval, process custody and proof still belong to
  * their existing owners. Action hints are navigation/proposal guidance,
  * never credentials or permission to bypass an owning operation. */
+import { heldFindingCount } from "./findings.js";
 import { machineChecked } from "./machine-check.js";
 import { resultCheckLevel } from "./result-follow-ups.js";
 import { diagnoseTaskDispatch } from "./dispatch.js";
@@ -28,7 +29,7 @@ export function workDecisionAction(taskId, decision, principal) {
         access: principal === "operator" ? "operator-control" : "proposal-only", retry: "refresh-before-acting" };
 }
 const PROPOSABLE = new Set(["answer-decision", "write-scope", "unhold"]);
-const READ_ACTIONS = new Set(["open-result", "open-pr", "inspect-task", "inspect-run", "inspect-stop", "inspect-decisions"]);
+const READ_ACTIONS = new Set(["open-result", "open-pr", "inspect-task", "inspect-findings", "inspect-run", "inspect-stop", "inspect-decisions"]);
 /** Pure counterpart for callers already holding the same facts. */
 export function workSummaryOf(facts, principal, resultDisplay) {
     const status = workStatusOf(facts, resultDisplay);
@@ -48,6 +49,8 @@ export function workSummaryOf(facts, principal, resultDisplay) {
             primary = make("resume-run", status.action.label, { runId: facts.control.run });
         else if (status.token === "waiting-decision" && questionAction !== null)
             primary = questionAction;
+        else if (status.token === "finding-held")
+            primary = make("inspect-findings", status.action.label);
         else if (facts.dispatch?.code === "vanished-run")
             primary = make("reconcile-run", "Check the unfinished attempt", { runId: facts.unfinishedRunId ?? null });
         else if (status.action.kind === "open-result" || status.action.kind === "open-review")
@@ -98,7 +101,7 @@ export function taskWorkSummaryOf(store, taskId, now, access) {
         ...(machineChecked(store, task.id) ? { machine: true } : {}),
         dispatch: diagnoseTaskDispatch(store, taskId, now, access.dependencyRepos ?? null), liveRunId: live?.id ?? null,
         unfinishedRunId: runs.find(one => one.outcome === null && one.role !== "reviewer")?.id ?? null,
-        control: taskControlOf(store, ref.id, now), openDecision: openWorkDecisionOf(store, ref.id, now),
+        control: taskControlOf(store, ref.id, now), openDecision: openWorkDecisionOf(store, ref.id, now), heldFindings: heldFindingCount(store, taskId),
         result: result === null ? null : {
             runId: result.id, role: result.role, outcome: result.outcome,
             verdict: proof?.verdict ?? null, reasons: proof?.reasons ?? [], accepted: store.proofAcceptance(result.id) !== null,

package/dist/workspace-ui.d.ts

@@ -106,7 +106,7 @@ export type NextAction = {
     label: string;
     /** Where the act lives — the page, not a URL, so every surface can
      * build its own link (a task page anchors, a row links out). */
-    kind: "open-result" | "open-review" | "open-task" | "open-run" | "open-pr";
+    kind: "open-result" | "open-review" | "open-task" | "open-findings" | "open-run" | "open-pr";
 };
 export type DisplayStatus = {
     /** The stable `data-work-status` token pages and tests key off. */
@@ -175,6 +175,8 @@ export type WorkFacts = {
         question: string;
         overdue: boolean;
     } | null;
+    /** Findings of this task's family that used their rounds and wait on a person (findings.ts). */
+    heldFindings?: number;
 };
 export type WorkStatus = DisplayStatus & {
     /** Which shortcut views list this row; `all` always does. */

package/dist/workspace-ui.js

@@ -470,7 +470,8 @@ function workStatusWordsOf(facts, resultDisplay) {
     const result = facts.state === "done" ? resultDisplay ?? resultStatusOf(facts.result, facts.publication) : null;
     const running = facts.liveRunId !== null || (dispatch?.condition === "running" && !REVIEW_TOKENS.has(dispatch.code));
     const question = (facts.state === "queued" || facts.state === "running" || facts.state === "done") ? facts.openDecision ?? null : null;
-    const needs = (dispatch !== null && !REVIEW_TOKENS.has(dispatch.code) && needsPerson(dispatch)) || question !== null;
+    const held = (facts.heldFindings ?? 0) > 0 && facts.state !== "cancelled";
+    const needs = (dispatch !== null && !REVIEW_TOKENS.has(dispatch.code) && needsPerson(dispatch)) || question !== null || held;
     const views = ["all"];
     if (needs)
         views.push("needs-you");
@@ -480,6 +481,10 @@ function workStatusWordsOf(facts, resultDisplay) {
         views.push("queued");
     if (facts.state === "done")
         views.push("completed");
+    const findingWords = (behind) => ({
+        token: "finding-held", label: "Needs you", detail: NEEDS.finding.sentence({}), tone: "attention", action: { label: NEEDS.finding.action.label, kind: "open-findings" }, views, rank: 0,
+        ...(behind === null ? {} : { diagnostics: [behind] }),
+    });
     const dispatchWords = (tone, rank, action) => ({
         token: dispatch?.code ?? "unknown",
         label: dispatch?.summary ?? "Status unknown",
@@ -505,6 +510,8 @@ function workStatusWordsOf(facts, resultDisplay) {
                 tone: "attention", action: { label: "Answer question", kind: "open-task" }, views, rank: 0,
                 diagnostics: [{ token: result.token, label: result.label, detail: result.detail, tone: result.tone }] };
         }
+        if (held && result.tone !== "problem")
+            return findingWords({ token: result.token, label: result.label, detail: result.detail, tone: result.tone });
         return { ...result, views, rank: needs ? 0 : 3 };
     }
     if (facts.state === "cancelled") {
@@ -519,6 +526,8 @@ function workStatusWordsOf(facts, resultDisplay) {
             }),
         };
     }
+    if (held && facts.state !== "failed")
+        return findingWords(dispatch === null ? null : { token: dispatch.code, label: dispatch.summary, detail: dispatch.detail, tone: running ? "live" : "attention" });
     if (running) {
         return dispatchWords("live", 1, { label: "Watch the build", kind: facts.liveRunId === null ? "open-task" : "open-run" });
     }