toolroll 0.9.0 → 0.9.1

package/dist/browser-workspace.d.ts

@@ -322,6 +322,11 @@ export type BrowserTaskView = {
         html: string;
         open: boolean;
     } | null;
+    /** "Do this every time…": Settings → Flows with the matching starter flow marked. */
+    everyTime?: {
+        href: string;
+        starter: string;
+    } | null;
 };
 /** One project on the Projects page; opening it is a POST to /projects/open. */
 export type BrowserProjectRow = {
@@ -467,7 +472,7 @@ export type BrowserResultView = {
 export type BrowserFlowStage = {
     id: string;
     title: string;
-    kind: "inbox" | "task" | "report" | "approval" | "check" | "update" | "notify" | "sort" | "draft" | "request" | "email" | "tool" | "wait" | "teammate" | "done";
+    kind: "inbox" | "task" | "report" | "approval" | "check" | "pull-request" | "update" | "notify" | "sort" | "draft" | "request" | "email" | "tool" | "wait" | "teammate" | "done";
     zone: {
         x: number;
         y: number;
@@ -525,9 +530,14 @@ export type BrowserFlowStage = {
     } | null;
     /** v91: a Wait zone waits for a reply to the card's email (onFail: no reply in time) or a set time; any other zone may have a time limit. */
     wait?: {
-        for: "reply" | "time";
+        for: "reply" | "time" | "hours";
         minutes: number;
+        from?: string;
+        to?: string;
+        timeZone?: string;
     };
+    /** A Pull request zone merges once checks pass (after a person approved), this way. */
+    merge?: "squash" | "merge" | "rebase" | undefined;
     limit?: {
         minutes: number;
         to: string | null;

package/dist/chat-actions.d.ts

@@ -61,6 +61,11 @@ export declare const CHAT_ACTIONS: {
         readonly protected: false;
         readonly password: false;
     };
+    readonly flow_starter: {
+        readonly label: "Switch on";
+        readonly protected: false;
+        readonly password: false;
+    };
     readonly flow_edit: {
         readonly label: "Save flow";
         readonly protected: false;

package/dist/chat-actions.js

@@ -28,6 +28,7 @@ import { cleanMemory, editMemory, forgetMemory, tellTeammate } from "./teammate-
 import { addRoutine, removeRoutine, routineSchedule, routinesOf } from "./teammate-desk.js";
 import { requestUndo, undoFor } from "./teammate-week.js";
 import { kitInstalled, kitOf, KITS, setUpKitNow } from "./kits.js";
+import { starterFlowOf, starterOf, startersFor, starterTerms, STARTER_FLOWS, switchOnStarter } from "./flow-starters.js";
 import { answerTeammateQuestion } from "./teammate-work.js";
 import { callWords, checkRule, defaultRule, grantListed, revokeTool, ruleWords, setToolRules } from "./teammate-tools.js";
 /** A tool from the lead's card: a common tool by its id, or the operator's own program or address. */
@@ -77,6 +78,8 @@ export const CHAT_ACTIONS = {
     tool_remove: { label: "Remove tool", protected: false, password: false },
     // Flows: a drawing and cards on it. Any work a card files is an ordinary task under the usual approvals.
     flow_create: { label: "Create flow", protected: false, password: false },
+    // A starter flow: its zones and its trigger, switched on with one yes (flow-starters.ts).
+    flow_starter: { label: "Switch on", protected: false, password: false },
     flow_edit: { label: "Save flow", protected: false, password: false },
     flow_card_add: { label: "Add card", protected: false, password: false },
     flow_card_move: { label: "Move card", protected: false, password: false },
@@ -128,7 +131,8 @@ export const CHAT_ACTION_FIELDS = {
     knowledge_restore: ["repo", "restore"],
     tool_add: ["repo", "catalog", "name", "command", "args", "url", "secrets", "about"],
     tool_remove: ["repo", "name"],
-    flow_create: ["repo", "name", "definition"],
+    flow_create: ["repo", "name", "definition", "trigger"],
+    flow_starter: ["repo", "starter"],
     flow_edit: ["flow", "name", "definition"],
     flow_card_add: ["flow", "title", "description", "zone"],
     flow_card_move: ["card", "zone"],
@@ -265,7 +269,7 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
     const task = operation.startsWith("skill_") || operation.startsWith("knowledge_") || operation.startsWith("decision_") || operation.startsWith("tool_") || operation.startsWith("flow_") || operation.startsWith("teammate_") || operation.startsWith("kit_")
         ? null
         : text(input, "task", 64);
-    const flowTarget = operation.startsWith("flow_") && operation !== "flow_create" && operation !== "flow_script_save" ? flowTargetOf(store, input) : null;
+    const flowTarget = operation.startsWith("flow_") && operation !== "flow_create" && operation !== "flow_script_save" && operation !== "flow_starter" ? flowTargetOf(store, input) : null;
     // v92: a teammate names its project; a question names it through its card's flow.
     const mateTarget = operation.startsWith("teammate_") && operation !== "teammate_create" && operation !== "teammate_answer" ? store.getTeammate(integer(input, "teammate")) : null;
     if (mateTarget !== null && mateTarget.state === "removed")
@@ -551,6 +555,28 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
             state = {};
             title = `Create the ${name} flow in ${project}`;
             terms.push(...flowTerms(definition, null));
+            // A template's trigger (Issues to PRs: labelled issues) comes with it, checked as the flow will have it.
+            if (input["trigger"] !== undefined) {
+                const draft = { id: 0, repo, name, definitionJson: JSON.stringify(definition), revision: 1, state: "active", createdBy: who.name, createdAt: now.toISOString(), updatedBy: who.name, updatedAt: now.toISOString(), owner: who.name };
+                const config = validateTriggerConfig(input["trigger"], { store, flow: draft, definition, actor: who.name });
+                if (takesDeliveries(config))
+                    throw Error("Webhook addresses are secrets, so they are set up on the flow's Triggers panel.");
+                request["trigger"] = config;
+                terms.push(`Starts cards from: ${describeTrigger(config, store)}. Only what happens from now on counts.`);
+            }
+        }
+        else if (operation === "flow_starter") {
+            const starter = starterOf(String(input["starter"] ?? ""));
+            if (starter === null)
+                throw Error(`Choose a starter flow: ${STARTER_FLOWS.map(one => one.id).join(", ")}.`);
+            if (starterFlowOf(store, starter, repo) !== null)
+                throw Error(`${starter.name} is already on in ${project}.`);
+            const blocked = startersFor(store, repo).find(one => one.id === starter.id)?.blocked ?? null;
+            if (blocked !== null)
+                throw Error(blocked);
+            state = {};
+            title = `Switch on ${starter.name} in ${project}`;
+            terms.push(...starterTerms(store, starter, repo));
         }
         else if (operation === "flow_edit") {
             const { flow, definition: before } = flowTarget;
@@ -1214,9 +1240,23 @@ function runFlowAction(store, payload, actor, repos, root, now) {
         return { said: `${said}${filed}`, href: card === null ? `/flows/${flow}` : flowCardHref(flow, card) };
     };
     if (payload.operation === "flow_create") {
-        const id = store.createFlow({ repo: payload.repo, name: String(req["name"]), definitionJson: JSON.stringify(req["definition"]), by: actor }, now);
+        const id = store.transact(() => {
+            const made = store.createFlow({ repo: payload.repo, name: String(req["name"]), definitionJson: JSON.stringify(req["definition"]), by: actor }, now);
+            if (req["trigger"] !== undefined) {
+                const trigger = addFlowTriggerTo(store, store.getFlow(made), req["trigger"], actor, now, null);
+                if (!trigger.ok)
+                    throw Error(trigger.message);
+            }
+            return made;
+        });
         return { said: "Flow created. Add cards to it here or on its canvas.", href: `/flows/${id}` };
     }
+    if (payload.operation === "flow_starter") {
+        const switched = switchOnStarter(store, starterOf(String(req["starter"])), payload.repo, actor, now, configDirOf(store));
+        if (!switched.ok)
+            throw Error(switched.said);
+        return { said: switched.said, href: `/flows/${switched.flow}` };
+    }
     if (payload.operation === "flow_edit") {
         const flow = Number(payload.state["flow"]);
         if (!store.saveFlow(flow, { name: String(req["name"]), definitionJson: JSON.stringify(req["definition"]), sawRevision: Number(payload.state["revision"]), by: actor }, now))

package/dist/cli.d.ts

@@ -39,7 +39,7 @@ export type ParseResult = {
     error: string;
 };
 type Write = (line: string) => void;
-export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
 export declare function parseArgs(argv: readonly string[]): ParseResult;
 /** The commands that operate the queue rather than report on the world. */
 /** Every verb the CLI routes OUTSIDE runOperate. Exported (with

package/dist/cli.js

@@ -59,7 +59,7 @@ Usage
   toolroll skills get <name>  print one guide (version-matched, never stale)
   toolroll demo             a seeded throwaway sandbox — see it working in 90 seconds
   toolroll up               app + builder for every saved project — the normal start
-  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes)
+  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)
   toolroll status           running, queued, ready results, release check and plan windows
   toolroll integrations     which integrations work, and what to do about the ones that don't (--json)
   toolroll session          native coding sessions through the running service

package/dist/desktop-update.d.ts

@@ -66,6 +66,7 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -79,7 +80,6 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
-    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/flow-engine.js

@@ -8,7 +8,7 @@
 import { assignmentOf } from "./assignment.js";
 import { filerFor } from "./approval-policy.js";
 import { diagnoseTaskDispatch } from "./dispatch.js";
-import { deciderOf, durationWords, fillFlowText, validateFlowDefinition } from "./flows.js";
+import { deciderOf, durationWords, fillFlowText, validateFlowDefinition, withinHours } from "./flows.js";
 import { reportSummaryFor } from "./report-summary.js";
 import { fileTaskProposal } from "./proposal.js";
 import { requestResultChanges } from "./result-actions.js";
@@ -138,6 +138,17 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
             return;
         case "wait": {
             const wait = stage.wait ?? { for: "reply", minutes: 24 * 60 };
+            // Set hours (like 22:00–06:00): a card goes on once the clock is inside them, at once when it already is.
+            if (wait.for === "hours") {
+                if (withinHours(wait, now)) {
+                    onward("ok");
+                    return;
+                }
+                const waiting = `Waiting until ${wait.from}.`;
+                if (card.waiting !== waiting)
+                    store.updateFlowCard(card.id, { waiting }, now);
+                return;
+            }
             const entered = Date.parse(store.flowCardEnteredAt(card.id) ?? card.updatedAt);
             const words = durationWords(wait.minutes);
             if (now.getTime() < entered + wait.minutes * 60_000) {
@@ -217,6 +228,7 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
             workStage(store, flow, stage, card, now, options, outcome, onward);
             return;
         case "check":
+        case "pull-request":
         case "update":
         case "sort":
         case "draft":

package/dist/flow-pull-request.d.ts

@@ -0,0 +1,11 @@
+import type { Runner } from "./backend.js";
+import type { FlowDefinition, FlowStage } from "./flows.js";
+import type { FlowCardRow, FlowRow, Store } from "./store.js";
+export type PullRequestIo = {
+    gh: Runner;
+    evidenceRoot?: string;
+};
+/** Whether a person approved this card at a "Person decides" zone since it was last built; their name when so. */
+export declare function approvedSinceBuild(store: Store, definition: FlowDefinition, card: FlowCardRow): string | null;
+/** One pass of a Pull request zone for one card. Returns whether it changed anything. */
+export declare function pullRequestStep(store: Store, flow: FlowRow, definition: FlowDefinition, stage: FlowStage, card: FlowCardRow, now: Date, io: PullRequestIo): Promise<boolean>;

package/dist/flow-pull-request.js

@@ -0,0 +1,123 @@
+/**
+ * A flow's Pull request zone (flows.ts): the card's built result becomes a pull request under the project's pull
+ * request setup — the same grant, publisher and merge as Complete → pull request (pull-request-flow.ts) — and CI
+ * decides where the card goes: on when checks pass (merging first when the zone says so), down the failure path
+ * when they fail, with the failing check named on the card. A failure path back to a Build zone becomes a revision
+ * of that same work carrying the failure, as a person's send back does.
+ *
+ * A zone that merges only ever merges a card a person approved (a "Person decides" zone) after it was last built:
+ * the flow can't be drawn otherwise (validateFlowDefinition), and a card moved in by hand or by a trigger is checked
+ * here too. Without that approval the checks passing leave it waiting for a person.
+ *
+ * Model-free, in the worker's step pass. The publisher and CI observation run in the watch loop; this reads what
+ * they recorded, and reads GitHub itself only to name a failing check and to merge.
+ */
+import { createHash } from "node:crypto";
+import { assignmentOf } from "./assignment.js";
+import { cardFollowers, notifyPeople } from "./flow-people.js";
+import { failingCheckOf, mergePullRequest, owePullRequest, pullRequestBlocker, pullRequestFollowOf } from "./pull-request-flow.js";
+import { requestResultChanges } from "./result-actions.js";
+import { revisionSourceOf } from "./result-review.js";
+/** Whether a person approved this card at a "Person decides" zone since it was last built; their name when so. */
+export function approvedSinceBuild(store, definition, card) {
+    const kindOf = (id) => definition.stages.find(one => one.id === id)?.kind ?? null;
+    const events = store.flowEvents(card.id);
+    let built = -1;
+    events.forEach((event, index) => { if (kindOf(event.fromStage) === "task" || kindOf(event.toStage) === "task")
+        built = index; });
+    const approval = events.slice(built + 1).reverse().find(event => event.outcome === "approved" && kindOf(event.fromStage) === "approval");
+    return approval === undefined ? null : approval.actor;
+}
+/** One pass of a Pull request zone for one card. Returns whether it changed anything. */
+export async function pullRequestStep(store, flow, definition, stage, card, now, io) {
+    const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? "another zone";
+    const waiting = (said) => {
+        if (card.waiting === said)
+            return false;
+        store.updateFlowCard(card.id, { waiting: said }, now);
+        return true;
+    };
+    const passed = (said, output) => {
+        store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: output }, waiting: null }, now);
+        if (stage.next === null)
+            return waiting(`${said} Move the card on when you're ready.`);
+        return store.moveFlowCard(card.id, { to: stage.next, outcome: "ok", actor: "flow", historyNote: said, expectEntry: card.entry }, now);
+    };
+    const failed = (said, revision = null) => {
+        store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: said } }, now);
+        if (stage.onFail === null) {
+            if (!waiting(`${said} Fix it, then move the card to try again.`))
+                return false;
+        }
+        else if (!store.moveFlowCard(card.id, { to: stage.onFail, outcome: "fail", actor: "flow", note: said, ...(revision === null ? {} : { task: revision }), expectEntry: card.entry }, now))
+            return false;
+        const people = card.owner === null ? cardFollowers(store, card) : [card.owner];
+        notifyPeople(store, card, people, null, { key: `step-failed:${card.entry}`, subject: `${stage.title} didn't pass for “${card.title}”`, attention: true,
+            body: `${said}${stage.onFail === null ? "" : `\n\nIt's back in ${titleOf(stage.onFail)}${revision === null ? "" : `, as revision ${revision}`}.`}` }, now);
+        return true;
+    };
+    // With no failure path, a card that didn't pass waits for a person to move it (a move is a fresh visit).
+    if (stage.onFail === null && card.waiting !== null && card.waiting.endsWith(" Fix it, then move the card to try again."))
+        return false;
+    const task = card.primaryTask;
+    const receipt = task === null ? null : assignmentOf(store, task, now, { principal: "operator", repos: [flow.repo] }, io.evidenceRoot)?.receipt ?? null;
+    if (receipt === null)
+        return failed("There's no built result on this card to open a pull request for.");
+    const runId = receipt.runId;
+    let publication = store.publicationForRun(runId);
+    if (publication === null || pullRequestFollowOf(store, publication.id) === null) {
+        if (publication === null) {
+            const blocked = pullRequestBlocker(store, runId);
+            if (blocked !== null)
+                return failed(blocked === "Pull requests aren't set up for this project." ? "Pull requests aren't set up for this project. Turn them on in Projects → Pull requests, then move the card back here." : blocked);
+        }
+        publication = owePullRequest(store, runId, `flow ${flow.name}`, card.id, now);
+    }
+    const pr = publication.prNumber === null ? "the pull request" : `PR #${publication.prNumber}`;
+    if (publication.state === "failed")
+        return failed(`Couldn't open the pull request: ${publication.lastError ?? "GitHub refused it"}. The commit is safe locally.`);
+    if (publication.state !== "opened")
+        return waiting(publication.lastError === null ? "Opening the pull request…" : `Opening the pull request. Retrying: ${publication.lastError}`);
+    const link = publication.prUrl ?? pr;
+    if (publication.remoteState === "MERGED")
+        return passed(`${pr} was merged on GitHub.`, `Merged: ${link}`);
+    if (publication.remoteState === "CLOSED")
+        return failed(`${pr} was closed on GitHub without merging.`);
+    // Only what CI said since the card came here counts: a card moved back to try again waits for a fresh look.
+    const entered = store.flowCardEnteredAt(card.id) ?? card.updatedAt;
+    const fresh = publication.lastCheckAt !== null && publication.lastCheckAt >= entered;
+    if (!fresh || publication.lastCheckState === "running")
+        return waiting(`Waiting for CI on ${pr}.`);
+    if (publication.lastCheckState !== "passing" && publication.lastCheckState !== "failing")
+        return waiting(`No CI checks have reported on ${pr} yet. If this project has none, move the card on.`);
+    if (publication.lastCheckState === "failing") {
+        const found = await failingCheckOf(io.gh, publication);
+        const said = found === null ? `CI failed on ${pr}. GitHub couldn't be read to name the check.` : `CI check “${found.check}” failed on ${pr}.`;
+        // Back to a Build zone: a revision of the same work, carrying the failure (fenced as untrusted CI output).
+        let revision = null;
+        const target = definition.stages.find(one => one.id === stage.onFail);
+        if (target?.kind === "task" && io.evidenceRoot !== undefined) {
+            const runTask = store.externalIdFor(store.getRun(runId)?.taskRef ?? -1);
+            const revised = runTask === null ? null : requestResultChanges(store, io.evidenceRoot, {
+                run: runId, source: revisionSourceOf(store.getScope(runTask)?.digest ?? null), actor: "toolroll", repos: [flow.repo], batch: "",
+                note: found?.note ?? said, path: "", line: "", allowMode: true,
+                request: createHash("sha256").update(`flow-ci ${card.id} ${card.entry} ${publication.id}`).digest("hex").slice(0, 32),
+            }, now);
+            if (revised?.ok === true)
+                revision = revised.id;
+        }
+        return failed(said, revision);
+    }
+    // Checks pass.
+    if (stage.merge === undefined)
+        return passed(`${pr} passed its checks.`, `Pull request: ${link} (checks passed)`);
+    const approver = approvedSinceBuild(store, definition, card);
+    if (approver === null)
+        return waiting(`Checks passed on ${pr}, but no person approved this card since it was built, so it wasn't merged. Merge it from its task, or send it through a decision.`);
+    const merged = await mergePullRequest(store, { runId, by: `${approver} (approved in ${flow.name})`, exec: io.gh, method: stage.merge, clock: () => now });
+    if (merged.ok)
+        return passed(`Merged ${pr} (${stage.merge}).`, `Merged: ${link}`);
+    if (merged.reason === "checks" || merged.reason === "unread")
+        return waiting(`${merged.message} (${pr})`);
+    return failed(`Couldn't merge ${pr}: ${merged.message}`);
+}

package/dist/flow-starters-ui.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Settings → Flows: the starter flows for a project, each switched on with one yes. A row says what it's for,
+ * what it will do and what it never does — the whole of what the yes agrees to — then one button. A starter
+ * that's on links to its flow; one that can't run here says why.
+ */
+import type { StarterView } from "./flow-starters.js";
+export declare const STARTERS_CSS: string;
+export declare function startersHtml(input: {
+    repo: string;
+    projects: readonly {
+        path: string;
+        name: string;
+    }[];
+    starters: readonly StarterView[];
+    csrf: string;
+    canSwitch: boolean;
+    suggested: string | null;
+    said: string | null;
+    problem: string | null;
+}): string;

package/dist/flow-starters-ui.js

@@ -0,0 +1,35 @@
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export const STARTERS_CSS = `.starters{max-width:760px;min-width:0}.starters h2{margin:24px 0 4px;font-size:.9375rem}` +
+    `.starter{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:4px 16px;align-items:start;padding:14px 0;border-top:1px solid var(--so-line);min-width:0}` +
+    `.starter:first-of-type{border-top:0}.starter>:not(.starter-action){grid-column:1}.starter h3{margin:0;font-size:.9375rem;display:flex;flex-wrap:wrap;gap:6px 10px;align-items:center}` +
+    `.starter p,.starter ul{margin:2px 0 0;min-width:0;overflow-wrap:anywhere}.starter ul{padding-left:18px;color:var(--so-muted);font-size:.875rem;line-height:1.5}` +
+    `.starter .starter-never{font-size:.875rem;font-weight:500}.starter-action{grid-column:2;grid-row:1 / span 4;align-self:center;margin:0}` +
+    `.starter-action button,.starter-action .button-link{min-height:44px;white-space:nowrap}.starter .starter-action button{width:auto}` +
+    `.starter .starter-action a.starter-open{background:var(--so-paper);color:var(--so-ink);border:1px solid var(--so-input-line)}` +
+    `.starter[data-suggested="true"]{margin:0 -12px;padding:14px 12px;border:1px solid var(--so-accent,var(--so-line));border-radius:10px}` +
+    `.starter-on{display:inline-flex;align-items:center;gap:6px;font-size:.75rem;font-weight:500;padding:0 8px;border-radius:5px;line-height:20px;color:var(--so-success);background:var(--so-success-soft)}` +
+    `.starter-on i{width:6px;height:6px;border-radius:50%;background:currentColor}.starters .starter-blocked{color:var(--so-muted);font-size:.875rem}` +
+    `.starters form.starters-project{display:flex;flex-wrap:wrap;gap:8px;align-items:flex-end;margin:0 0 8px}.starters form.starters-project label{display:grid;gap:4px}` +
+    `@media (max-width:560px){.starter{grid-template-columns:minmax(0,1fr)}.starter .starter-action{grid-column:1;grid-row:auto;margin-top:10px}` +
+    `.starter .starter-action button,.starter .starter-action .button-link{width:100%;justify-content:center}.starters select{font-size:16px}}`;
+export function startersHtml(input) {
+    const note = input.problem ? `<p class="problem" role="alert">${e(input.problem)}</p>` : input.said ? `<p role="status">${e(input.said)}</p>` : "";
+    const selector = input.projects.length > 1
+        ? `<form class="starters-project" method="get" action="/settings/flows"><label>Project<select name="repo">${input.projects.map(one => `<option value="${e(one.path)}"${one.path === input.repo ? " selected" : ""}>${e(one.name)}</option>`).join("")}</select></label><button>Show</button></form>` : "";
+    // The one asked about ("Do this every time…") comes first, marked.
+    const ordered = [...input.starters].sort((a, b) => Number(b.id === input.suggested) - Number(a.id === input.suggested));
+    const rows = ordered.map(one => {
+        const action = one.on !== null ? `<p class="starter-action"><a class="button-link starter-open" href="/flows/${one.on.flow}">Open flow</a></p>`
+            : one.blocked !== null || !input.canSwitch ? ""
+                : `<form method="post" action="/settings/flows/on" class="starter-action"><input type="hidden" name="csrf" value="${e(input.csrf)}"><input type="hidden" name="repo" value="${e(input.repo)}">` +
+                    `<input type="hidden" name="starter" value="${e(one.id)}"><button type="submit">Switch on</button></form>`;
+        return `<div class="starter" id="starter-${e(one.id)}" data-starter="${e(one.id)}" data-suggested="${one.id === input.suggested && one.on === null}">` +
+            `<h3>${e(one.name)}${one.on === null ? "" : ` <span class="starter-on"><i aria-hidden="true"></i>On</span>`}</h3>` +
+            `<p>${e(one.summary)}</p>` +
+            // What the yes agrees to, in full, before it; nothing to agree to once it's on or can't be.
+            (one.on === null && one.blocked === null ? `<ul>${one.does.map(line => `<li>${e(line)}</li>`).join("")}</ul><p class="starter-never">${e(one.never)}</p>` : "") +
+            (one.on === null && one.blocked !== null ? `<p class="starter-blocked">${e(one.blocked)}</p>` : "") + action + `</div>`;
+    }).join("");
+    const nobody = !input.canSwitch && input.starters.some(one => one.on === null) ? `<p class="meta">An approver switches these on.</p>` : "";
+    return `<section class="starters">${note}${selector}<h2>Starter flows</h2>${rows}${nobody}<p class="meta"><a href="/flows">All flows</a></p></section>`;
+}

package/dist/flow-starters.d.ts

@@ -0,0 +1,55 @@
+import { type FlowStepInput } from "./flows.js";
+import type { FlowRow, Store } from "./store.js";
+export declare const STARTER_IDS: readonly ["ci-fix", "issue-task", "overnight"];
+export type StarterId = (typeof STARTER_IDS)[number];
+export type StarterFlow = {
+    id: StarterId;
+    /** The flow's name, and how the starter is called everywhere. */
+    name: string;
+    /** One line: what it's for. */
+    summary: string;
+    /** What switching it on does, in order. */
+    does: (where: {
+        github: string | null;
+        branch: string;
+    }) => string[];
+    /** What it never does. */
+    never: string;
+    github: boolean;
+    steps: FlowStepInput[];
+    trigger: (where: {
+        branch: string;
+    }) => Record<string, unknown>;
+};
+export declare const STARTER_FLOWS: readonly StarterFlow[];
+export declare const starterOf: (id: string) => StarterFlow | null;
+/** The flow a starter made in a project, while it is on. */
+export declare function starterFlowOf(store: Store, starter: StarterFlow, repo: string): FlowRow | null;
+export type StarterView = {
+    id: StarterId;
+    name: string;
+    summary: string;
+    does: string[];
+    never: string;
+    on: {
+        flow: number;
+    } | null;
+    blocked: string | null;
+};
+/** Each starter for a project: what it does there, whether it's on, and why it can't be switched on when it can't. */
+export declare function startersFor(store: Store, repo: string): StarterView[];
+export type SwitchedOn = {
+    ok: true;
+    flow: number;
+    said: string;
+    already: boolean;
+} | {
+    ok: false;
+    said: string;
+};
+/** Switch a starter on in a project: its flow (zones) and its trigger, together or not at all. Once is enough. */
+export declare function switchOnStarter(store: Store, starter: StarterFlow, repo: string, by: string, now: Date, dir: string | null): SwitchedOn;
+/** The starter that would do a task's kind of work every time: fixing CI, an issue, or a queued job. */
+export declare function starterForWork(text: string): StarterFlow;
+/** What switching a starter on means, for a chat card's terms. */
+export declare function starterTerms(store: Store, starter: StarterFlow, repo: string): string[];

package/dist/flow-starters.js

@@ -0,0 +1,104 @@
+/**
+ * Starter flows: flows that are on from day one, each switched on with one yes from `toolroll onboard`,
+ * Settings → Flows, a task's "Do this every time…" or chat. Switching one on makes an ordinary flow (its zones)
+ * and its trigger, exactly as drawing them by hand would; it is on while that flow is. Each says in plain words
+ * what it will do and what it never does: no starter merges or ships anything without a person.
+ */
+import { flowDefinitionOf } from "./flow-engine.js";
+import { addFlowTriggerTo, githubRepoOf } from "./flow-triggers.js";
+import { flowFromSteps, ISSUE_LABEL } from "./flows.js";
+import { publishingOf } from "./pull-request-flow.js";
+export const STARTER_IDS = ["ci-fix", "issue-task", "overnight"];
+export const STARTER_FLOWS = [
+    {
+        id: "ci-fix",
+        name: "Fix failing CI",
+        summary: "When CI fails on the main branch, a task to fix it is filed.",
+        does: ({ github, branch }) => [`Watches checks on ${branch} in ${github ?? "your GitHub repository"}.`, "Files a task to fix each failure, under your usual approvals.", "Asks you to review the fix."],
+        never: "Never merges or pushes to your branch. You decide what ships.",
+        github: true,
+        steps: [
+            { id: "fix", title: "Fix it", kind: "task", instructions: "CI failed on the main branch: {{card.title}}\n\n{{card.description}}\n\nFind the cause and make the failing check pass without weakening it.\n\nChanges asked for (if any): {{note}}" },
+            { id: "review", title: "Review the fix", kind: "approval", decider: "owner" },
+        ],
+        trigger: ({ branch }) => ({ kind: "github", watch: "checks", branch }),
+    },
+    {
+        id: "issue-task",
+        name: "Issues become tasks",
+        summary: `A GitHub issue labelled “${ISSUE_LABEL}” becomes a task.`,
+        does: ({ github }) => [`Watches issues labelled “${ISSUE_LABEL}” in ${github ?? "your GitHub repository"}, from people with write access.`, "Builds each one as a task, under your usual approvals.", "Asks you to review it, then comments on the issue."],
+        never: "Never merges or closes anything without you.",
+        github: true,
+        steps: [
+            { id: "build", title: "Build", kind: "task" },
+            { id: "review", title: "Review", kind: "approval", decider: "owner" },
+            { id: "comment", title: "Comment on the issue", kind: "update", message: "Done: {{card.title}}. The result is ready in Toolroll.", close: false },
+        ],
+        trigger: () => ({ kind: "github", watch: "issues", label: ISSUE_LABEL }),
+    },
+    {
+        id: "overnight",
+        name: "Overnight queue",
+        summary: "Cards you add during the day start after 22:00; results wait for you in the morning.",
+        does: () => ["Adds a “Queue for tonight” button.", "Holds each card until 22:00, then builds it as a task, under your usual approvals.", "Results wait for your review in the morning."],
+        never: "Never merges or ships anything without you.",
+        github: false,
+        steps: [
+            { id: "tonight", title: "Tonight", kind: "wait", waitFor: "hours", from: "22:00", until: "06:00" },
+            { id: "build", title: "Build", kind: "task" },
+            { id: "morning", title: "Morning review", kind: "approval", decider: "owner" },
+        ],
+        trigger: () => ({ kind: "button", label: "Queue for tonight", questions: ["What needs doing?", "Details"] }),
+    },
+];
+export const starterOf = (id) => STARTER_FLOWS.find(one => one.id === id) ?? null;
+/** The flow a starter made in a project, while it is on. */
+export function starterFlowOf(store, starter, repo) {
+    return store.listFlows([repo]).find(one => one.name === starter.name && one.state === "active") ?? null;
+}
+/** Each starter for a project: what it does there, whether it's on, and why it can't be switched on when it can't. */
+export function startersFor(store, repo) {
+    const github = githubRepoOf(repo);
+    const publishing = publishingOf(store, repo);
+    const branch = publishing.on ? publishing.base : "main";
+    return STARTER_FLOWS.map(starter => {
+        const flow = starterFlowOf(store, starter, repo);
+        return { id: starter.id, name: starter.name, summary: starter.summary, does: starter.does({ github, branch }), never: starter.never,
+            on: flow === null ? null : { flow: flow.id }, blocked: starter.github && github === null ? "This project isn't on GitHub, so this can't watch it." : null };
+    });
+}
+/** Switch a starter on in a project: its flow (zones) and its trigger, together or not at all. Once is enough. */
+export function switchOnStarter(store, starter, repo, by, now, dir) {
+    const had = starterFlowOf(store, starter, repo);
+    if (had !== null)
+        return { ok: true, flow: had.id, said: `${starter.name} is already on.`, already: true };
+    if (starter.github && githubRepoOf(repo) === null)
+        return { ok: false, said: "This project isn't on GitHub, so this can't watch it." };
+    const publishing = publishingOf(store, repo);
+    try {
+        const flow = store.transact(() => {
+            const id = store.createFlow({ repo, name: starter.name, definitionJson: JSON.stringify(flowFromSteps(starter.steps, null)), by }, now);
+            const made = store.getFlow(id);
+            const trigger = addFlowTriggerTo(store, made, { ...starter.trigger({ branch: publishing.on ? publishing.base : "main" }), zone: flowDefinitionOf(made).start }, by, now, dir);
+            if (!trigger.ok)
+                throw new Error(trigger.message);
+            return id;
+        });
+        return { ok: true, flow, said: `${starter.name} is on.`, already: false };
+    }
+    catch (error) {
+        return { ok: false, said: `${starter.name} couldn't be switched on: ${error instanceof Error ? error.message : "unknown"}` };
+    }
+}
+/** The starter that would do a task's kind of work every time: fixing CI, an issue, or a queued job. */
+export function starterForWork(text) {
+    const id = /\b(ci|checks?|build|pipeline|workflow)\b[^.\n]{0,60}\b(fail|failed|failing|failure|red|broken)\b|\b(fail|failed|failing|broken)\b[^.\n]{0,60}\b(ci|checks?|pipeline)\b/i.test(text) ? "ci-fix"
+        : /github\.com\/[^/\s]+\/[^/\s]+\/issues\/\d+|\bissue\s*#?\d+|\bGitHub issue\b/i.test(text) ? "issue-task" : "overnight";
+    return starterOf(id);
+}
+/** What switching a starter on means, for a chat card's terms. */
+export function starterTerms(store, starter, repo) {
+    const view = startersFor(store, repo).find(one => one.id === starter.id);
+    return [view.summary, ...view.does, view.never];
+}

package/dist/flow-steps.js

@@ -15,6 +15,8 @@
  * - sort   — (v85) asks Jev through OpenRouter which of the zone's answers
  *            fits the card (flow-sort.ts), and sends it where that answer
  *            leads, or down the not-sure path.
+ * - pull-request — opens a pull request for the card's result and follows
+ *            its CI (flow-pull-request.ts).
  *
  * One run per visit to the zone (flow_step_run): two workers never run it
  * twice. Trouble reaching a service is retried three times, 5 then 15
@@ -40,6 +42,7 @@ import { recordSent, threadOf } from "./flow-replies.js";
 import { ASKED, teammateReady, teammateTurn } from "./teammate-work.js";
 import { budgetHoldWords, claudeMachineBilling, monthOf } from "./spend.js";
 import { toolRefusal } from "./policy.js";
+import { pullRequestStep } from "./flow-pull-request.js";
 const RETRY_MS = [5 * 60_000, 15 * 60_000];
 /** A teammate's turn tries again sooner: a card waiting on a person's colleague shouldn't wait long for a hiccup. */
 const TEAMMATE_RETRY_MS = [60_000, 5 * 60_000];
@@ -71,6 +74,17 @@ export async function runFlowSteps(store, repo, now, io) {
             await teammateStep(store, known.flow, known.definition, stage, card, now, io, pass);
             continue;
         }
+        // A pull request: opened for the card's result, then CI decides where it goes (flow-pull-request.ts).
+        if (stage.kind === "pull-request") {
+            try {
+                if (await pullRequestStep(store, known.flow, known.definition, stage, card, now, { gh: io.gh, ...(io.evidenceRoot === undefined ? {} : { evidenceRoot: io.evidenceRoot }) }))
+                    pass.ran++;
+            }
+            catch (error) {
+                pass.problems.push(`flow card ${card.id}: ${error instanceof Error ? error.message : "the pull request step couldn't run"}`);
+            }
+            continue;
+        }
         if (!["check", "update", "sort", "draft", "request", "email", "tool"].includes(stage.kind))
             continue;
         // Email and tools wait, saying why, until what they need is set up.