toolroll 0.8.2 → 0.9.1

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.

package/dist/flows-ui.d.ts

@@ -2,7 +2,7 @@
  * (the React view's data, plus a plain fallback page the view replaces). */
 import type { BrowserFlowView } from "./browser-workspace.js";
 import type { FlowRow, Store } from "./store.js";
-export declare const FLOWS_CSS = ".flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}";
+export declare const FLOWS_CSS = ".flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:\"\";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}";
 /** The flows a person can open, with how many cards wait in each, and the new-flow form. */
 export declare function flowsListHtml(store: Store, flows: readonly FlowRow[], projects: readonly string[], csrf: string, canCreate: boolean, problem: string | null): string;
 /** One flow's canvas for one person. */

package/dist/flows-ui.js

@@ -13,7 +13,7 @@ import { callWords, receiptWords } from "./teammate-tools.js";
 import { undoFor } from "./teammate-week.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 const projectName = (repo) => repo.split(/[\\/]/).filter(Boolean).pop() ?? repo;
-export const FLOWS_CSS = `.flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}`;
+export const FLOWS_CSS = `.flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:"";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}`;
 /** The flows a person can open, with how many cards wait in each, and the new-flow form. */
 export function flowsListHtml(store, flows, projects, csrf, canCreate, problem) {
     const rows = flows.map(flow => {
@@ -71,11 +71,12 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         const decision = parseSortDecision(decisions.get(card.id)?.decisionJson ?? null);
         const shown = stage?.kind === "approval" && definition !== null ? draftFor(definition, stage) : null;
         // v91: when a Wait zone gives up (or moves on), or a zone's time limit comes.
-        const clock = stage?.wait ?? stage?.limit;
+        // An "hours" wait has no deadline of its own: it goes on when the clock reaches its hours.
+        const clock = stage?.wait?.for === "hours" ? stage.limit : stage?.wait ?? stage?.limit;
         const until = card.state !== "active" || stage === undefined || clock === undefined ? null : new Date(Date.parse(store.flowCardEnteredAt(card.id) ?? card.updatedAt) + clock.minutes * 60_000);
         const deadline = until === null || until.getTime() <= Date.now() ? null : {
             at: until.toISOString(),
-            label: stage.wait !== undefined ? (stage.wait.for === "reply" ? "No reply by" : "Moves on at") : stage.limit.to !== null ? `Moves to ${title(stage.limit.to)} at` : "Reminder at",
+            label: stage.wait !== undefined && stage.wait.for !== "hours" ? (stage.wait.for === "reply" ? "No reply by" : "Moves on at") : stage.limit.to !== null ? `Moves to ${title(stage.limit.to)} at` : "Reminder at",
         };
         // Its open question: one of its own, or (v94) a tool call waiting for approval.
         const asked = card.state === "active" ? store.openTeammateQuestionOn(card.id, card.entry) : null;

package/dist/flows.d.ts

@@ -1,4 +1,4 @@
-export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "done"];
+export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "done"];
 export type FlowStageKind = (typeof FLOW_STAGE_KINDS)[number];
 export declare const FLOW_COLORS: readonly ["slate", "blue", "violet", "amber", "green", "rose"];
 export type FlowColor = (typeof FLOW_COLORS)[number];
@@ -48,11 +48,18 @@ export type FlowTool = {
     name: string;
     args: string;
 };
-/** wait (v91): for a reply to the card's email (next: replied, onFail: no reply in time), or for a set time (then next). */
+/** wait (v91): for a reply to the card's email (next: replied, onFail: no reply in time), or for a set time (then next).
+ * "hours": until the clock is between `from` and `to` (like 22:00–06:00), in the computer's time zone unless one is named. */
 export type FlowWait = {
-    for: "reply" | "time";
+    for: "reply" | "time" | "hours";
     minutes: number;
+    from?: string;
+    to?: string;
+    timeZone?: string;
 };
+/** How a Pull request zone merges once checks pass. */
+export declare const FLOW_MERGE_METHODS: readonly ["squash", "merge", "rebase"];
+export type FlowMergeMethod = (typeof FLOW_MERGE_METHODS)[number];
 /** A time limit on a zone (v91): after this long, the person it waits on is reminded, and a Holding or
  * "Person decides" zone can move the card on (`to`). */
 export type FlowLimit = {
@@ -102,6 +109,8 @@ export type FlowStage = {
     teammate?: string;
     /** v96: a "Teammate handles it" zone sends what the teammate writes back to whoever asked (the person who added the card, its chat thread, or the teammate's manager). */
     reply?: boolean;
+    /** pull-request: merge once checks pass, this way. Only allowed after a "Person decides" zone, and a card merges only when a person approved it after it was built. */
+    merge?: FlowMergeMethod;
     /** Where a card goes when this zone's step succeeds, and when it fails or is sent back (sort: when it isn't sure). */
     next: string | null;
     onFail: string | null;
@@ -132,12 +141,18 @@ export declare const LONGEST_WAIT_MINUTES: number;
 export declare function durationMinutes(value: unknown): number | null;
 /** Minutes in the words people use: "3 days", "1 day 4 hours", "45 minutes". */
 export declare function durationWords(minutes: number): string;
+/** "22:00", "9:30" as "HH:MM"; null when it isn't a time of day. */
+export declare function clockTime(value: unknown): string | null;
+/** Whether a time falls inside an "hours" wait (22:00–06:00 runs past midnight), in its time zone or this computer's. */
+export declare function withinHours(wait: Pick<FlowWait, "from" | "to" | "timeZone">, now: Date): boolean;
 /** Who decides at an approval zone: its named person, the flow's owner, or null for anyone who approves on the project. */
 export declare function deciderOf(stage: Pick<FlowStage, "approver" | "toOwner">, flow: {
     owner: string;
 }): string | null;
 /** A flow as drawn on the canvas, checked whole. Throws in plain words. */
 export declare function validateFlowDefinition(input: unknown): FlowDefinition;
+/** The zones a card can reach from `start` without passing through a zone `stop` picks (those zones aren't included). */
+export declare function reachableWithout(stages: readonly FlowStage[], start: string, stop: (stage: FlowStage) => boolean): Set<string>;
 /** What a card's work is held to: the zones' steps and paths, never where they sit on the canvas. */
 export declare function flowDigest(definition: FlowDefinition): string;
 /** Fill a zone's text from the card: title, description, the latest note and earlier zones' reports. */
@@ -194,10 +209,15 @@ export type FlowStepInput = {
     server?: string;
     tool?: string;
     args?: Record<string, unknown> | string;
-    /** wait (v91): for a reply (the default) or a set time, and how long ("3 days"); where a card goes when no reply comes. */
-    waitFor?: "reply" | "time";
+    /** wait (v91): for a reply (the default) or a set time, and how long ("3 days"); where a card goes when no reply comes.
+     * "hours": until the clock is between `from` and `until` ("22:00", "06:00"). */
+    waitFor?: "reply" | "time" | "hours";
     wait?: string | number;
     ifNoReply?: string;
+    from?: string;
+    until?: string;
+    /** pull-request: merge once checks pass (true is squash). Needs a decision before it. */
+    merge?: boolean | FlowMergeMethod;
     /** Any step but wait and done (v91): remind after this long ("2 days"; "none" removes it), and on holding and approval steps, move the card to this step then. */
     remindAfter?: string | number;
     thenMoveTo?: string;
@@ -220,10 +240,14 @@ export declare const DRAFT_DEFAULT = "Write a short, friendly reply to the perso
 export declare function flowFromSteps(input: unknown, previous?: FlowDefinition | null): FlowDefinition;
 /** 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 declare function flowTerms(definition: FlowDefinition, previous: FlowDefinition | null): string[];
-/** Ready-made flows: the coding flow is the whole business process around a change. */
+/** The label an issue gets to become work: what the Issues to PRs template and the issue starter flow watch for. */
+export declare 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 declare const FLOW_TEMPLATES: readonly {
     id: string;
     label: string;
     about: string;
     definition: FlowDefinition;
+    trigger?: Record<string, unknown>;
 }[];