toolroll 0.9.104 → 0.9.105

package/dist/chat-decide.js

@@ -1,17 +1,3 @@
-/** Decisions finish in the chat app. A pushed card about a result, a failed task, a plan waiting for approval or a
- * pull request ready to merge carries buttons that act in place: Accept and finish, Request changes, Retry,
- * Approve & start, Merge. Every act that changes something asks twice ("Accept and finish 'X'? [Yes] [Cancel]"),
- * and each button is one opaque token bound to the exact result, receipt, plan or commit the card showed: a card a
- * newer result, a finished task or a changed plan has overtaken says so and acts on nothing.
- *
- * A person with the authority approves a plan or merges from their own linked chat by default (owner's decision,
- * docs/plans/toolroll-cards.md); their own off or limits (chat-approval.ts) and a signed mode's chatApprove term still
- * hold. A tap is theirs alone, and the card binds it to the exact terms. The change requests one youiyoux pass filed come as one card that shows every word of each
- * task's terms, with Approve all and each one's own Approve (the requests card, below).
- *
- * The same in every chat app: Telegram's bridge and the shared engine Slack, Discord and Teams run on (chat-delivery.ts)
- * offer, mint and answer these through the same tokens (the `channel` column). Every act runs through the door the
- * console uses. */
 import { routeChangeOf } from "./route-change.js";
 import { CONFIRM_TTL_MS, NIGHTLY_CHECK_ONLY, RELEASE_MERGES_ONLY, nightlyTaskRef, releaseTaskRef } from "./store.js";
 import { isAcpProfile } from "./acp-agents.js";
@@ -40,7 +26,6 @@ import { FILED_PER_PASS, requestKindWord, requestPassOf } from "./youiyoux-intak
 import { discordPlain } from "./reply-shape.js";
 import { PLATFORM_LIMITS } from "./text-limits.js";
 export { permissionPlainWords };
