toolroll 0.9.104 → 0.9.105

package/dist/flow-browser.js

@@ -1,21 +1,7 @@
-/**
- * Browser use in a flow's script zone: a per-flow approval a person gives with their own proof, so that zone's launch
- * gets the one sandbox rule a project check gets for Chromium (sandbox-runtime.ts SEATBELT_CHROMIUM) and nothing more.
- *
- * Two halves, both needed. The flow's drawing says which "Run a script" zones start a browser (`browser: true`, part of
- * the flow's digest and said when the flow is confirmed); anyone who may change the flow can say it. Then a person, with
- * their password, sign-in or own yes in chat (never a lead's or remote run's token: person-proof.ts), approves browser use for the flow
- * as it stands. The approval seals the flow's digest and, for each browser zone, its script's name and content digest.
- * At launch (flow-steps.ts) the zone gets the rule only while all of that still holds: the same drawing, the same
- * scripts, a person's proof, a signer who still reaches the project. Anything else gets nothing, and the card waits with
- * a plain line naming the missing approval instead of Chromium crashing in the sandbox. Builds, checks, tool servers and
- * every other flow launch (setup, triggers, zones that don't say browser) are untouched.
- */
 import { createHash } from "node:crypto";
 import { canonicalJson } from "./canonical-json.js";
 import { personProof } from "./person-proof.js";
 import { flowDigest, validateFlowDefinition } from "./flows.js";
-/** v144: each approval of browser use, live or ended. `digest` is browserApprovalDigest of what was approved. Additive only. */
 export const FLOW_BROWSER_SCHEMA = `
 CREATE TABLE IF NOT EXISTS flow_browser_grant (
   id            INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -41,14 +27,9 @@ function definitionOf(flow) {
         return null;
     }
 }
-/** The approval's digest: domain-separated over the whole of its terms, so a changed flow, drawing, revision or any
- * covered script (a restored one is a new version) is a different approval. */
 export function browserApprovalDigest(terms) {
     return createHash("sha256").update(`toolroll:flow-browser:${canonicalJson(terms)}`, "utf8").digest("hex").slice(0, 32);
 }
-/** The flow's script zones that say they start a browser, each with the script it runs now; null when one's script is
- * missing, waiting for approval, or runs a project file (an approval seals the script's own text, never a file the
- * project can change). */
 export function browserZonesOf(store, flow, definition) {
     const out = [];
     for (const stage of definition.stages) {
@@ -61,7 +42,6 @@ export function browserZonesOf(store, flow, definition) {
     }
     return out;
 }
-/** What an approval of this flow would be about now, read from the store; null when it can't be approved. */
 export function browserTermsOf(store, flow) {
     const definition = definitionOf(flow);
     const zones = definition === null ? null : browserZonesOf(store, flow, definition);
@@ -82,23 +62,13 @@ function readGrant(row) {
     return { id: Number(row["id"]), flow: Number(row["flow"]), repo: String(row["repo"]), revision: Number(row["flow_revision"]), flowDigest: String(row["flow_digest"]), digest: String(row["digest"]),
         zones: zones, signedBy: String(row["signed_by"]), signedAt: String(row["signed_at"]), proof: String(row["proof"]) };
 }
-/** The flow's live approval, as recorded (whether it still stands is browserStanding's question). */
 export function liveBrowserGrant(store, flowId) {
     return readGrant(store.handle.prepare("SELECT * FROM flow_browser_grant WHERE flow = ? AND revoked_at IS NULL").get(flowId));
 }
-/** Whether `name` may approve on `repo` now: a live approver account that reaches the project. */
 function approverNow(store, name, repo) {
     const account = store.accountOf(name);
     return account !== null && account.revokedAt === null && account.role === "approver" && store.accountCanAccess(name, repo);
 }
-/**
- * Whether `zone` of this flow may start a browser now. `run`, when given, is what the caller is about to run — the
- * drawing it read and the very script object it hands the launch — and the answer is about exactly that. The live
- * approval stands only when its digest is the approval this flow would be now (same flow, project, drawing revision and
- * digest, and every browser zone's script name, version and digest), it was a person's, and its signer is still an
- * approver who reaches the project; `run`'s drawing must be that drawing and its script that zone's script. Anything
- * unreadable, changed or mismatched is a no, with the plain words a card waits with.
- */
 export function browserStanding(store, flowId, zone, run) {
     const flow = store.getFlow(flowId);
     const definition = flow === null ? null : definitionOf(flow);
@@ -120,19 +90,12 @@ export function browserStanding(store, flowId, zone, run) {
         && personProof(grant.proof) && approverNow(store, grant.signedBy, flow.repo);
     return stands ? { allowed: true } : { allowed: false, said: `${stage.title} starts a browser, but browser use was approved for an earlier version of the ${flow.name} flow or its scripts, so it didn't run. ${approve}` };
 }
