toolroll 0.9.104 → 0.9.105

package/dist/lead-tools.js

@@ -30,18 +30,6 @@ import { RESULT_IMAGES_PER_TURN_CAP, selectResultImages } from "./chat-evidence.
 import { CHAT_CONTROLS, chatControlHref, isChatControl } from "./chat-controls.js";
 import { LIMITS } from "./decision.js";
 import { CHAT_TASK_ACTIONS, chatTaskRun, chatTaskStamp, isChatTaskAction } from "./chat-task-actions.js";
-/**
- * The lead's tools (mate arc §2): reads over the approver's ceiling and
- * proposals that become rows — never a write. Every result passes through
- * `leadView`, a fail-closed choke point (ruling 4; slice-1 review finding
- * 9): repos use `r1..rN` in the principal's order, and every string
- * that leaves is scrubbed of path-shaped text, digests, and account names
- * — titles, questions, and reasons included, because a human typed those
- * and a human may have typed a path into them. Consequences and
- * recommendations are never read at all. The coordinator keeps its own
- * richer DTOs. list_repos alone adds bounded display labels from admitted
- * projects after scrubbing; full paths and arbitrary text remain redacted.
- */
 import { Buffer } from "node:buffer";
 import { LEAD_ASK_OTHER, refArchived } from "./store.js";
 import { releaseFactsOf, tidyDigest, tidyGroups, tidyPreview, TIDY_DEFAULT_DAYS } from "./tidy.js";
@@ -86,11 +74,8 @@ import { utcMinute } from "./when-html.js";
 const REPO_ID = /^r[0-9]{1,3}$/;
 const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const ISO_STAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
