toolroll 0.8.1 → 0.9.0

package/dist/operate.js

@@ -3,7 +3,8 @@ import { parseProtectedPaths } from "./approval-policy.js";
 import { rulesSummary } from "./approval-rules-ui.js";
 import { evidencePack, exportDay, ledgerExportChunks, standaloneEvidenceHtml } from "./evidence-pack.js";
 import { matchesOutsideCheckpoint } from "./ledger-chain.js";
-import { bytesWords, storageReport } from "./storage.js";
+import { CLEANUP_CHOICES, bytesWords, cleanupWords, parseCleanup, storageReport } from "./storage.js";
+import { checkoutPlan, cleanCheckouts, discardCheckout, whyWords } from "./checkout-cleanup.js";
 import { MIN_DAYS, RETENTION_KINDS, countWords, dailyRetention, isRetentionKind, lastSweepAt, parsePeriod, periodWords, retentionPlan, sweepWords } from "./retention.js";
 import { checkPolicy, parseList, policyParts } from "./policy.js";
 import { billingOf, budgetHoldWords, budgetLabel, budgetStates, monthNamed, monthOf, spendItems, teammateNames, usd as spendUsd } from "./spend.js";
@@ -12,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";
@@ -66,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";
@@ -135,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";
@@ -193,10 +196,6 @@ import { PACKAGE_VERSION } from "./version.js";
  * caller deciding whether to try the next task or wake somebody up.
  */
 export const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
-/** Storage retention: how long a finished task's clean checkout is kept after it was let go, and a result marked
- * complete's or a release candidate's after it was (its checkout holds the build a deploy installs). */
-export const CHECKOUT_KEEP_MS = 2 * 24 * 60 * 60_000;
-export const RESULT_KEEP_MS = 7 * 24 * 60 * 60_000;
 const STATES = ["queued", "running", "done", "failed", "cancelled"];
 export const OPERATE_HELP = `toolroll — operating the queue
 
@@ -213,11 +212,17 @@ export const OPERATE_HELP = `toolroll — operating the queue
                                         --not-requester on|off, --protect none|project, --protect-paths "a/**,b/**"
   toolroll task evidence <id>        the task's evidence pack as JSON (--html for a printable page; --out <file>)
   toolroll storage                   where the disk goes: database, build checkouts, releases, evidence
+  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,19 +829,18 @@ 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":
             return exportCommand(positional, flags, context);
         case "policy":
             return policyCommand(positional, flags, context);
-        case "storage": {
-            const report = storageReport(context.store, context.databaseFile, context.clock(), CHECKOUT_KEEP_MS);
-            return succeed(context.write, context.json, "storage", report, () => [
-                `${report.folder}: ${bytesWords(report.total)}`,
-                ...report.lines.map(one => `  ${one.what.padEnd(17)} ${bytesWords(one.bytes).padStart(8)}${one.count === undefined ? "" : `  (${one.count})`}${one.note === undefined ? "" : `  ${one.note}`}`),
-            ]);
-        }
+        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));
@@ -4313,13 +4324,9 @@ async function reconcileCommand(flags, context) {
             reaped: reaped.map(claim => claim.leaseId),
         });
     }