-/** The words, said once. */
 export const DECIDE_LABELS = {
     accept: "Accept",
     changes: "Send back",
@@ -49,9 +34,7 @@ export const DECIDE_LABELS = {
     "not-now": "Not now",
     merge: "Merge",
     look: "Look first",
-    /** A result's one link (docs/plans/plain-toolroll.md P1.5). */
     open: "Open result",
-    /** A plan card's one button: it shows the full terms, and the Approve sits under them. Never an approval itself. */
     review: "Review plan",
     details: "Details",
     edit: "Edit",
@@ -65,23 +48,15 @@ export const WHAT_SHOULD_CHANGE = "What should change?";
 const sha = (text) => createHash("sha256").update(text).digest("hex");
 const isAct = (one) => "act" in one;
 const title = (store, taskId) => phoneText(chatTitle(store, taskId), 60);
-// ---- the chatApprove term ----------------------------------------------------------
 export { chatApproveMode };
 const money = (micro) => `$${(micro / 1_000_000).toFixed(2)}`;
-/** A plan this person's chat may approve now: the term, the plan's exact bytes, and none of the reasons it must open
- * Toolroll instead. `digest` binds the scope and the plan document the card shows. */
-export function planInChat(store, taskId, approver, now, channel, root, 
-/** A youiyoux card asking (requestsOffer): its own words are checked there, every one shown. */
-from) {
-    // A change request's terms are outside text: they approve in chat only on its own card, which shows every word.
+export function planInChat(store, taskId, approver, now, channel, root, from) {
     if (from !== "requests" && store.filedViaOf(taskId) === YOUIYOUX_FILED_VIA)
         return { ok: false, why: OUTSIDE_TERMS };
     const ref = store.lookupRef(taskId);
     const scope = store.getScope(taskId);
     if (ref === null || ref.repo === null || scope === null)
         return { ok: false, why: "This plan isn't available now." };
-    // Approved only as dispatch reads it (approval policy): an old seal a lead token made, or one whose authority has
-    // ended, is no approval, so the person can approve it here.
     if (approvalOf(scope).approved && store.modeApprovalLive(ref.id, now))
         return { ok: false, why: "This plan is already approved." };
     if (ref.plan === "requested")
@@ -94,7 +69,6 @@ from) {
     const family = store.taskFamilyOf(taskId, [ref.repo], false);
     if (family === null || family.problem !== null || family.current.id !== taskId)
         return { ok: false, why: "A newer version of this task is current." };
-    // Terms a machine wrote, or checks that reach past the sandbox: a person reads every word before a yes, so the card shows them whole.
     const whole = ref.coordinatorCid !== null || quarantinedAuthor(scope.proposedVia ?? null);
     if (scope.profileState === "unresolved" || scope.routeEra == null || (scope.termsProblem ?? null) !== null)
         return { ok: false, why: "This plan can't say exactly which agents run, so you approve it in Toolroll." };
@@ -106,7 +80,6 @@ from) {
         return { ok: false, why: gateWords(gate) };
     if (store.scopePolicyRefusal(taskId) !== null)
         return { ok: false, why: "Your organisation's policy needs this plan approved in Toolroll." };
-    // A revision approves only against notes that still verify, as on the console.
     if (ref.revisionBriefArtifact !== null) {
         const brief = store.getArtifact(ref.revisionBriefArtifact);
         let verified = false;
@@ -119,7 +92,6 @@ from) {
         if (!verified)
             return { ok: false, why: "This revision's notes can't be verified here, so you approve it in Toolroll." };
     }
-    // The plan the card shows must be the saved one, verified, as the console's approval reads it.
     const plan = store.latestPlanArtifact(ref.id);
     if (plan !== null) {
         let verified = false;
@@ -132,16 +104,12 @@ from) {
         if (!verified)
             return { ok: false, why: "The saved plan can't be verified here, so you approve it in Toolroll." };
     }
-    // Terms shown whole are part of what the card is bound to, so the digest kept on its buttons covers those words.
     return { ok: true, modeDigest: mode.digest, source: mode.source, scope, whole, digest: sha(`${scope.digest}:${plan?.sha256 ?? ""}${whole ? `:${cardTermsDigest(scopeTermsText(scope))}` : ""}`) };
 }
-/** A ready pull request this person's chat may merge now, bound to the exact commit. */
 export function mergeInChat(store, taskId, run, approver, now, channel) {
     const ref = store.lookupRef(taskId);
-    // The nightly check of main never merges (release-once.md, part 3).
     if (ref !== null && nightlyTaskRef(store, ref.id))
         return { ok: false, why: NIGHTLY_CHECK_ONLY };
-    // A release's result merges only through its coordinator.
     if (ref !== null && releaseTaskRef(store, ref.id))
         return { ok: false, why: RELEASE_MERGES_ONLY };
     const publication = store.publicationForRun(run);
@@ -157,20 +125,10 @@ export function mergeInChat(store, taskId, run, approver, now, channel) {
         return mode;
     return { ok: true, modeDigest: mode.digest, source: mode.source, head: publication.headSha };
 }
-// ---- a youiyoux pass's card -----------------------------------------------------------------
-/**
- * What one youiyoux pass filed (youiyoux-intake.ts), as one card: every task still waiting on this person, Approve all,
- * and each one's own Approve and Open. Its terms are outside text (anyone who can write the project's folder wrote
- * them), so a task is approved here only when this card shows every word of its terms (chat-terms.ts), the whole card
- * arrives as one message every chat app shows as written, and every plan rule holds (planInChat). Its button carries
- * each task with the digest of the words shown; the seal recomputes that digest from the live scope (store.ts). A task
- * that can't be shown whole, or may not be approved here, is named with its link to Toolroll instead.
- */
 const REQUESTS_DIGEST = "youiyoux:";
 const OPEN_IN_TOOLROLL = "Open in Toolroll";
 const OUTSIDE_TERMS = "A youiyoux request is approved from its own youiyoux card, which shows every word, or in Toolroll.";
 const TOO_LONG = "its full terms don't fit in one chat message";
-/** Room left under each app's limit for the question a tap adds ("Approve 10 tasks?") and the names it leaves out. */
 const ROOM = 400;
 const listedDigest = (list) => `${REQUESTS_DIGEST}${list.map(one => `${one.taskId}=${one.digest}`).join(",")}`;
 const LISTABLE_ID = /^[A-Za-z0-9._-]{1,64}$/;
@@ -186,9 +144,6 @@ function listedOf(digest) {
     }
     return list.length === 0 || list.length > FILED_PER_PASS ? null : list;
 }
-/** Whether a card's words arrive as one message that shows each of them as written: within Telegram's part, Slack's and
- * (after its escapes) Discord's limits, with room for the question a tap adds. Teams draws card text as Markdown, where
- * a link's label hides its address, and Slack turns `:name:` into an emoji: there such words never approve. */
 export function shownWhole(text, channel) {
     if (!shownAsWritten(text, channel))
         return false;
@@ -199,18 +154,14 @@ export function shownWhole(text, channel) {
         case "teams": return false;
     }
 }
-/** Words a chat message never carries (chat-display.ts hides them elsewhere): a key, or an absolute folder on this
- * computer (a home folder, a drive). A project's own relative paths and a page's route are fine. */
 function privateWords(text) {
     return scanForSecrets(text).length > 0 || /\b\d{5,}:[A-Za-z0-9_-]{20,}\b/.test(text) || /(?:^|[\s"'`(<[=:,])(?:\/Users\/|\/home\/|\/root\/|~\/)|(?:[A-Za-z]:[\\/]|\\\\)/.test(text);
 }
-/** Still waiting on a person's yes: not finished, and no approval on its current terms. */
 function waitsForApproval(store, taskId) {
     const state = store.getTask(taskId)?.state;
     const scope = store.getScope(taskId);
     return state !== undefined && state !== "done" && state !== "cancelled" && scope !== null && !(scope.approvedDigest != null && scope.approvedDigest === scope.digest);
 }
-/** The card for the pass `taskId` was filed in, as it stands for this person now; null when nothing waits on them. */
 function requestsOffer(store, taskId, who, now, channel, root, said) {
     const waiting = requestPassOf(store, taskId).filter(id => {
         const ref = store.lookupRef(id);
@@ -232,10 +183,8 @@ function requestsOffer(store, taskId, who, now, channel, root, said) {
             ...(open.length === 0 ? [] : [[...(shown.length === 0 ? [] : ["Open in Toolroll to approve:"]), ...open.map(one => `${one.n}. ${one.name}${one.why === null ? "" : `: ${one.why}`}`)].join("\n")])].join("\n\n");
     };
     if (!mode.ok) {
-        // Nothing approves here: each task's title, files and goal in short, and its link.
         const summary = items.map(one => {
             const scope = store.getScope(one.taskId);
-            // The request's own goal, without the line the intake puts first (which request, on which route).
             const goal = scope.goal.startsWith("From youiyoux request ") && scope.goal.includes("\n\n") ? scope.goal.slice(scope.goal.indexOf("\n\n") + 2) : scope.goal;
             return [`${one.n}. ${one.name}`, `Files: ${scope.touches.length === 0 ? "any file (no file list)" : phoneText(scope.touches.join(", "), 160)}`, phoneText(goal, 200)].join("\n");
         });
@@ -252,12 +201,10 @@ function requestsOffer(store, taskId, who, now, channel, root, said) {
             item.why = "it needs your password in Toolroll";
             continue;
         }
-        // Shown whole means shown raw: words chat text otherwise hides (a key, a folder on this computer) stay in Toolroll.
         if (privateWords(scopeTermsText(plan.scope))) {
             item.why = "its terms name a key or a folder on this computer";
             continue;
         }
-        // In order, each whole or not at all: one that doesn't fit beside the ones before it is named instead.
         item.listed = { taskId: item.taskId, digest: shownTermsDigest(plan.scope) };
         if (!shownWhole(compose(), channel)) {
             item.listed = null;
@@ -275,8 +222,6 @@ function requestsOffer(store, taskId, who, now, channel, root, said) {
     }
     return { text: compose(), rows };
 }
-/** The tasks a youiyoux card's button names, as they stand now: each still waiting, within every rule, on exactly the
- * words the card showed (ready), or named with why not (skipped). */
 function requestsNow(store, tokenTask, digest, who, now, channel, root) {
     const listed = listedOf(digest);
     const repo = store.lookupRef(tokenTask)?.repo ?? null;
@@ -311,13 +256,9 @@ function requestsNow(store, tokenTask, digest, who, now, channel, root) {
     }
     return { ok: true, ready, skipped };
 }
-/** The owner's own yes from chat, sealed as theirs ("chat"), never as a mode's: it stands like the console's after the
- * mode or setting ends. `terms`: the digest of every word a youiyoux card showed, which the seal checks. */
 function sealPlanInChat(store, who, seat, repo, taskId, plan, now, terms) {
     if (!store.sealScopeApproval(taskId, who.name, now, {}, { kind: "chat", modeDigest: plan.modeDigest, ...(terms === undefined ? {} : { card: "terms", cardDigest: terms }) }))
         return false;
-    // The person's proof beside the seal, bound to these exact words (approval policy §1.2): a paired-chat tap, never a
-    // password. Release, deploy and the protected counters read it as a person's.
     const sealedDigest = store.getScope(taskId)?.approvedDigest ?? "";
     store.recordAction({ at: now.toISOString(), actor: who.name, repo, taskId, runId: null, action: APPROVAL_PROOF, outcome: "chat",
         source: "request", detail: approvalProofDetail(now.getTime(), store.accountOf(who.name)?.generation ?? 0, sealedDigest) });
@@ -325,8 +266,6 @@ function sealPlanInChat(store, who, seat, repo, taskId, plan, now, terms) {
         source: "request", detail: `via ${seat.channel} · chat binding #${seat.binding} · ${plan.source} ${plan.modeDigest}${terms === undefined ? "" : ` · youiyoux card, terms ${terms}`}` });
     return true;
 }
-/** A youiyoux card's yes: each task it names that still stands as shown is sealed, each with its own proof; the rest are
- * named, never approved. The card then offers what still waits, so one can be approved after another. */
 function approveRequests(store, seat, who, tokenTask, digest, target, body, message, root, now) {
     const read = requestsNow(store, tokenTask, digest, who, now, seat.channel, root);
     if (!read.ok)
@@ -347,8 +286,6 @@ function approveRequests(store, seat, who, tokenTask, digest, target, body, mess
         return { ack, edit: { text: `${body}\n\n${said}`, rows: skipped.length === 0 ? [] : linksFor(target), tokens: [] } };
     return { ack, edit: { text: again.text ?? said, ...mintDecideButtons(store, seat, target, again, now, message) } };
 }
-/** The plan card: title, goal in two lines, what changes, done when, and what the yes allows. On Telegram the yes's
- * terms come second, under the title, and the steps are fewer: the full plan is behind Edit. */
 export function planCardText(store, taskId, scope, root, channel) {
     const ref = store.lookupRef(taskId);
     const artifact = ref === null ? null : store.latestPlanArtifact(ref.id);
@@ -365,12 +302,10 @@ export function planCardText(store, taskId, scope, root, channel) {
         }
     }
     const bullets = (items, cap) => [...items.slice(0, cap).map(one => `• ${phoneText(one, 120)}`), ...(items.length > cap ? [`• and ${items.length - cap} more`] : [])];
-    // The goal in two lines at most: its first two, each kept short.
     const goal = scope.goal.split("\n").filter(one => one.trim() !== "").slice(0, 2).map(one => phoneText(one, 160));
     const allowing = [permissionPlainWords(scope.profile), scope.budgetMicrousd === null ? "no attempt limit" : `up to ${money(scope.budgetMicrousd)} per attempt`]
         .filter((one) => one !== null);
     const changed = routeChangeOf(store, taskId);
-    // Fallback agents are terms: in full on every card, near the top, and never cut.
     const chain = chainTermsLines(scope);
     if (channel === "telegram") {
         return [
@@ -404,23 +339,18 @@ export function planCardText(store, taskId, scope, root, channel) {
         `You're allowing: ${allowing.join(" · ")}`,
     ].join("\n");
 }
-// ---- what a card offers ---------------------------------------------------------------
-/** The acts a card about this target can take in chat right now, or null when none can (the card keeps its own
- * link). Reads only; nothing is minted. */
 export function decideOffer(store, target, who, now, channel, root) {
     const ref = store.lookupRef(target.taskId);
     if (ref === null || ref.repo === null || !who.repos.includes(ref.repo))
         return null;
     switch (target.kind) {
         case "result": {
-            // Accepting and requesting changes read the saved result: without it, the card keeps its link.
             if (root === undefined)
                 return null;
             const fresh = resultFresh(store, target.taskId, target.run, who, now, root);
             if (!fresh.ok)
                 return null;
             const look = { label: DECIDE_LABELS.open, path: chatResultHref(target.taskId, target.run, "changes") };
-            // A result accepted only with a reason ("Accept anyway") keeps its link: the reason is typed on the result.
             if (fresh.exception)
                 return null;
             return { text: null, rows: [[{ act: "accept", run: target.run, digest: fresh.receipt }, { act: "changes", run: target.run, digest: fresh.source }], [look]] };
@@ -436,8 +366,6 @@ export function decideOffer(store, target, who, now, channel, root) {
             if (!plan.ok)
                 return null;
             const release = deployGateScope(plan.scope);
-            // Checks beyond the sandbox seal only on the person's password (store.ts sealScopeApproval): the card says so and
-            // links to the approval in Toolroll, and offers no Continue or Approve that would dead-end. A release or a plan.
             if (passwordOnlySeal(plan.scope)) {
                 let head;
                 try {
@@ -449,7 +377,6 @@ export function decideOffer(store, target, who, now, channel, root) {
                 }
                 return { text: [...head, "", needsFullCard(plan.scope)].join("\n"), rows: [[{ label: "Approve in Toolroll", path: chatControlHref("approval", target.taskId) }]] };
             }
-            // A deploy gate is approved from chat only through its release card (chat-management.md §0a.5).
             if (release) {
                 const release = releaseInChat(store, target.taskId, who.name, now, channel, "offer", root);
                 if (!release.ok)
@@ -459,8 +386,6 @@ export function decideOffer(store, target, who, now, channel, root) {
                     rows: [[{ act: "approve", run: null, digest: releaseDigest(card), label: "Continue" }], [{ label: DECIDE_LABELS.edit, path: chatControlHref("approval", target.taskId) }, { act: "not-now", run: null, digest: releaseDigest(card) }]],
                     ...(channel === "telegram" ? { file: { name: card.fileName, text: card.full } } : {}) };
             }
-            // One line, one button and Details (docs/plans/plain-toolroll.md P1.5): Review plan shows the full terms in the
-            // card, and only there does Approve appear, bound to the same digest.
             return { text: planLineOf(store, target.taskId, ref.id),
                 rows: [[{ act: "approve", run: null, digest: plan.digest, label: DECIDE_LABELS.review }], [{ label: DECIDE_LABELS.details, path: chatControlHref("approval", target.taskId) }]] };
         }
@@ -473,7 +398,6 @@ export function decideOffer(store, target, who, now, channel, root) {
         }
     }
 }
-/** Is the result the card showed still the one waiting to be finished? */
 function resultFresh(store, taskId, run, who, now, root) {
     const assignment = assignmentOf(store, taskId, now, { principal: "operator", repos: who.repos }, root);
     if (assignment === null)
@@ -495,7 +419,6 @@ function retryStamp(store, taskId, who) {
     const stamp = chatTaskStamp(store, who, taskId);
     return stamp === null ? null : sha(stamp);
 }
-/** One fingerprint of what the card offers, without its tokens: a repaint with the same offer keeps its buttons. */
 export function offerFingerprint(offer) {
     return sha(JSON.stringify(offer));
 }
@@ -512,7 +435,6 @@ function mint(store, seat, message, spec, taskId, phase, now) {
     VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`).run(token, seat.channel, seat.binding, seat.chat, message, spec.act, phase, taskId, spec.run, spec.digest, now.toISOString(), new Date(now.getTime() + (phase === "offer" ? OFFER_TTL_MS : CONFIRM_TTL_MS)).toISOString());
     return token;
 }
-/** The card's buttons, minted now (message unknown until it is sent: `placeDecideTokens` puts them on it). */
 export function mintDecideButtons(store, seat, target, offer, now, message = null) {
     const tokens = [];
     const rows = offer.rows.map(row => row.map((one) => {
@@ -524,25 +446,20 @@ export function mintDecideButtons(store, seat, target, offer, now, message = nul
     }));
     return { rows, tokens };
 }
-/** Put freshly minted tokens on the message they ride: a tap on any other message proves itself stale. */
 export function placeDecideTokens(store, tokens, message) {
     const place = store.handle.prepare("UPDATE chat_decide_action SET message = ? WHERE token = ? AND message IS NULL");
     for (const token of tokens)
         place.run(message, token);
 }
-/** Every live button on one message stops working: the card was repainted, or one of its acts was taken. */
 export function retireDecideTokens(store, channel, chat, message, now) {
     store.handle.prepare("UPDATE chat_decide_action SET consumed_at = ? WHERE channel = ? AND chat = ? AND message = ? AND consumed_at IS NULL")
         .run(now.toISOString(), channel, chat, message);
 }
-/** Buttons minted for a send or an edit that didn't land: they never act. */
 export function dropDecideTokens(store, tokens, now) {
     const drop = store.handle.prepare("UPDATE chat_decide_action SET consumed_at = ? WHERE token = ? AND consumed_at IS NULL");
     for (const token of tokens)
         drop.run(now.toISOString(), token);
 }
-/** Whether a message still carries a button that acts (an offer, or an armed Yes or Cancel): a card whose acts were
- * all spent, as by Not now, needs fresh ones. */
 export function hasLiveDecideTokens(store, channel, chat, message, now) {
     return store.handle.prepare("SELECT 1 FROM chat_decide_action WHERE channel = ? AND chat = ? AND message = ? AND consumed_at IS NULL AND expires_at > ? LIMIT 1")
         .get(channel, chat, message, now.toISOString()) !== undefined;
@@ -550,23 +467,13 @@ export function hasLiveDecideTokens(store, channel, chat, message, now) {
 export function isDecideToken(store, token) {
     return token.startsWith("d:") && store.handle.prepare("SELECT 1 FROM chat_decide_action WHERE token = ?").get(token) !== undefined;
 }
-/** A release card's acts carry its card digest (release-card.ts), never a plan's. */
 const RELEASE_DIGEST = "release:";
-/** Why a password-only scope (passwordOnlySeal) isn't approved from chat, for a release or a plan. */
 const needsFullCard = (scope) => `This ${deployGateScope(scope) ? "release" : "plan"}'s checks run outside the sandbox, so this card can't approve it. Approve it in Toolroll, or ask your lead for its approval card, which shows every term.`;
-/** Whether only a person's password ceremony seals this scope (store.ts sealScopeApproval): checks that reach beyond the
- * sandbox (sign-ins, or none at all) or extra macOS services, sealed into its profile. */
 const passwordOnlySeal = (scope) => {
     const profile = scope.profile;
     return profile != null && (profile["checkAccess"] !== undefined || profile["machLookup"] !== undefined);
 };
 const releaseDigest = (card) => `${RELEASE_DIGEST}${card.digest}`;
-/**
- * Whether a release card's tap comes from the person's own private chat with Toolroll (chat-management.md §0a.5), from
- * the binding's own record, failing closed: Telegram, a private chat (a positive id, which Telegram makes equal to the
- * user's own id) that is the binding's chat and its user's; Slack, a direct-message channel (D…) that is the binding's.
- * Any other chat app, a missing chat or binding, or another person's binding is not.
- */
 export function privateReleaseChat(store, seat) {
     const row = store.handle.prepare("SELECT member, channel, approver FROM chat_binding WHERE provider = ? AND id = ? AND revoked IS NULL").get(seat.channel, seat.binding);
     if (row === undefined || String(row["approver"]) !== seat.approver || seat.chat !== String(row["channel"]))
@@ -577,15 +484,7 @@ export function privateReleaseChat(store, seat) {
         return /^D[A-Z0-9]+$/.test(seat.chat);
     return false;
 }
-/**
- * A deploy gate this person may approve from this chat now, through its release card: every plain-plan rule
- * (planInChat: their Approve from chat setting and limits, no coordinator-, lead- or scout-written text, organisation
- * policy, protected work), never a nightly check, only in their private chat, and the card as the live records say
- * it now (chat-management.md §0a.5).
- */
-export function releaseInChat(store, taskId, approver, now, channel, 
-/** The seat a tap came from, checked strictly; "offer" only where the card is drawn for the binding's own chat (no act). */
-seat, root) {
+export function releaseInChat(store, taskId, approver, now, channel, seat, root) {
     const plan = planInChat(store, taskId, approver, now, channel, root);
     if (!plan.ok)
         return plan;
@@ -605,7 +504,6 @@ seat, root) {
     catch {
         return { ok: false, why: "This release's terms can't be shown here, so you approve it in Toolroll." };
     }
-    // What changed is part of what's approved: a list that couldn't be read (or was refused as rewritten history) is no card.
     if (plan.scope.releaseTerms != null && card.changes.commits === null)
         return { ok: false, why: "This release's list of changes couldn't be read, so you approve it in Toolroll." };
     return { ok: true, card, modeDigest: plan.modeDigest, source: plan.source, scope: plan.scope };
@@ -627,18 +525,11 @@ function targetOf(row) {
         default: return { kind: "plan", taskId: row.taskId };
     }
 }
-/** Why the card's act no longer applies, or null while it still does — checked at the offer and again at the yes. */
-/**
- * A release card's terms, then its Approve (Continue, and a release card refreshed after it changed): the full terms
- * (a file on Telegram, where a message is limited; inline elsewhere), Approve and Cancel bound to this card's digest,
- * and on Telegram the card to show instead when the file didn't arrive: no Approve, a Continue to send it again.
- */
 function releaseContinue(store, seat, message, taskId, name, card, now, ack, lead) {
     const spec = { act: "approve", run: null, digest: releaseDigest(card) };
     const yes = mint(store, seat, message, spec, taskId, "yes", now);
     const cancel = mint(store, seat, message, spec, taskId, "cancel", now);
     const text = `${seat.channel === "telegram" ? card.short : `${card.short}\n\n${card.full}`}${lead === null ? "" : `\n\n${lead}`}`;
-    // Telegram carries the terms only as the file: Approve shows only once that file has arrived (telegram.ts).
     const again = seat.channel === "telegram" ? mint(store, seat, message, spec, taskId, "offer", now) : null;
     return { ack, file: { name: card.fileName, text: card.full },
         edit: { text: `${text}\n\nApprove release "${name}"? This approves exactly these terms${seat.channel === "telegram" ? `, every one in ${card.fileName}` : ""}.`,
@@ -665,7 +556,6 @@ function staleWhy(store, row, who, now, channel, root) {
         case "approve":
         case "not-now": {
             if (row.digest.startsWith(RELEASE_DIGEST)) {
-                // The button's own seat as it was minted: its binding's chat, checked against the binding's record.
                 const release = releaseInChat(store, row.taskId, who.name, now, channel, { channel, binding: row.binding ?? -1, chat: row.chat ?? "", approver: who.name }, root);
                 if (!release.ok)
                     return release.why;
@@ -682,7 +572,6 @@ function staleWhy(store, row, who, now, channel, root) {
             const plan = planInChat(store, row.taskId, who.name, now, channel, root);
             if (!plan.ok)
                 return plan.why;
-            // A deploy gate's plain plan card never approves it: only its release card does.
             if (deployGateScope(plan.scope))
                 return "This is a release: approve it from its release card.";
             if (passwordOnlySeal(plan.scope))
@@ -697,7 +586,6 @@ function staleWhy(store, row, who, now, channel, root) {
         }
     }
 }
-/** The links a card keeps once its acts are spent or stale: where to look, never a token. */
 export function linksFor(target) {
     switch (target.kind) {
         case "result": return [[{ label: DECIDE_LABELS.open, link: { label: DECIDE_LABELS.open, path: chatResultHref(target.taskId, target.run, "changes") } }]];
@@ -707,8 +595,6 @@ export function linksFor(target) {
         case "requests": return [[{ label: OPEN_IN_TOOLROLL, link: { label: OPEN_IN_TOOLROLL, path: YOUIYOUX_HOME_PATH } }]];
     }
 }
-/** Where a plan card's task is now, for a card whose buttons no longer act: the family's current version, named only
- * inside this person's projects, and linked only while it still waits on them. Never a live button. */
 export function planWhereNow(store, taskId, who, now, root) {
     const family = store.taskFamilyOf(taskId, who.repos, false);
     if (family === null)
@@ -729,21 +615,15 @@ export function planWhereNow(store, taskId, who, now, root) {
     return { said: `"${name}" is under way.`, rows: [] };
 }
 const QUESTION_STARTS = ["Accept \"", "Accept and finish \"", "Retry \"", "Approve and start \"", "Merge \"", "Approve release "];
-/** The card's words without a question this module appended. */
 function cardBody(shown) {
     const at = shown.lastIndexOf("\n\n");
     return at >= 0 && (QUESTION_STARTS.some(start => shown.startsWith(start, at + 2)) || /^Approve \d+ tasks\?/.test(shown.slice(at + 2))) ? shown.slice(0, at) : shown;
 }
-/**
- * One tap on a decide button, inside the caller's transaction. Null: not this module's token. The seat must be the
- * token's own (person, chat, message); a spent, expired or foreign button acts on nothing.
- */
 export function applyDecideTap(store, seat, input) {
     const raw = input.token.startsWith("d:") ? store.handle.prepare("SELECT * FROM chat_decide_action WHERE token = ?").get(input.token) : undefined;
     if (raw === undefined)
         return null;
     const read = readAction(raw);
-    // A saved button that can't be read acts on nothing, and says why.
     if (!read.ok)
         return { ack: `That button can't be read (${read.issues.map(issue => issue.line).join("; ")}). Nothing was done.`, ignored: true };
     const row = read.value;
@@ -761,17 +641,14 @@ export function applyDecideTap(store, seat, input) {
     const name = title(store, row.taskId);
     const body = cardBody(input.shown);
     const spend = () => {
-        // This token by its own id (it may never have been placed on a message), then every other button on the card.
         store.handle.prepare("UPDATE chat_decide_action SET consumed_at = ? WHERE token = ? AND consumed_at IS NULL").run(now.toISOString(), row.token);
         retireDecideTokens(store, seat.channel, seat.chat, input.message, now);
     };
-    // A plan's card names where its task is now (its newest version, or finished), and links it only while it waits.
     const here = target.kind === "plan" ? planWhereNow(store, row.taskId, who, now, input.root) : null;
     const stale = (why) => {
         spend();
         return { ack: why, edit: { text: `${body}\n\n${why} Nothing was done.${here === null || here.rows.length > 0 && why.startsWith("The plan changed") ? "" : ` ${here.said}`}`, rows: here?.rows ?? linksFor(target), tokens: [] } };
     };
-    // An expired button: the card says so and where the work is now, so it is never a dead end; the old button never acts.
     if (row.expiresAt <= now.toISOString()) {
         spend();
         return { ack: "That button expired.", edit: { text: `${body}\n\nThat button expired. Nothing was done.${here === null ? "" : ` ${here.said}`}`, rows: here?.rows ?? linksFor(target), tokens: [] } };
@@ -786,10 +663,6 @@ export function applyDecideTap(store, seat, input) {
     }
     const why = staleWhy(store, row, who, now, seat.channel, input.root);
     if (why !== null) {
-        // A release that changed while it was read: the new card, with fresh buttons, so the person reads it again.
-        // Through the same gate as Continue: the new terms go first (as a file where the chat app limits a message), and
-        // Approve shows only once they arrived; else a Continue to send them again. A release that is now password-only
-        // gets its card with the link to Toolroll.
         if (row.digest.startsWith(RELEASE_DIGEST) && row.act === "approve" && why === "This release changed while you were reading.") {
             spend();
             const release = releaseInChat(store, row.taskId, who.name, now, seat.channel, seat, input.root);
@@ -813,7 +686,6 @@ export function applyDecideTap(store, seat, input) {
             return { ack: "Okay, it waits.", edit: { text: `${body}\n\nNot now. It waits for you in Tasks.`,
                     rows: [[{ label: DECIDE_LABELS.edit, link: { label: DECIDE_LABELS.edit, path: chatControlHref("approval", row.taskId) } }]], tokens: [] } };
         }
-        // A release card's Continue: the card again from the live records, its full terms as a file, then Approve.
         if (row.act === "approve" && row.digest.startsWith(RELEASE_DIGEST)) {
             const release = releaseInChat(store, row.taskId, who.name, now, seat.channel, seat, input.root);
             if (!release.ok)
@@ -821,7 +693,6 @@ export function applyDecideTap(store, seat, input) {
             spend();
             return releaseContinue(store, seat, input.message, row.taskId, name, release.card, now, "Read the terms, then approve.", null);
         }
-        // A youiyoux card's Approve: how many still stand as the card showed them, and which don't (named, never approved).
         if (row.act === "approve" && row.digest.startsWith(REQUESTS_DIGEST)) {
             const read = requestsNow(store, row.taskId, row.digest, who, now, seat.channel, input.root);
             if (!read.ok)
@@ -835,8 +706,6 @@ export function applyDecideTap(store, seat, input) {
             return { ack: "Confirm below.", edit: { text: `${body}\n\n${asked}`,
                     rows: [[{ label: DECIDE_LABELS.yes, token: yes }, { label: DECIDE_LABELS.cancel, token: cancel }]], tokens: [yes, cancel] } };
         }
-        // A plan card's Review plan: the full terms in the card, and under them the Approve (the yes, bound to the same
-        // digest the card was minted with, checked again at the tap). Approve is reachable only from here.
         if (row.act === "approve") {
             const plan = planInChat(store, row.taskId, who.name, now, seat.channel, input.root);
             if (!plan.ok)
@@ -845,13 +714,11 @@ export function applyDecideTap(store, seat, input) {
             const spec = { act: "approve", run: null, digest: row.digest };
             const yes = mint(store, seat, input.message, spec, row.taskId, "yes", now);
             const later = mint(store, seat, input.message, { act: "not-now", run: null, digest: row.digest }, row.taskId, "offer", now);
-            // Terms a machine wrote go on the card word for word, or the yes isn't to what they say.
             if (plan.whole && scopeTermsText(plan.scope).length > PLATFORM_LIMITS[seat.channel] - ROOM)
                 return stale(`This plan's ${TOO_LONG}, so you approve it in Toolroll.`);
             return { ack: "Read the plan, then approve.", edit: { text: `${plan.whole ? `${name}\n\n${scopeTermsText(plan.scope)}` : planCardText(store, row.taskId, plan.scope, input.root, seat.channel)}\n\n${QUESTIONS.approve(name)} This approves exactly this plan.`,
                     rows: [[{ label: DECIDE_LABELS.approve, token: yes }], [{ label: DECIDE_LABELS.edit, link: { label: DECIDE_LABELS.edit, path: chatControlHref("approval", row.taskId) } }, { label: DECIDE_LABELS["not-now"], token: later }]], tokens: [yes, later] } };
         }
-        // The first tap asks; only the yes acts, bound to exactly what this button was.
         spend();
         const spec = { act: row.act, run: row.run, digest: row.digest };
         const yes = mint(store, seat, input.message, spec, row.taskId, "yes", now);
@@ -859,7 +726,6 @@ export function applyDecideTap(store, seat, input) {
         return { ack: "Confirm below.", edit: { text: `${body}\n\n${QUESTIONS[row.act](name)}`,
                 rows: [[{ label: DECIDE_LABELS.yes, token: yes }, { label: DECIDE_LABELS.cancel, token: cancel }]], tokens: [yes, cancel] } };
     }
-    // The yes: the act itself, through the door the console uses.
     spend();
     const done = (said, rows = []) => ({ ack: said, edit: { text: `${body}\n\n${said}`, rows, tokens: [] } });
     const notDone = (said) => ({ ack: "Not done.", edit: { text: `${body}\n\n✗ Not done: ${said}`, rows: linksFor(target), tokens: [] } });
@@ -884,7 +750,6 @@ export function applyDecideTap(store, seat, input) {
                 if (!release.ok)
                     return notDone(release.why);
                 const cardDigest = release.card.digest;
-                // The seal knows which card it came from: a chat seal of a deploy gate needs this evidence (store.ts).
                 if (!store.sealScopeApproval(row.taskId, who.name, now, {}, { kind: "chat", modeDigest: release.modeDigest, card: "release", cardDigest }))
                     return notDone("the release couldn't be approved from chat. Open it in Toolroll.");
                 const sealedDigest = store.getScope(row.taskId)?.approvedDigest ?? "";
@@ -893,7 +758,6 @@ export function applyDecideTap(store, seat, input) {
                 const where = `${CHANNEL_NAMES[seat.channel]} · chat binding #${seat.binding}`;
                 store.recordAction({ at: now.toISOString(), actor: who.name, repo: ref.repo, taskId: row.taskId, runId: null, action: "release approved in chat", outcome: "approved",
                     source: "request", detail: `via ${where} · ${release.source} ${release.modeDigest} · card ${cardDigest}` });
-                // Said everywhere the person hears from Toolroll (their other chats and push), naming the chat it came from.
                 const terms = release.scope.releaseTerms ?? null;
                 store.enqueueNotification({ dedupeKey: `release-approved-chat:${row.taskId}:${cardDigest}`, kind: "release-approved", recipient: who.name, pushClass: "attention",
                     subject: `Release${terms === null ? "" : ` ${terms.packageVersion}`} approved from ${CHANNEL_NAMES[seat.channel]}`,
@@ -910,8 +774,6 @@ export function applyDecideTap(store, seat, input) {
                 return notDone("This is a release: approve it from its release card.");
             if (passwordOnlySeal(plan.scope))
                 return notDone(needsFullCard(plan.scope));
-            // The one approval every road shares (scope.ts approve): the rules, two-person votes and the proof, as this person.
-            // plan.digest matched this button's kept digest above (staleWhy), so these are the words its card showed.
             const words = scopeTermsText(plan.scope);
             if (plan.whole && (plan.digest !== row.digest || words.length > PLATFORM_LIMITS[seat.channel] - ROOM))
                 return notDone("this plan changed. Open it in Toolroll.");
@@ -929,8 +791,6 @@ export function applyDecideTap(store, seat, input) {
             if (!merge.ok)
                 return notDone(merge.why);
             const via = `via ${seat.channel} · chat binding #${seat.binding} · ${merge.source} ${merge.modeDigest} · ${merge.head.slice(0, 12)}`;
-            // The approval is ledgered with the tap, so a bridge that stops before GitHub answers still leaves it on record;
-            // what GitHub then did is its own line (recordChatMerge).
             store.recordAction({ at: now.toISOString(), actor: who.name, repo: ref.repo, taskId: row.taskId, runId: row.run ?? null, action: "merge approved in chat", outcome: "approved",
                 source: "request", detail: via });
             return { ack: "Merging…", edit: { text: `${body}\n\nMerging…`, rows: [], tokens: [] }, merge: { runId: row.run ?? 0, taskId: row.taskId, by: who.name, repo: ref.repo, via } };
@@ -939,24 +799,20 @@ export function applyDecideTap(store, seat, input) {
             return { ack: "That button doesn't do anything now.", ignored: true };
     }
 }
-/** A chat merge's second ledger line, after the GitHub call: merged, or failed and why (its approval is the first). */
 export function recordChatMerge(store, merge, result, now) {
     store.recordAction({ at: now.toISOString(), actor: merge.by, repo: merge.repo, taskId: merge.taskId, runId: merge.runId, action: "merge from chat",
         outcome: result.ok ? "merged" : "failed", source: "request", detail: result.ok ? merge.via : `${merge.via} · ${phoneText(result.message, 160)}` });
 }
-/** What the card says once the merge came back. */
 export function mergedText(shown, result) {
     const body = shown.replace(/\n\nMerging…$/, "");
     return result.ok ? `${body}\n\n✓ Merged.` : `${body}\n\n✗ Not merged: ${result.message}`;
 }
-/** One open "What should change?" per person and chat: a newer one replaces it. */
 export function openDecidePrompt(store, seat, taskId, run, digest, now) {
     store.handle.prepare("UPDATE chat_decide_prompt SET consumed_at = ? WHERE channel = ? AND binding = ? AND chat = ? AND consumed_at IS NULL")
         .run(now.toISOString(), seat.channel, seat.binding, seat.chat);
     return Number(store.handle.prepare("INSERT INTO chat_decide_prompt (channel, binding, chat, task_id, run, digest, created_at, expires_at) VALUES (?,?,?,?,?,?,?,?)")
         .run(seat.channel, seat.binding, seat.chat, taskId, run, digest, now.toISOString(), new Date(now.getTime() + PROMPT_TTL_MS).toISOString()).lastInsertRowid);
 }
-/** The message that asked "What should change?", once it was sent. */
 export function placeDecidePrompt(store, id, message) {
     store.handle.prepare("UPDATE chat_decide_prompt SET message = ? WHERE id = ? AND message IS NULL").run(message, id);
 }
@@ -966,12 +822,9 @@ export function openPromptFor(store, seat, now) {
     return row === undefined ? null : { id: Number(row["id"]), taskId: String(row["task_id"]), run: Number(row["run"]), digest: String(row["digest"]),
         message: row["message"] == null ? null : String(row["message"]) };
 }
-/** Whether this message answers the prompt: the person's next message, unless it replies to some other message. */
 export function answersPrompt(prompt, replyTo) {
     return replyTo === null || (prompt.message !== null && prompt.message === replyTo);
 }
-/** The person's message after "What should change?": a revision of the exact result, with these words as its
- * feedback, through the result page's own service. Says what was sent, once. */
 export function applyDecideFeedback(store, seat, prompt, text, repos, root, now) {
     store.handle.prepare("UPDATE chat_decide_prompt SET consumed_at = ? WHERE id = ?").run(now.toISOString(), prompt.id);
     const name = title(store, prompt.taskId);
@@ -986,7 +839,6 @@ export function applyDecideFeedback(store, seat, prompt, text, repos, root, now)
     const revised = requestResultChanges(store, root, {
         run: prompt.run, batch: "", source: prompt.digest, actor: verified.who.name, repos: verified.who.repos,
         note: text, path: "", line: "", request: sha(`chat-decide:${seat.channel}:${prompt.id}`).slice(0, 32), allowMode: true,
-        // The chat's own verified person, answering "What should change?" in their own words.
         origin: "person",
     }, now);
     if (!revised.ok)
@@ -999,13 +851,11 @@ export function applyDecideFeedback(store, seat, prompt, text, repos, root, now)
         link: approved ? { label: "Open task", path: chatControlHref("task", revised.id) } : { label: "Review & start", path: chatControlHref("approval", revised.id) },
     };
 }
-/** The link a card keeps when it can't act in chat: a plan's is Review & start, where the password step lives. */
 export function decideFallbackLink(target) {
     if (target?.kind === "requests")
         return { label: OPEN_IN_TOOLROLL, path: YOUIYOUX_HOME_PATH };
     return target?.kind === "plan" ? { label: "Review & start", path: chatControlHref("approval", target.taskId) } : null;
 }
-/** Which card a pushed notification is, from its recorded kind and task — never from its words. */
 export function decideTargetOf(row) {
     if (row.taskId === null)
         return null;
@@ -1021,7 +871,6 @@ export function decideTargetOf(row) {
         return { kind: "failed", taskId: row.taskId };
     return null;
 }
-/** A plan card's one line: the task's number, "plan ready", and its title (docs/plans/plain-toolroll.md P1.5). */
 function planLineOf(store, taskId, number) {
     return `#${number}: plan ready · ${title(store, taskId)}`;
 }