toolroll 0.8.2 → 0.9.0

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,7 @@ 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 { 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 +215,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 +269,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 +541,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"];
@@ -577,6 +586,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 +731,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 +829,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 +839,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 +7246,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 +7734,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 +7774,23 @@ 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`;
+        }),
     });
+    // 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 +8579,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 +9177,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 +11388,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/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.

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

@@ -0,0 +1,140 @@
+/**
+ * Complete → pull request → merge, without a person running git.
+ *
+ * Setup is one step per project: the project's GitHub remote and default branch are read, `gh` must be signed
+ * in with push rights, and a publication grant is saved that publishes only when a person chooses "Complete and
+ * open a pull request" (never on every build). The publisher (publish.ts) then pushes the exact accepted commit
+ * and opens or adopts the PR, as it always has.
+ *
+ * The follower reads what observeChecks saw: a red head files ONE revision carrying the failing check's name and
+ * a short log excerpt, fenced as untrusted CI output — at most two across one task's revisions, then a person is
+ * asked instead. A green head on the exact accepted commit is announced once as Ready to merge.
+ *
+ * Merging is a person's act behind their password (or the project's opt-in "Merge when checks pass"): a fresh
+ * read must show the PR open, on the accepted commit, with checks passing; GitHub's head-commit match guards
+ * the race; the branch is deleted; the merge commit and who merged are recorded in the ledger.
+ */
+import { type ObservedPullRequest, type PublishExec } from "./publish.js";
+import type { VerifiedApprover } from "./principal.js";
+import type { Publication, Store } from "./store.js";
+export type MergeMethod = "squash" | "merge" | "rebase";
+export declare const MERGE_METHODS: readonly MergeMethod[];
+/** CI revisions one task may file across its revisions before a person is asked instead. */
+export declare const MAX_CI_REVISIONS = 2;
+export declare const MERGED_ACTION = "pull request merged";
+export declare const REQUESTED_ACTION = "pull request requested";
+type Result<T> = ({
+    ok: true;
+} & T) | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+export type PublishingPlan = {
+    repo: string;
+    githubRepo: string;
+    remote: string;
+    base: string;
+    account: string | null;
+};
+/** owner/name from a GitHub remote URL (https, ssh or scp form), or null when it is not GitHub. */
+export declare function githubRepoOf(remoteUrl: string): string | null;
+/** Everything setup needs, checked in the order a person would fix it — each refusal says what to do next. */
+export declare function checkPublishing(repo: string, options?: {
+    exec?: PublishExec;
+    remote?: string;
+}): Promise<Result<{
+    plan: PublishingPlan;
+}>>;
+export type PublishingSettings = {
+    mergeMethod: MergeMethod;
+    mergeWhenGreen: boolean;
+};
+export type Publishing = {
+    on: false;
+} | ({
+    on: true;
+    githubRepo: string;
+    base: string;
+    grantedBy: string;
+    legacy: boolean;
+} & PublishingSettings);
+export declare function publishingOf(store: Store, repo: string | null): Publishing;
+/** The grant setup creates: this project's GitHub repo, its default branch, Toolroll's own branches, pull requests
+ * only when a person asks at Complete, ready for review, squash by default, branch deleted on merge. */
+export declare function savePublishing(store: Store, plan: PublishingPlan, by: string, settings: Partial<PublishingSettings>, now: Date): void;
+/** Change how merges happen, keeping every other term of the live grant. */
+export declare function saveMergeSettings(store: Store, repo: string, settings: PublishingSettings, by: string, now: Date): Result<object>;
+/** Whether "Complete and open a pull request" may be offered for this result, and if not, why (null = offer it). */
+export declare function pullRequestBlocker(store: Store, runId: number): string | null;
+/**
+ * Mark the exact displayed result complete and owe a pull request for its exact commit — one transaction, so
+ * "complete" and "this must reach a PR" can't come apart. A result already marked complete may still open its
+ * pull request. The watch process pushes and opens it; the task shows its progress.
+ */
+export declare function completeAndOpenPullRequest(store: Store, input: {
+    taskId: string;
+    digest: string;
+    runId: number;
+    who: VerifiedApprover;
+    root: string;
+}, now: Date): Result<{
+    publication: Publication;
+}>;
+export type FollowReport = {
+    revisions: number;
+    asked: number;
+    ready: number;
+    merged: number;
+    problems: string[];
+};
+/** The revision note: the failing check by name, then its log as fenced, labelled untrusted data. At most 500 characters. */
+export declare function ciRevisionNote(check: string, prNumber: number, head: string, excerpt: string | null): string;
+/**
+ * What observeChecks saw, acted on for pull requests opened through Complete: one revision per red head (at most
+ * two per task, then a person is asked), Ready to merge once per green head on the accepted commit, and the merge
+ * itself when the project merges on green. A remote merge done elsewhere is recorded with its commit.
+ */
+export declare function followPullRequests(store: Store, seen: readonly ObservedPullRequest[], options: {
+    evidenceRoot: string;
+    exec?: PublishExec;
+    clock?: () => Date;
+}): Promise<FollowReport>;
+/** A person's merge: their password first, then the same checked merge. */
+export declare function mergeAsPerson(store: Store, input: {
+    runId: number;
+    name: string;
+    password: string;
+    exec?: PublishExec;
+    clock?: () => Date;
+}): Promise<Result<{
+    commit: string | null;
+}>>;
+/**
+ * Merge a followed pull request: callers have already established who is merging. A fresh read must show it open,
+ * not a draft, on the accepted commit, with checks passing; the merge names that commit so GitHub refuses a head
+ * that moved, uses the project's method, and deletes the branch.
+ */
+export declare function mergePullRequest(store: Store, input: {
+    runId: number;
+    by: string;
+    exec?: PublishExec;
+    clock?: () => Date;
+}): Promise<Result<{
+    commit: string | null;
+}>>;
+export type PullRequestView = {
+    runId: number;
+    prNumber: number | null;
+    prUrl: string | null;
+    state: "opening" | "running" | "waiting" | "ready" | "failing" | "merged" | "closed" | "failed";
+    label: string;
+    detail: string;
+    mergeCommit: string | null;
+    mergeMethod: MergeMethod;
+    canMerge: boolean;
+    revisionTask: string | null;
+};
+/** The pull request a result opened through Complete, in plain words; null when it opened none. */
+export declare function pullRequestViewOf(store: Store, runId: number): PullRequestView | null;
+export {};