@plainconceptsplatform/workflows 0.6.1 → 0.16.2

package/loops/actions/audit-close/action.yml

@@ -1,128 +1,180 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/actions/audit-close/action.yml. Update with workflows update --force; consumer edits may be overwritten.
-name: Close audit reports
-description: Close open audit reports once every issue they reference is closed.
-inputs:
-  token:
-    description: GitHub token with issues write access.
-    required: true
-runs:
-  using: composite
-  steps:
-    - name: Close every report whose referenced issues are all closed
-      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-      with:
-        github-token: ${{ inputs.token }}
-        script: |
-          const reports = await github.paginate(github.rest.issues.listForRepo, {
-            ...context.repo,
-            state: 'open',
-            labels: 'audit',
-            per_page: 100,
-          });
-
-          if (reports.length === 0) {
-            core.info('No open audit reports.');
-            return;
-          }
-
-          // Skip `owner/repo#12` and `abc#12`: only a bare `#12` references this repository.
-          const referencedIssues = (body) => {
-            const matches = (body ?? '').matchAll(/(?:^|[^A-Za-z0-9_/])#(\d+)/g);
-            return [...new Set([...matches].map((match) => Number(match[1])))];
-          };
-
-          let closed = 0;
-          let keptOpen = 0;
-
-          for (const report of reports.sort((a, b) => a.number - b.number)) {
-            const refs = referencedIssues(report.body).filter((n) => n !== report.number);
-
-            const stillOpen = [];
-            const unknown = [];
-            let closedRefs = 0;
-            let resolved = 0;
-
-            for (const ref of refs) {
-              let state;
-
-              try {
-                ({ data: { state } } = await github.rest.issues.get({
-                  ...context.repo,
-                  issue_number: ref,
-                }));
-              } catch (error) {
-                if (error.status === 404) {
-                  core.info(`#${report.number}: ignoring #${ref}, not an issue in this repository`);
-                  continue;
-                }
-                unknown.push(ref);
-                resolved += 1;
-                continue;
-              }
-
-              resolved += 1;
-              if (state === 'closed') closedRefs += 1;
-              else stillOpen.push(ref);
-            }
-
-            if (stillOpen.length > 0) {
-              core.info(`#${report.number}: kept open, still-open references: ${stillOpen.join(', ')}`);
-              keptOpen += 1;
-              continue;
-            }
-
-            if (unknown.length > 0) {
-              core.info(`#${report.number}: kept open, undetermined references: ${unknown.join(', ')}`);
-              keptOpen += 1;
-              continue;
-            }
-
-            const reason = resolved === 0
-              ? 'This report references no issues.'
-              : `All ${closedRefs} referenced issue(s) are closed.`;
-
-            // Do not close if there are open PRs that close this issue.
-            // The audit report may have spawned implement workers whose PRs
-            // are still under review — closing the report prematurely is misleading.
-            const openPRs = await github.paginate(github.rest.pulls.list, {
-              ...context.repo,
-              state: 'open',
-              per_page: 100,
-            });
-
-            const closesThisReport = openPRs.some((pr) => {
-              const body = pr.body ?? '';
-              const patterns = [
-                new RegExp(`(?:^|[^A-Za-z0-9_/])#(?:closes?|fixes?|resolves?|closed?)\\s+#${report.number}\\b`, 'i'),
-                new RegExp(`(?:^|[^A-Za-z0-9_/])#${report.number}\\b`),
-              ];
-              return patterns.some((p) => p.test(body));
-            });
-
-            if (closesThisReport) {
-              core.info(`#${report.number}: kept open, has open PR(s) that close it.`);
-              keptOpen += 1;
-              continue;
-            }
-
-            await github.rest.issues.createComment({
-              ...context.repo,
-              issue_number: report.number,
-              body: `Closed automatically by \`Work Router: audit-close\`. ${reason}`,
-            });
-
-            await github.rest.issues.update({
-              ...context.repo,
-              issue_number: report.number,
-              state: 'closed',
-              state_reason: 'completed',
-            });
-
-            core.info(`#${report.number}: closed. ${reason}`);
-            closed += 1;
-          }
-
-          await core.summary
-            .addHeading('Audit close', 2)
-            .addList([`Reports closed: ${closed}`, `Reports left open: ${keptOpen}`])
-            .write();
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/audit-close/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Close audit reports
+description: Close open audit reports once every issue they reference is closed.
+inputs:
+  token:
+    description: GitHub token with issues write access.
+    required: true
+  stale-after-days:
+    description: >-
+      How long a report may sit open before it is marked stale-audit. A stale report stops
+      counting against the audit's backpressure and is listed for a person instead.
+    required: false
+    default: '14'
+runs:
+  using: composite
+  steps:
+    - name: Close every report whose referenced issues are all closed
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        STALE_AFTER_DAYS: ${{ inputs.stale-after-days }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const reports = await github.paginate(github.rest.issues.listForRepo, {
+            ...context.repo,
+            state: 'open',
+            labels: 'audit',
+            per_page: 100,
+          });
+
+          if (reports.length === 0) {
+            core.info('No open audit reports.');
+            return;
+          }
+
+          const STALE_LABEL = 'stale-audit';
+          const staleAfterMs = Number(process.env.STALE_AFTER_DAYS) * 86400 * 1000;
+
+          // One list for every report. This used to be fetched inside the loop, so a repository
+          // with three open reports paid for three full pull-request listings each night.
+          const openPRs = await github.paginate(github.rest.pulls.list, {
+            ...context.repo,
+            state: 'open',
+            per_page: 100,
+          });
+
+          // Skip `owner/repo#12` and `abc#12`: only a bare `#12` references this repository.
+          const referencedIssues = (body) => {
+            const matches = (body ?? '').matchAll(/(?:^|[^A-Za-z0-9_/])#(\d+)/g);
+            return [...new Set([...matches].map((match) => Number(match[1])))];
+          };
+
+          // Only a real closing keyword counts. There were two patterns here and both were
+          // wrong in opposite directions: the first required the literal text `#closes #12`,
+          // which nothing has ever written, so it matched nothing; the second matched a bare
+          // `#12` anywhere in any open pull request body, so one passing mention of the report
+          // pinned it open for as long as that pull request stayed open. A report referenced
+          // by a merged-and-closed chain then never closed, and the three of them silently
+          // used up the audit backpressure.
+          const closesReport = (number) => {
+            const pattern = new RegExp(`(?:clos(?:e|es|ed)|fix(?:es|ed)?|resolves?)\\s+#${number}\\b`, 'i');
+            return openPRs.some((pr) => pattern.test(pr.body ?? ''));
+          };
+
+          let closed = 0;
+          let keptOpen = 0;
+          let stale = 0;
+
+          const markStale = async (report, why) => {
+            if (report.labels.some((l) => (typeof l === 'string' ? l : l.name) === STALE_LABEL)) return;
+            if (Date.now() - new Date(report.created_at).getTime() < staleAfterMs) return;
+            // Creating the label is idempotent; 422 means it already exists.
+            await github.rest.issues.createLabel({
+              ...context.repo,
+              name: STALE_LABEL,
+              color: 'd4c5f9',
+              description: 'Audit report nobody actioned; no longer blocks the next audit',
+            }).catch((error) => { if (error.status !== 422) throw error; });
+            await github.rest.issues.addLabels({
+              ...context.repo, issue_number: report.number, labels: [STALE_LABEL],
+            });
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: report.number,
+              body: `Labelled \`${STALE_LABEL}\` after ${process.env.STALE_AFTER_DAYS} days: ${why} This report no longer counts against the audit backpressure, so the next audit can run, and it is listed in the housekeeping digest for a person to pick up or close.`,
+            });
+            core.info(`#${report.number}: marked ${STALE_LABEL}. ${why}`);
+            stale += 1;
+          };
+
+          for (const report of reports.sort((a, b) => a.number - b.number)) {
+            const refs = referencedIssues(report.body).filter((n) => n !== report.number);
+
+            const stillOpen = [];
+            const unknown = [];
+            let closedRefs = 0;
+            let resolved = 0;
+
+            for (const ref of refs) {
+              let state;
+
+              try {
+                ({ data: { state } } = await github.rest.issues.get({
+                  ...context.repo,
+                  issue_number: ref,
+                }));
+              } catch (error) {
+                if (error.status === 404) {
+                  core.info(`#${report.number}: ignoring #${ref}, not an issue in this repository`);
+                  continue;
+                }
+                unknown.push(ref);
+                resolved += 1;
+                continue;
+              }
+
+              resolved += 1;
+              if (state === 'closed') closedRefs += 1;
+              else stillOpen.push(ref);
+            }
+
+            // A report referencing nothing is a report nothing was done about. Refine turns a
+            // report into children and writes their numbers into it; a body with no bare `#N`
+            // means refine never ran, or ran and produced nothing. Closing that as `completed`
+            // used to throw the finding away silently and was the single most common way an
+            // audit ended: every finding closed, nothing implemented. Leave it open, and once
+            // it is past its budget mark it stale so it stops blocking the next audit.
+            if (resolved === 0) {
+              core.info(`#${report.number}: kept open, references no issues, so no work was done on it`);
+              keptOpen += 1;
+              await markStale(report, 'it references no issues, so nothing was ever implemented from it.');
+              continue;
+            }
+
+            if (stillOpen.length > 0) {
+              core.info(`#${report.number}: kept open, still-open references: ${stillOpen.join(', ')}`);
+              keptOpen += 1;
+              await markStale(report, `its children are still open (${stillOpen.map((n) => `#${n}`).join(', ')}).`);
+              continue;
+            }
+
+            if (unknown.length > 0) {
+              core.info(`#${report.number}: kept open, undetermined references: ${unknown.join(', ')}`);
+              keptOpen += 1;
+              continue;
+            }
+
+            // The report may have spawned implement workers whose pull requests are still under
+            // review; closing it while they are open would be misleading.
+            if (closesReport(report.number)) {
+              core.info(`#${report.number}: kept open, an open pull request closes it`);
+              keptOpen += 1;
+              continue;
+            }
+
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: report.number,
+              body: `Closed automatically by \`Work Router: audit-close\`. All ${closedRefs} referenced issue(s) are closed.`,
+            });
+
+            await github.rest.issues.update({
+              ...context.repo,
+              issue_number: report.number,
+              state: 'closed',
+              state_reason: 'completed',
+            });
+
+            core.info(`#${report.number}: closed. All ${closedRefs} referenced issue(s) are closed.`);
+            closed += 1;
+          }
+
+          await core.summary
+            .addHeading('Audit close', 2)
+            .addList([
+              `Reports closed: ${closed}`,
+              `Reports left open: ${keptOpen}`,
+              `Reports marked stale: ${stale}`,
+            ])
+            .write();