-/** What approving means, in words the person reads before they give their password. */
 export function browserTerms(zones) {
     return [
         `Lets ${zones.map(one => `the ${one.script} script (zone ${one.zone})`).join(", ")} start Playwright's Chromium headless shell inside the flow's sandbox: the same one macOS service a project check gets for it, and nothing else.`,
         "Changing the flow or one of these scripts (even back to how it was) ends it; nothing else gets it.",
     ];
 }
-/**
- * Approve browser use for the flow as it stands. `proof` is the signer's credential method, proved by the caller just
- * now; only a person's counts (a lead's or remote run's token is refused), from an approver who reaches the project.
- * Re-reads the flow, its zones and scripts in the one transaction that writes; `sawDigest` (required) is the approval
- * (browserApprovalDigest: drawing and scripts) the person read, and anything else is refused. Replaces any live one.
- */
 export function signFlowBrowser(store, input, now) {
     if (!personProof(input.proof))
         return { ok: false, message: "Browser use needs a person's own approval (a lead's or remote run's token can't give it)." };
@@ -167,7 +130,6 @@ export function signFlowBrowser(store, input, now) {
         return { ok: true, grant: { ...terms, id, digest, signedBy: input.signer, signedAt: now.toISOString(), proof: input.proof } };
     });
 }