-// ------------------------------------------------------------- leadView
-/** What a mate-facing string may not carry: an absolute path, a hex digest of 32+ digits, an account name. */
 const PATH_SHAPED = /(?:^|[\s"'`(<[=:,])(\/(?:[A-Za-z0-9._~-]+\/)*[A-Za-z0-9._~-]+)/g;
 const HEX_DIGEST = /\b[0-9a-f]{32,}\b/gi;
-/** Scrub one string. Exact repo paths and their basenames go first (v13: no paths, no basenames), then shapes. */
 export function redactForLead(text, view) {
     let out = text;
     for (const repo of view.repos) {
@@ -111,7 +96,6 @@ export function redactForLead(text, view) {
     }
     return out;
 }
-/** The choke point: every string inside a tool result, recursively, scrubbed. */
 export function leadView(value, view) {
     const walk = (node) => {
         if (typeof node === "string")
@@ -131,8 +115,6 @@ export function leadView(value, view) {
 export function leadViewContextFor(store, who) {
     return { repos: who.repos, names: store.listApprovers().map(one => one.name) };
 }
-/** Project names are deliberate display metadata, not a general basename
- * exemption. Invalid, sensitive or account-identifying labels stay opaque. */
 export function projectLabelForLead(path, index, names) {
     const base = path.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "";
     const label = redactForLead(base, { repos: [], names });
@@ -140,7 +122,6 @@ export function projectLabelForLead(path, index, names) {
         && !/\b\d{5,}:[A-Za-z0-9_-]{20,}\b/.test(label)
         ? label : `Project ${index + 1}`;
 }
-// ------------------------------------------------------------- helpers
 function repoIdOf(who, path) {
     if (path === null)
         return null;
@@ -153,7 +134,6 @@ function repoPathOf(who, id) {
     const path = who.repos[Number(id.slice(1)) - 1];
     return path ?? null;
 }
-/** Plain text of bounded length with no control characters, disguised text, or credential-shaped runs (finding 4). */
 function honest(value, maxChars) {
     return (typeof value === "string" &&
         value.trim() !== "" &&
@@ -166,7 +146,6 @@ function taskIdOf(args) {
     const id = args["task"];
     return typeof id === "string" && TASK_ID.test(id) ? id : null;
 }
-/** The task's ref inside the principal's ceiling, or null — a task outside answers not-found, never its repo. */
 function admittedRef(ctx, taskId) {
     const ref = ctx.store.lookupRef(taskId);
     if (ref === null || ref.repo === null)
@@ -174,7 +153,6 @@ function admittedRef(ctx, taskId) {
     const repoId = repoIdOf(ctx.who, ref.repo);
     return repoId === null ? null : { id: ref.id, repo: ref.repo, repoId };
 }
-/** The same text rule, for the gateway's proposals. */
 export function honestText(value, maxChars) {
     return honest(value, maxChars);
 }
@@ -190,9 +168,6 @@ export function readTouches(value) {
         return null;
     return value;
 }
-/** v39: the rubric a mate or coordinator proposal drafts — mandatory,
- * parsed the same way every other authoring road parses one. `null` means
- * the argument did not even parse into a non-empty rubric. */
 export function readAcceptanceArg(value) {
     const parsed = parseAcceptanceCriteria(value);
     if (parsed.problems.length > 0 || parsed.criteria.length === 0)
@@ -200,27 +175,16 @@ export function readAcceptanceArg(value) {
     return parsed.criteria;
 }
 const tooMany = () => ({ ok: false, message: `this turn already holds ${LEAD_MAX_PROPOSALS_PER_TURN} proposals` });
-/** How far back a task search reads: enough for a busy month, bounded. */
 const SEARCH_FAMILIES = 400;
-/** Words that never name work on their own. */
 const SEARCH_FILLER = new Set(["a", "an", "and", "the", "of", "to", "for", "in", "on", "at", "by", "with", "about", "from", "that", "this", "these", "those", "it", "its", "is", "was", "my", "our", "your", "thing", "things", "stuff", "one", "task", "tasks", "work", "job", "please", "fix", "make"]);
-/** The operator's words for a task, lowercased, without filler. */
 function searchWords(text) {
     return [...new Set(text.toLowerCase().split(/[^a-z0-9]+/).filter(word => word.length > 1 && !SEARCH_FILLER.has(word)))].slice(0, 12);
 }
-/** How many of the words appear in the task's own text (a word also matches its plural or a longer form). */
 function searchHits(words, fields) {
     const text = fields.join(" ").toLowerCase();
     return words.filter(word => text.includes(word.length > 3 && word.endsWith("s") ? word.slice(0, -1) : word)).length;
 }
 const notFound = () => ({ ok: false, message: "not-found: no such task in your projects" });
-// ------------------------------------------------- shared queries (§2)
-// The one set of queries both the lead and the MCP gateway read. Every
-// row names its repo by INDEX into the caller's admitted list; the view
-// then labels it — `rN` for the lead, the path for a coordinator whose
-// allowlist is its authority. Consequences and recommendations are never
-// read here at all.
-/** Replace every `repoIndex` with a `repo` label, recursively. */
 export function labelRepos(value, label) {
     const walk = (node) => {
         if (Array.isArray(node))
@@ -240,8 +204,6 @@ export function labelRepos(value, label) {
     return walk(value);
 }
 export function recapOver(store, repos, now, since) {
-    // Ages arrive rounded to the hour, so the horizon is inclusive by half an
-    // hour: a row newer than `since` is never dropped (finding 8).
     const horizonHours = since === null ? Infinity : Math.max(0, (now.getTime() - Date.parse(since)) / 3_600_000) + 0.5;
     const snapshot = store.chatSnapshot(repos, now);
     const recent = (rows) => rows.filter(one => one.ageHours <= horizonHours);
@@ -258,8 +220,6 @@ export function recapOver(store, repos, now, since) {
             queued: mine(snapshot.tasks).filter(one => one.state === "queued").length,
             finished: mine(tasks).filter(one => one.state === "done").length,
             failed: mine(tasks).filter(one => one.state === "failed").length,
-            // v39: a finished task whose proof is short or refuted reads as
-            // waiting on you too — the same split the inbox and board make.
             needsVerification: mine(tasks).filter(one => one.state === "done" && !one.proofAccepted && (one.proofVerdict === "short" || one.proofVerdict === "refuted")).length,
         };
     });
@@ -282,12 +242,6 @@ export function decisionsOver(store, repos, now) {
         truncated: snapshot.decisionsSaturated,
     };
 }
-/**
- * One decision as a proposer may read it (mate arc v3, rule change #3):
- * the question, each option's id, label, reversibility, and consequence —
- * never the recap or the builder's recommendation. `repoIndex` names the
- * task's repo for the view; a decision outside `repos` is null.
- */
 export function decisionOver(store, repos, decisionId, now) {
     const decision = store.getDecision(decisionId);
     if (decision === null)
@@ -299,8 +253,6 @@ export function decisionOver(store, repos, decisionId, now) {
     const repoIndex = repos.indexOf(ref.repo);
     if (repoIndex === -1)
         return null;
-    // "Open" is derived, not stored (v3 review, finding 7): a decision past
-    // its deadline is expired here whether or not the sweep has run.
     const state = decision.supersededReason !== null ? "closed" : decision.state === "open" && decision.deadline !== null && Date.parse(decision.deadline) <= now.getTime() ? "expired" : decision.state;
     return {
         repoIndex,
@@ -326,7 +278,6 @@ export function queueOver(store, repo, now) {
     return { queueRevision: store.queueRevision(), columns: ordered.map(([column, tasks]) => ({ column, tasks })) };
 }
 export const ISO_STAMP_RULE = ISO_STAMP;
-/** Whether a queued task's scope stands approved as written. */
 function scopeStandingOf(store, taskId) {
     const scope = store.getScope(taskId);
     if (scope === null)
@@ -337,15 +288,6 @@ function scopeStandingOf(store, taskId) {
 }
 const ROLE_WORD = { plan: "planner", build: "builder", repair: "repair", review: "reviewer" };
 const ROLE_OF_WORD = { planner: "plan", plan: "plan", builder: "build", build: "build", repair: "repair", reviewer: "review", review: "review" };
-/**
- * THE AGENTS A TASK RUNS UNDER, as chat reads them (v48): the task's size,
- * the same one-line summary the task page and CLI
- * print, each role's exact agent with its reasons, the standing of those
- * agents (approved / awaiting approval / recommended), and — for a
- * proposal — only the configured, role-valid choices an operator could
- * pick. Nothing here is a term chat may bind on its own; every change goes
- * through a confirmed card into the one authenticated edit transaction.
- */
 export function agentsOver(store, taskId, now) {
     const ref = store.lookupRef(taskId);
     if (ref === null)
@@ -379,31 +321,18 @@ export function agentsOver(store, taskId, now) {
         demands: route.demands.filter(reason => !/review/i.test(reason)),
         agents: route.legs.filter(leg => leg.phase !== "review").map(leg => ({ role: ROLE_WORD[leg.phase], provider: leg.provider, model: leg.model, chosen: chosenWords(leg), reasons: leg.reasons.map(reason => reason.replace("builder and reviewer", "builder")), problem: leg.problem })),
         problems: routeProblems(route),
-        // Only SELECTABLE choices are offered to the lead: a current agent the
-        // configuration no longer names appears under `agents` (what runs
-        // today) and nowhere a proposal could pick it.
         choices: Object.fromEntries(PHASES.filter(phase => phase !== "review").map(phase => [ROLE_WORD[phase], choices[phase].filter(one => one.selectable).map(one => ({ provider: one.provider, model: one.model, current: one.current }))])),
     };
 }
-/**
- * The tools every request advertises (docs/plans/lead-deferred-tools.md): the ones most replies use, and every tool a
- * guard requires read in an earlier step (search_project_memory before any proposal, get_capabilities before work that
- * needs an agent, get_result before propose_review, get_decision before propose_answer). The rest are found with
- * find_tools and advertised from the next request of the same reply.
- */
 export const LEAD_CORE_TOOLS = new Set([
     "find_tools", "get_brief", "recap", "list_repos", "get_project_context", "get_project_activity", "search_project_memory", "get_capabilities",
     "list_tasks", "get_task", "get_result", "get_diff", "get_check_log", "list_decisions", "get_decision",
     "get_actions", "get_action_status", "propose_action", "propose_task", "propose_start", "propose_scope", "propose_steer",
     "propose_answer", "propose_review", "remember", "ask_owner", "commit_to",
-    // The lead's queue verbs: basic, and small enough that deferring them saves almost nothing.
     "queue", "propose_next", "propose_reserve", "propose_hold", "propose_unhold", "propose_cancel",
-    // Task and result acts a reply uses often (links to a control, a result's images and evidence, the task's own acts):
-    // small, so deferral is kept for the large, occasional families (flows, subagents, sweeps, project tools).
     "show_control", "get_controls", "get_result_images", "get_acceptance_evidence", "offer_approval", "propose_task_action", "propose_agents",
     "get_agents", "propose_dependency_repair",
 ]);
-/** Words a deferred tool is found by, beyond its name and description. */
 const LEAD_TOOL_KEYWORDS = {
     show_card: ["findings", "handover", "card", "table", "chart", "graph", "report", "summary", "numbers", "data", "spend", "projects", "builders", "workers", "integrations", "show", "dashboard"],
     propose_flow: ["flow", "automation", "workflow", "schedule", "trigger", "every", "when", "email", "inbox", "sort", "follow-up", "nudge"],
@@ -427,16 +356,13 @@ const LEAD_TOOL_KEYWORDS = {
     release_commitment: ["promise", "commitment", "release", "forget"],
     get_person: ["person", "people", "who", "member", "teammate"],
 };
-/** At most this many find_tools searches per reply, results per search, and bytes of found tool schemas per reply. */
 export const FIND_TOOLS_PER_TURN = 3;
 export const FIND_TOOLS_MAX_RESULTS = 6;
 export const FIND_TOOLS_SCHEMA_BYTES = 48_000;
 const FIND_TOOLS_NONE = "Nothing matched. The other tools cover flows, subagents, sweeps, agents and models, project tools and integrations, controls and settings pages, holds and the queue, task actions (retry, stop, merge), result images and evidence, people, and promises — search again with one of those words.";
 const MAKE_WORDS = new Set(["make", "add", "create", "set", "draft", "new", "start", "change", "edit", "build", "run", "hold", "cancel", "release", "move", "switch", "turn"]);
 const LOOK_WORDS = new Set(["show", "list", "see", "what", "which", "how", "check", "read", "look", "find", "open", "where"]);
-/** The deferred tools a query finds, best first: an exact name, then words in the name, keywords and description. */
 export function findLeadTools(query) {
-    // A plural matches its singular ("sweeps" finds sweep tools).
     const words = query.toLowerCase().split(/[^a-z0-9-]+/).filter(one => one.length >= 3).map(one => one.length > 4 && one.endsWith("s") && !one.endsWith("ss") ? one.slice(0, -1) : one);
     const exact = query.trim().toLowerCase();
     const scored = LEAD_TOOLS.filter(tool => !LEAD_CORE_TOOLS.has(tool.name)).map(tool => {
@@ -445,7 +371,6 @@ export function findLeadTools(query) {
         let score = name === exact ? 100 : 0;
         for (const word of words)
             score += (name.includes(word) ? 5 : 0) + (keywords.includes(word) ? 3 : 0) + (description.includes(word) ? 1 : 0);
-        // What the person wants done leans the match: making or changing something → a proposal; looking → a read.
         if (score > 0 && words.some(word => MAKE_WORDS.has(word)))
             score += name.startsWith("propose_") ? 4 : 0;
         if (score > 0 && words.some(word => LOOK_WORDS.has(word)))
@@ -454,12 +379,10 @@ export function findLeadTools(query) {
     }).filter(one => one.score > 0).sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name));
     return scored.slice(0, FIND_TOOLS_MAX_RESULTS).map(({ tool }) => ({ name: tool.name, summary: summaryLine(tool.description) }));
 }
-/** A description's first sentence, at most 160 characters. */
 function summaryLine(description) {
     const first = /^(.+?[.!?])(\s|$)/.exec(description)?.[1] ?? description;
     return first.length <= 160 ? first : `${first.slice(0, 157).trimEnd()}…`;
 }
-/** A fixed destination this person may open, checked once for show_control and for a card's Button. */
 function controlTarget(ctx, args) {
     const control = args["control"];
     if (!isChatControl(control))
@@ -486,7 +409,6 @@ function controlTarget(ctx, args) {
     }
     return { ok: true, control, task, project, run };
 }
-/** A card's Button: a control by show_control's own checks, or a proposal drafted earlier in this very reply. */
 function cardButtonOf(ctx, props) {
     if (props["proposal"] !== undefined) {
         const proposal = ctx.store.getLeadProposal(Number(props["proposal"]));
@@ -502,7 +424,6 @@ function cardButtonOf(ctx, props) {
         return target;
     return { ok: true, button: { label: CHAT_CONTROLS[target.control].label, path: chatControlHref(target.control, target.task ?? "", target.run, target.project ?? undefined) } };
 }
-/** What a card reads, as this person, through the reads the lead's own tools use. */
 function cardReaderOf(ctx) {
     const capabilities = (repos) => capabilitiesOf(ctx.store, { repos, admitted: ctx.who.repos, actor: ctx.who.name, integrations: ctx.integrations?.() ?? integrationsNow(integrationIoOf(ctx)), ...(ctx.authMode === undefined ? {} : { authMode: ctx.authMode }), now: ctx.now });
     return { store: ctx.store, now: ctx.now, who: ctx.who, ...(ctx.evidenceRoot === undefined ? {} : { evidenceRoot: ctx.evidenceRoot }), integrations: () => ctx.integrations?.() ?? integrationsNow(integrationIoOf(ctx)),
@@ -511,7 +432,6 @@ function cardReaderOf(ctx) {
 }
 const LEAD_TOOL_HANDLERS = {
     find_tools: {
-        // Counted before the call is read, so an invalid search still uses one of the reply's three.
         prepare: (ctx, raw) => { if (ctx.findTools !== undefined)
             ctx.findTools.searches++; return raw; },
         description: "Find the lead's other tools by what you want to do — flows, subagents, sweeps, agents and models, project tools and integrations, controls and settings pages, holds and the queue, task actions (retry, stop, merge), result images and evidence, people, promises. Search before saying something can't be done. Matching tools become available from your next step in this reply: call them then, not in the same step.",
@@ -609,7 +529,6 @@ const LEAD_TOOL_HANDLERS = {
                 return { ok: false, message: 'Use propose_flow for flows.' };
             if (operation.startsWith('subagent_'))
                 return { ok: false, message: 'Use propose_subagent for subagents.' };
-            // A Start card is drafted only by propose_start, whose preview comes from the turn loop, never from arguments.
             if (operation === 'task_start')
                 return { ok: false, message: 'Use propose_start for a small change to start now.' };
             const input = { ...args };
@@ -731,7 +650,6 @@ const LEAD_TOOL_HANDLERS = {
             if (task === null || admittedRef(ctx, task) === null)
                 return notFound();
             const current = ctx.store.taskFamilyOf(task, ctx.who.repos, false)?.current.id ?? task;
-            // Its buttons go to the paired Telegram chat (pairedHere), so it is that chat's authority that counts.
             const plan = planInChat(ctx.store, current, ctx.who.name, ctx.now, "telegram", ctx.evidenceRoot);
             if (!plan.ok)
                 return { ok: true, body: { offered: false, task: current, why: plan.why, control: "approval" } };
@@ -870,7 +788,6 @@ const LEAD_TOOL_HANDLERS = {
             const ref = ctx.store.lookupRef(task);
             if (ref === null)
                 return { ok: false, message: "That task is not in your projects." };
-            // Only what THIS ask selected is recorded under the turn; the turn's own cap still holds across asks.
             const recorded = new Set(ctx.selectEvidence?.(selection.selected.map(one => ({ taskId: task, taskRef: ref.id, run: selection.run, artifact: one.artifact, sha256: one.sha256, format: one.format, bytes: one.bytes, caption: one.caption }))) ?? []);
             const documents = ctx.mediaDelivery === "documents";
             const selectedImages = documents ? selection.selected.filter(one => recorded.has(one.artifact)) : selection.selected;
@@ -994,7 +911,6 @@ const LEAD_TOOL_HANDLERS = {
             const reachable = (repo) => ctx.who.repos.includes(repo) && ctx.store.accountCanAccess(ctx.who.name, repo);
             const needsYou = (flow, definition, card) => {
                 const at = definition?.stages.find(one => one.id === card.stage);
-                // A "Person chooses" zone waits for the card's person; a "Person decides" one for its decider.
                 if (at?.kind === "choose")
                     return flowPersonOf(card, flow) === ctx.who.name;
                 if (at?.kind !== "approval")
@@ -1014,7 +930,6 @@ const LEAD_TOOL_HANDLERS = {
                 const active = cards.filter(one => one.state === "active"), finished = cards.filter(one => one.state !== "active").slice(-10);
                 return { ok: true, body: {
                         flow: flow.id, name: flow.name, project: repoIdOf(ctx.who, flow.repo),
-                        // Browser use (flow-browser.ts), only for a flow whose script zones start one. Names never reach the model.
                         ...(() => {
                             const view = browserViewOf(ctx.store, flow);
                             return view === null ? {} : { browser: view.status === "allowed" ? "allowed: its browser zones may start Chromium (turn_off_browser stops it)"
@@ -1045,13 +960,11 @@ const LEAD_TOOL_HANDLERS = {
                         cards: [...active, ...finished].map(card => ({
                             card: card.id, title: card.title, ...(card.description === null ? {} : { description: card.description.slice(0, 300) }),
                             at: titleOf(card.stage) ?? card.stage, state: card.state, needsYou: card.state === "active" && needsYou(flow, definition, card),
-                            // Names never reach the model; a decision says whose it is in its own terms.
                             waiting: card.state === "active" && definition.stages.find(one => one.id === card.stage)?.kind === "choose" && card.waiting !== null
                                 ? (flowPersonOf(card, flow) === ctx.who.name ? "Waiting for you to choose (operation choose: choice by number, or note to reply)" : "Waiting for someone else to choose")
                                 : card.state !== "active" || definition.stages.find(one => one.id === card.stage)?.kind !== "approval" || card.waiting === null ? card.waiting
                                     : needsYou(flow, definition, card) ? "Waiting for you to approve or send it back" : "Waiting for someone else to decide",
                             task: card.task ?? card.primaryTask, ...(card.note === null ? {} : { lastNote: card.note.slice(0, 300) }),
-                            // Names never reach the model: people read as you or a subagent.
                             owner: card.owner === null ? null : card.owner === ctx.who.name ? "you" : "another person", following: ctx.store.flowCardWatchers(card.id).includes(ctx.who.name),
                             ...(() => {
                                 const said = ctx.store.flowComments(card.id).filter(one => one.kind === "comment");
@@ -1064,7 +977,6 @@ const LEAD_TOOL_HANDLERS = {
                             return { trigger: trigger.id, kind: trigger.kind, what: config === null ? "can't be read" : describeTrigger(config, ctx.store),
                                 startsIn: titleOf(config?.zone ?? definition.start), state: trigger.state, lastCheck: trigger.lastOutcome };
                         }),
-                        // "Runs on its own" is the owner's own yes, on its card or the flow page; a model only proposes it.
                         runsOnItsOwn: (() => {
                             const own = activeUnattendedGrant(ctx.store, flow.id, ctx.now);
                             return own === null || own.terms.flowRevision !== flow.revision ? { on: false, change: `Propose allow_unattended with days: the owner's own yes turns it on. Or the flow page: /flows/${flow.id}` }
@@ -1085,7 +997,6 @@ const LEAD_TOOL_HANDLERS = {
                             cards: cards.length, needYou: cards.filter(card => needsYou(flow, definition, card)).length, triggers: ctx.store.flowTriggers(flow.id).length };
                     }),
                     templates: FLOW_TEMPLATES.map(one => ({ template: one.id, about: one.about })),
-                    // Scripts belong to a project, not a flow: they exist (and can be saved) before any flow does.
                     scripts: (repo === null ? ctx.who.repos : [repo]).filter(reachable).map(one => ({ project: repoIdOf(ctx.who, one), scripts: ctx.store.flowScripts(one).map(script => ({ name: script.name, about: script.about, version: script.version })) })),
                     rule: "Scripts belong to a project, not to a flow: save one with propose_flow save_script and the project's repo, even before any flow exists. A 'check' step in any flow of that project runs it by name.",
                 } };
@@ -1093,7 +1004,6 @@ const LEAD_TOOL_HANDLERS = {
     },
     propose_flow: {
         description: "Draft a flow change as a card the operator confirms. To make a flow, create with a template or the steps in plain names; leave instructions out unless the operator gave them, and use decider 'me' when they decide. To change one, edit with the whole step list, keeping existing steps by id. For cards use add_card, move_card, approve, send_back with the operator's note, or cancel_card; find the card by what it is about; comment (with @name to ping someone), assign and follow here too. For triage, spam, lead, effort or exception routing, start from the matching template, with the sort as the first step. Use remindAfter and thenMoveTo for follow-ups and decisions that stall. The Issues to PRs template runs GitHub issues labelled toolroll through build, approval, pull request and a comment on the issue. When the operator asks for something to happen every time (fix CI when it fails, turn labelled issues into tasks, queue work overnight, review what went wrong every morning), offer the matching starter; each is one yes, and none merges without a person. When someone new wants a support desk, bug triage, sales follow-up or requests handled, a kit sets up the subagent and its flow in one card. Subagents: propose_subagent adds one (from a template: support, sales, ops, triage), changes one rule section (edit_section), pauses, resumes or removes it, passes it a note, or answers its question for the operator; put it to work with a flow here. When the operator says something like 'Maya can approve refunds up to $100 now', change that section of her soul file; when it's for this week or a one-off, pass it as a note. Subagents use the project's tools under a rule per action (do it, ask first: the operator approves each exact call, never, or up to a limit on a number); propose_subagent use_tool, stop_tool and tool_rule change them, and when a rule has a limit also change the soul file so its words agree. forget or edit_memory when the operator says a subagent has something wrong; a rule change it suggests is a question for the operator, answered only as they say. propose_subagent add_routine puts a card on its desk on a schedule; propose_subagent undo undoes a tool call only when its action has an undo set (tool_rule undoWith). Actions: starter: switch on a starter flow in a project (repo, starter: ci-fix files a fix task when CI fails on the main branch, issue-task makes a task of each GitHub issue labelled toolroll, overnight holds cards added in the day until 22:00 and leaves results for the morning, plane-review reviews the plane's last 24 hours every morning and turns each problem worth fixing into a researched fix and a pull request) — its zones and trigger in one card; offer the matching one when the operator says to do something every time. kit: set up a starter kit in a project (repo, kit: support-desk, bug-triage, sales-follow-up or ops-requests) — a subagent, the flow it works and its buttons, in one card; prefer it when the operator wants a support desk, bug triage, sales follow-up or requests handled. create: a template, or the steps in order (each leads to the next; Done is added; instructions may be left out). 'request' calls a web address (method, url with its host written out, headers — {{secret.NAME}} uses a secret the operator saved on the step, never in chat — and body); 'email' sends mail (to, subject, body; {{card.email}} is the card's email address); 'tool' calls one of the project's tools (server: the tool's name from get_project_tools, tool: its function, args: an object). Put a decision before any of these when they send what a model wrote or what an outsider sent. A 'draft' step has Claude write something from the card (instructions: what to write); follow it with an approval step (decider 'owner' asks the flow's owner in their chat app, where they can approve, edit or send it back), then an 'update' or 'notify' step whose message is '{{stage.<draft id>}}'. A 'sort' step has Jev pick one of its answers; make it the first step (never a holding step before it, or new cards wait unsorted): question, answers (answer, means: a few words Jev reads, goesTo: a step), sureAt (percent, default 80), ifNotSure (a step; otherwise the card waits for a person), and up to 3 alsoNote (score with levels lowest first, or yes-no); a sort has no next, so give each branch's last step its own next. A 'pull-request' step opens a pull request for the card's built result and waits for CI: next when it passes, ifFails when it fails (only this step defaults it: to the build before it, as a revision carrying the failing check); merge ('squash', 'merge' or 'rebase') merges once checks pass, and needs an approval step before it on every path. waitFor 'hours' with from and until (like '22:00' and '06:00') holds cards until the clock is inside those hours. A 'wait' step, after an 'email' step, waits for a reply to that email from someone it went to (waitFor 'reply', the default): next is where a reply goes (the reply is {{stage.<wait id>}}), ifNoReply where the card goes when none comes within wait (like '3 days', up to 30 days); waitFor 'time' just waits, then next. Any step but wait and done can have remindAfter (like '2 days': whoever it waits on is reminded once; 'none' removes it) and, on holding and approval steps, thenMoveTo (a step the card moves to then). subagents (get_subagents): an approval step with subagent (its short name) is decided by that subagent within its rules, and it hands hard ones to the step's decider; a 'subagent' step (subagent, instructions, routes of answer and goesTo) has it read the card, pick where it goes and write what the next steps send (the email body is then {{stage.<id>}}), asking the flow's owner when its rules say to. edit: the full step list, keeping existing steps by id — what a kept step leaves out carries over. add_card (starts in the first zone unless zone is named), move_card, approve, send_back (needs a note), cancel_card, comment (note; @name pings that person), assign (owner: a name, 'me', or 'nobody'), follow, unfollow, save_script (repo, and script: name, about, language python|node|shell, and either body (short) or file (a path in the project, like scripts/enrich.py), and timeoutMinutes; scripts belong to the project, so no flow is needed; a 'check' step in any of its flows names it). A 'check' step runs its script with the card as JSON on stdin (and in $FLOW_INPUT); what it prints is its result for later steps ({{stage.<id>}}); runIn 'folder' (an empty folder: for scripts that work on data) or 'copy' (a copy of the card's work, after setup: for tests on code; the default); routes (answer, goesTo) that a last printed line 'goto: <answer>' picks; ifFails is where a failing script sends the card, such as back to the build (it has no default: without it the card waits there); secrets (names of saved secrets it gets as variables). add_trigger with settings (kind button: label, questions; schedule: schedule like 'daily 09:00 Europe/London', and title, or script (a saved script whose printed items — one per line, a title or JSON with title, description, key — each become a card, once) with secrets; github: repo owner/name, watch issues|pulls|checks, label, branch, from team|anyone; linear: team, state, label; flow: follow (another flow's id), when (its zone); email: folder (default INBOX), sender (addresses or domains), subject (words it must contain); plane-review: at (HH:MM, default 07:30), timeZone — every day it reads the plane's last 24 hours and makes one card per problem worth fixing, a returning problem joining its card); pause_trigger, resume_trigger, remove_trigger with trigger. A 'send' step ('Send to me') sends the card's owner what the step before produced (summary, links, screenshots) in their chat apps, then moves on; a 'choose' step sends the same with 2 to 4 options (label, goesTo: a step, or 'end' to ignore the card) as buttons, ifReplied (where a reply goes as {{note}}; the build before by default), and remindAfter with ifNoReply. choose (card, and choice by number or a note to reply) answers one for the operator. A 'task' step may build in another project: repo (from list_repos). Read get_flows first except to create. allow_browser (flow): when get_flows says a flow's browser zones wait, propose allowing them to start Chromium; the operator allows it with their own password in the secure screen, never on the card. turn_off_browser (flow) stops it.",
-        // An edit's kept steps may leave their kind and name to the zone they keep: they are filled in before the call is read.
         prepare: (ctx, given) => {
             const editing = given["operation"] === "edit" && Number.isSafeInteger(given["flow"]) ? ctx.store.getFlow(Number(given["flow"])) : null;
             const kept = editing !== null && ctx.who.repos.includes(editing.repo) ? flowDefinitionOf(editing) : null;
@@ -1102,8 +1012,6 @@ const LEAD_TOOL_HANDLERS = {
         handle: (ctx, read) => {
             const args = read;
             const pick = (keys) => Object.fromEntries(keys.filter(key => args[key] !== undefined).map(key => [key, args[key]]));
-            // "me" in a step means the operator; the drawing stores their name.
-            // A build step in another project names it as list_repos does (r2); the drawing keeps its path.
             const steps = () => stepsFor(Array.isArray(args["steps"]) ? args["steps"] : [], ctx.who.name).map(step => {
                 if (step === null || typeof step !== "object" || step.repo === undefined)
                     return step;
@@ -1120,7 +1028,6 @@ const LEAD_TOOL_HANDLERS = {
             try {
                 switch (args["operation"]) {
                     case "starter": {
-                        // a starter flow — its zones and its trigger, one yes.
                         const repo = repoPathOf(ctx.who, args["repo"]);
                         if (repo === null)
                             return { ok: false, message: "Choose a project from list_repos." };
@@ -1129,7 +1036,6 @@ const LEAD_TOOL_HANDLERS = {
                         break;
                     }
                     case "kit": {
-                        // a starter kit — a subagent, the flow it works, its buttons.
                         const repo = repoPathOf(ctx.who, args["repo"]);
                         if (repo === null)
                             return { ok: false, message: "Choose a project from list_repos." };
@@ -1211,7 +1117,6 @@ const LEAD_TOOL_HANDLERS = {
                     }
                     case "add_trigger": {
                         const settings = args["settings"] !== null && typeof args["settings"] === "object" ? { ...args["settings"] } : {};
-                        // A trigger following another flow names it as "follow"; the drawing stores it as the flow it follows.
                         if (settings["follow"] !== undefined) {
                             settings["flow"] = settings["follow"];
                             delete settings["follow"];
@@ -1232,7 +1137,6 @@ const LEAD_TOOL_HANDLERS = {
                         operation = "flow_trigger_remove";
                         input = pick(["trigger"]);
                         break;
-                    // Browser use in the flow's script zones: a proposal only; the person allows it with their own yes on its card.
                     case "allow_browser":
                         operation = "flow_browser";
                         input = pick(["flow"]);
@@ -1283,17 +1187,13 @@ const LEAD_TOOL_HANDLERS = {
                         worksOn: zonesOf(ctx.store, mate).map(one => ({ flow: one.flow, flowName: one.flowName, zone: one.title, how: one.kind })),
                         today: summaryOf(ctx.store, mate, today.toISOString()).said,
                         questions: ctx.store.openSubagentQuestions([mate.id]).map(one => ({ question: one.id, card: one.card, asks: one.question, options: one.options.map(option => option.label), askedOf: whoIs(one.askedOf), ...(one.toolCall === null ? {} : { approvesToolCall: true }), ...(one.suggestion === null ? {} : { suggestsRuleChange: true }) })),
-                        // v96: where messages to it by name and its routines land, and its routines.
                         desk: deskOf(ctx.store, mate)?.id ?? null,
                         routines: routinesOf(ctx.store, mate).map(one => ({ routine: one.id, schedule: one.schedule, text: one.text, working: one.state === "active", last: one.lastOutcome })),
-                        // v95: what it remembers (what people told it, and what it kept), newest first.
                         memory: ctx.store.subagentMemories(mate.id, { limit: args["subagent"] === undefined ? 5 : 40 }).map(one => ({ memory: one.id, text: one.text, from: one.source === "person" ? whoIs(one.createdBy) : "itself" })),
-                        // v94: the tools it may use, and its rule for each action.
                         tools: ctx.store.subagentGrants(mate.id).map(grant => ({ tool: grant.tool, actions: grant.actions.map(action => ({ action: action.name, rule: ruleWords(grant.rules[action.name] ?? defaultRule(action)) })) })),
                         ...(args["subagent"] === undefined ? {} : {
                             recent: ctx.store.subagentEvents(mate.id, 30).map(one => ({ kind: one.kind, said: one.said, at: one.at })),
                             toolCalls: ctx.store.subagentCallsOf(mate.id, 20).map(one => ({ call: one.id, card: one.card, what: callWords(one.tool, one.action, one.input, 200), outcome: callOutcome(one), at: one.createdAt, ...(undoFor(ctx.store, one) === null ? {} : { undoWith: undoFor(ctx.store, one) }) })),
-                            // v97: its week, as its manager's report reads.
                             week: weekWords(mate, weekOf(ctx.store, mate, ctx.now)),
                         }),
                     })),
@@ -1360,7 +1260,6 @@ const LEAD_TOOL_HANDLERS = {
                         const mate = Number.isSafeInteger(args["subagent"]) ? ctx.store.getSubagent(Number(args["subagent"])) : null;
                         if (mate === null || !ctx.who.repos.includes(mate.repo))
                             return { ok: false, message: "Choose a subagent from get_subagents." };
-                        // A tool's name and one of its actions: "shop" and "refund_order", also taken as "shop.refund_order", or the action alone when one tool has it.
                         let tool = typeof args["tool"] === "string" ? args["tool"].trim() : "", action = typeof args["action"] === "string" ? args["action"].trim() : "";
                         const dot = tool.search(/\.|→/);
                         if (dot > 0) {
@@ -1496,7 +1395,6 @@ const LEAD_TOOL_HANDLERS = {
             const thread = ctx.store.liveLeadThreadFor(ctx.who.name, { kind: "task", key: root });
             if (thread === null || thread.ceilingDigest !== ctx.who.ceilingDigest)
                 return { ok: true, body: { task: root, messages: [], notice: "No conversation about this task yet." } };
-            // What the lead reads of a task's conversation is what it has been told: admitted messages only (v128).
             const messages = ctx.store.listLeadHistory(thread.id, limit).map(one => ({ from: one.role === "operator" ? "operator" : "lead", text: one.text.length > 1_200 ? `${one.text.slice(0, 1_200)}…` : one.text, at: one.createdAt }));
             return { ok: true, body: { task: root, title: family?.root.title ?? null, messages, notice: messages.length === limit ? "Only the most recent messages are shown." : null } };
         },
@@ -1598,7 +1496,6 @@ const LEAD_TOOL_HANDLERS = {
             if (!honest(args["text"], 240))
                 return { ok: false, message: "Say the correction in one sentence." };
             const text = String(args["text"]).trim();
-            // One card per correction: a card still waiting in this conversation for the same change is the one to confirm.
             const waiting = ctx.thread === undefined ? [] : ctx.store.listLeadProposals(ctx.thread, ["drafting", "pending", "confirming"])
                 .filter(one => one.kind === "action" && one.payload["repo"] === repo);
             const same = (words) => typeof words === "string" && words.trim().toLowerCase() === text.toLowerCase();
@@ -1614,7 +1511,6 @@ const LEAD_TOOL_HANDLERS = {
             }
             else if (args["kind"] === "instruction") {
                 const view = knowledgeView(ctx.store, repo, ctx.who.name), current = view.knowledge.instructions.trim();
-                // The card adds a line to the instructions the lead read; once they have changed it would replace someone else's edit.
                 if (args["revision"] === undefined)
                     return { ok: false, message: "Pass the instructions revision from your catch-up (0 when the project has none)." };
                 if (args["revision"] !== view.revision)
@@ -1651,7 +1547,6 @@ const LEAD_TOOL_HANDLERS = {
             const name = typeof args["name"] === "string" && args["name"].trim() !== "" ? args["name"] : undefined;
             if (id === undefined && name === undefined)
                 return { ok: false, message: "Give an id from your catch-up's people index or a name." };
-            // In a team chat, the same people the room's catch-up lists: that room and its members.
             const found = personEntry(ctx.store, ctx.who.name, ctx.who.repos, { ...(id === undefined ? {} : { id }), ...(name === undefined ? {} : { name }) }, teamRoomOf(ctx.store, ctx.thread));
             if (found === null)
                 return { ok: false, message: "No one by that name or id works with you. Your catch-up's people index lists who does." };
@@ -1679,7 +1574,6 @@ const LEAD_TOOL_HANDLERS = {
                 return { ok: false, message: "Choose a project from list_repos." };
             const repos = repo === null ? ctx.who.repos.slice(0, 8) : [repo];
             const found = capabilitiesOf(ctx.store, { repos, admitted: ctx.who.repos, actor: ctx.who.name, integrations: ctx.integrations?.() ?? integrationsNow(integrationIoOf(ctx)), ...(ctx.authMode === undefined ? {} : { authMode: ctx.authMode }), now: ctx.now });
-            // Only the projects actually read are covered: a proposal on one left out (past the first eight) still needs its own read.
             for (const path of repos)
                 if (!ctx.checkedCapabilities?.has(path))
                     ctx.checkedCapabilities?.set(path, ctx.step);
@@ -1736,7 +1630,6 @@ const LEAD_TOOL_HANDLERS = {
             });
             const tools = runtimeStates(ctx.store).map(one => ({ name: one.name, installed: one.installed, latest: one.latest, updateAvailable: one.behind }));
             const newModels = ["claude", "codex", "gemini"].flatMap(source => seenModels(ctx.store, source)).filter(model => isNewModel(model, ctx.now)).map(model => ({ name: model.name, id: model.id, price: priceWords(model), released: model.releasedAt }));
-            // Results routing: the same suggestions and rules Settings → Models and `toolroll models suggestions` show.
             const suggestions = ctx.who.repos.flatMap(repo => suggestionsFor(ctx.store, repo, ctx.now)).map(one => ({ id: one.id, repo: one.repo, words: suggestionWords(one),
                 review: `/settings/models?scope=${encodeURIComponent(one.repo)}&suggestion=${encodeURIComponent(one.id)}#models-suggested` }));
             const rules = ctx.who.repos.flatMap(repo => rulesOf(ctx.store, repo, ctx.now)).map(one => ({ id: one.id, repo: one.repo, state: one.state, words: earnedRuleWords(ctx.store, one) }));
@@ -1756,9 +1649,7 @@ const LEAD_TOOL_HANDLERS = {
             const words = searchWords(typeof args["search"] === "string" ? args["search"] : "");
             if (typeof args["search"] === "string" && words.length === 0)
                 return { ok: false, message: "search needs a word that names the work, such as a page, feature or file" };
-            // A search reads further back than the newest page, then ranks by how many of the words each task's title and goal hold.
             const listed = ctx.store.taskFamiliesAdmitted(repo === null ? ctx.who.repos : [repo], false, { limit: words.length === 0 ? limit + 1 : SEARCH_FAMILIES, order: words.length === 0 ? "created" : "updated", ...(args["state"] === undefined ? {} : { states: [args["state"]] }) });
-            // A put-away task (v145) is out of every list, the lead's included.
             const families = (words.length === 0 ? listed : listed
                 .map((one, index) => ({ one, index, hits: searchHits(words, [one.root.id, one.root.title, one.current.title, ctx.store.getScope(one.current.id)?.goal ?? "", ctx.store.getScope(one.root.id)?.goal ?? ""]) }))
                 .filter(match => match.hits > 0)
@@ -1831,12 +1722,10 @@ const LEAD_TOOL_HANDLERS = {
                     attempts: runs.length,
                     lastAttempt: runs[0] === undefined ? null : { build: runs[0].id, outcome: runs[0].outcome ?? "unfinished", worker: runs[0].runner, tools: ctx.store.runTools(runs[0].id), secretsFenced: ctx.store.runFence(runs[0].id)?.method ?? null },
                     decisionsOpen,
-                    // Operator steering (v120), in the task page's words: read (and when), waiting, or for the next attempt.
                     steering: (() => {
                         const live = ctx.store.steeringLiveBuild(ref.id, ctx.now) !== null;
                         return ctx.store.listSteerNotes(ref.id).slice(-5).map(one => ({ note: one.id, filedAt: one.createdAt, state: steerStandingWords(one, live, utcMinute) }));
                     })(),
-                    // Live steering: the running Claude build a note reaches in seconds and a pause can reach, and its pause.
                     liveBuild: (() => {
                         const run = ctx.store.liveInputRun(ref.id, ctx.now);
                         if (run === null)
@@ -1845,10 +1734,7 @@ const LEAD_TOOL_HANDLERS = {
                         const until = pause?.state === "paused" && pause.pausedAt !== null && pause.limitMs !== null ? new Date(Date.parse(pause.pausedAt) + pause.limitMs).toISOString() : null;
                         return { build: run, pause: pause?.state ?? null, ...(until === null ? {} : { pausedUntil: until }) };
                     })(),
-                    // The running agent's open questions (Agents board): reply with propose_steer and its question id.
                     agentQuestions: openAgentQuestions(ctx.store, ref.id).map(one => ({ question: one.id, key: one.key, asks: one.question, askedAt: one.askedAt })),
-                    // "Can I merge?" (merge-checklist.ts; `toolroll task ready` is its twin): the answer and each check; a blocker
-                    // names its act (run-checks, retry, or fix: Send back with that note), which the person takes.
                     canMerge: (() => {
                         const list = mergeChecklistOf(ctx.store, taskId, ctx.now, { principal: "coordinator", repos: ctx.who.repos }, ctx.evidenceRoot);
                         return list === null ? null : { answer: list.answer, sentence: list.sentence,
@@ -1919,7 +1805,6 @@ const LEAD_TOOL_HANDLERS = {
             if (planning !== "auto" && planning !== "required" && planning !== "skip")
                 return { ok: false, message: "planning is auto, required, or skip" };
             const report = args["report"] === true;
-            // A level, or the person's own words ("skip the tests", "run the full checks").
             const checks = args["checks"] === undefined ? null : isCheckLevel(args["checks"]) ? args["checks"] : typeof args["checks"] === "string" ? checkLevelFromWords(args["checks"]) : null;
             if (args["checks"] !== undefined && checks === null)
                 return { ok: false, message: "checks is quick, full or off" };
@@ -1936,8 +1821,6 @@ const LEAD_TOOL_HANDLERS = {
             if (!checked.ok)
                 return { ok: false, message: checked.message };
             const { repo, repoId, title } = checked.input;
-            // Eligible: a Start card from the loop's own preview (the request names it back; the card checks it is this
-            // person's, this turn's, on chat). Anything else: today's task card, built directly, and why in the body.
             const prepared = ctx.startPrepared;
             let why = fastRefusalWords(prepared === undefined ? "classifier" : prepared.eligible ? "classifier" : prepared.reason);
             if (prepared !== undefined && prepared.eligible) {
@@ -2019,8 +1902,6 @@ const LEAD_TOOL_HANDLERS = {
             const ref = taskId === null ? null : admittedRef(ctx, taskId);
             if (taskId === null || ref === null)
                 return notFound();
-            // The revision and the place are read in ONE transaction (finding 10):
-            // the door's revision check then vouches for the position it saw.
             const seen = ctx.store.transact(() => ({ queueRevision: ctx.store.queueRevision(), position: ctx.store.queuePosition(taskId) }));
             if (seen.position === null)
                 return { ok: false, message: "that task is not queued" };
@@ -2063,9 +1944,6 @@ const LEAD_TOOL_HANDLERS = {
                 return notFound();
             if (!honest(args["reason"], 200))
                 return { ok: false, message: "reason is plain text ≤200" };
-            // The operator's existing hold, if any, is the CAS material (finding
-            // 10): a hold placed by hand after this proposal must not be
-            // overwritten by model text when the stale card is confirmed.
             const existing = ctx.store.activeHolds(ref.id, ctx.now).find(one => one.ownerKind === "operator");
             const id = ctx.draft("hold", { task: taskId, repoId: ref.repoId, reason: args["reason"], sawHold: existing?.id ?? null });
             if (id === null)
@@ -2106,14 +1984,11 @@ const LEAD_TOOL_HANDLERS = {
             }
             if (task.state === "done" || task.state === "cancelled")
                 return { ok: false, message: "that task is finished, so guidance has no next attempt to reach" };
-            // A pause binds to the build running now: confirming it later reaches that build or none.
             const sawRun = mode === "note" ? null : ctx.store.liveInputRun(ref.id, ctx.now);
             if (mode !== "note" && sawRun === null)
                 return { ok: false, message: `that task has no running Claude build to ${mode === "resume" ? "resume" : "pause"}; send the guidance as a note instead` };
             if (mode === "resume" && ctx.store.pauseStateOf(sawRun) !== "paused")
                 return { ok: false, message: "that task's build isn't paused, so there is nothing to resume" };
-            // A reply names exactly one open question of this task's running agent; the confirmation re-checks it. A reply is
-            // an ordinary note (the confirmation files it through the question's own door), so it never rides a pause or resume.
             if (typeof args["question"] === "number" && mode !== "note")
                 return { ok: false, message: "a reply to the agent's question is sent as a note; propose it without mode" };
             const asked = typeof args["question"] === "number" ? agentQuestion(ctx.store, args["question"]) : null;
@@ -2346,12 +2221,8 @@ const LEAD_TOOL_HANDLERS = {
         },
     },
 };
-/** The lead's tools, in the order the model is shown them: each one's inputSchema is its contract, derived. */
 export const LEAD_TOOLS = Object.keys(LEAD_TOOL_INPUTS).map((name) => {
     const input = LEAD_TOOL_INPUTS[name];
-    // Flow proposals already used their strict contract in 0.9.36; keep that validation unchanged. A shared action's
-    // unknown keys reach prepareSharedAction, whose per-operation check refused them in 0.9.36 and still does. Every other
-    // tool ignored unknown arguments and still strips them.
     const reader = name === "propose_flow" ? LEAD_TOOL_READ_INPUTS[name] : name === "propose_action" ? LEAD_TOOL_READ_INPUTS[name].loose() : LEAD_TOOL_READ_INPUTS[name].strip();
     const handler = LEAD_TOOL_HANDLERS[name];
     return {
@@ -2362,10 +2233,8 @@ export const LEAD_TOOLS = Object.keys(LEAD_TOOL_INPUTS).map((name) => {
         handle: (ctx, args) => handler.handle(ctx, args),
     };
 });
-/** Pages sized under the tool-result cap once wrapped in JSON. */
 const DIFF_PAGE_CHARS = 10_000;
 const LOG_PAGE_CHARS = 8_000;
-/** A finished result the person may read: the exact run named, or the task's newest finished build. */
 function finishedResultOf(ctx, args) {
     const task = taskIdOf(args);
     if (task === null)
@@ -2382,7 +2251,6 @@ function finishedResultOf(ctx, args) {
         return { ok: false, message: "There is no finished result for that version yet." };
     return { ok: true, task, run: found.id };
 }
-/** A unified diff, file by file, with each file's added and removed lines. */
 export function patchFiles(patch) {
     return patch.split(/^(?=diff --git )/m).filter(part => part.startsWith("diff --git ")).map(part => {
         const names = /^diff --git a\/(.+?) b\/(.+)$/m.exec(part);
@@ -2397,13 +2265,11 @@ export function patchFiles(patch) {
         return { path: names?.[2] ?? names?.[1] ?? "(unnamed file)", added, removed, text: part };
     });
 }
-/** The files Settings → Integrations reads, beside this database, when the surface supplied none. */
 function integrationIoOf(ctx) {
     const file = ctx.store.databaseFile();
     const dir = file === null ? null : dirname(file);
     return { store: ctx.store, dir, telegramTokenFile: dir === null ? null : join(dir, "telegram-token"), env: process.env, repos: ctx.who.repos };
 }
-/** The admitted project a proposal is about, when its arguments name one: the project, task, result, flow, card, subagent or decision. */
 function proposalRepoOf(ctx, args) {
     const { store } = ctx;
     const id = (key) => Number.isSafeInteger(args[key]) && Number(args[key]) > 0 ? Number(args[key]) : null;
@@ -2424,12 +2290,6 @@ function proposalRepoOf(ctx, args) {
 function hasRecordedDecisions(store, repo) {
     return store.handle.prepare("SELECT 1 AS hit FROM project_decision WHERE repo = ? AND status = 'active' LIMIT 1").get(repo) !== undefined;
 }
-/**
- * A proposal on a project with recorded decisions needs search_project_memory over that project (or every project) in an
- * EARLIER step of this turn, as propose_review needs get_result first: a recommendation is checked against what the
- * project already settled. When the arguments name no project, it could be about any of them: each admitted project
- * with decisions needs a search (one over every project covers them all).
- */
 function memoryUnsearched(ctx, name, args) {
     if (!name.startsWith("propose_"))
         return null;
@@ -2444,11 +2304,6 @@ function memoryUnsearched(ctx, name, args) {
             ? "Your projects have recorded decisions. Search them with search_project_memory first (leave out the project to search them all), then propose in a later step, citing any decision you rely on."
             : "This project has recorded decisions. Search them with search_project_memory first, then propose in a later step, citing any decision you rely on." };
 }
-/**
- * A proposal or promise whose work needs an agent, a worker or an integration (needsCapabilities) needs get_capabilities
- * read over its project in an EARLIER step of this turn, as a proposal needs its memory search: the
- * lead never promises what it has not checked can run. One that names no project is covered by any read this turn.
- */
 function capabilitiesUnread(ctx, name, args) {
     const read = ctx.checkedCapabilities;
     if (read === undefined || !needsCapabilities(name, args, ctx.channel))
@@ -2459,13 +2314,10 @@ function capabilitiesUnread(ctx, name, args) {
         return null;
     return { ok: false, message: CAPABILITIES_UNREAD };
 }
-/** remember about-you: a card for one line about the owner. It replaces a line only when the lead names it with
- * replaces, and then the card shows both; otherwise the line is added. */
 function rememberAboutYou(ctx, args) {
     const checked = checkAboutYouLine(args["text"]);
     if (!checked.ok || !honest(args["text"], 240))
         return { ok: false, message: checked.ok ? "Say it in one plain line." : checked.message };
-    // A shared team chat's lead speaks for the room; what the owner's own lead knows about them is theirs.
     if (teamRoomOf(ctx.store, ctx.thread) !== null)
         return { ok: false, message: "What your lead knows about someone is kept in their own chat with it, not a team chat." };
     const lines = aboutYouOf(ctx.store, ctx.who.name);
@@ -2489,7 +2341,6 @@ function rememberAboutYou(ctx, args) {
             ...(replaces === 0 ? {} : { replaces: { line: replaces, was: lines[replaces - 1] } }),
             next: "Once confirmed it is in your next catch-up's aboutYou." } };
 }
-/** get_person names people, subagents and team chat members on purpose; the scrub took them out with the rest. */
 function personNamesBack(raw, scrubbed) {
     if (!raw.ok || !scrubbed.ok)
         return scrubbed;
@@ -2510,8 +2361,6 @@ export const LEAD_TOOL_SCHEMAS = LEAD_TOOLS.map(({ name, description, inputSchem
 export function isLeadTool(name) {
     return LEAD_TOOLS.some(one => one.name === name);
 }
-/** Scrub every result. Only list_repos then adds validated display metadata
- * from the same admitted project list; no user-authored result gets an exemption. */
 export function executeLeadTool(ctx, name, args, view) {
     const tool = LEAD_TOOLS.find(one => one.name === name);
     const scrub = view ?? leadViewContextFor(ctx.store, ctx.who);
@@ -2519,8 +2368,6 @@ export function executeLeadTool(ctx, name, args, view) {
         return { ok: false, message: `no tool named ${redactForLead(name, scrub)}` };
     let result;
     try {
-        // The call is read by the contract's compatible reader, before any check or handler: a refusal is every path-named
-        // line (`acceptance[0].evidence: at least 1 item`), so the next step can correct exactly that.
         const read = tool.read(ctx, args);
         if (!read.ok) {
             result = { ok: false, message: read.issues.map(one => one.line).join("\n") };
@@ -2533,7 +2380,6 @@ export function executeLeadTool(ctx, name, args, view) {
     catch {
         result = { ok: false, message: "that tool refused — the plane could not answer it right now" };
     }
-    // A result is checked against its output schema before it is scrubbed; a disagreement is reported, never refused.
     if (result.ok)
         reportToolOutput("lead", name, LEAD_TOOL_OUTPUTS[name], result.body);
     const sanitized = name === "get_person" ? personNamesBack(result, leadView(result, scrub)) : leadView(result, scrub);
@@ -2544,14 +2390,9 @@ export function executeLeadTool(ctx, name, args, view) {
     }
     return sanitized;
 }
-/** Bytes of a serialized tool result as it will sit inside the request body. */
 export function toolResultBytes(text) {
     return Buffer.byteLength(JSON.stringify(text), "utf8");
 }
-/** What propose_start may start with, checked before Toolroll asks the classifier (docs/plans/one-step-chat.md C3): the
- * call's contract, the same memory and capability checks every proposal makes, never a team chat, a project the person
- * can reach now, and the same text and secret checks as propose_task. The conversation loop runs this, and only then
- * prepares a preview; the handler runs it again. Invalid input never reaches the classifier. */
 export function startInputOf(ctx, args) {
     const tool = LEAD_TOOLS.find(one => one.name === "propose_start");
     if (tool === undefined)
@@ -2562,7 +2403,6 @@ export function startInputOf(ctx, args) {
     const unchecked = memoryUnsearched(ctx, "propose_start", read.value) ?? capabilitiesUnread(ctx, "propose_start", read.value);
     if (unchecked !== null && !unchecked.ok)
         return { ok: false, message: unchecked.message };
-    // A start is the person's own yes in their own chat with you: a shared team chat proposes an ordinary task.
     if (teamRoomOf(ctx.store, ctx.thread) !== null)
         return { ok: false, message: "Starting work in one step is for the person's own chat. Use propose_task here." };
     const repo = repoPathOf(ctx.who, read.value["repo"]);