package/loops/actions/classify-route/classify-route.sh

@@ -8,10 +8,15 @@
 
 set -euo pipefail
 
-readonly AUDIT_CRON="17 1 * * 1"
+# The audit slot is per repository, so it comes from the router's own env: block rather than
+# from here. The fallback is the package default and matches the cron the router ships; a run
+# fired on a cron this file does not know classifies to no route and dies silently, so the
+# route matrix asserts the two still agree.
+readonly AUDIT_CRON="${AUDIT_CRON:-17 1 * * 1}"
 readonly AUDIT_CLOSE_CRON="43 3 * * *"
 readonly CLEANUP_ARTIFACTS_CRON="0 6 * * *"
 readonly RECONCILE_BOT_PR_RUNS_CRON="17 * * * *"
+readonly HOUSEKEEPING_CRON="23 */6 * * *"
 
 has_label() {
   jq -e --arg name "$1" 'index($name)' >/dev/null 2>&1 <<<"${ISSUE_LABELS:-[]}"
@@ -173,6 +178,7 @@ classify_route() {
         "$AUDIT_CLOSE_CRON") route="audit-close" ;;
         "$CLEANUP_ARTIFACTS_CRON") route="cleanup-artifacts" ;;
         "$RECONCILE_BOT_PR_RUNS_CRON") route="reconcile-bot-pr-runs" ;;