-/** Any approver on the project ends it, with no password: lowering authority. False when there was none. */
 export function revokeFlowBrowser(store, flowId, by, now) {
     return store.transact(() => {
         const flow = store.getFlow(flowId);
@@ -178,10 +140,6 @@ export function revokeFlowBrowser(store, flowId, by, now) {
     });
 }
 const dayWords = (at) => new Date(at).toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
-/**
- * Browser use for one flow, read from the store (no writes: page visits call it). Whether it is allowed is exactly
- * browserStanding's answer for the flow's browser zones; the rest only says why in plain words.
- */
 export function browserViewOf(store, flow) {
     const definition = definitionOf(flow);
     const stages = definition?.stages.filter(stage => stage.kind === "check" && stage.browser === true) ?? [];

package/dist/flow-cadence.js

@@ -1,25 +1,11 @@
-/**
- * Flow passes that don't wait for builds. The worker's pass used to move
- * cards only between builds, so a card whose research finished sat still
- * while another build ran (Oct 4: five minutes). Now the worker runs these
- * passes on their own cadence beside its builds, and a finished build,
- * research or check moves its card at once.
- *
- * Model-free and cheap: nothing here starts a build. Cards entering a build
- * zone file their task, which waits for a free slot like any other.
- */
 import { advanceFlows } from "./flow-engine.js";
 import { runFlowTriggers } from "./flow-triggers.js";
 import { watchFlowReplies } from "./flow-replies.js";
 import { runFlowSteps } from "./flow-steps.js";
 import { gitOf } from "./landed-cleanup.js";
 import { NO_YOUIYOUX_PASS, runYouiyoux } from "./youiyoux-intake.js";
-/** How often the worker moves cards, checks triggers, reads replies and runs steps, builds or not. */
 export const FLOW_EVERY_MS = 15_000;
 const running = new Set();
-/** One pass of a kind for a project at a time in this process: a second one asked for while it runs is skipped
- * (`idle`), and the next cadence takes up whatever it would have done. Cards are also claimed in the database,
- * so passes in other processes can't act twice either. */
 export async function alone(kind, project, idle, run) {
     const key = `${kind}\u0000${project}`;
     if (running.has(key))
@@ -33,9 +19,6 @@ export async function alone(kind, project, idle, run) {
     }
 }
 const NO_REQUESTS = NO_YOUIYOUX_PASS;
-/** One project's flow pass: triggers (which may start cards), youiyoux requests (which file tasks that wait for a
- * person, and move an options request's options to youiyoux's hub and a decision there back), replies (which move waiting cards), steps, then moves. `halted` (a stop or paused admission) skips
- * everything that reaches outside; moves still run. */
 export async function flowHousekeeping(store, repo, clock, io, halted) {
     const triggers = halted() ? { added: 0, checked: 0, problems: [] }
         : await alone("triggers", repo, { added: 0, checked: 0, problems: [] }, () => runFlowTriggers(store, repo, clock(), io.triggers));
@@ -48,17 +31,13 @@ export async function flowHousekeeping(store, repo, clock, io, halted) {
                 return { ...NO_REQUESTS, problems: [`youiyoux: ${error instanceof Error ? error.message : "could not read requests"}`] };
             }
         });
-    // One mailbox serves every project, so its reads are one at a time across them all.
     const replies = halted() ? { read: 0, taken: 0, problem: null }
         : await alone("replies", "*", { read: 0, taken: 0, problem: null }, () => watchFlowReplies(store, clock(), io.replies));
     const steps = halted() ? { ran: 0, problems: [] }
         : await alone("steps", repo, { ran: 0, problems: [] }, () => runFlowSteps(store, repo, clock(), io.steps));
-    // Last, so a step that just finished, or a card a trigger just added, moves now.
     const flows = moveCards(store, repo, clock(), io.evidenceRoot);
     return { triggers, youiyoux, replies, steps, flows };
 }
