toolroll 0.8.2 → 0.9.1

package/dist/mate-tools.js

@@ -51,6 +51,7 @@ import { TEAMMATE_TEMPLATES, withSection } from "./teammates.js";
 import { callOutcome, callWords, defaultRule, ruleWords } from "./teammate-tools.js";
 import { deskOf, routinesOf } from "./teammate-desk.js";
 import { KITS } from "./kits.js";
+import { STARTER_IDS } from "./flow-starters.js";
 import { undoFor, weekOf, weekWords } from "./teammate-week.js";
 const REPO_ID = /^r[0-9]{1,3}$/;
 const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -820,7 +821,8 @@ export const MATE_TOOLS = [
                             ...(stage.tool === undefined ? {} : { server: stage.tool.server, tool: stage.tool.name, args: stage.tool.args.slice(0, 600) }),
                             ...(stage.kind === "sort" && stage.sort !== null ? { question: stage.sort.question, answers: stage.sort.answers.map(one => ({ answer: one.answer, means: one.means, goesTo: titleOf(one.to) })),
                                 sureAt: Math.round(stage.sort.sureAt * 100), ...(stage.sort.notes.length === 0 ? {} : { alsoNote: stage.sort.notes.map(one => ({ question: one.question, kind: one.kind, ...(one.levels === null ? {} : { levels: one.levels }) })) }) } : {}),
-                            ...(stage.wait === undefined ? {} : { waitFor: stage.wait.for, wait: durationWords(stage.wait.minutes) }),
+                            ...(stage.wait === undefined ? {} : stage.wait.for === "hours" ? { waitFor: "hours", from: stage.wait.from, until: stage.wait.to } : { waitFor: stage.wait.for, wait: durationWords(stage.wait.minutes) }),
+                            ...(stage.merge === undefined ? {} : { merge: stage.merge }),
                             ...(stage.teammate === undefined ? {} : { teammate: stage.teammate }),
                             ...(stage.kind === "teammate" && stage.routes !== undefined ? { routes: stage.routes.map(one => ({ answer: one.answer, goesTo: titleOf(one.to) })) } : {}),
                             ...(stage.limit === undefined ? {} : { remindAfter: durationWords(stage.limit.minutes), ...(stage.limit.to === null ? {} : { thenMoveTo: titleOf(stage.limit.to) }) }),
@@ -869,10 +871,11 @@ export const MATE_TOOLS = [
     },
     {
         name: "propose_flow",
-        description: "Draft a flow change as a card the operator confirms. kit: set up a starter kit in a project (repo, kit: support-desk, bug-triage, sales-follow-up or ops-requests) — a teammate, the flow it works and its buttons, in one card; prefer it when the operator wants a support desk, bug triage, sales follow-up or requests handled. create: a template, or the steps in order (each leads to the next; Done is added; instructions may be left out). 'request' calls a web address (method, url with its host written out, headers — {{secret.NAME}} uses a secret the operator saved on the step, never in chat — and body); 'email' sends mail (to, subject, body; {{card.email}} is the card's email address); 'tool' calls one of the project's tools (server: the tool's name from get_project_tools, tool: its function, args: an object). Put a decision before any of these when they send what a model wrote or what an outsider sent. A 'draft' step has Claude write something from the card (instructions: what to write); follow it with an approval step (decider 'owner' asks the flow's owner in their chat app, where they can approve, edit or send it back), then an 'update' or 'notify' step whose message is '{{stage.<draft id>}}'. A 'sort' step has Jev pick one of its answers; make it the first step (never a holding step before it, or new cards wait unsorted): question, answers (answer, means: a few words Jev reads, goesTo: a step), sureAt (percent, default 80), ifNotSure (a step; otherwise the card waits for a person), and up to 3 alsoNote (score with levels lowest first, or yes-no); a sort has no next, so give each branch's last step its own next. A 'wait' step, after an 'email' step, waits for a reply to that email from someone it went to (waitFor 'reply', the default): next is where a reply goes (the reply is {{stage.<wait id>}}), ifNoReply where the card goes when none comes within wait (like '3 days', up to 30 days); waitFor 'time' just waits, then next. Any step but wait and done can have remindAfter (like '2 days': whoever it waits on is reminded once; 'none' removes it) and, on holding and approval steps, thenMoveTo (a step the card moves to then). AI teammates (get_teammates): an approval step with teammate (its short name) is decided by that teammate within its rules, and it hands hard ones to the step's decider; a 'teammate' step (teammate, instructions, routes of answer and goesTo) has it read the card, pick where it goes and write what the next steps send (the email body is then {{stage.<id>}}), asking the flow's owner when its rules say to. edit: the full step list, keeping existing steps by id — what a kept step leaves out carries over. add_card (starts in the first zone unless zone is named), move_card, approve, send_back (needs a note), cancel_card, comment (note; @name pings that person), assign (owner: a name, 'me', or 'nobody'), follow, unfollow, save_script (repo, and script: name, about, language python|node|shell, and either body (short) or file (a path in the project, like scripts/enrich.py), and timeoutMinutes; scripts belong to the project, so no flow is needed; a 'check' step in any of its flows names it). A 'check' step runs its script with the card as JSON on stdin (and in $FLOW_INPUT); what it prints is its result for later steps ({{stage.<id>}}); runIn 'folder' (an empty folder: for scripts that work on data) or 'copy' (a copy of the card's work, after setup: for tests on code; the default); routes (answer, goesTo) that a last printed line 'goto: <answer>' picks; secrets (names of saved secrets it gets as variables). add_trigger with settings (kind button: label, questions; schedule: schedule like 'daily 09:00 Europe/London', and title, or script (a saved script whose printed items — one per line, a title or JSON with title, description, key — each become a card, once) with secrets; github: repo owner/name, watch issues|pulls|checks, label, branch, from team|anyone; linear: team, state, label; flow: follow (another flow's id), when (its zone); email: folder (default INBOX), sender (addresses or domains), subject (words it must contain)); pause_trigger, resume_trigger, remove_trigger with trigger. Read get_flows first except to create.",
+        description: "Draft a flow change as a card the operator confirms. starter: switch on a starter flow in a project (repo, starter: ci-fix files a fix task when CI fails on the main branch, issue-task makes a task of each GitHub issue labelled toolroll, overnight holds cards added in the day until 22:00 and leaves results for the morning) — its zones and trigger in one card; offer the matching one when the operator says to do something every time. kit: set up a starter kit in a project (repo, kit: support-desk, bug-triage, sales-follow-up or ops-requests) — a teammate, the flow it works and its buttons, in one card; prefer it when the operator wants a support desk, bug triage, sales follow-up or requests handled. create: a template, or the steps in order (each leads to the next; Done is added; instructions may be left out). 'request' calls a web address (method, url with its host written out, headers — {{secret.NAME}} uses a secret the operator saved on the step, never in chat — and body); 'email' sends mail (to, subject, body; {{card.email}} is the card's email address); 'tool' calls one of the project's tools (server: the tool's name from get_project_tools, tool: its function, args: an object). Put a decision before any of these when they send what a model wrote or what an outsider sent. A 'draft' step has Claude write something from the card (instructions: what to write); follow it with an approval step (decider 'owner' asks the flow's owner in their chat app, where they can approve, edit or send it back), then an 'update' or 'notify' step whose message is '{{stage.<draft id>}}'. A 'sort' step has Jev pick one of its answers; make it the first step (never a holding step before it, or new cards wait unsorted): question, answers (answer, means: a few words Jev reads, goesTo: a step), sureAt (percent, default 80), ifNotSure (a step; otherwise the card waits for a person), and up to 3 alsoNote (score with levels lowest first, or yes-no); a sort has no next, so give each branch's last step its own next. A 'pull-request' step opens a pull request for the card's built result and waits for CI: next when it passes, ifFails when it fails (only this step defaults it: to the build before it, as a revision carrying the failing check); merge ('squash', 'merge' or 'rebase') merges once checks pass, and needs an approval step before it on every path. waitFor 'hours' with from and until (like '22:00' and '06:00') holds cards until the clock is inside those hours. A 'wait' step, after an 'email' step, waits for a reply to that email from someone it went to (waitFor 'reply', the default): next is where a reply goes (the reply is {{stage.<wait id>}}), ifNoReply where the card goes when none comes within wait (like '3 days', up to 30 days); waitFor 'time' just waits, then next. Any step but wait and done can have remindAfter (like '2 days': whoever it waits on is reminded once; 'none' removes it) and, on holding and approval steps, thenMoveTo (a step the card moves to then). AI teammates (get_teammates): an approval step with teammate (its short name) is decided by that teammate within its rules, and it hands hard ones to the step's decider; a 'teammate' step (teammate, instructions, routes of answer and goesTo) has it read the card, pick where it goes and write what the next steps send (the email body is then {{stage.<id>}}), asking the flow's owner when its rules say to. edit: the full step list, keeping existing steps by id — what a kept step leaves out carries over. add_card (starts in the first zone unless zone is named), move_card, approve, send_back (needs a note), cancel_card, comment (note; @name pings that person), assign (owner: a name, 'me', or 'nobody'), follow, unfollow, save_script (repo, and script: name, about, language python|node|shell, and either body (short) or file (a path in the project, like scripts/enrich.py), and timeoutMinutes; scripts belong to the project, so no flow is needed; a 'check' step in any of its flows names it). A 'check' step runs its script with the card as JSON on stdin (and in $FLOW_INPUT); what it prints is its result for later steps ({{stage.<id>}}); runIn 'folder' (an empty folder: for scripts that work on data) or 'copy' (a copy of the card's work, after setup: for tests on code; the default); routes (answer, goesTo) that a last printed line 'goto: <answer>' picks; ifFails is where a failing script sends the card, such as back to the build (it has no default: without it the card waits there); secrets (names of saved secrets it gets as variables). add_trigger with settings (kind button: label, questions; schedule: schedule like 'daily 09:00 Europe/London', and title, or script (a saved script whose printed items — one per line, a title or JSON with title, description, key — each become a card, once) with secrets; github: repo owner/name, watch issues|pulls|checks, label, branch, from team|anyone; linear: team, state, label; flow: follow (another flow's id), when (its zone); email: folder (default INBOX), sender (addresses or domains), subject (words it must contain)); pause_trigger, resume_trigger, remove_trigger with trigger. Read get_flows first except to create.",
         inputSchema: schema({
-            operation: { type: "string", enum: ["create", "edit", "add_card", "move_card", "approve", "send_back", "cancel_card", "comment", "assign", "follow", "unfollow", "save_script", "add_trigger", "pause_trigger", "resume_trigger", "remove_trigger", "kit"] },
+            operation: { type: "string", enum: ["create", "edit", "add_card", "move_card", "approve", "send_back", "cancel_card", "comment", "assign", "follow", "unfollow", "save_script", "add_trigger", "pause_trigger", "resume_trigger", "remove_trigger", "kit", "starter"] },
             repo: REPO_ARG, flow: { type: "integer", minimum: 1 }, card: { type: "integer", minimum: 1 }, kit: { type: "string", enum: KITS.map(one => one.id) },
+            starter: { type: "string", enum: [...STARTER_IDS] },
             name: { type: "string", maxLength: 80 }, template: { type: "string", enum: FLOW_TEMPLATES.map(one => one.id) },
             steps: { type: "array", minItems: 1, maxItems: 24, items: { type: "object", additionalProperties: false, properties: {
                         id: { type: "string", maxLength: 32 }, title: { type: "string", maxLength: 60 }, kind: { type: "string", enum: [...FLOW_STAGE_KINDS] },
@@ -888,7 +891,8 @@ export const MATE_TOOLS = [
                         server: { type: "string", maxLength: 64 }, tool: { type: "string", maxLength: 100 }, args: { type: "object" },
                         runIn: { type: "string", enum: ["folder", "copy"] }, routes: { type: "array", maxItems: 12, items: { type: "object", additionalProperties: false, properties: { answer: { type: "string", maxLength: 40 }, goesTo: { type: "string", maxLength: 60 } } } },
                         secrets: { type: "array", maxItems: 10, items: { type: "string", maxLength: 40 } },
-                        waitFor: { type: "string", enum: ["reply", "time"] }, wait: { type: "string", maxLength: 40 }, ifNoReply: { type: "string", maxLength: 60 },
+                        waitFor: { type: "string", enum: ["reply", "time", "hours"] }, wait: { type: "string", maxLength: 40 }, ifNoReply: { type: "string", maxLength: 60 },
+                        from: { type: "string", maxLength: 5 }, until: { type: "string", maxLength: 5 }, merge: { type: "string", enum: ["squash", "merge", "rebase"] },
                         remindAfter: { type: "string", maxLength: 40 }, thenMoveTo: { type: "string", maxLength: 60 }, teammate: { type: "string", maxLength: 40 },
                         next: { type: "string", maxLength: 60 }, ifFails: { type: "string", maxLength: 60 }, ifNotSure: { type: "string", maxLength: 60 },
                     } } },
@@ -917,6 +921,15 @@ export const MATE_TOOLS = [
             let operation, input;
             try {
                 switch (args["operation"]) {
+                    case "starter": {
+                        // a starter flow — its zones and its trigger, one yes.
+                        const repo = repoPathOf(ctx.who, args["repo"]);
+                        if (repo === null)
+                            return { ok: false, message: "Choose a project from list_repos." };
+                        operation = "flow_starter";
+                        input = { repo, starter: args["starter"] };
+                        break;
+                    }
                     case "kit": {
                         // a starter kit — a teammate, the flow it works, its buttons.
                         const repo = repoPathOf(ctx.who, args["repo"]);
@@ -937,7 +950,7 @@ export const MATE_TOOLS = [
                         if (name === undefined)
                             return { ok: false, message: "Name the flow." };
                         operation = "flow_create";
-                        input = { repo, name, definition: template === undefined ? flowFromSteps(steps(), null) : structuredClone(template.definition) };
+                        input = { repo, name, definition: template === undefined ? flowFromSteps(steps(), null) : structuredClone(template.definition), ...(template?.trigger === undefined ? {} : { trigger: template.trigger }) };
                         break;
                     }
                     case "edit": {

package/dist/models-ui.js

@@ -1,7 +1,8 @@
 import { priceWords } from "./model-catalog.js";
+import { whenUtc } from "./when-html.js";
 const e = (s) => String(s ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
 const hidden = (data) => Object.entries(data).map(([k, v]) => `<input type="hidden" name="${e(k)}" value="${e(v)}">`).join("");
-const when = (iso) => iso === null ? "never" : `${iso.slice(0, 16).replace("T", " ")} UTC`;
+const when = (iso) => iso === null ? "never" : whenUtc(iso);
 export const MODELS_CSS = `.models{max-width:780px;min-width:0;overflow-wrap:anywhere}.models .card{padding:16px 20px;margin:12px 0;min-width:0}.models h2{margin:24px 0 8px}.models form{margin:0}.models label{display:grid;gap:6px}.models select,.models input[type=search]{box-sizing:border-box;width:100%;max-width:100%;min-width:0}.models button,.models summary,.models .button-link{min-height:44px}.models button{white-space:nowrap}.models summary{padding:12px 0;cursor:pointer}.models .tool{display:flex;gap:12px;align-items:center;justify-content:space-between;flex-wrap:wrap}.models .role{display:grid;grid-template-columns:minmax(0,1fr);gap:8px}.models .role-row{display:flex;gap:12px;align-items:end;flex-wrap:wrap}.models .role-row select{flex:1 1 240px;width:auto;min-width:0}.models .role-name{font-weight:600}.models .new{font-weight:600}.models ul{padding-left:20px}.models .meta{font-size:.86rem}@media(max-width:600px){.models .card{padding:14px}}`;
 function toolRow(one, manage, csrf) {
     const state = one.installed === null ? "Version unknown"
@@ -48,7 +49,7 @@ export function modelsHtml(view) {
             `<button type="submit" class="secondary">${view.watch.enabled ? "Turn off" : "Turn on"}</button></form></details>`
         : "";
     return `<section class="models">${status}${problem}` +
-        `<h2>AI tools</h2>${tools}<p class="meta">Checked ${e(when(view.watch.checkedAt))} ${check}</p>` +
+        `<h2>AI tools</h2>${tools}<p class="meta">Checked ${when(view.watch.checkedAt)} ${check}</p>` +
         fresh +
         `<h2>Default agents</h2><p class="meta">New tasks use these. Approved tasks keep the agents they were approved with.</p>` +
         view.roles.map(role => roleForm(role, manage, view.csrf)).join("") +

package/dist/monitoring-ui.js

@@ -1,6 +1,7 @@
 import { targetOf } from "./monitoring.js";
+import { whenUtc } from "./when-html.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
-const when = (at) => `${e(at.slice(0, 16).replace("T", " "))} UTC`;
+const when = (at) => whenUtc(at);
 export const MONITORING_CSS = `.monitoring{max-width:720px;min-width:0}.monitoring fieldset{border:0;padding:0;margin:20px 0 0;min-width:0}` +
     `.monitoring legend{font-weight:600;font-size:.9375rem;margin-bottom:6px}.monitoring label{display:grid;gap:4px;margin:10px 0 0;font-size:.875rem}` +
     `.monitoring input[type=text],.monitoring input[type=url],.monitoring input[type=password]{width:100%;box-sizing:border-box}.monitoring .choice{display:flex;gap:8px;align-items:center}` +

package/dist/operate.d.ts

@@ -1,3 +1,4 @@
+import { type IntegrationIo } from "./integrations.js";
 import { type OnboardIo } from "./agent-onboard.js";
 import { type TriggerIo } from "./flow-triggers.js";
 import { type StepIo } from "./flow-steps.js";
@@ -55,6 +56,8 @@ export type OperateOptions = {
     flowTriggerIo?: Partial<TriggerIo>;
     /** Injected by tests: how flow check and update steps run commands and reach GitHub and Linear. */
     flowStepIo?: Partial<StepIo>;
+    /** Injected by tests: how `integrations` checks reach services (fetch, gh, sign-in checks, mail servers). */
+    integrationIo?: Partial<IntegrationIo>;
     /** Injected by tests: the mate's provider fetch, key environment, and stdin lines. */
     mateSeams?: MateCliSeams;
     /** Injected by tests: a held-session coordinator, so a `tick` exercises
@@ -72,7 +75,7 @@ export type OperateOptions = {
         openBrowser?: (url: string) => void;
     };
 };
-export type OnboardSeams = Partial<Pick<OnboardIo, "home" | "env" | "cwd" | "interactive" | "confirm" | "findRepo" | "checkConnection">>;
+export type OnboardSeams = Partial<Pick<OnboardIo, "home" | "env" | "cwd" | "interactive" | "confirm" | "findRepo" | "checkConnection" | "pullRequests">>;
 export declare const OPERATE_HELP: string;
 /** Parsed flags, with the positionals left over. */
 type Args = {
@@ -89,7 +92,7 @@ type Args = {
  * (surface.ts) is tested for exact equality against them.
  */
 export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise"];
-export declare const PUBLISH_ACTIONS: readonly ["grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
+export declare const PUBLISH_ACTIONS: readonly ["setup", "grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
 export declare const CONFIG_ACTIONS: readonly ["show", "set", "clear"];
 export declare const APPROVER_ACTIONS: readonly ["list", "add"];
 export declare const ROUTINE_ACTIONS: readonly ["list", "add", "show", "approve", "refresh", "pause", "resume", "run-now"];

package/dist/operate.js

@@ -13,6 +13,7 @@ import { buildExport, exportSummary, exportZip, writeExportFolder } from "./expo
 import { startBudgetAlerts } from "./budget-alerts.js";
 import { liftAuthPause, openAuthPauses, signInGate, signInWords, startSignInProbes } from "./provider-auth.js";
 import { createConnectionChecker } from "./provider-connection.js";
+import { checkIntegrations, integrationsBrokenLine, integrationsNow, renderIntegrations } from "./integrations.js";
 import { buildHandoff, handoffLines, loginAccount, runOnboard } from "./agent-onboard.js";
 import { backupFiles, backupFolderOf, backupOwner, backupNow, restoreDatabase, startBackups } from "./backup.js";
 import { pushLimitSink } from "./provider-limits.js";
@@ -67,7 +68,7 @@ import { runTaskOutcomeCommand } from "./task-outcome-cli.js";
  */
 import { homedir, hostname, tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
-import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, DEFAULT_ACTOR, parseCapabilityKey, verifiedAuthor, contestantProfileOf, } from "./store.js";
+import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, DEFAULT_ACTOR, parseCapabilityKey, verifiedAuthor, contestantProfileOf, isDigestTime, } from "./store.js";
 import { randomBytes, randomInt, randomUUID } from "node:crypto";
 import { authorizePlanUnderMode } from "./plan-auto.js";
 import { ghDispatchAdapter, mirrorTaskId, syncPass } from "./sync.js";
@@ -136,6 +137,8 @@ import { verifyApproverByPassword } from "./principal.js";
 import { authorizedProject, canonicalProject, projectName, resolveCeiling } from "./project.js";
 import { tally, spendLine } from "./summary.js";
 import { bodyHashOf, describePublicationGrant, observeChecks, publicationBody, publishPass, sweepMerges, } from "./publish.js";
+import { checkPublishing, publishingOf, savePublishing, followPullRequests } from "./pull-request-flow.js";
+import { starterOf, startersFor, switchOnStarter } from "./flow-starters.js";
 import { acquire, acquireFallback, acquireIfReady, completeFenced, finalizeFailureFenced, finalizeMalformedFenced, finalizeParkFenced, finalizePlanFenced, finalizePlanFailureFenced, finalizeScoutFenced, finalizeScoutFailureFenced, heartbeat, release, reap, currentClaim, DEFAULT_LEASE_MS, SYNC_MAX_AGE_MS, acquireContinuation, } from "./claim.js";
 import { disposeBuildOutcome, holdStaleApproval, regateTask } from "./dispose.js";
 import { attendedLivenessState } from "./liveness.js";
@@ -213,11 +216,14 @@ export const OPERATE_HELP = `toolroll — operating the queue
   toolroll storage clean [--yes]     preview removing finished tasks' clean checkouts (their branches stay); --yes removes them
   toolroll storage cleanup <when>    remove a finished task's clean checkout: finished|2d|7d|never (instance operator)
   toolroll storage discard <path> --yes   throw away a checkout kept for its changes; its branch stays
+  toolroll integrations [--json]     which integrations work: Connected, Not set up or Broken, and what to do (--saved: no new checks)
   toolroll monitoring                where the audit stream and traces go, and how each destination is doing
   toolroll check-progress <run>      current or final approved check progress
   toolroll spend [--month YYYY-MM] [--csv]   what agent work cost, by project, person, teammate and model
   toolroll export --out <path> [--zip]   everything Toolroll knows, in a folder or .zip (no secrets)
   toolroll budget list|set|remove    monthly budgets (--all | --project <p> | --person <name> | --teammate <id>) --usd <n> [--alerts-only]
+  toolroll notifications [quiet|all]   how chats reach you: only when you're needed (the default), or every step
+  toolroll notifications digest <HH:MM>|off   one evening message: what finished, what waits, what failed
   toolroll retention show|preview    how long evidence, checkout records, chat and notifications are kept; what the daily sweep would remove
   toolroll retention set <kind> <period>   evidence|checkouts|chat|notifications, 30d|1y|forever (instance operator)
   toolroll backup now|list          back the database up now; list backups and how the last ones went
@@ -264,6 +270,10 @@ External trackers — build what a tracker nominates, under local approvals
                                         the dispatch grant: its own explicit
                                         yes, never in any default; writes a
                                         plane marker label to the repository
+  toolroll publish setup [--repo <path>] [--merge-method squash|merge|rebase]
+      [--merge-when-green] --yes      one-step pull requests: checks gh sign-in
+                                        and push rights, then Complete offers
+                                        "Complete and open a pull request"
   toolroll publish grant --github <owner/name> --allow-merge
       --merge-method squash|merge|rebase [--merge-delete-branch] --yes
                                         auto-merge this plane's own PRs —
@@ -532,7 +542,7 @@ export const TASK_ACTIONS = [
     "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan",
     "review", "accept", "repair", "route", "stop", "resume", "complete", "revise",
 ];
-export const PUBLISH_ACTIONS = ["grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
+export const PUBLISH_ACTIONS = ["setup", "grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
 export const CONFIG_ACTIONS = ["show", "set", "clear"];
 export const APPROVER_ACTIONS = ["list", "add"];
 export const ROUTINE_ACTIONS = ["list", "add", "show", "approve", "refresh", "pause", "resume", "run-now"];
@@ -567,6 +577,8 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "label", "reviewers", "limit", "role", "key-file", "weekly-usd", "daily-turns", "per-hour", "token-file", "race", "compare", "race-per-usd", "race-total-usd", "race-count", "race-agents", "budget-usd", "build-usd", "sync-max-age", "merge-method",
     "phase", "risk", "tier", "clear-phase",
     "run", "containment", "agent",
+    // onboard: the starter flows to switch on.
+    "starter",
     "token-env", "after", "repair-max-attempts", "consumer", "batch", "feedback", "source", "view", "cursor", "why", "supersedes", "decision", "sessions", "timeout",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
@@ -577,6 +589,8 @@ export const OPERATE_BOOLEAN_FLAGS = new Set([
     "html", "csv", "alerts-only",
     // v105: the full export.
     "zip",
+    // Settings → Integrations: the last checks, without checking again.
+    "saved",
 ]);
 export function parseOperateArgs(argv) {
     const positional = [];
@@ -720,6 +734,7 @@ export async function runOperate(command, argv, write, options = {}) {
             ...(options.dispatchAdapter === undefined ? {} : { dispatchAdapter: options.dispatchAdapter }),
             ...(options.flowTriggerIo === undefined ? {} : { flowTriggerIo: options.flowTriggerIo }),
             ...(options.flowStepIo === undefined ? {} : { flowStepIo: options.flowStepIo }),
+            ...(options.integrationIo === undefined ? {} : { integrationIo: options.integrationIo }),
             ...(options.shouldStop === undefined ? {} : { shouldStop: options.shouldStop }),
             ...(options.mateSeams === undefined ? {} : { mateSeams: options.mateSeams }),
             ...(options.heldCoordinator === undefined ? {} : { heldCoordinator: options.heldCoordinator }),
@@ -817,6 +832,8 @@ async function dispatch(command, positional, flags, context) {
             return budgetCommand(positional, flags, context);
         case "retention":
             return retentionCommand(positional, flags, context);
+        case "notifications":
+            return notificationsCommand(positional, flags, context);
         case "backup":
             return backupCommand(positional, flags, context);
         case "export":
@@ -825,6 +842,8 @@ async function dispatch(command, positional, flags, context) {
             return policyCommand(positional, flags, context);
         case "storage":
             return storageCommand(positional, flags, context);
+        case "integrations":
+            return integrationsCommand(positional, flags, context);
         case "monitoring": {
             // Where the audit stream and traces go, and how each destination is doing. Settings → Monitoring changes it.
             const settings = readMonitoring(dirname(context.databaseFile));
@@ -7230,6 +7249,14 @@ async function runWatchLoop(args) {
                     });
                     if (checks.failing > 0)
                         progress(`watch: CI is red on ${checks.failing} published PR(s) — the outbox has it`);
+                    const followed = await followPullRequests(store, checks.seen, {
+                        evidenceRoot: context.evidenceRoot,
+                        ...(context.publishExec === undefined ? {} : { exec: context.publishExec }),
+                    });
+                    if (followed.revisions > 0)
+                        progress(`watch: filed ${followed.revisions} CI revision(s)`);
+                    if (followed.merged > 0)
+                        progress(`watch: merged ${followed.merged} pull request(s) whose checks passed`);
                 }
                 catch (error) {
                     progress(`watch: CI observation failed — ${describe(error)}; retrying on its next interval`);
@@ -7710,7 +7737,7 @@ async function onboardCommand(flags, context) {
     const gitRun = context.gitRunner ?? ((file, args, opts) => run(file, [...args], { ...(opts?.cwd === undefined ? {} : { cwd: opts.cwd }), timeoutMs: 10_000 }));
     const registryPath = registryPathOf(context);
     const checker = createConnectionChecker({ home, env });
-    return runOnboard({
+    const code = await runOnboard({
         write,
         json,
         yes: flag(flags, "yes"),
@@ -7750,7 +7777,38 @@ async function onboardCommand(flags, context) {
             return { ok: true, added: "error" in before || !before.repos.includes(repo) };
         },
         checkConnection: seams.checkConnection ?? (agent => checker(agent)),
+        pullRequests: seams.pullRequests ?? (async (repo) => {
+            const publishing = publishingOf(store, repo);
+            if (publishing.on)
+                return `on for ${publishing.githubRepo} into ${publishing.base}`;
+            const checked = await checkPublishing(repo, context.publishExec === undefined ? {} : { exec: context.publishExec });
+            if (!checked.ok)
+                return `off: ${checked.message}`;
+            return `off: turn on with toolroll publish setup --repo ${repo} --yes (asks your password), or in Settings → Projects`;
+        }),
+        starterFlag: text(flags, "starter"),
+        // Starter flows belong to a person: the flow's decisions ask them. With no account yet, none can be switched on.
+        starters: {
+            list: async (repo) => {
+                const views = startersFor(store, repo);
+                return store.listApprovers().length > 0 ? views : views.map(one => ({ ...one, blocked: one.blocked ?? "Needs your account first: run toolroll up, then onboard again." }));
+            },
+            switchOn: async (repo, id) => {
+                const owner = onboardLogin(store, loginFile)?.account ?? store.listApprovers()[0]?.name ?? null;
+                const starter = starterOf(id);
+                if (owner === null || starter === null)
+                    return { ok: false, said: "Needs your account first: run toolroll up, then onboard again." };
+                return switchOnStarter(store, starter, repo, owner, clock(), dirname(context.databaseFile));
+            },
+        },
     });
+    // One line when an integration is Broken, from the last checks only (never a new check here).
+    if (!json) {
+        const line = integrationsBrokenLine(await savedIntegrations(context).catch(() => []));
+        if (line !== null)
+            write(line);
+    }
+    return code;
 }
 async function upCommand(flags, context) {
     const { store, write, json, clock } = context;
@@ -8539,6 +8597,42 @@ async function publishCommand(positional, flags, context) {
     if (action !== undefined && !PUBLISH_ACTIONS.includes(action)) {
         return fail(write, json, "publish", "usage", `unknown \`publish ${action}\` — try ${PUBLISH_ACTIONS.join(", ")}, or bare \`publish\` for the publication pass`, EXIT.usage);
     }
+    if (action === "setup") {
+        const mergeMethod = text(flags, "merge-method") ?? "squash";
+        if (!["squash", "merge", "rebase"].includes(mergeMethod)) {
+            return fail(write, json, "publish setup", "usage", "--merge-method is squash, merge or rebase", EXIT.usage);
+        }
+        const checked = await checkPublishing(repo, context.publishExec === undefined ? {} : { exec: context.publishExec });
+        if (!checked.ok)
+            return fail(write, json, "publish setup", checked.reason, checked.message, EXIT.refused);
+        const settings = { mergeMethod: mergeMethod, mergeWhenGreen: flags.has("merge-when-green") };
+        const plan = checked.plan;
+        const terms = [
+            `Pull requests for ${plan.githubRepo} into ${plan.base}${plan.account === null ? "" : `, as ${plan.account}`}.`,
+            "Complete will offer \"Complete and open a pull request\"; the pull request opens from the exact completed commit.",
+            `Merges ${settings.mergeMethod} and delete the branch${settings.mergeWhenGreen ? ", by themselves once checks pass" : " when a person selects Merge"}.`,
+        ];
+        if (!flags.has("yes")) {
+            if (json) {
+                write(envelopeJson({ ok: false, command: "publish setup", reason: "unconfirmed", proposed: { ...plan, ...settings } }));
+                return EXIT.refused;
+            }
+            for (const line of terms)
+                write(line);
+            write("Nothing is set up yet. Repeat with --yes --as <you> --token <password> to turn it on.");
+            return EXIT.refused;
+        }
+        const acting = await askCredentials(flags, context);
+        if (acting === null) {
+            return fail(write, json, "publish setup", "usage", "turning on pull requests takes --as <you> --token <your password>", EXIT.usage);
+        }
+        const authenticated = authenticateApprover(store, acting.name, acting.token, repo);
+        if (!authenticated.ok) {
+            return fail(write, json, "publish setup", authenticated.reason, describeApproveFailure(authenticated.reason, acting.name), EXIT.refused);
+        }
+        savePublishing(store, plan, acting.name, settings, clock());
+        return succeed(write, json, "publish setup", { publishing: publishingOf(store, repo) }, () => ["Pull requests are on.", ...terms]);
+    }
     if (action === "grant") {
         const github = text(flags, "github");
         if (github === undefined || !/^[\w.-]+\/[\w.-]+$/.test(github)) {
@@ -9101,7 +9195,49 @@ async function statusCommand(positional, flags, context) {
         notifySecurityRelease(context.store, release, current, method.updateCommand, context.clock());
     const line = updateLine(release, current, method.updateCommand);
     const update = release === null ? {} : { update: { current, latest: release.version, security: release.security, updateCommand: method.updateCommand, url: release.url } };
-    return succeed(context.write, context.json, command, { ...status, ...update }, () => [...renderInstallationStatus(status), ...(line === null ? [] : [line])]);
+    // One line when an integration is Broken, from the last checks only: status never waits on a check.
+    const brokenIntegrations = await savedIntegrations(context).then(list => list.filter(one => one.state === "broken"), () => []);
+    const brokenLine = integrationsBrokenLine(brokenIntegrations);
+    const integrations = brokenIntegrations.length === 0 ? {} : { integrations: { broken: brokenIntegrations.map(one => ({ key: one.key, name: one.name, fix: one.action.kind === "fix" ? one.action.words : null })) } };
+    return succeed(context.write, context.json, command, { ...status, ...update, ...integrations }, () => [...renderInstallationStatus(status), ...(line === null ? [] : [line]), ...(brokenLine === null ? [] : [brokenLine])]);
+}
+/** Where `integrations` looks: the installation's files beside the database, and every project it knows. */
+async function integrationIoFor(context) {
+    const registered = await loadProjectRegistry(registryPathOf(context)).catch(() => ({ error: "unreadable" }));
+    const repos = [...new Set([...("error" in registered ? [] : registered.repos), ...context.store.listProjects().map(one => one.path)])];
+    const seams = context.integrationIo ?? {};
+    return {
+        store: context.store,
+        dir: dirname(context.databaseFile),
+        telegramTokenFile: context.telegramTokenFile,
+        env: process.env,
+        repos,
+        gh: (file, args, options) => run(file, [...args], options),
+        checkConnection: createConnectionChecker(),
+        clock: context.clock,
+        ...seams,
+    };
+}
+/** The integrations from files and the last checks: no network, for `status` and `onboard`. */
+async function savedIntegrations(context) {
+    return integrationsNow(await integrationIoFor(context));
+}
+/** `toolroll integrations [--json]`: check every integration now and say which work. `--saved` skips the checks. */
+async function integrationsCommand(positional, flags, context) {
+    const command = "integrations";
+    const allowed = new Set(["db", "json", "saved"]);
+    for (const name of flags.keys()) {
+        if (!allowed.has(name))
+            return fail(context.write, context.json, command, "usage", `--${name} is not an integrations option.`, EXIT.usage);
+    }
+    if (positional.length > 0)
+        return fail(context.write, context.json, command, "usage", "Use `toolroll integrations [--saved] [--json]`.", EXIT.usage);
+    const io = await integrationIoFor(context);
+    const list = flag(flags, "saved") ? integrationsNow(io) : await checkIntegrations(io);
+    const counts = { connected: 0, "not-set-up": 0, broken: 0 };
+    for (const one of list)
+        counts[one.state] += 1;
+    return succeed(context.write, context.json, command, { integrations: list, counts }, () => renderIntegrations(list));
 }
 async function waitTask(positional, flags, context) {
     const command = "task wait";
@@ -11270,6 +11406,35 @@ async function budgetCommand(positional, flags, context) {
     const saved = store.setBudget({ scope: target.scope, key: target.key, limitMicrousd: Math.round(dollars) * 1_000_000, hardStop: !flags.has("alerts-only") }, acting.name, context.clock());
     return succeed(context.write, context.json, command, { budget: saved }, () => [`${budgetLabel(saved).replace(/'s$/, "")}: ${spendUsd(saved.limitMicrousd)} a month${saved.hardStop ? ", API work stops at 100%" : ", alerts only"}.`]);
 }
+/** `notifications [quiet | all | digest <HH:MM> | digest off]`: how chats reach this person — only when they are
+ * needed (the default), every step, and an optional evening digest. Each person sets their own. */
+async function notificationsCommand(positional, flags, context) {
+    const [action, value, ...extra] = positional;
+    const command = `notifications${action === undefined ? "" : ` ${action}`}`;
+    const store = context.store;
+    for (const name of flags.keys())
+        if (!["as", "token", "token-file", "token-env", "db", "json"].includes(name))
+            return fail(context.write, context.json, command, "usage", `--${name} is not a notifications option.`, EXIT.usage);
+    const usage = "Use notifications quiet, notifications all, or notifications digest <HH:MM>|off.";
+    if (extra.length > 0 || (action !== undefined && !["quiet", "all", "digest"].includes(action)) || (action === "digest") !== (value !== undefined)) {
+        return fail(context.write, context.json, command, "usage", usage, EXIT.usage);
+    }
+    if (action === "digest" && value !== "off" && !isDigestTime(value))
+        return fail(context.write, context.json, command, "usage", "The digest time is HH:MM on a 24-hour clock, like 18:30, or off.", EXIT.usage);
+    const acting = await askCredentials(flags, context);
+    const verified = acting === null ? null : authenticateApprover(store, acting.name, acting.token);
+    if (acting === null || verified === null || !verified.ok) {
+        return fail(context.write, context.json, command, "refused", "Notifications are set per person: pass --as and --token (or use the remembered login).", EXIT.refused);
+    }
+    const now = context.clock();
+    const preference = action === "quiet" || action === "all" ? store.setNotificationPreference(acting.name, { mode: action }, acting.name, now)
+        : action === "digest" ? store.setNotificationPreference(acting.name, { digestAt: value === "off" ? null : value }, acting.name, now)
+            : store.notificationPreference(acting.name);
+    return succeed(context.write, context.json, command, { mode: preference.mode, digestAt: preference.digestAt }, () => [
+        preference.mode === "quiet" ? "Only when you're needed: one message per task, updated as it moves, and a new one when something needs you." : "Every step: a message for each update.",
+        preference.digestAt === null ? "No evening digest." : `Evening digest at ${preference.digestAt}: what finished, what waits and what failed.`,
+    ]);
+}
 /** `retention show | preview | set <kind> <period>` (v105): how long each kind of data is kept, and what the daily
  * sweep would remove now. Setting takes an instance operator. */
 async function retentionCommand(positional, flags, context) {

package/dist/policy-ui.js

@@ -1,3 +1,4 @@
+import { whenUtc } from "./when-html.js";
 import { LEVEL_HINTS, LEVEL_NAMES, PERMISSION_LEVELS, POLICY_PROVIDERS, PROVIDER_NAMES, policyParts } from "./policy.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 export const POLICY_CSS = `.policy{max-width:720px;min-width:0}.policy dl{display:grid;grid-template-columns:max-content minmax(0,1fr);gap:6px 16px;margin:12px 0 0;font-size:.875rem}` +
@@ -13,7 +14,7 @@ function historyItem(entry) {
     const what = entry.action.replace(/^organisation policy: /, "");
     const [before, after] = (entry.detail ?? "").split(" → ");
     return `<li><span class="what">${e(what.charAt(0).toUpperCase() + what.slice(1))}: ${e(before ?? "")} → <strong>${e(after ?? "")}</strong></span>` +
-        `<span class="meta">${e(entry.actor)} · <time datetime="${e(entry.at)}">${e(entry.at.slice(0, 16).replace("T", " "))} UTC</time></span></li>`;
+        `<span class="meta">${e(entry.actor)} · ${whenUtc(entry.at)}</span></li>`;
 }
 export function policyHtml(view, csrf, notice) {
     const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";

package/dist/project-delete.js

@@ -231,6 +231,7 @@ function deleteRows(store, repo, d, now) {
     del("telegram_conversation_part", `${IN("conversation")} OR ${IN("source_run")} OR ${IN("task_id")}`, conversations, R, K);
     del("telegram_conversation", IN("id"), conversations);
     del("telegram_outbound_message", `project = ? OR ${IN("notification")} OR ${IN("task_ref")} OR ${IN("source_run")}`, repo, notifications, T, R);
+    del("chat_card_task", IN("task_ref"), T);
     del("push_delivery", IN("notification"), notifications);
     del("notification_delivery", IN("notification"), notifications);
     del("notification", IN("id"), notifications);

package/dist/publish.d.ts

@@ -20,6 +20,7 @@
  * @-mention in its conclusion cannot acquire GitHub semantics.
  */
 import { type ExecResult, type RunOptions } from "./exec.js";
+import { summarizeChecks } from "./pulls.js";
 import type { Publication, PublicationGrant, Store } from "./store.js";
 export declare const BODY_TEMPLATE_VERSION = 2;
 /** After this many failed attempts a publication stops retrying and pages instead. */
@@ -69,6 +70,16 @@ export type CheckReport = {
     failing: number;
     resolved: number;
     problems: string[];
+    /** Every observation that won its settle, for the pull-request follower (CI revisions, Ready to merge). */
+    seen: ObservedPullRequest[];
+};
+export type ObservedPullRequest = {
+    publication: Publication;
+    headOid: string;
+    state: ReturnType<typeof summarizeChecks>;
+    remoteState: "MERGED" | "CLOSED" | null;
+    rollup: unknown;
+    mergeCommit: string | null;
 };
 /**
  * Read CI for every PR this control plane opened — structured rollup and the

package/dist/publish.js

@@ -254,7 +254,7 @@ async function openOrAdopt(store, publication, grant, exec, clock) {
 export async function observeChecks(store, options) {
     const clock = options.clock ?? (() => new Date());
     const exec = options.exec ?? execRun;
-    const report = { observed: 0, failing: 0, resolved: 0, problems: [] };
+    const report = { observed: 0, failing: 0, resolved: 0, problems: [], seen: [] };
     for (const publication of store.openedPublications()) {
         if (publication.prNumber === null)
             continue;
@@ -266,7 +266,7 @@ export async function observeChecks(store, options) {
         const viewed = await exec("gh", [
             "pr", "view", String(publication.prNumber),
             "--repo", publication.githubRepo,
-            "--json", "statusCheckRollup,headRefOid,state",
+            "--json", "statusCheckRollup,headRefOid,state,mergeCommit",
         ], { timeoutMs: EXEC_TIMEOUT_MS });
         if (viewed.code !== 0) {
             report.problems.push(`PR #${publication.prNumber}: not read — ${viewed.notFound ? "gh is not on PATH" : firstLine(viewed.stderr) || `exit ${viewed.code}`}`);
@@ -290,11 +290,15 @@ export async function observeChecks(store, options) {
         // remote state is recorded, its episodes resolve, and neither the
         // review queue nor the next observation pass carries it forever.
         const remoteState = typeof payload.state === "string" ? payload.state.toUpperCase() : null;
+        const mergeCommit = typeof payload.mergeCommit === "object" && payload.mergeCommit !== null && typeof payload.mergeCommit.oid === "string"
+            ? payload.mergeCommit.oid : null;
         if (remoteState === "MERGED" || remoteState === "CLOSED") {
+            let won = false;
             store.transact(() => {
                 const settled = store.settleObservation({ githubRepo: publication.githubRepo, prNumber: publication.prNumber, headSha: headOid, state: "none", generation }, clock());
                 if (!settled.won)
                     return;
+                won = true;
                 store.recordPublicationRemoteState(publication.id, remoteState, clock());
                 report.resolved += store.resolveCiEpisodes(publication.githubRepo, publication.prNumber, null, clock());
                 // A closed PR moots its merge blocker and supersedes its intent —
@@ -311,6 +315,8 @@ export async function observeChecks(store, options) {
                     });
                 }
             });
+            if (won)
+                report.seen.push({ publication, headOid, state: "none", remoteState, rollup: payload.statusCheckRollup, mergeCommit });
             continue;
         }
         const state = summarizeChecks(payload.statusCheckRollup);
@@ -322,6 +328,7 @@ export async function observeChecks(store, options) {
             continue;
         }
         store.recordPublicationCheckState(publication.id, state, clock());
+        report.seen.push({ publication, headOid, state, remoteState: null, rollup: payload.statusCheckRollup, mergeCommit });
         // The episode identity carries the REPOSITORY (audit C-2): PR #55 in
         // repo A and PR #55 in repo B are different worlds, and one's failure
         // must never light the other's repair button.