+        "$HOUSEKEEPING_CRON") route="housekeeping" ;;
         *) error="no route for cron '${SCHEDULE:-}'" ;;
       esac
       ;;
@@ -227,7 +233,7 @@ classify_route() {
           route="${OPERATION}"
           trigger_kind="${INPUT_TRIGGER_KIND:-manual}"
           ;;
-        audit-close | cleanup-artifacts | reconcile-bot-pr-runs | validate)
+        audit-close | cleanup-artifacts | reconcile-bot-pr-runs | housekeeping | validate)
           route="${OPERATION}"
           ;;
         release)

package/loops/actions/housekeeping/action.yml

@@ -0,0 +1,251 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/housekeeping/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Housekeeping
+description: >-
+  Retry work the machine stalled on, tidy the state it strands behind, and report what genuinely
+  still needs a person. Deterministic: no model runs here.
+
+inputs:
+  token:
+    description: Token with issues, pull-requests and contents write access.
+    required: true
+  retry-after-hours:
+    description: How long an issue may sit stalled before it is retried.
+    required: false
+    default: '6'
+  max-retries:
+    description: How many times the janitor retries one issue before leaving it to a person.
+    required: false
+    default: '3'
+  stale-pr-days:
+    description: A bot pull request older than this with no CI verdict is reported, never closed.
+    required: false
+    default: '3'
+  digest-title:
+    description: Title of the single issue that reports what needs a human. Empty disables it.
+    required: false
+    default: 'Needs a human'
+  dry-run:
+    description: Compute everything and write nothing. Every intended change is printed.
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    - name: Sweep
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        RETRY_AFTER_HOURS: ${{ inputs.retry-after-hours }}
+        MAX_RETRIES: ${{ inputs.max-retries }}
+        STALE_PR_DAYS: ${{ inputs.stale-pr-days }}
+        DIGEST_TITLE: ${{ inputs.digest-title }}
+        DRY_RUN: ${{ inputs.dry-run }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const dryRun = process.env.DRY_RUN === 'true';
+          const retryAfterMs = Number(process.env.RETRY_AFTER_HOURS) * 3600 * 1000;
+          const maxRetries = Number(process.env.MAX_RETRIES);
+          const stalePrMs = Number(process.env.STALE_PR_DAYS) * 86400 * 1000;
+          const digestTitle = process.env.DIGEST_TITLE;
+
+          // Every write goes through this, so --dry-run is honest rather than hopeful: there is
+          // no second path that forgets to check it.
+          const planned = [];
+          const act = async (what, run) => {
+            planned.push(what);
+            if (dryRun) { core.info(`[dry-run] ${what}`); return; }
+            core.info(what);
+            await run();
+          };
+
+          const RETRY_MARKER = '<!-- housekeeping-retry -->';
+          const DIGEST_MARKER = '<!-- housekeeping-digest -->';
+          const WORK_LABELS = ['implement', 'refine', 'triage'];
+          const isBot = (login) => login.endsWith('[bot]') || login.startsWith('app/');
+          const age = (iso) => Date.now() - new Date(iso).getTime();
+          const days = (ms) => Math.floor(ms / 86400000);
+
+          const issues = await github.paginate(github.rest.issues.listForRepo, {
+            ...context.repo, state: 'open', per_page: 100,
+          });
+          const pulls = await github.paginate(github.rest.pulls.list, {
+            ...context.repo, state: 'open', per_page: 100,
+          });
+          const names = (issue) => issue.labels.map((l) => (typeof l === 'string' ? l : l.name));
+
+          const needsHuman = [];
+          let retried = 0;
+
+          // 1. Retry what the machine stalled on. `stalled` marks a park caused by a crash, a
+          // timeout or an empty output; `review` alone is a decision the agent made, and
+          // re-running a decision only reproduces it, so those are reported and never retried.
+          for (const issue of issues) {
+            if (issue.pull_request) continue;
+            const labels = names(issue);
+            if (!labels.includes('review')) continue;
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              ...context.repo, issue_number: issue.number, per_page: 100,
+            });
+            const attempts = comments.filter((c) => (c.body ?? '').includes(RETRY_MARKER)).length;
+            const work = WORK_LABELS.find((l) => labels.includes(l));
+            const waited = age(issue.updated_at);
+
+            if (!labels.includes('stalled')) {
+              needsHuman.push({ kind: 'decided', issue, labels, waited });
+              continue;
+            }
+            if (waited < retryAfterMs) continue;
+            if (attempts >= maxRetries || !work) {
+              needsHuman.push({ kind: attempts >= maxRetries ? 'retries-exhausted' : 'no-work-label', issue, labels, waited, attempts });
+              continue;
+            }
+
+            await act(`#${issue.number}: retrying ${work} (attempt ${attempts + 1} of ${maxRetries}, stalled ${Math.floor(waited / 3600000)}h)`, async () => {
+              await github.rest.issues.createComment({
+                ...context.repo, issue_number: issue.number,
+                body: `${RETRY_MARKER}\nThis issue stalled rather than reaching a decision, so it is being retried automatically: attempt ${attempts + 1} of ${maxRetries}. If it stalls ${maxRetries} times it stays parked for a person.`,
+              });
+              // Removing the labels is what lets it route again; the work label is already there.
+              for (const label of ['review', 'stalled']) {
+                await github.rest.issues.removeLabel({ ...context.repo, issue_number: issue.number, name: label })
+                  .catch((error) => { if (error.status !== 404) throw error; });
+              }
+              await github.rest.actions.createWorkflowDispatch({
+                ...context.repo, workflow_id: 'work-router.yml',
+                ref: context.payload.repository.default_branch,
+                inputs: { operation: work, 'issue-number': String(issue.number) },
+              });
+            });
+            retried += 1;
+          }
+
+          // 2. Strands. pr-pending says a pull request is open and waiting; when that pull request
+          // closed without merging, nothing ever took the label off.
+          for (const issue of issues) {
+            if (issue.pull_request || !names(issue).includes('pr-pending')) continue;
+            const linked = pulls.some((p) => new RegExp(`(clos(e|es|ed)|fix(es|ed)?|resolves?)\\s+#${issue.number}\\b`, 'i').test(p.body ?? ''));
+            if (linked) continue;
+            await act(`#${issue.number}: removing pr-pending, no open pull request closes it`, () =>
+              github.rest.issues.removeLabel({ ...context.repo, issue_number: issue.number, name: 'pr-pending' })
+                .catch((error) => { if (error.status !== 404) throw error; }));
+          }
+
+          // 3. Split parents. Refine leaves the parent open as a tracker and nothing has ever
+          // closed one: once every child is done the parent sits there for ever with an unticked
+          // checklist. Children carry `<!-- split-parent: N -->`, which is the only machine-
+          // readable link between them.
+          const childrenOf = new Map();
+          for (const issue of await github.paginate(github.rest.issues.listForRepo, { ...context.repo, state: 'all', per_page: 100 })) {
+            const match = /<!-- split-parent: (\d+) -->/.exec(issue.body ?? '');
+            if (!match || issue.pull_request) continue;
+            const parent = Number(match[1]);
+            if (!childrenOf.has(parent)) childrenOf.set(parent, []);
+            childrenOf.get(parent).push(issue);
+          }
+          for (const [parent, children] of childrenOf) {
+            const open = children.filter((c) => c.state === 'open');
+            if (open.length > 0 || !issues.some((i) => i.number === parent)) continue;
+            await act(`#${parent}: closing split parent, all ${children.length} children are done`, async () => {
+              await github.rest.issues.createComment({
+                ...context.repo, issue_number: parent,
+                body: `${DIGEST_MARKER}\nClosed automatically: every child of this split is closed (${children.map((c) => `#${c.number}`).join(', ')}).`,
+              });
+              await github.rest.issues.update({ ...context.repo, issue_number: parent, state: 'closed', state_reason: 'completed' });
+            });
+          }
+
+          // 4. Branches. Nothing in the fleet has ever deleted one, so they accumulate for ever
+          // after a merge and after a close alike. Only ever touch a branch whose pull request is
+          // finished; never the default branch, and never one with a pull request still open.
+          //
+          // Deleting the branch of a pull request that closed WITHOUT merging does not throw the
+          // work away: GitHub keeps `refs/pull/<n>/head` for the life of the pull request, which
+          // is what its own "Restore branch" button restores from. Verified on this fleet --
+          // after the first sweep removed six branches, every one of their pull requests still
+          // resolved through that ref. So `git fetch origin pull/<n>/head` brings any of this
+          // back, and the pull request page still shows the diff.
+          const branches = await github.paginate(github.rest.repos.listBranches, { ...context.repo, per_page: 100 });
+          const defaultBranch = context.payload.repository.default_branch;
+          const allPulls = await github.paginate(github.rest.pulls.list, { ...context.repo, state: 'all', per_page: 100 });
+          const byHead = new Map();
+          for (const pull of allPulls) {
+            if (!byHead.has(pull.head.ref)) byHead.set(pull.head.ref, []);
+            byHead.get(pull.head.ref).push(pull);
+          }
+          for (const branch of branches) {
+            if (branch.name === defaultBranch) continue;
+            const forBranch = byHead.get(branch.name) ?? [];
+            if (forBranch.length === 0) continue;                       // never opened a PR: not ours to judge
+            if (forBranch.some((p) => p.state === 'open')) continue;    // still in use
+            if (!forBranch.every((p) => isBot(p.user?.login ?? ''))) continue;
+            const merged = forBranch.some((p) => p.merged_at);
+            await act(`branch ${branch.name}: deleting (${merged ? 'merged' : 'closed unmerged'})`, () =>
+              github.rest.git.deleteRef({ ...context.repo, ref: `heads/${branch.name}` })
+                .catch((error) => { if (error.status !== 404 && error.status !== 422) throw error; }));
+          }
+
+          // 5. Pull requests that need a person: parked by a gate verdict, or old with no CI.
+          for (const pull of pulls) {
+            if (!isBot(pull.user?.login ?? '')) continue;
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              ...context.repo, issue_number: pull.number, per_page: 100,
+            });
+            const verdict = [...comments].reverse().find((c) => (c.body ?? '').includes('<!-- agent-merge-gate -->') && (c.body ?? '').includes('**Verdict:**'));
+            const parsed = verdict ? /\*\*Verdict:\*\*\s*(\w+)/.exec(verdict.body)?.[1] : undefined;
+            if (parsed && parsed !== 'merge') {
+              needsHuman.push({ kind: 'pr-parked', pull, verdict: parsed, waited: age(verdict.created_at) });
+            } else if (!verdict && age(pull.created_at) > stalePrMs) {
+              needsHuman.push({ kind: 'pr-stale', pull, waited: age(pull.created_at) });
+            }
+          }
+
+          // 6. One digest. Everything above either fixed itself or is listed here, so there is a
+          // single place to look instead of four repositories and three label queries.
+          const line = (entry) => {
+            if (entry.kind === 'pr-parked') return `- PR #${entry.pull.number} · parked ${days(entry.waited)}d · gate verdict \`${entry.verdict}\` · ${entry.pull.title}`;
+            if (entry.kind === 'pr-stale') return `- PR #${entry.pull.number} · ${days(entry.waited)}d old · no gate verdict yet · ${entry.pull.title}`;
+            if (entry.kind === 'retries-exhausted') return `- #${entry.issue.number} · stalled ${days(entry.waited)}d · retried ${entry.attempts}× and still stalling · ${entry.issue.title}`;
+            if (entry.kind === 'no-work-label') return `- #${entry.issue.number} · stalled ${days(entry.waited)}d · no work label to retry with · ${entry.issue.title}`;
+            return `- #${entry.issue.number} · waiting ${days(entry.waited)}d · ${entry.labels.filter((l) => l !== 'review').join(', ') || 'no other labels'} · ${entry.issue.title}`;
+          };
+          const section = (heading, kinds) => {
+            const rows = needsHuman.filter((e) => kinds.includes(e.kind));
+            return rows.length === 0 ? '' : `\n### ${heading} (${rows.length})\n\n${rows.map(line).join('\n')}\n`;
+          };
+          const body = [
+            DIGEST_MARKER,
+            `_Updated ${new Date().toISOString().slice(0, 16).replace('T', ' ')} UTC. This issue is rewritten by the housekeeping job; edits to it are lost._`,
+            section('Waiting on a decision', ['decided']),
+            section('Pull requests parked by the gate', ['pr-parked', 'pr-stale']),
+            section('Stalled beyond the retry budget', ['retries-exhausted', 'no-work-label']),
+            needsHuman.length === 0 ? '\nNothing is waiting on a person right now.\n' : '',
+            `\n---\n\nThis run retried ${retried} stalled issue(s) and made ${planned.length} change(s) in total.`,
+          ].filter(Boolean).join('\n');
+
+          if (digestTitle) {
+            const existing = issues.find((i) => !i.pull_request && i.title === digestTitle && (i.body ?? '').includes(DIGEST_MARKER));
+            if (existing) {
+              if (needsHuman.length === 0) {
+                await act(`closing the digest #${existing.number}: nothing is waiting`, () =>
+                  github.rest.issues.update({ ...context.repo, issue_number: existing.number, body, state: 'closed', state_reason: 'completed' }));
+              } else {
+                await act(`updating the digest #${existing.number}: ${needsHuman.length} item(s)`, () =>
+                  github.rest.issues.update({ ...context.repo, issue_number: existing.number, body }));
+              }
+            } else if (needsHuman.length > 0) {
+              await act(`opening the digest: ${needsHuman.length} item(s)`, () =>
+                github.rest.issues.create({ ...context.repo, title: digestTitle, body }));
+            }
+          }
+
+          await core.summary
+            .addHeading('Housekeeping', 2)
+            .addList([
+              `Retried: ${retried}`,
+              `Waiting on a person: ${needsHuman.length}`,
+              `Changes ${dryRun ? 'planned' : 'made'}: ${planned.length}`,
+            ])
+            .addRaw(planned.length ? `\n\n${planned.map((p) => `- ${p}`).join('\n')}` : '')
+            .write();