-/** Move one project's cards. Synchronous, so two can't overlap in a process; each move is checked against the
- * card's visit in its own transaction, so a pass in another process can't move a card twice. */
 export function moveCards(store, repo, now, evidenceRoot) {
     try {
         return advanceFlows(store, repo, now, evidenceRoot === undefined ? {} : { evidenceRoot });
@@ -67,8 +46,6 @@ export function moveCards(store, repo, now, evidenceRoot) {
         return { moved: 0, filed: [], problems: [`flows: ${error instanceof Error ? error.message : "could not move cards"}`] };
     }
 }
-/** A build, research or check just finished: move the cards in this project, and in the project of any flow whose
- * card that task belongs to (a build zone may build in another project), now rather than on the next pass. */
 export function moveCardsAfter(store, repo, tasks, now, evidenceRoot) {
     const projects = new Set([repo]);
     for (const task of tasks) {
@@ -78,7 +55,7 @@ export function moveCardsAfter(store, repo, tasks, now, evidenceRoot) {
             if (flow !== null)
                 projects.add(flow.repo);
         }
-        catch { /* not a task with a card */ }
+        catch { }
     }
     const outcome = { moved: 0, filed: [], problems: [] };
     for (const project of projects) {

package/dist/flow-card-task.js

@@ -1,5 +1,3 @@
-/** The task behind an agent zone, read through the same status as its task page.
- * Only saved milestone progress belongs on the card; tool calls and logs do not. */
 import { machineChecked } from "./machine-check.js";
 import { assignmentOf } from "./assignment.js";
 import { scanForSecrets } from "./evidence.js";
@@ -7,8 +5,6 @@ import { scrubIntegrationText } from "./integrations.js";
 import { assignmentStatusFacts, taskStatusOf } from "./task-status.js";
 import { taskWorkSummaryOf } from "./work-summary.js";
 import { buildProgressOf } from "./workspace-ui.js";
-/** Redact before shortening: a cut-off credential must never slip through a scanner.
- * Structured arguments, commands and credential assignments aren't card copy. */
 function cardReason(text, fallback, secrets) {
     if (text === null)
         return fallback;
@@ -20,9 +16,6 @@ function cardReason(text, fallback, secrets) {
         return fallback;
     return clean.length > 100 ? `${clean.slice(0, 99).trimEnd()}…` : clean;
 }
-/** A task's status as its page reads it, from the store alone (no evidence files); null when it can't be read. */
-/** `root`: where results' saved evidence is. Without it the receipt is read without its saved checks, so a completion
- * (bound to the receipt read with them) doesn't read as one: a status that must say Complete passes it. */
 export function storedTaskStatus(store, taskId, repo, now, root) {
     const access = { principal: "operator", repos: [repo], dependencyRepos: [repo] };
     const assignment = assignmentOf(store, taskId, now, access, root);
@@ -35,10 +28,7 @@ export function storedTaskStatus(store, taskId, repo, now, root) {
     const facts = assignmentStatusFacts(assignment, { work: work.status, planning: live?.role === "planner" });
     if (machineChecked(store, assignment.activeTaskId))
         facts.machine = true;
-    // The canvas reads no evidence files. Keep the machine's recorded check visible
-    // when the full receipt has no artifact root from which to read its check.
     const check = assignment.receipt === null ? null : store.runCheckFor(assignment.receipt.runId);
-    // With neither, nothing about the check was read here: the line says nothing about it, never a pass and never an ask.
     if (facts.checks?.status === "unavailable")
         facts.checks = check === null ? null : { ...facts.checks, status: check.status, exitCode: check.exitCode };
     return { status: taskStatusOf(facts), activeTaskId: assignment.activeTaskId, live };
@@ -50,7 +40,6 @@ export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
     const { status, live } = read;
     if (status.headline === "Needs you") {
         const fallback = status.need?.action.label ?? "Open the task";
-        // The question itself is useful; routine approvals are clearer as the short action.
         const what = status.need?.key === "answer" || status.need?.key === "other"
             ? cardReason(status.sentence, fallback, secrets) : fallback;
         return `Waiting on you: ${what}`;

package/dist/flow-changed.js

@@ -1,17 +1,5 @@
-/**
- * The one road for a change to what a flow runs: its drawing saved, or a script one of its zones runs saved or removed.
- * Every approval a person gave for the flow as it was ends here, in the same transaction as the write, with its ledger
- * line, so the flow page, `flows show` and chat all say it ended and why:
- *  - "Runs on its own" (flow-unattended.ts): its grants end ("flow changed" / "script changed"), and the work they
- *    pre-authorized falls back to a person.
- *  - Browser use (flow-browser.ts): its approval seals the drawing and each browser zone's script, so the change itself
- *    stops it standing (browserStanding re-proves at every launch). Here it is said once in the ledger, for each
- *    flow whose approval stood before the write and doesn't after; the page shows it as expired with the reason.
- * Nothing here widens anything: it only ends approvals.
- */
 import { browserViewOf } from "./flow-browser.js";
 import { endUnattendedGrants } from "./flow-unattended.js";
-/** The flows a change reaches: the flow itself, or every flow in the script's project with a zone that runs it. */
 function flowsOf(store, change) {
     if ("flow" in change) {
         const flow = store.getFlow(change.flow);
@@ -27,10 +15,6 @@ function flowsOf(store, change) {
         }
     });
 }
-/**
- * Run `write` (the change itself) and end what it ends, all in one transaction. `write` answers whether it changed
- * anything; when it didn't, nothing else happens. Returns what `write` returned.
- */
 export function flowChanged(store, change, by, now, write, changed = result => result === true) {
     return store.transact(() => {
         const before = new Map(flowsOf(store, change).map(flow => [flow.id, browserViewOf(store, flow)?.status === "allowed"]));

package/dist/flow-code.js

@@ -1,20 +1,3 @@
-/**
- * Code in flows (v90): the project's scripts — shell, Python or Node, written
- * in the library or a file already in the project — run with no AI.
- *
- * - The script gets the card: as JSON on stdin and in the file $FLOW_INPUT
- *   (its title, details, email, note, owner, where it came from, and what
- *   every earlier zone produced), with a few plain variables beside it.
- *   Card text reaches it only as data, never as part of a command.
- * - What it prints is the step's result: later zones use it as
- *   {{stage.<zone>}}. A last line "goto: <answer>" picks the zone the card
- *   goes to next, from the zone's answers.
- * - Secrets the zone names come from the flow's saved secrets as
- *   environment variables; their values never reach the output or the log.
- * - It runs inside the same fence as agents (Toolroll's own state and
- *   keys are out of reach), under a time limit, with the setup's plain
- *   environment rather than this process's.
- */
 import { prepareProtectedStorage, storageRefusalOf } from "./protected-storage.js";
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
@@ -32,32 +15,24 @@ export { projectFile };
 import { LANGUAGE_WORDS } from "./flows.js";
 export { LANGUAGE_WORDS, SCRIPT_LANGUAGES } from "./flows.js";
 const EXTENSION = { shell: "sh", python: "py", node: "mjs" };
-/** A step's result on the card: what the script printed, up to what a step passes on (the end, when longer; the whole
- * is in the step's log). */
 export const CODE_OUTPUT_CHARS = TEXT_LIMITS.stageOutput;
 const LOG_CHARS = 64_000;
-/** How a file runs in each language: sh, Python 3, and the Node this app runs on. */
 function runtimeOf(language, file) {
     return language === "python" ? { file: "python3", args: [file] } : language === "node" ? { file: process.execPath, args: [file] } : { file: "/bin/sh", args: [file] };
 }
-/** What it printed, without key-shaped lines or saved secrets, and the goto line taken off the end. */
 export function codeOutput(stdout, secrets) {
     const clean = scrubSecrets(stdout.replace(/\r\n?/g, "\n"), secrets);
     const lines = clean.replace(/\s+$/, "").split("\n");
     const last = lines.at(-1) ?? "";
     const goto = /^goto:\s*(.{1,40})$/i.exec(last.trim());
-    // Whole: the step passes it on whole up to CODE_OUTPUT_CHARS, and attaches longer to the card, linked (flow-steps settle).
     const body = (goto === null ? lines : lines.slice(0, -1)).join("\n").trim();
     return { output: redactSecretLines(body, scanForSecrets(body)), goTo: goto === null ? null : goto[1].trim() };
 }
-/** Run one script once, with the card as its input. */
 export async function runCode(run) {
     const { script } = run;
     const language = script.language;
     const tag = randomBytes(6).toString("hex");
     mkdirSync(run.scratch, { recursive: true });
-    // The input and an inline script live in the launch's own folder, the one place beside its working folder its fence
-    // gives back (every other launch folder, and every other flow copy in the scratch pool, stay out of reach).
     const files = run.launch?.folder ?? run.scratch;
     const inputFile = join(files, `flow-input-${tag}.json`);
     let scriptFile = null;
@@ -75,8 +50,6 @@ export async function runCode(run) {
             scriptFile = own;
         }
         const runtime = runtimeOf(language, scriptFile);
-        // The card goes in on stdin from its file (never a pipe): a script that doesn't read it can finish
-        // first without breaking anything. Only our own paths are in the command; the card is only data.
         const ran = await run.shell("/bin/sh", ["-c", 'exec "$@" < "$FLOW_INPUT"', "flow-script", runtime.file, ...runtime.args], {
             cwd: run.cwd, timeoutMs: script.timeoutMinutes * 60_000, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST, processGroup: true,
             env: { ...run.env, ...run.secrets, ...(run.launch?.env ?? {}), FLOW_INPUT: inputFile }, ...(run.launch?.fence ?? {}),
@@ -90,7 +63,6 @@ export async function runCode(run) {
             return { state: "failed", exitCode: null, output: printed.output, printed: all, goTo: null, log, said: `${script.name} ran out of time after ${script.timeoutMinutes} minute${script.timeoutMinutes === 1 ? "" : "s"}.` };
         if (ran.notFound)
             return { state: "failed", exitCode: null, output: "", printed: all, goTo: null, log, said: `${script.name} couldn't start: no shell was found.` };
-        // 127: the shell couldn't find the language's program.
         if (ran.code === 127 && language === "python" && /python3/.test(ran.stderr))
             return { state: "failed", exitCode: 127, output: "", printed: all, goTo: null, log, said: "Python 3 isn't installed on this computer, so the script couldn't run." };
         if (ran.code !== 0) {
@@ -106,18 +78,11 @@ export async function runCode(run) {
             rmSync(scriptFile, { force: true });
     }
 }
-/** A clean folder to run in, made fresh for one run. */
 export function cleanFolder(scratch, name) {
     const path = join(scratch, `${name}-${randomBytes(4).toString("hex")}`);
     mkdirSync(path, { recursive: true, mode: 0o700 });
     return path;
 }
-/**
- * Cards from what a script printed (a Script trigger): a JSON list of
- * objects, JSON lines, or plain lines (each one a title). An object has a
- * title, and may have details, an email and its own key; otherwise the
- * words themselves are the key, so the same item never makes two cards.
- */
 export function cardsFromOutput(stdout) {
     const text = stdout.trim();
     if (text === "")
@@ -143,7 +108,7 @@ export function cardsFromOutput(stdout) {
         if (one !== null)
             return [one];
     }
-    catch { /* JSON lines or plain lines */ }
+    catch { }
     return text.split("\n").map(line => {
         const trimmed = line.trim();
         if (trimmed.startsWith("{")) {
@@ -163,8 +128,6 @@ export async function flowLaunch(store, options) {
         return null;
     const available = options.available ?? (() => macosFenceAvailable() || linuxFenceAvailable());
     const fenced = available();
-    // Asked first: a launch with no fence of its own (an instance operator allowed it, as inside another sandbox) makes
-    // its folder in the temp folder it was given, never among the fenced launches' (which an outer sandbox may hold).
     if (!fenced && !store.unfencedAgentsAllowed()) {
         return { problem: "This machine can't confine the flow's script (no macOS sandbox, no working bubblewrap), so it didn't run. Install bubblewrap, socat and ripgrep (Linux), or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`." };
     }
@@ -183,27 +146,20 @@ export async function flowLaunch(store, options) {
         return { folder: own, env, dispose };
     try {
         const poolRoots = [join(dirname(databaseFile), "worktrees"), options.scratch, ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
-        // Its scratch folder is a pool root (so another flow's copy is out of reach) and sealed: never read, at any policy.
-        // A copy is held to its project by the plane's own record of the repository, never what the copy says.
         const binding = options.copy ? trustedWorktreeBinding(options.repo, options.folder, poolRoots) : null;
-        // The policy its flow sealed; nothing sealed is v1 (the home configuration denied), never a wider one implicitly.
         const home = options.home ?? homedir();
-        // The storage check, awaited off this thread (protected-storage.ts).
         const storage = await prepareProtectedStorage(home);
         const boundary = taskBoundary({ worktree: options.folder, provider: "command", home, binding, policy: options.policy ?? 1, storage });
         const cache = buildCacheFolder(options.repo, home);
         const allowed = store.projectWrites(options.repo) !== "workspace" ? null : writeAllowlist({ provider: "command", home, worktree: options.folder, binding, launchFolder: own, cache });
-        // The project's read denies apply to flows as to builds (read live: a flow seals no list, and these only narrow).
         const readDeny = store.projectSandbox(options.repo).readDeny.map(one => readDenyPath(one, home));
         const fence = fenceFor("flow", { databaseFile, worktree: options.folder, home, boundary, readDeny, storage, policy: options.policy ?? 1, scratchRoots: [options.scratch], binding, runFolders: runFolders(own), poolRoots, extra: allowed?.deny ?? [],
             writes: allowed === null ? null : { writes: allowed.writes, readOnly: allowed.readOnly }, network: { mode: "open" },
-            // Chromium's one service, only for a script zone whose browser use a person approved, proved by the caller now.
             ...(options.browser === true ? { browser: true } : {}) });
         return { folder: own, env: { ...env, ...(allowed === null ? {} : buildCacheEnv(cache)) }, fence, dispose };
     }
     catch (error) {
         dispose();
-        // The storage check's own words survive: what didn't finish, and which program macOS may need to allow.
         return { problem: storageRefusalOf(error)?.message ?? "The flow's copy couldn't be bound to its project, so nothing ran." };
     }
 }

package/dist/flow-draft.js

@@ -1,12 +1,3 @@
-/**
- * Draft steps (v86): Claude writes something from a card — a reply, a
- * summary, a note — through the same locked-down harness the lead chat uses
- * on a subscription (subscription-chat.ts): a clean temporary folder, no
- * repository, no tools, no MCP servers, and credential environment stripped.
- * The card is data, never instructions. The draft is kept on the card and
- * nothing is sent: a later zone shows it to a person, and a later step posts
- * it ({{stage.<id>}}).
- */
 import { inEvalWorld } from "./eval-gate.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { run } from "./exec.js";
@@ -15,13 +6,9 @@ import { fillFlowText } from "./flows.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
 import { LIMITS } from "./decision.js";
 import { limitRule, TEXT_LIMITS } from "./text-limits.js";
-/** How long a draft may take, and how long it may be: what a step passes on. Claude is told the limit before it writes,
- * asked once to shorten a draft over it, and a draft still over it is kept whole (draftCard). */
 const DRAFT_TIMEOUT_MS = 180_000;
 export const DRAFT_CHARS = TEXT_LIMITS.stageOutput;
 const clip = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1)}…`;
-/** What Claude is asked: the zone's instructions, then the card as data — with the last draft and a person's note when it
- * was sent back. `shorten`: the repair turn, with the draft that came back too long and what to cut it to. */
 export function draftPrompt(stage, card, definition, shorten = null) {
     const ask = fillFlowText(stage.instructions ?? "", card);
     const earlier = definition.stages.filter(one => one.id !== stage.id && card.outputs[one.id] !== undefined)
@@ -47,20 +34,16 @@ export function draftPrompt(stage, card, definition, shorten = null) {
         ...(shorten === null ? [] : ["", "THE DRAFT YOU JUST WROTE, WHICH IS TOO LONG", shorten.draft, "", shorten.ask, "Reply with only the shortened draft."]),
     ].join("\n");
 }
-/** A draft as Claude wrote it, kept whole: trimmed, and never holding a key-shaped line. */
 export function wholeDraft(text) {
     const trimmed = text.trim();
     return redactSecretLines(trimmed, scanForSecrets(trimmed));
 }
-/** A draft a person edited, as kept: trimmed, whole (one over DRAFT_CHARS is refused where it is written, never cut), and never holding a key-shaped line. */
 export function keptDraft(text) {
     const trimmed = text.trim();
     return redactSecretLines(trimmed, scanForSecrets(trimmed));
 }
-/** The production runner: Claude through the sign-in on this computer, with no tools, no MCP servers and no repository. */
 export function claudeDraftRunner(runner = run) {
     return request => inScratchDir("standing-orders-draft-", async (dir) => {
-        // An eval world makes no provider call it can't cap and record (eval-gate.ts).
         if (inEvalWorld())
             return { ok: false, said: "Drafts aren't written in an eval world." };
         const started = Date.now();