toolroll 0.9.104 → 0.9.105

package/dist/flows.js

@@ -1,52 +1,3 @@
-/**
- * Flows (v81): a canvas of zones that work moves through. Each zone is one
- * stage of a team's process; each card is one piece of work. When a card
- * is routed or dropped into a zone, the zone's step runs:
- *
- * - inbox     — a holding zone: cards wait for someone to move them.
- * - task      — build it: files the card's work as an ordinary task, so the
- *               existing plan → approve → build → verify pipeline (with its
- *               approvals and agent fence) does the work; the card moves on
- *               when the result is ready, or down its failure path.
- * - report    — research it: files a report task (no code changes) and
- *               keeps the report on the card for later zones.
- * - approval  — a person decides: approve moves on; send back (with a
- *               note) takes the failure path, and a send back to a build
- *               zone becomes a revision of the card's work.
- * - notify    — posts a message to the project's chat and moves on.
- * - draft     — (v86) Claude writes something from the card (a reply, a
- *               summary, a note) in seconds, with no repository and no
- *               tools. Nothing is sent: a later zone shows it to a person
- *               and a later step posts it ({{stage.<id>}}).
- * - sort      — (v85) Jev, a decision model reached through OpenRouter,
- *               reads the card and picks one of the zone's answers; the
- *               card goes where that answer leads, or down the not-sure
- *               path when Jev is less sure than the zone asks. It can also
- *               note a few scores or yes/no answers on the card.
- * - request   — (v87) calls an address on the web (an API) with the card's
- *               details, and keeps what it answers; a refusal takes the
- *               failure path. Secrets ride headers only ({{secret.NAME}}).
- * - email     — (v87) sends an email from the address in Settings → Email;
- *               {{card.email}} is the first address the card mentions.
- * - tool      — (v87) calls one tool of one of the project's MCP servers
- *               (Settings → Tools), with arguments filled from the card.
- * - pull-request — opens a pull request for the card's built result under
- *               the project's pull request setup (flow-pull-request.ts),
- *               waits for CI, and moves on when it passes or down the
- *               failure path, naming the failing check, when it fails. It
- *               can merge once checks pass, only after a person approved.
- * - send      — "Send to me": sends the card's person (its owner, else the
- *               flow's) what the step before produced — its summary, links
- *               and images — in each chat app they paired and on the card,
- *               then moves on.
- * - choose    — "Person chooses": the same content, with 2 to 4 buttons the
- *               flow names (each leads to a zone, or ends the card as
- *               Ignored). A reply instead is the {{note}} for where replies go.
- * - done      — the end.
- *
- * The engine is deterministic and model-free: it runs in the worker's pass
- * beside builds, and no card ever skips an approval the task itself needs.
- */
 import { TEXT_LIMITS } from "./text-limits.js";
 import { createHash } from "node:crypto";
 import { projectName } from "./project.js";
@@ -56,7 +7,6 @@ import { stageReferenceProblems } from "./contracts/stage-output.js";
 import { CHOICES_MAX, CHOICES_MIN, FLOW_ALIASES, FLOW_COLORS, FLOW_DEFINITION_VERSION, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, flowDefinitionSchema, flowStepsSchema, HEADERS_MAX, legacySubagentStep, LONGEST_WAIT_MINUTES, savedFlowDefinitionSchema, SCRIPT_LANGUAGES, SCRIPT_NAME, sortKeyOf, SURE_AT_MAX, SURE_AT_MIN, ZONE_ID, } from "./contracts/flow.js";
 import { isRecord } from "./is-record.js";
 export { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME, sortKeyOf };