package/loops/actions/merge-agent-pr/action.yml

@@ -32,5 +32,18 @@ runs:
           HEAD_SHA=$(gh pr view "$PR_NUM" --repo "$REPO" --json headRefOid --jq '.headRefOid')
           [[ "$HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]] || { echo "::error::Invalid pull request head SHA for #$PR_NUM"; exit 1; }
 
+          HEAD_REF=$(gh pr view "$PR_NUM" --repo "$REPO" --json headRefName --jq '.headRefName')
+
           gh pr merge "$PR_NUM" --repo "$REPO" --squash --match-head-commit "$HEAD_SHA"
+
+          # Delete the branch, because nothing else ever has: four repositories had accumulated
+          # 47 non-main branches, every one the head of a pull request merged or closed months
+          # ago. Done after the merge and with its failure swallowed rather than through
+          # `gh pr merge --delete-branch`, which also tries to delete the local branch and can
+          # turn a completed merge into a red step. `delete_branch_on_merge` on the repository
+          # does the same job, but only where someone remembered to switch it on.
+          if [ -n "$HEAD_REF" ] && [ "$HEAD_REF" != "null" ]; then
+            gh api -X DELETE "repos/$REPO/git/refs/heads/$HEAD_REF" >/dev/null 2>&1 ||
+              echo "::notice::branch $HEAD_REF was already gone or is protected"
+          fi
         done