-    // Storage retention: finished work's clean checkouts go two days after they were let go (their branches stay); a
-    // result marked complete, or a release candidate, a week after (a deploy installs the build in its checkout).
-    const pruned = await worktrees.prune(repo, clock(), CHECKOUT_KEEP_MS, () => store.keptBranches(repo, clock(), RESULT_KEEP_MS));
-    for (const row of pruned.removed) {
-        store.recordAction({ at: clock().toISOString(), actor: "worker", repo, taskId: row.taskRef === null ? null : store.externalIdFor(row.taskRef), runId: null,
-            action: "checkout removed", outcome: "removed", source: "work", detail: `${basename(row.path)} (released ${row.releasedAt?.slice(0, 10) ?? "?"})` });
-    }
+    // Checkout cleanup (Settings → Storage): finished work's clean checkouts go as the setting says (by default when
+    // the task is complete or cancelled); their branches stay. Each removal is in the ledger.
+    const pruned = await cleanCheckouts(store, worktrees, clock, { manual: false, actor: "worker", repo });
     // Retention (Settings → Retention): once a day, what's older than its setting goes; one ledger entry says what.
     let retention = null;
     try {
@@ -4341,7 +4348,7 @@ async function reconcileCommand(flags, context) {
         reaped: reaped.map(claim => claim.leaseId),
         adopted: adoption.adopted,
         forgotten: adoption.forgotten,
-        checkoutsRemoved: pruned.removed.map(row => row.path),
+        checkoutsRemoved: pruned.removed.map(one => one.path),
         checkoutsKept: pruned.kept,
         liveViewsSwept: liveSwept.removed.length,
         retention: retention === null ? null : { counts: retention.counts, freedBytes: retention.freed },
@@ -4352,7 +4359,7 @@ async function reconcileCommand(flags, context) {
             ...(reaped.length === 0 ? [] : [`Reaped ${reaped.length} expired lease(s).`]),
             ...adoption.adopted.map(path => `Adopted ${path} — released, unverified, somebody should look.`),
             ...adoption.forgotten.map(path => `Forgot ${path} — its directory is gone.`),
-            ...(pruned.removed.length === 0 ? [] : [`Removed ${pruned.removed.length} checkout(s) nobody has used for two days; their branches stay.`]),
+            ...(pruned.removed.length === 0 ? [] : [`Removed ${pruned.removed.length} finished task checkout(s), about ${bytesWords(pruned.freed)}; their branches stay.`]),
             ...(liveSwept.removed.length === 0 ? [] : [`Cleared ${liveSwept.removed.length} finished live view(s).`]),
             ...(retention === null || retained.length === 0 ? [] : [`Retention removed ${sweepWords(retention.counts, retention.freed)}.`]),
         ]);
@@ -7239,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`);
@@ -7719,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"),
@@ -7759,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;
@@ -8548,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)) {
@@ -9110,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";
@@ -11279,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) {
@@ -11323,6 +11461,97 @@ async function retentionCommand(positional, flags, context) {
     const periods = store.setRetentionPeriod(kind, days, acting.name, context.clock());
     return succeed(context.write, context.json, command, { periods }, () => [`${label(kind)}: kept ${days === null ? "forever" : `for ${periodWords(days)}`}.`]);
 }
+/** `storage`, `storage cleanup [<when>]`, `storage clean [--yes]`, `storage discard <path> --yes`: where the disk goes,
+ * and task checkouts: when a finished task's clean checkout is removed, cleaning up now, and throwing away one kept for
+ * its changes. Changing anything takes an instance operator. */
+async function storageCommand(positional, flags, context) {
+    const [action, ...rest] = positional;
+    const command = `storage ${action ?? ""}`.trim();
+    const store = context.store;
+    const changes = (action === "cleanup" && rest.length > 0) || (action === "clean" && flags.has("yes")) || action === "discard";
+    const allowed = new Set([...(changes ? ["as", "token", "token-file", "token-env"] : []), ...(action === "clean" || action === "discard" ? ["yes"] : []), "db", "json"]);
+    for (const name of flags.keys())
+        if (!allowed.has(name))
+            return fail(context.write, context.json, command, "usage", `--${name} is not a ${command} option.`, EXIT.usage);
+    const pool = new WorktreePool(store, { root: join(dirname(context.databaseFile), "worktrees"), ...(context.gitRunner === undefined ? {} : { runner: context.gitRunner }) });
+    const operator = async () => {
+        const acting = await askCredentials(flags, context);
+        const verified = acting === null ? null : authenticateApprover(store, acting.name, acting.token);
+        return acting !== null && verified !== null && verified.ok && store.isInstanceOperator(acting.name) ? acting.name : null;
+    };
+    const refused = (what) => fail(context.write, context.json, command, "refused", `An instance operator ${what}: pass --as and --token (or use the remembered login).`, EXIT.refused);
+    const summary = (plan) => [
+        `Checkouts: ${plan.count}, ${bytesWords(plan.totalBytes)}. ${plan.waitingReview} waiting for review, ${plan.withChanges} kept because they have changes.`,
+        plan.go.length === 0 ? "A clean up now would free nothing." : `A clean up now would free about ${bytesWords(plan.freeBytes)} (${plan.go.length} checkout${plan.go.length === 1 ? "" : "s"}): toolroll storage clean`,
+        `A finished task's clean checkout is removed ${cleanupWords(plan.cleanup)}; its branch stays.`,
+    ];
+    const itemLine = (one) => `  ${bytesWords(one.bytes).padStart(8)}  ${one.path}${one.why === null ? "" : `  (${whyWords(one)})`}`;
+    if (action === undefined) {
+        const plan = await checkoutPlan(store, pool, context.clock(), { manual: true });
+        const report = storageReport(store, context.databaseFile, plan.go.length === 0 ? "nothing to clean up" : `about ${bytesWords(plan.freeBytes)} to clean up`);
+        return succeed(context.write, context.json, "storage", { ...report, checkouts: checkoutSummary(plan) }, () => [
+            `${report.folder}: ${bytesWords(report.total)}`,
+            ...report.lines.map(one => `  ${one.what.padEnd(17)} ${bytesWords(one.bytes).padStart(8)}${one.count === undefined ? "" : `  (${one.count})`}${one.note === undefined ? "" : `  ${one.note}`}`),
+            ...summary(plan),
+        ]);
+    }
+    if (action === "cleanup") {
+        if (rest.length === 0) {
+            const cleanup = store.checkoutCleanup();
+            return succeed(context.write, context.json, command, { cleanup }, () => [`A finished task's clean checkout is removed ${cleanupWords(cleanup)}; its branch stays.`]);
+        }
+        const cleanup = rest.length === 1 ? parseCleanup(rest[0]) : undefined;
+        if (cleanup === undefined)
+            return fail(context.write, context.json, command, "usage", `Use storage cleanup <${CLEANUP_CHOICES.map(one => one.value).join("|")}>.`, EXIT.usage);
+        const actor = await operator();
+        if (actor === null)
+            return refused("sets checkout cleanup");
+        const saved = store.setCheckoutCleanup(cleanup, actor, context.clock());
+        return succeed(context.write, context.json, command, { cleanup: saved }, () => [`Saved. A finished task's clean checkout is removed ${cleanupWords(saved)}; its branch stays.`]);
+    }
+    if (action === "clean") {
+        if (rest.length > 0)
+            return fail(context.write, context.json, command, "usage", "Use storage clean to preview, then storage clean --yes.", EXIT.usage);
+        if (!flags.has("yes")) {
+            const plan = await checkoutPlan(store, pool, context.clock(), { manual: true });
+            return succeed(context.write, context.json, command, { preview: true, go: plan.go, stay: plan.stay, freeBytes: plan.freeBytes }, () => [
+                ...(plan.go.length === 0 ? ["Nothing to clean up."] : [`Would remove ${plan.go.length} checkout${plan.go.length === 1 ? "" : "s"}, freeing about ${bytesWords(plan.freeBytes)} (their branches stay):`, ...plan.go.map(itemLine)]),
+                ...(plan.stay.length === 0 ? [] : [`Stays (${plan.stay.length}):`, ...plan.stay.map(itemLine)]),
+                plan.go.length === 0 ? "Nothing was removed." : "Nothing was removed. Run toolroll storage clean --yes to remove them.",
+            ]);
+        }
+        const actor = await operator();
+        if (actor === null)
+            return refused("cleans up checkouts");
+        const done = await cleanCheckouts(store, pool, context.clock, { manual: true, actor });
+        return succeed(context.write, context.json, command, { removed: done.removed, kept: done.kept, freedBytes: done.freed }, () => [
+            done.removed.length === 0 ? "Nothing to clean up." : `Removed ${done.removed.length} checkout${done.removed.length === 1 ? "" : "s"}, about ${bytesWords(done.freed)}; their branches stay.`,
+            ...done.removed.map(itemLine),
+            ...done.kept.map(one => `  kept ${one.path} (${whyWords({ why: one.why })})`),
+        ]);
+    }
+    if (action === "discard") {
+        const [path, ...extra] = rest;
+        if (path === undefined || extra.length > 0)
+            return fail(context.write, context.json, command, "usage", "Use storage discard <path> --yes.", EXIT.usage);
+        const target = resolve(path);
+        if (store.getWorktree(target) === null)
+            return fail(context.write, context.json, command, "not-found", `${target} is not a task checkout. toolroll storage clean lists them.`, EXIT.refused);
+        if (!flags.has("yes"))
+            return fail(context.write, context.json, command, "usage", `This throws away ${target} and its uncommitted changes (its branch stays). Add --yes to discard it.`, EXIT.usage);
+        const actor = await operator();
+        if (actor === null)
+            return refused("discards a checkout");
+        const done = await discardCheckout(store, pool, target, context.clock(), actor);
+        if (!done.ok)
+            return fail(context.write, context.json, command, "refused", done.message, EXIT.refused);
+        return succeed(context.write, context.json, command, { discarded: target, freedBytes: done.bytes }, () => [`Discarded ${target}, about ${bytesWords(done.bytes)}; its branch stays.`]);
+    }
+    return fail(context.write, context.json, command, "usage", "Use storage, storage cleanup <when>, storage clean [--yes] or storage discard <path> --yes.", EXIT.usage);
+}
+function checkoutSummary(plan) {
+    return { count: plan.count, totalBytes: plan.totalBytes, waitingReview: plan.waitingReview, withChanges: plan.withChanges, cleanBytes: plan.freeBytes, cleanCount: plan.go.length, cleanup: plan.cleanup };
+}
 /** `policy show | set` (sprint 8): the organisation policy. Setting it takes an instance operator's credentials; each rule
  * that changed is in the ledger, before → after. A flag left out keeps its rule; "any" lifts it. */
 async function policyCommand(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/prompt.d.ts

@@ -7,12 +7,17 @@
  */
 /** Whether asking is even possible: a human on both ends of the pipe. */
 export declare function interactive(): boolean;
+/** The program names of this process's ancestors, nearest first: each one's command and, for a script run by node
+ * or python, the script's name. Empty where `ps` cannot say. */
+export declare function ancestorPrograms(): string[];
 /**
  * Whether a coding agent is running this command. An agent's shell can be a
  * real terminal, yet whatever is printed lands in its transcript and nobody
- * types at the prompt, so it is treated like no terminal at all.
+ * types at the prompt, so it is treated like no terminal at all. The agent is
+ * known by a variable it sets or, for one that sets none, by the program above
+ * this one. `programs` is read only for this process's own environment.
  */
-export declare function underAgent(env?: Record<string, string | undefined>): boolean;
+export declare function underAgent(env?: Record<string, string | undefined>, programs?: () => readonly string[]): boolean;
 export declare function ask(question: string): Promise<string>;
 /** Like ask, but what is typed never echoes — passwords live here. */
 /**

package/dist/prompt.js

@@ -5,22 +5,51 @@
  * gets the same immediate usage refusal as always, because a scheduler
  * hanging on "password:" at 3am is the one bug this module must not have.
  */
+import { spawnSync } from "node:child_process";
+import { basename } from "node:path";
 import { createInterface } from "node:readline";
 /** Whether asking is even possible: a human on both ends of the pipe. */
 export function interactive() {
     return process.stdin.isTTY === true && process.stdout.isTTY === true;
 }
-/** Variables a coding agent sets for the commands it runs. CODEX_HOME and CODEX_API_KEY are a person's own settings. */
-const AGENT_VARIABLES = ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "GEMINI_CLI", "CURSOR_AGENT", "OPENCODE"];
-const PERSON_CODEX_VARIABLES = new Set(["CODEX_HOME", "CODEX_API_KEY"]);
+/** Variables a coding agent sets for the commands it runs. Only Codex's own CODEX_ names: a person exports others
+ * (CODEX_HOME, CODEX_API_KEY, a profile) for themselves. */
+const AGENT_VARIABLES = ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "GEMINI_CLI", "CURSOR_AGENT", "OPENCODE", "GOOSE_TERMINAL", "AIDER_CHAT",
+    "CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CODEX_THREAD_ID", "CODEX_CI", "CODEX_MANAGED_BY_NPM", "CODEX_MANAGED_BY_BUN"];
+/** Agents known by the program running this command, for those that set no variable of their own. */
+const AGENT_PROGRAMS = new Set(["claude", "codex", "gemini", "cursor-agent", "opencode", "aider", "copilot", "amp", "goose", "crush", "qwen"]);
+/** The program names of this process's ancestors, nearest first: each one's command and, for a script run by node
+ * or python, the script's name. Empty where `ps` cannot say. */
+export function ancestorPrograms() {
+    if (process.platform === "win32")
+        return [];
+    const names = [];
+    let pid = process.ppid;
+    for (let depth = 0; depth < 12 && pid > 1; depth++) {
+        const answered = spawnSync("/bin/ps", ["-o", "ppid=,args=", "-p", String(pid)], { encoding: "utf8", timeout: 2000 });
+        const found = answered.status === 0 ? /^\s*(\d+)\s+(.*)$/.exec(answered.stdout.trim()) : null;
+        if (!found)
+            break;
+        const words = found[2].split(/\s+/);
+        const program = basename(words[0] ?? "");
+        names.push(program);
+        if (/^(node|bun|deno|python[\d.]*)$/.test(program) && words[1] !== undefined && !words[1].startsWith("-"))
+            names.push(basename(words[1]));
+        pid = Number(found[1]);
+    }
+    return names;
+}
 /**
  * Whether a coding agent is running this command. An agent's shell can be a
  * real terminal, yet whatever is printed lands in its transcript and nobody
- * types at the prompt, so it is treated like no terminal at all.
+ * types at the prompt, so it is treated like no terminal at all. The agent is
+ * known by a variable it sets or, for one that sets none, by the program above
+ * this one. `programs` is read only for this process's own environment.
  */
-export function underAgent(env = process.env) {
-    return Object.entries(env).some(([name, value]) => value !== undefined && value !== ""
-        && (AGENT_VARIABLES.includes(name) || (name.startsWith("CODEX_") && !PERSON_CODEX_VARIABLES.has(name))));
+export function underAgent(env = process.env, programs = env === process.env ? ancestorPrograms : () => []) {
+    if (AGENT_VARIABLES.some(name => env[name] !== undefined && env[name] !== ""))
+        return true;
+    return programs().some(name => AGENT_PROGRAMS.has(name.replace(/\.(?:js|mjs|cjs|py|exe)$/, "")));
 }
 export function ask(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });

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.