-/** What each kind is called and does, in the words the canvas uses. */
 export const FLOW_KIND_WORDS = {
     inbox: { label: "Holding", about: "Cards wait here until someone moves them." },
     task: { label: "Build", about: "An agent does the work as a task, with the usual approvals and checks." },
@@ -78,11 +28,9 @@ export const FLOW_KIND_WORDS = {
     done: { label: "Done", about: "The end of the flow." },
 };
 export const LANGUAGE_WORDS = { shell: "Shell", python: "Python", node: "Node" };
-/** The default for "sure enough to act alone". */
 export const SORT_SURE_AT = 0.8;
 const HEADER = /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/;
 const UNITS = [[/^(m|min|mins|minute|minutes)$/, 1], [/^(h|hr|hrs|hour|hours)$/, 60], [/^(d|day|days)$/, 24 * 60], [/^(w|wk|wks|week|weeks)$/, 7 * 24 * 60]];
-/** "3 days", "4 hours", "90 minutes", "1 week" (or a number of minutes) as minutes; null when it isn't one. */
 export function durationMinutes(value) {
     if (typeof value === "number")
         return Number.isInteger(value) && value >= 1 && value <= LONGEST_WAIT_MINUTES ? value : null;
@@ -95,7 +43,6 @@ export function durationMinutes(value) {
     const minutes = Math.round(Number(match[1]) * unit[1]);
     return minutes >= 1 && minutes <= LONGEST_WAIT_MINUTES ? minutes : null;
 }
-/** Minutes in the words people use: "3 days", "1 day 4 hours", "45 minutes". */
 export function durationWords(minutes) {
     const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
     if (minutes % (7 * 24 * 60) === 0)
@@ -103,7 +50,6 @@ export function durationWords(minutes) {
     const days = Math.floor(minutes / (24 * 60)), hours = Math.floor((minutes % (24 * 60)) / 60), rest = minutes % 60;
     return [days > 0 ? plural(days, "day") : "", hours > 0 ? plural(hours, "hour") : "", rest > 0 ? plural(rest, "minute") : ""].filter(one => one !== "").join(" ");
 }
-/** "22:00", "9:30" as "HH:MM"; null when it isn't a time of day. */
 export function clockTime(value) {
     const match = typeof value === "string" ? /^\s*([01]?[0-9]|2[0-3]):([0-5][0-9])\s*$/.exec(value) : null;
     return match === null ? null : `${match[1].padStart(2, "0")}:${match[2]}`;
@@ -117,7 +63,6 @@ export function knownTimeZone(zone) {
         return false;
     }
 }
-/** Whether a time falls inside an "hours" wait (22:00–06:00 runs past midnight), in its time zone or this computer's. */
 export function withinHours(wait, now) {
     const parts = new Intl.DateTimeFormat("en-GB", { hour: "2-digit", minute: "2-digit", hourCycle: "h23", ...(wait.timeZone === undefined ? {} : { timeZone: wait.timeZone }) }).formatToParts(now);
     const at = Number(parts.find(one => one.type === "hour")?.value ?? 0) * 60 + Number(parts.find(one => one.type === "minute")?.value ?? 0);
@@ -125,11 +70,9 @@ export function withinHours(wait, now) {
     const from = minutesOf(wait.from), to = minutesOf(wait.to);
     return from < to ? at >= from && at < to : at >= from || at < to;
 }
-/** Who decides at an approval zone: its named person, the flow's owner, or null for anyone who approves on the project. */
 export function deciderOf(stage, flow) {
     return stage.toOwner === true ? flow.owner : stage.approver;
 }
-/** A flow refused by its contract: every problem, each naming its path (`stages[2].instructions: required`). */
 export class FlowContractError extends Error {
     lines;
     constructor(lines) {
@@ -137,13 +80,9 @@ export class FlowContractError extends Error {
         this.lines = lines;
     }
 }
-// ------------------------------------------------------------------ reading a drawing
-/** Text as every release has kept it: trimmed, and blank as none. Anything else is left for the schema to name. */
 const said = (value) => value === undefined || value === null ? null : typeof value === "string" ? value.trim() === "" ? null : value.trim() : value;
 const coordinate = (value, min, max, fallback) => typeof value === "number" && Number.isFinite(value) ? Math.round(Math.min(max, Math.max(min, value))) : fallback;
 const given = (value) => value !== undefined && value !== null;
-/** A sort zone's settings as every release has kept them: an answer's meaning defaults to its name, sureAt to 0.8 (within
- * 0.5–0.99), and each extra note gets a free id. */
 function canonicalSort(input) {
     const raw = isRecord(input) ? input : {};
     const answers = Array.isArray(raw["answers"]) ? raw["answers"] : given(raw["answers"]) ? raw["answers"] : [];
@@ -171,7 +110,6 @@ function canonicalSort(input) {
         sureAt, notes,
     };
 }
-/** A script's or subagent's answers as every release has kept them: trimmed, none left out. */
 function canonicalRoutes(input) {
     if (!given(input))
         return undefined;
@@ -184,7 +122,6 @@ function canonicalRoutes(input) {
         return { answer: typeof row["answer"] === "string" ? row["answer"].trim() : row["answer"] ?? "", to: typeof row["to"] === "string" ? row["to"].trim() : row["to"] ?? "" };
     });
 }
-/** A Wait zone's settings: "hours" between two times of day, or a reply or a set time for so long. */
 function canonicalWait(input) {
     const raw = isRecord(input) ? input : {};
     if (raw["for"] === "hours") {
@@ -193,11 +130,6 @@ function canonicalWait(input) {
     }
     return { for: raw["for"] === "time" ? "time" : "reply", minutes: durationMinutes(raw["minutes"]) };
 }
-/**
- * One zone of a version 1 drawing, as every release from 0.9.0 has read it: a zone saved before a field existed gets
- * that field's default, text is trimmed (blank is none), the canvas place is clamped, a field another kind uses is
- * set aside, and a value no release accepted is left as it is for the schema to name.
- */
 function canonicalStage(input, index) {
     if (!isRecord(input))
         return input;
@@ -223,16 +155,13 @@ function canonicalStage(input, index) {
         message: said(stage["message"]),
         close: kind === "update" ? stage["close"] !== false : null,
         script: kind === "check" ? said(stage["script"]) : null,
-        // Left out, a script runs where every script ran before v90: in a copy of the card's work.
         ...(kind === "check" ? { ...(runIn === undefined ? {} : { runIn }), ...(routes === undefined ? {} : { routes }), ...(secrets === undefined ? {} : { secrets }),
-            // v144: a script that starts a browser says so; false or none is a script that doesn't (and keeps its digest).
             ...(!given(stage["browser"]) || stage["browser"] === false ? {} : { browser: stage["browser"] }) } : {}),
         sort: kind === "sort" ? canonicalSort(stage["sort"]) : null,
         ...(kind === "request" ? { request: { method, url: said(request["url"]), headers: Object.fromEntries(Object.entries(isRecord(request["headers"]) ? request["headers"] : {}).flatMap(([name, value]) => { const one = said(value); return one === null ? [] : [[name, one]]; })), body: method === "GET" || method === "DELETE" ? null : said(request["body"]) } } : {}),
         ...(kind === "email" ? { email: { to: said(email["to"]), subject: said(email["subject"]), body: said(email["body"]) } } : {}),
         ...(kind === "tool" ? { tool: { server: said(tool["server"]), name: said(tool["name"]), args: said(tool["args"]) ?? "{}" } } : {}),
         ...(kind === "wait" ? { wait: canonicalWait(stage["wait"]) } : {}),
-        // true is a squash, the default; false or none is no merge.
         ...(kind === "pull-request" && given(stage["merge"]) && stage["merge"] !== false ? { merge: stage["merge"] === true ? "squash" : stage["merge"] } : {}),
         ...((kind === "approval" || kind === "subagent") && given(stage["subagent"]) && stage["subagent"] !== "" ? { subagent: stage["subagent"] } : {}),
         ...(kind === "subagent" && routes !== undefined ? { routes } : {}),
@@ -244,7 +173,6 @@ function canonicalStage(input, index) {
         onFail: said(stage["onFail"]),
     };
 }
-/** A version 1 drawing as every release has read it (canonicalStage); its start is the first zone unless it names one. */
 function canonicalDefinition(input) {
     const stages = Array.isArray(input["stages"]) ? input["stages"].map(canonicalStage) : input["stages"];
     const ids = Array.isArray(stages) ? stages.map(one => (isRecord(one) ? one["id"] : undefined)) : [];
@@ -252,9 +180,6 @@ function canonicalDefinition(input) {
     return { version: Object.prototype.hasOwnProperty.call(input, "version") ? input["version"] : FLOW_DEFINITION_VERSION, start, stages };
 }
 const issue = (path, what, kind = "invalid") => ({ path, kind, line: `${path}: ${what}` });
-/** What JSON Schema can't say about a drawing, each named by its path: paths lead to zones that exist and never back into
- * their own zone, answers and options have names of their own, a web address's host is written out, tool arguments are a
- * JSON object, an hours wait's times differ in a real time zone, and a merge comes after a person's decision. */
 export function drawingProblems(definition) {
     const problems = [];
     const ids = new Set();
@@ -334,7 +259,6 @@ export function drawingProblems(definition) {
     });
     if (problems.length > 0)
         return problems;
-    // A zone that merges comes after a person's decision on every path to it: never merged without one.
     const unapproved = reachableWithout(definition.stages, definition.start, one => one.kind === "approval");
     definition.stages.forEach((stage, index) => {
         if (stage.merge !== undefined && unapproved.has(stage.id))
@@ -342,29 +266,20 @@ export function drawingProblems(definition) {
     });
     return problems;
 }
-/**
- * Read a flow's drawing: the canvas's, a step list's once built, or one saved earlier (`stored`, which keeps working under
- * rules added since: its instructions keep the length they were saved with). A version 1 drawing is read as every release
- * has read it (canonicalStage), then the schema checks it, then drawingProblems; a newer version is refused plainly.
- */
 export function readFlowDefinition(input, options = {}) {
     const body = isRecord(input) ? canonicalDefinition(input) : input;
     const read = readVersioned(options.stored === true ? savedFlowDefinitionSchema : flowDefinitionSchema, body, {}, FLOW_ALIASES);
-    // The start is the first zone unless a zone it names exists: a problem with it is a problem with the zones, said there.
     if (!read.ok)
         return { ok: false, issues: read.issues.some(one => one.path.startsWith("stages")) ? read.issues.filter(one => one.path !== "start") : read.issues };
     const problems = drawingProblems(read.value);
     return problems.length === 0 ? read : { ok: false, issues: problems };
 }
-/** The saved drawing's fields in the words steps and flow files use for them. */
 const STEP_WORDS = [
     [/^tool\.args/, "args"], [/^tool\.server/, "server"], [/^tool\.name/, "tool"], [/^request\.(url|headers|body|method)/, "$1"], [/^email\.(to|subject|body)/, "$1"],
     [/^sort\.answers\[(\d+)\]\.to/, "answers[$1].goesTo"], [/^sort\.answers/, "answers"], [/^sort\.question/, "question"], [/^sort\.sureAt/, "sureAt"], [/^sort\.notes/, "alsoNote"],
     [/^(routes|options)\[(\d+)\]\.to/, "$1[$2].goesTo"], [/^limit\.to/, "thenMoveTo"], [/^limit(\.minutes)?/, "remindAfter"], [/^wait\.to/, "until"], [/^wait\.(from|timeZone)/, "$1"], [/^wait(\.minutes)?/, "wait"],
     [/^approver/, "decider"], [/^toOwner/, "decider"],
 ];
-/** A refusal of the drawing a step list or flow file became, in its words: `stages[2].sort.answers[0].to` is
- * `steps[2].answers[0].goesTo` (each zone is the step at its index), and a zone's failure path is the step's own name for it. */
 export function inStepWords(line, list, kinds) {
     const match = /^stages\[(\d+)\](?:\.([^:]*))?:(.*)$/s.exec(line);
     if (match === null)
@@ -381,15 +296,12 @@ export function inStepWords(line, list, kinds) {
             }
     return `${list}[${index}]${field === "" ? "" : `.${field}`}:${match[3]}`;
 }
-/** A flow as drawn on the canvas, checked whole (readFlowDefinition). Throws FlowContractError, naming every path. */
 export function validateFlowDefinition(input, options = {}) {
     const read = readFlowDefinition(input, options);
     if (!read.ok)
         throw new FlowContractError(read.issues.map(one => one.line));
     return read.value;
 }
-/** A drawing's refusal as the canvas shows it: each line as it is, after the name of the zone it is about, so a person
- * finds it on the canvas (`Build · stages[1].instructions: required`). */
 export function withZoneNames(lines, input) {
     const stages = isRecord(input) && Array.isArray(input["stages"]) ? input["stages"] : [];
     return lines.map(line => {
@@ -399,11 +311,7 @@ export function withZoneNames(lines, input) {
         return title === null ? line : `${title} · ${line}`;
     }).join("\n");
 }
-/** The instructions 0.9.26 and earlier read from a saved zone: they re-check this length on every read, and a flow with a
- * longer one won't load. A saved zone keeps its first part under it, and the rest in `instructionsMore`, which they ignore. */
 export const FLOW_INSTRUCTIONS_STORED = 4000;
-/** A flow's definition as the store saves it: any zone's instructions over FLOW_INSTRUCTIONS_STORED are split, so a
- * person who goes back a version still opens the flow (with its instructions' first part). Unchanged otherwise. */
 export function flowDefinitionForStore(json) {
     let raw;
     try {
@@ -429,7 +337,6 @@ export function flowDefinitionForStore(json) {
     });
     return split ? JSON.stringify({ ...raw, stages: kept }) : json;
 }
-/** A saved flow's definition with every zone's instructions whole again (flowDefinitionForStore). */
 export function flowDefinitionFromStore(json) {
     if (!json.includes("\"instructionsMore\""))
         return json;
@@ -452,7 +359,6 @@ export function flowDefinitionFromStore(json) {
     });
     return JSON.stringify({ ...raw, stages: whole });
 }
-/** The zones a card can reach from `start` without passing through a zone `stop` picks (those zones aren't included). */
 export function reachableWithout(stages, start, stop) {
     const seen = new Set();
     const queue = [start];
@@ -466,46 +372,33 @@ export function reachableWithout(stages, start, stop) {
     }
     return seen;
 }
-/** The zones a choose zone's options lead to (an option that ends the card leads to none). */
 export function choiceTargets(stage) {
     return (stage.options ?? []).map(one => one.to).filter(to => to !== FLOW_END);
 }
-/** Where a reply to a choice goes, as its {{note}}: the zone's reply path, else its first option that leads somewhere; null when none does. */
 export function replyTarget(stage) {
     return stage.onFail ?? choiceTargets(stage)[0] ?? null;
 }
-/** What a card's work is held to: the zones' steps and paths, never where they sit on the canvas. */
 export function flowDigest(definition) {
     const terms = definition.stages.map(({ zone: _zone, ...rest }) => rest);
     return createHash("sha256").update(JSON.stringify({ start: definition.start, terms })).digest("hex").slice(0, 32);
 }
-/** {{stage.<id>}} is an earlier zone's output; a report zone also fills {{stage.<id>.items}} and {{stage.<id>.report}}. */
 const FILLED = /\{\{\s*(card\.title|card\.description|card\.email|card\.source|note|stage\.([a-z0-9-]+(?:\.(?:items|report))?))\s*\}\}/g;
-/** Fill a zone's text from the card: title, description, the latest note and earlier zones' reports. */
 export function fillFlowText(template, card, encode = value => value) {
     return template.replace(FILLED, (_match, key, stage) => encode(fillOne(key, stage, card))).trim();
 }
-/** The task door's goal limit (task-text.ts). A work zone's goal is kept within it. */
 export const FLOW_GOAL_LIMIT = TEXT_LIMITS.goal;
-/** What stands in a goal for a filled-in value too long to hold whole: the agent is given it whole, attached (flowGoalCuts). */
 export const flowAttachedMark = (label) => `[${label}: attached in full below]`;
-/** A work zone's words, plus the card and any send-back note when the words leave them out. "Fix the bug on the card"
- * says nothing on its own (found in the real e2e: the builder saw only the branch name). */
 export function flowWorkTemplate(instructions, card) {
     const names = (key) => new RegExp(`\\{\\{\\s*${key.replace(".", "\\.")}\\s*\\}\\}`).test(instructions);
     const extra = [
         ...(names("card.title") || names("card.description") ? [] : [`The card: {{card.title}}${card.description ? "\n\n{{card.description}}" : ""}`]),
         ...(names("card.title") && !names("card.description") && card.description ? ["Details on the card:\n{{card.description}}"] : []),
         ...(names("note") || !card.note ? [] : ["Changes asked for: {{note}}"]),
-        // v126: an outside event's card says where it came from — a filled value like the others, so it is fitted into the
-        // goal with them (whole when it fits, attached when it doesn't), never at the cost of the zone's own words.
         ...(names("card.source") || cardReference(card.source) === "" ? [] : ["{{card.source}}"]),
     ];
     return [instructions, ...extra].join("\n\n");
 }
-/** Script output can carry carriage returns, colour codes and hidden marks a task goal refuses; the goal drops them. */
 const goalSafe = (value) => value.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000B-\u001F\u007F-\u009F\u2028\u2029\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/g, "");
-/** How a filled-in value is named where it is attached: the same words flowGoalCuts labels it with. */
 export function flowValueLabel(key, stageTitle = id => id) {
     if (key === "card.title")
         return "The card's title";
@@ -522,11 +415,6 @@ export function flowValueLabel(key, stageTitle = id => id) {
         return key;
     return `What ${stageTitle(match[1])} ${match[2] === "items" ? "listed" : match[2] === "report" ? "reported in full" : "found"}`;
 }
-/** A work zone's goal, filled from the card and kept within `limit`: the zone's own words stay whole, and every filled-in
- * value goes in whole. When they don't all fit, the longest values are attached instead (each named in the goal by
- * flowAttachedMark, and given to the agent whole by flowGoalCuts) until the rest fits: nothing is cut. Words that fill
- * the limit to the last character leave attached values a shorter mark, then none (they are still attached). Null only
- * when the template's own words are over the limit: the caller then files the zone's words alone (flowGoal). */
 export function fitFlowText(template, card, limit = FLOW_GOAL_LIMIT, stageTitle) {
     const matches = [...template.matchAll(FILLED)];
     const values = matches.map(match => goalSafe(fillOne(match[1], match[2], card)));
@@ -534,7 +422,6 @@ export function fitFlowText(template, card, limit = FLOW_GOAL_LIMIT, stageTitle)
     const attached = new Set();
     const build = () => { let at = 0; return template.replace(FILLED, () => { const i = at++; return attached.has(i) ? marks[i] : values[i]; }).trim(); };
     let goal = build();
-    // The longest first, so the fewest values leave the goal.
     const order = values.map((value, i) => i).filter(i => values[i].length > marks[i].length).sort((a, b) => values[b].length - values[a].length);
     for (const i of order) {
         if (goal.length <= limit)
@@ -551,12 +438,9 @@ export function fitFlowText(template, card, limit = FLOW_GOAL_LIMIT, stageTitle)
     }
     return goal.length <= limit ? goal : null;
 }
-/** A work zone's goal for a card: its words, the card and any note, fitted (fitFlowText); when the zone's words leave no
- * room for the card's own lines, its words alone, with the card attached. Null only for words over the limit. */
 export function flowGoal(instructions, card, stageTitle) {
     return fitFlowText(flowWorkTemplate(instructions, card), card, FLOW_GOAL_LIMIT, stageTitle) ?? fitFlowText(instructions, card, FLOW_GOAL_LIMIT, stageTitle);
 }
-/** The first email address a card mentions, or "" — what {{card.email}} holds. */
 export function cardEmailOf(card) {
     return /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/.exec(`${card.title}\n${card.description ?? ""}`)?.[0] ?? "";
 }
@@ -576,11 +460,9 @@ function fillOne(key, stage, card) {
     }
 }
 const KIND_COLORS = { inbox: "slate", task: "blue", report: "violet", approval: "amber", check: "blue", "pull-request": "blue", update: "green", notify: "green", sort: "violet", draft: "violet", request: "blue", email: "green", tool: "blue", wait: "slate", subagent: "violet", send: "green", choose: "amber", done: "green" };
-/** A step id as the lead may write it (sort_by_hand, Sort-By-Hand) in the one form zones use. */
 const idOf = (value) => value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
 const slugOf = (title) => title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 28) || "zone";
 const overlaps = (a, b) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
-/** A wait step's settings: what it waits for and how long (3 days when neither the step nor the zone it keeps says). */
 function waitFromStep(step, old, at) {
     if ((step.waitFor ?? old?.for) === "hours") {
         const from = clockTime(step.from ?? old?.from ?? "22:00"), to = clockTime(step.until ?? old?.to ?? "06:00");
@@ -594,7 +476,6 @@ function waitFromStep(step, old, at) {
         throw new FlowContractError([`${at}.wait: say how long it waits, like "3 days" or "4 hours" (up to 30 days)`]);
     return { for: step.waitFor ?? old?.for ?? "reply", minutes };
 }
-/** A step's time limit: the one it gives, the one its zone had, or none ("none" removes one). */
 function limitFromStep(step, old, at, find) {
     if (step.remindAfter === undefined)
         return old === null ? null : { ...old, ...(step.thenMoveTo === undefined ? {} : { to: step.thenMoveTo.trim() === "" ? null : find(step.thenMoveTo, "thenMoveTo") }) };
@@ -605,21 +486,16 @@ function limitFromStep(step, old, at, find) {
         throw new FlowContractError([`${at}.remindAfter: say when to remind, like "2 days" (up to 30 days)`]);
     return { minutes, to: typeof step.thenMoveTo === "string" && step.thenMoveTo.trim() !== "" ? find(step.thenMoveTo, "thenMoveTo") : step.thenMoveTo === undefined ? old?.to ?? null : null };
 }
-/** What a draft zone asks for when the steps leave it out. */
 export const DRAFT_DEFAULT = "Write a short, friendly reply to the person who sent this card, in plain words.";
-/** What an agent is asked when the steps leave it out: the card, any send-back note, and every earlier research step's report. */
 function defaultInstructions(kind, earlier) {
     const notes = earlier.filter(one => one.kind === "report").map(one => `\n\nNotes from ${one.title}:\n{{stage.${one.id}}}`).join("");
     return kind === "task"
         ? `{{card.title}}\n\n{{card.description}}${notes}\n\nChanges asked for (if any): {{note}}`
         : `Investigate this and write a short, clear report with a summary first: {{card.title}}\n\n{{card.description}}${notes}\n\nFeedback to address (if any): {{note}}`;
 }
-/** Steps as the lead's flow tool and `toolroll flows` take them: "me" as a decider is the person asking, stored by name. */
 export function stepsFor(steps, name) {
     return Array.isArray(steps) ? steps.map(step => isRecord(step) && typeof step["decider"] === "string" && /^(me|myself|i|you|the operator)$/i.test(step["decider"].trim()) ? { ...step, decider: name } : step) : steps;
 }
-/** An edit's steps with what a kept step leaves out of its kind and name filled from the zone it keeps (by id), so each
- * reads as the one schema its kind has. Anything else it leaves out carries over when the flow is drawn (flowFromSteps). */
 export function withKeptSteps(steps, previous) {
     if (previous === null || !Array.isArray(steps))
         return steps;
@@ -640,18 +516,10 @@ export function withKeptSteps(steps, previous) {
         };
     });
 }
-/** A flow's steps, read by their one schema: `steps[0].routes[0]: unknown key 'to' (did you mean goesTo?)`. */
 export function readFlowSteps(input, previous = null) {
     const read = parseContract(flowStepsSchema, { steps: withKeptSteps(Array.isArray(input) ? input.map(legacySubagentStep) : input, previous) }, FLOW_ALIASES);
     return read.ok ? { ok: true, value: read.value.steps } : read;
 }
-/**
- * A flow from an ordered list of steps: ids from names, each step leading
- * to the next, a Done zone at the end when none is listed, and a decision
- * sending work back to the nearest earlier step that does work. New zones
- * are laid out in rows; zones kept from `previous` keep their place. Throws
- * FlowContractError, each line naming the step's path (`steps[2].next: ...`).
- */
 export function flowFromSteps(input, previous = null) {
     const read = readFlowSteps(input, previous);
     if (!read.ok)
@@ -665,7 +533,6 @@ export function flowFromSteps(input, previous = null) {
         if (title === "")
             throw new FlowContractError([`steps[${index}].title: must not be empty`]);
         const kind = step.kind;
-        // A new step keeps an id it is given (so the other steps can point at it by that id); otherwise its name makes one.
         const given = ZONE_ID.test(asked) && !used.has(asked) ? asked : null;
         let id = old?.id ?? given ?? slugOf(title);
         for (let n = 2; old === null && used.has(id); n++)
@@ -703,11 +570,8 @@ export function flowFromSteps(input, previous = null) {
         const onFail = kind === "done" ? null
             : typeof notSure === "string" && notSure.trim() !== "" ? find(notSure, failKey)
                 : keptFail ?? (kind === "approval" ? worker?.id ?? (drafts[0].id === id ? null : drafts[0].id)
-                    // A reply to a choice says what to change: it goes back to the work before it, as its note.
                     : kind === "choose" ? worker?.id ?? null
-                        // Red CI goes back to the build before it, carrying the failing check.
                         : kind === "pull-request" ? [...earlier].reverse().find(one => one.kind === "task")?.id ?? null : null);
-        // "owner": whoever owns the flow when the card arrives.
         const toOwner = kind === "approval" && (step.decider === undefined ? old?.toOwner === true : typeof step.decider === "string" && /^(owner|the owner|flow owner|the flow owner|the flow's owner)$/i.test(step.decider.trim()));
         const approver = kind !== "approval" || toOwner ? null
             : step.decider === undefined ? old?.approver ?? null
@@ -716,7 +580,6 @@ export function flowFromSteps(input, previous = null) {
         stages.push({
             id, title, kind,
             zone: old?.zone ?? { x: 0, y: 0, w: 260, h: kind === "done" || kind === "notify" || kind === "send" ? 220 : 300, color: KIND_COLORS[kind] },
-            // A kept step on our default instructions gets the default again, so it reads any research step added before it.
             instructions: kind === "subagent" ? step.instructions?.trim() || old?.instructions || "Read the card and decide what happens next."
                 : kind === "draft" ? step.instructions?.trim() || old?.instructions || DRAFT_DEFAULT
                     : kind === "task" || kind === "report"
@@ -729,7 +592,6 @@ export function flowFromSteps(input, previous = null) {
                 : kind === "update" ? step.message?.trim() || old?.message || "Done: {{card.title}}" : null,
             close: kind === "update" ? step.close ?? old?.close ?? true : null,
             script: kind === "check" ? step.script?.trim() || old?.script || null : null,
-            // Left out, a code step runs in a copy of the project (the card's work, or the main branch), as scripts always have.
             ...(kind === "check" ? {
                 ...(step.runIn !== undefined ? { runIn: step.runIn } : old?.runIn === undefined ? {} : { runIn: old.runIn }),
                 ...(step.routes !== undefined ? routesOf(step.routes) : old?.routes === undefined ? {} : { routes: old.routes }),
@@ -742,14 +604,12 @@ export function flowFromSteps(input, previous = null) {
             ...(kind === "tool" ? { tool: { server: step.server ?? old?.tool?.server ?? "", name: step.tool ?? old?.tool?.name ?? "", args: typeof step.args === "string" ? step.args : step.args !== undefined ? JSON.stringify(step.args) : old?.tool?.args ?? "{}" } } : {}),
             ...(kind === "wait" ? { wait: waitFromStep(step, old?.wait ?? null, at) } : {}),
             ...(kind === "pull-request" && (step.merge === undefined ? old?.merge !== undefined : step.merge !== false) ? { merge: step.merge === undefined || step.merge === true || step.merge === false ? old?.merge ?? "squash" : step.merge } : {}),
-            // v92: "nobody" (or "none") takes a subagent off an approval step.
             ...((kind === "approval" || kind === "subagent") && (step.subagent === undefined ? old?.subagent !== undefined : !/^(nobody|none|no one)$/i.test(step.subagent.trim())) ? { subagent: idOf(step.subagent ?? old.subagent) } : {}),
             ...(kind === "subagent" ? step.routes !== undefined ? routesOf(step.routes) : old?.routes === undefined ? {} : { routes: old.routes } : {}),
             ...(kind === "subagent" && (step.reply ?? old?.reply) === true ? { reply: true } : {}),
             ...(kind === "choose" ? { options: choicesFromStep(step, old?.options ?? null, at, find) } : {}),
             ...(kind === "task" && (step.repo ?? old?.repo) !== undefined && (step.repo ?? old?.repo).trim() !== "" ? { repo: (step.repo ?? old?.repo).trim() } : {}),
             ...(() => {
-                // "If no reply" on a choice is where it moves once the reminder comes.
                 const asked = kind === "choose" && step.thenMoveTo === undefined && typeof step.ifNoReply === "string" ? { ...step, thenMoveTo: step.ifNoReply } : step;
                 if (kind === "choose" && asked.thenMoveTo !== undefined && asked.remindAfter === undefined && old?.limit === undefined)
                     throw new FlowContractError([`${at}.remindAfter: say how long to wait for a choice first (like "2 days")`]);
@@ -759,8 +619,6 @@ export function flowFromSteps(input, previous = null) {
             next, onFail,
         });
     });
-    // {{stage.<ref>}} in a step's words names a step as the lead wrote it (draftReply, Draft reply):
-    // it is rewritten to that step's id, the same way the steps themselves are named.
     const refs = (text) => text.replace(/\{\{\s*stage\.([A-Za-z0-9_ -]{1,60}?)(\.items|\.report)?\s*\}\}/g, (whole, ref, part) => {
         const hit = drafts.find(one => one.id === ref) ?? drafts.find(one => one.id === idOf(ref) || one.id.replace(/-/g, "") === idOf(ref).replace(/-/g, "") || one.title.toLowerCase() === ref.trim().toLowerCase());
         return hit === undefined ? whole : `{{stage.${hit.id}${part ?? ""}}}`;
@@ -777,9 +635,6 @@ export function flowFromSteps(input, previous = null) {
         if (stage.tool !== undefined)
             stage.tool = { ...stage.tool, args: refs(stage.tool.args) };
     }
-    // Lay out the new zones: in rows of four on a new flow, beside the step before them on an edited one.
-    // A new flow that branches (a sort, or a script's answers) is laid out in columns by step instead,
-    // each branch below the one before, so no arrow crosses a zone.
     const placed = stages.filter(one => kept.get(one.id)?.zone === one.zone).map(one => one.zone);
     const branches = previous === null && stages.some(one => (one.sort?.answers.length ?? 0) > 0 || (one.routes?.length ?? 0) > 0 || choiceTargets(one).length > 0);
     const columns = new Map();
@@ -822,18 +677,15 @@ export function flowFromSteps(input, previous = null) {
         stage.zone = at;
         placed.push(at);
     });
-    // The drawing is checked as the canvas's is; its zones are the steps, in order, so a zone's problem names its step.
     const drawn = readFlowDefinition({ version: FLOW_DEFINITION_VERSION, start: stages[0].id, stages });
     const refuse = (issues) => new FlowContractError(issues.map(one => inStepWords(one.line, "steps", stages.map(stage => stage.kind))));
     if (!drawn.ok)
         throw refuse(drawn.issues);
-    // A {{stage.…}} these steps add must be one its zone hands on (src/contracts/stage-output.ts); ones the flow had stay.
     const references = stageReferenceProblems(drawn.value, previous);
     if (references.length > 0)
         throw refuse(references);
     return drawn.value;
 }
-/** A choose step's options: each with its words and the step it goes to ("end", or no step, ignores the card); kept ones carry over. */
 function choicesFromStep(step, old, at, find) {
     if (step.options === undefined) {
         if (old !== null)
@@ -846,12 +698,10 @@ function choicesFromStep(step, old, at, find) {
         return { label, to: goes === "" || /^(end|ignore|ignored|stop|close)$/i.test(goes) ? FLOW_END : find(goes, `options[${n}].goesTo`) };
     });
 }
-/** A sort step as the lead describes it: answers name the steps they go to; what it leaves out carries over from the zone it keeps. */
 function sortFromStep(step, old, find) {
     const answers = step.answers !== undefined
         ? step.answers.map((one, n) => ({ answer: one.answer.trim(), means: (one.means ?? "").trim() || one.answer.trim(), to: one.goesTo.trim() !== "" ? find(one.goesTo, `answers[${n}].goesTo`) : "" }))
         : old?.answers ?? [];
-    // A percentage (80) or a fraction (0.8).
     const sure = step.sureAt !== undefined ? (step.sureAt > 1 ? step.sureAt / 100 : step.sureAt) : old?.sureAt ?? SORT_SURE_AT;
     const notes = step.alsoNote !== undefined ? step.alsoNote.map(one => one.kind === "score"
         ? { id: one.id ?? "", kind: "score", question: one.question.trim(), levels: one.levels ?? [] }
@@ -859,18 +709,14 @@ function sortFromStep(step, old, find) {
         : old?.notes ?? [];
     return { question: step.question?.trim() || old?.question || "", answers, sureAt: sure, notes };
 }
-/** What confirming a new or changed flow means, in the canvas's words: each step's job and path, what changed, and that the usual approvals still apply. */
 export function flowTerms(definition, previous) {
     const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? "nowhere";
-    // "Then → Go ahead?" ends a sentence already.
     const to = (id) => { const title = titleOf(id); return /[.?!]$/.test(title) ? title : `${title}.`; };
-    // Fill-ins read as what they will hold.
     const plain = (text) => text.replace(/\{\{\s*(card\.title|card\.description|card\.email|note|stage\.([a-z0-9-]+))\s*\}\}/g, (_match, key, stage) => key === "card.title" ? "[card title]" : key === "card.description" ? "[card details]" : key === "card.email" ? "[the card's email address]" : key === "note" ? "[send-back note]" : `[${titleOf(stage ?? null)} report]`);
     const same = (a, b) => JSON.stringify({ ...a, zone: null }) === JSON.stringify({ ...b, zone: null });
     const describe = (stage, index, mark) => {
         const lines = [`${index + 1}. ${stage.title} — ${FLOW_KIND_WORDS[stage.kind].label}${mark}`];
         if (stage.kind === "task" || stage.kind === "report") {
-            // Instructions the steps left to us are said in words; the operator's own are shown as written.
             const earlier = definition.stages.slice(0, index);
             const reports = earlier.filter(one => one.kind === "report").map(one => one.title);
             const notes = reports.length === 0 ? "" : `, using the notes from ${reports.join(" and ")}`;
@@ -940,7 +786,6 @@ export function flowTerms(definition, previous) {
         if (removed.length > 0)
             terms.push(`Removes ${removed.map(one => one.title).join(", ")}. Any cards there go back to ${titleOf(definition.start)}.`);
     }
-    // New cards that start in a holding zone aren't sorted until someone moves them to the sort: say so before it's confirmed.
     const first = definition.stages.find(one => one.id === definition.start);
     const sorter = definition.stages.find(one => one.kind === "sort");
     if (first?.kind === "inbox" && sorter !== undefined)
@@ -962,10 +807,7 @@ export function flowTerms(definition, previous) {
 }
 const zone = (x, y, color, h = 300) => ({ x, y, w: 260, h, color });
 const stage = (id, title, kind, at, rest = {}) => ({ id, title, kind, zone: at, instructions: null, planning: kind === "task" ? "auto" : null, approver: null, message: null, close: kind === "update" ? true : null, script: null, sort: null, next: null, onFail: null, ...rest });
-/** The label an issue gets to become work: what the Issues to PRs template and the issue starter flow watch for. */
 export const ISSUE_LABEL = "toolroll";
-/** Ready-made flows: the coding flow is the whole business process around a change. A template's `trigger`
- * (a trigger's settings, as flow-triggers.ts reads them) is added with it. */
 export const FLOW_TEMPLATES = [
     {
         id: "coding",

package/dist/folder-gate.js

@@ -1,25 +1,7 @@
-/**
- * Whether the console may read a folder synchronously right now.
- *
- * The console answers every page on one thread, so one synchronous read of a folder that has stopped answering (a
- * drive that hangs, a folder macOS holds in iCloud) freezes the console with it: it listens and answers nothing, not
- * even /healthz (the 0.9.82 and 0.9.87 deploys). So the console's own work (its request handling and its background
- * pass, serve.ts) runs inside a folder scope: there, a synchronous read of a person's folder goes ahead only when that
- * folder answered an off-thread look lately (project-identity.ts `answering`), or it lies in the console's own data.
- * Otherwise the read isn't made and its caller refuses, says the folder is unavailable, or throws FolderUnavailable.
- *
- * Availability never decides authorization: a held-back canonicalization throws FolderUnavailable (project.ts), never
- * answers null, so no caller falls back to a path's spelling because a folder didn't answer.
- *
- * Work outside a console scope (the worker, even in the same process as the console; `up`; the CLI) reads as it
- * always did.
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { resolve, sep } from "node:path";
 const scope = new AsyncLocalStorage();
-/** What a caller says, and throws, when the gate holds a read back. */
 export const FOLDER_DIDNT_ANSWER = "the folder didn't answer";
-/** A synchronous read the console's folder gate held back: the folder is unavailable now, which is never a "no". */
 export class FolderUnavailable extends Error {
     path;
     constructor(path) {
@@ -28,16 +10,13 @@ export class FolderUnavailable extends Error {
         this.name = "FolderUnavailable";
     }
 }
-/** Runs `work` (and everything it starts) inside the console's folder scope. */
 export function inFolderScope(gate, work) {
     return scope.run(gate, work);
 }
-/** Whether a synchronous read of `path` may happen now. Outside a console's folder scope: always. */
 export function folderAnswers(path, pointer = false) {
     const gate = scope.getStore();
     return gate === undefined || gate(resolve(path), pointer);
 }
-/** `path` is `folder` or inside it (both resolved). */
 export function insideFolder(path, folder) {
     return path === folder || path.startsWith(folder.endsWith(sep) ? folder : folder + sep);
 }