mandrel 2.43.0 → 2.45.0

package/.agents/scripts/lib/ITicketingProvider.js

@@ -180,6 +180,33 @@ export class ITicketingProvider {
     throw new Error('Not implemented: ensureLabels');
   }
 
+  /**
+   * List the repository's whole label vocabulary.
+   *
+   * Implementations MUST paginate rather than take a fixed page cap: a cap is
+   * silent truncation, and a caller deciding what to delete from a truncated
+   * view is the exact failure Story #5189 exists to stop reproducing.
+   *
+   * @returns {Promise<Array<{ name: string, color: string|null, description: string|null }>>}
+   */
+  async listLabels() {
+    throw new Error('Not implemented: listLabels');
+  }
+
+  /**
+   * Delete one label by name.
+   *
+   * A label that is already gone MUST resolve as a successful no-op
+   * (`{ deleted: false, reason: 'not-found' }`) rather than throwing, so a
+   * re-run of any sweep built on this port is idempotent.
+   *
+   * @param {string} _name
+   * @returns {Promise<{ deleted: boolean, reason: string|null }>}
+   */
+  async deleteLabel(_name) {
+    throw new Error('Not implemented: deleteLabel');
+  }
+
   /**
    * Idempotent custom field creation on the Project board.
    * Only applicable when `projectNumber` is configured.

package/.agents/scripts/lib/observability/source-classifier.js

@@ -131,6 +131,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'pr-watch-with-update.js',
   'provision-git-hooks.js',
   'prune-baseline-orphans.js',
+  'prune-plan-run-labels.js',
   'quality-preview.js',
   'quality-watch.js',
   'resolve-doc-tiers.js',

package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches-detect.js

@@ -0,0 +1,187 @@
+/**
+ * branches-detect.js — the branch-reap phase's detection signals beyond
+ * the PR probe, and the whole remote-only walk (Stories #4395, #5188).
+ *
+ * Split out of `branches.js` for the same reason `branches-reap.js` was:
+ * each phase file stays small enough to read in one pass. `branches.js`
+ * keeps the two walks' orchestration (`planCleanup`) and the reap
+ * (`executeCleanup`); this module owns what a branch with no reapable PR
+ * verdict is measured against.
+ *
+ * @module lib/orchestration/git-cleanup/phases/branches-detect
+ */
+
+import { classifyLatestPr } from './git-probes.js';
+
+/** Fields a planner verdict forwards onto its `skipped[]` entry. */
+const SKIP_DETAIL_FIELDS = ['prNumber', 'tipSha', 'mergedSha', 'detail'];
+
+export function skipEntryFromVerdict(branch, verdict) {
+  const entry = { branch, reason: verdict.reason };
+  for (const field of SKIP_DETAIL_FIELDS) {
+    if (verdict[field] != null) entry[field] = verdict[field];
+  }
+  return entry;
+}
+
+/**
+ * Story #4395 — the third detection signal, shared by the local and
+ * remote-only walks (Story #5188). Reached only when the branch has no
+ * reapable PR verdict and is not an ancestor of `<base>` (or
+ * `origin/<base>`). Probes content-equivalence via `git merge-tree
+ * --write-tree` and, when the probe is conclusive and the merge is a
+ * no-op, classifies the branch as `content-merged` instead of falling
+ * through to the `not-merged` skip.
+ *
+ * `rev` is the revision handed to git, `branch` the short name every
+ * output reports. They differ on the remote-only path, where names are
+ * enumerated with the `<remote>/` prefix stripped: handing `git
+ * merge-tree` the bare short name resolves to no ref, so the probe would
+ * report `{ supported: false }` for every candidate and degrade the whole
+ * signal to silence. Defaulting `rev` to `branch` keeps the local walk
+ * unchanged.
+ */
+export function evaluateContentEquivalence({
+  branch,
+  rev = branch,
+  baseBranch,
+  cwd,
+  contentEquivalentFn,
+  branchLastCommitFn,
+  lastCommitOpts,
+  skipExtra,
+}) {
+  const verdict = contentEquivalentFn({ cwd, base: baseBranch, branch: rev });
+  if (verdict?.supported && verdict.equivalent) {
+    return { detectedBy: 'content-merged' };
+  }
+  return {
+    skip: {
+      branch,
+      reason: 'not-merged',
+      lastCommitAt: branchLastCommitFn(cwd, branch, lastCommitOpts),
+      ...skipExtra,
+    },
+  };
+}
+
+/**
+ * Story #5188 — the remote-only walk's no-PR cascade, the mirror of the
+ * local walk's: ancestry against the base first, then content-equivalence,
+ * else a `not-merged` skip. Reaching this at all is the fix — the walk
+ * used to return early on a `no-pr` verdict, recording the branch in
+ * neither `candidates[]` nor `skipped[]`, so a provably-merged orphan ref
+ * was absent from the rendered log and the `--json` envelope alike.
+ *
+ * `mergedRemote` is the `-r` ancestry set ({@link listRemoteMergedBranches}):
+ * the local `git branch --merged` listing that feeds the local cascade
+ * enumerates local heads only and can never contain a remote branch name.
+ * Both signals read the local object database, so the sweep stays offline.
+ *
+ * A hit carries a `detectedBy` distinct from the PR-detected
+ * `'remote-only'` — `'remote-git-merged'` for ancestry, and the existing
+ * `'content-merged'` for the weaker content signal, so every consumer that
+ * already treats that value as report-only keeps doing so here.
+ */
+function evaluateRemoteOnlyNoPr({
+  branch,
+  rev,
+  baseBranch,
+  cwd,
+  mergedRemote,
+  contentEquivalentFn,
+  branchLastCommitFn,
+  remoteName,
+}) {
+  if (mergedRemote.has(branch)) return { detectedBy: 'remote-git-merged' };
+  return evaluateContentEquivalence({
+    branch,
+    rev,
+    baseBranch,
+    cwd,
+    contentEquivalentFn,
+    branchLastCommitFn,
+    lastCommitOpts: { localExists: false, remoteName },
+    skipExtra: { localExists: false },
+  });
+}
+
+/**
+ * Story #5188 — resolve one remote-only branch's PR verdict into either a
+ * detection provenance or a skip. Split out of the walk so the loop reads
+ * as enumerate → resolve → record and every arm of the cascade is visibly
+ * total: each branch that passes the protected and filter checks leaves
+ * this function as exactly one of `{ detectedBy, prInfo }` or `{ skip }`.
+ */
+function resolveRemoteOnlyBranch({ verdict, branch, rev, noPrArgs }) {
+  if (verdict.kind === 'skip') {
+    return { skip: skipEntryFromVerdict(branch, verdict) };
+  }
+  if (verdict.kind === 'candidate') {
+    return { detectedBy: 'remote-only', prInfo: verdict.prInfo };
+  }
+  const out = evaluateRemoteOnlyNoPr({ ...noPrArgs, branch, rev });
+  return out.skip ? out : { detectedBy: out.detectedBy, prInfo: null };
+}
+
+export function collectRemoteOnlyCandidates({
+  remoteLister,
+  remoteName,
+  cwd,
+  baseBranch,
+  localSet,
+  classify,
+  filter,
+  prProbe,
+  branchTipShaFn,
+  ancestryFn,
+  mergedRemote,
+  contentEquivalentFn,
+  branchLastCommitFn,
+  skipped,
+}) {
+  const noPrArgs = {
+    baseBranch,
+    cwd,
+    mergedRemote,
+    contentEquivalentFn,
+    branchLastCommitFn,
+    remoteName,
+  };
+  const out = [];
+  for (const branch of remoteLister(cwd, remoteName)) {
+    if (localSet.has(branch)) continue;
+    if (classify(branch)) continue;
+    if (!filter(branch)) continue;
+    const verdict = classifyLatestPr({
+      prInfo: prProbe(branch, cwd),
+      branch,
+      cwd,
+      remoteName,
+      localExists: false,
+      branchTipShaFn,
+      ancestryFn,
+    });
+    const resolved = resolveRemoteOnlyBranch({
+      verdict,
+      branch,
+      rev: `${remoteName}/${branch}`,
+      noPrArgs,
+    });
+    if (resolved.skip) {
+      skipped.push(resolved.skip);
+      continue;
+    }
+    out.push({
+      branch,
+      prNumber: resolved.prInfo?.number ?? null,
+      mergedAt: resolved.prInfo?.mergedAt ?? null,
+      hasWorktree: false,
+      worktreePath: null,
+      detectedBy: resolved.detectedBy,
+      localExists: false,
+      behindMerge: verdict.reason === 'tip-behind-merge',
+    });
+  }
+  return out;
+}

package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches.js

@@ -1,7 +1,8 @@
 /**
  * branches.js — branch-reap phase of git-cleanup (Story #2466).
  * Owns `planCleanup` + `executeCleanup`. Reap helpers live in
- * `branches-reap.js`.
+ * `branches-reap.js`; the non-PR detection signals and the remote-only
+ * walk live in `branches-detect.js`.
  * @module lib/orchestration/git-cleanup/phases/branches
  */
 
@@ -13,6 +14,11 @@ import {
 } from '../../../git-branch-cleanup.js';
 import { Logger } from '../../../Logger.js';
 import { recordPendingCleanup } from '../../../worktree/lifecycle/pending-cleanup.js';
+import {
+  collectRemoteOnlyCandidates,
+  evaluateContentEquivalence,
+  skipEntryFromVerdict,
+} from './branches-detect.js';
 import {
   buildPruneSummary,
   reapLocalRef,
@@ -25,9 +31,11 @@ import {
   branchTipSha,
   classifyLatestPr,
   currentBranch as defaultCurrentBranch,
+  freshAnchoredMergedSet,
   listLocalBranches,
   listMergedBranches,
   listRemoteBranches,
+  listRemoteMergedBranches,
   probeAllPrs,
   probeContentEquivalent,
   probeLatestPr,
@@ -42,45 +50,6 @@ import { parsePrunedRefs } from './prune.js';
 
 const TAG = '[git-cleanup]';
 
-/** Fields a planner verdict forwards onto its `skipped[]` entry. */
-const SKIP_DETAIL_FIELDS = ['prNumber', 'tipSha', 'mergedSha', 'detail'];
-
-function skipEntryFromVerdict(branch, verdict) {
-  const entry = { branch, reason: verdict.reason };
-  for (const field of SKIP_DETAIL_FIELDS) {
-    if (verdict[field] != null) entry[field] = verdict[field];
-  }
-  return entry;
-}
-
-/**
- * Story #4395 — the third detection signal. Reached only when the branch
- * has no reapable PR verdict and is not an ancestor of `<base>` (or
- * `origin/<base>`). Probes content-equivalence via `git merge-tree
- * --write-tree` and, when the probe is conclusive and the merge is a
- * no-op, classifies the branch as `content-merged` instead of falling
- * through to the `not-merged` skip.
- */
-function evaluateContentEquivalence({
-  branch,
-  baseBranch,
-  cwd,
-  contentEquivalentFn,
-  branchLastCommitFn,
-}) {
-  const verdict = contentEquivalentFn({ cwd, base: baseBranch, branch });
-  if (verdict?.supported && verdict.equivalent) {
-    return { detectedBy: 'content-merged' };
-  }
-  return {
-    skip: {
-      branch,
-      reason: 'not-merged',
-      lastCommitAt: branchLastCommitFn(cwd, branch),
-    },
-  };
-}
-
 function evaluateLocalBranch({
   branch,
   baseBranch,
@@ -145,52 +114,6 @@ function evaluateLocalBranch({
   };
 }
 
-function collectRemoteOnlyCandidates({
-  remoteLister,
-  remoteName,
-  cwd,
-  localSet,
-  classify,
-  filter,
-  prProbe,
-  branchTipShaFn,
-  ancestryFn,
-  skipped,
-}) {
-  const out = [];
-  for (const branch of remoteLister(cwd, remoteName)) {
-    if (localSet.has(branch)) continue;
-    if (classify(branch)) continue;
-    if (!filter(branch)) continue;
-    const prInfo = prProbe(branch, cwd);
-    const verdict = classifyLatestPr({
-      prInfo,
-      branch,
-      cwd,
-      remoteName,
-      localExists: false,
-      branchTipShaFn,
-      ancestryFn,
-    });
-    if (verdict.kind === 'no-pr') continue;
-    if (verdict.kind === 'skip') {
-      skipped.push(skipEntryFromVerdict(branch, verdict));
-      continue;
-    }
-    out.push({
-      branch,
-      prNumber: verdict.prInfo.number ?? null,
-      mergedAt: verdict.prInfo.mergedAt ?? null,
-      hasWorktree: false,
-      worktreePath: null,
-      detectedBy: 'remote-only',
-      localExists: false,
-      behindMerge: verdict.reason === 'tip-behind-merge',
-    });
-  }
-  return out;
-}
-
 /**
  * Pure-ish: enumerate merged-branch candidates.
  *
@@ -229,6 +152,20 @@ function collectRemoteOnlyCandidates({
  *     git-only signals (ancestry + content-equivalence) rather than
  *     aborting the whole plan. The returned envelope's `ghDegraded` flag
  *     records whether this happened.
+ *
+ * Story #5188 makes the **remote-only** walk total (it now lives in
+ * `branches-detect.js`). It used to classify by
+ * the latest-PR verdict alone and return early on a `no-pr` verdict,
+ * recording neither a candidate nor a skip — so a remote ref no PR record
+ * covered was absent from `candidates[]`, `skipped[]`, the rendered log
+ * and the `--json` envelope alike. It now runs the same three-signal
+ * cascade the local walk does (PR verdict → ancestry → content
+ * -equivalence → `not-merged` skip), over its own remote-namespace
+ * ancestry source and with every git probe handed the qualified
+ * `<remote>/<branch>` rev. Every enumerated branch that passes the
+ * protected and filter checks therefore lands in exactly one of the two
+ * collections. Deletion is unchanged: a remote-only candidate still needs
+ * `--remote`, whichever signal detected it.
  */
 function buildGuardedPrProbe({ cwd, prIndexFn, prFallback, onDegrade }) {
   let prIndex;
@@ -269,6 +206,7 @@ export function planCleanup(ctx) {
     filter = () => true,
     includeRemoteOnly = false,
     remoteLister = listRemoteBranches,
+    remoteMergedLister = listRemoteMergedBranches,
     remoteName = 'origin',
     logger = Logger,
   } = ctx;
@@ -293,11 +231,12 @@ export function planCleanup(ctx) {
       branch,
     });
   const wtMap = worktreesFn(cwd);
-  const mergedByGit = new Set(mergedLister(cwd, baseBranch));
   const remoteBaseRef = `${remoteName}/${baseBranch}`;
-  if (refExistsFn(cwd, remoteBaseRef)) {
-    for (const b of mergedLister(cwd, remoteBaseRef)) mergedByGit.add(b);
-  }
+  const mergedSetArgs = { cwd, baseBranch, remoteBaseRef, refExistsFn };
+  const mergedByGit = freshAnchoredMergedSet({
+    ...mergedSetArgs,
+    lister: mergedLister,
+  });
   const localBranches = localLister(cwd);
   const localSet = new Set(localBranches);
   const candidates = [];
@@ -327,12 +266,20 @@ export function planCleanup(ctx) {
         remoteLister,
         remoteName,
         cwd,
+        baseBranch,
         localSet,
         classify,
         filter,
         prProbe,
         branchTipShaFn,
         ancestryFn,
+        mergedRemote: freshAnchoredMergedSet({
+          ...mergedSetArgs,
+          lister: remoteMergedLister,
+          remoteName,
+        }),
+        contentEquivalentFn,
+        branchLastCommitFn,
         skipped,
       }),
     );

package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js

@@ -45,6 +45,43 @@ export function listLocalBranches(cwd) {
     .filter(Boolean);
 }
 
+/**
+ * Pure: strip the `<remote>/` prefix off a remote-ref listing and drop the
+ * symbolic `HEAD` entry.
+ *
+ * `HEAD` arrives under two spellings. `%(refname:lstrip=3)` renders
+ * `refs/remotes/origin/HEAD` as the literal `HEAD`, but
+ * `%(refname:short)` — what both callers ask for — shortens it to the bare
+ * remote name `origin`, because git keeps the remote segment only when the
+ * result would otherwise be ambiguous. Missing that second spelling leaked
+ * a phantom `origin` candidate into the remote-only sweep, which the reap
+ * phase then reported as `already gone`.
+ *
+ * Both spellings are rejected **before** the prefix strip, because the
+ * strip is what makes them ambiguous: a real branch named `origin` lists
+ * as `origin/origin` and strips to `origin` too. Discriminating on the raw
+ * line keeps that branch reapable while still dropping the symbolic ref.
+ *
+ * Shared by {@link listRemoteBranches} and {@link listRemoteMergedBranches}
+ * so both enumerations speak the same short-name vocabulary the planner's
+ * remote-only walk keys on — a divergence there would make the ancestry
+ * signal miss every branch by name (Story #5188).
+ *
+ * @param {string} stdout
+ * @param {string} remoteName
+ * @returns {string[]}
+ */
+function shortRemoteNames(stdout, remoteName) {
+  const prefix = `${remoteName}/`;
+  return stdout
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .filter((l) => l !== 'HEAD' && l !== remoteName)
+    .map((l) => (l.startsWith(prefix) ? l.slice(prefix.length) : l))
+    .filter(Boolean);
+}
+
 /* node:coverage ignore next */
 export function listRemoteBranches(cwd, remoteName = 'origin') {
   const res = gitSpawn(
@@ -54,13 +91,41 @@ export function listRemoteBranches(cwd, remoteName = 'origin') {
     `refs/remotes/${remoteName}/`,
   );
   if (res.status !== 0) return [];
-  const prefix = `${remoteName}/`;
-  return res.stdout
-    .split('\n')
-    .map((l) => l.trim())
-    .filter(Boolean)
-    .map((l) => (l.startsWith(prefix) ? l.slice(prefix.length) : l))
-    .filter((b) => b && b !== 'HEAD');
+  return shortRemoteNames(res.stdout, remoteName);
+}
+
+/**
+ * The remote-only walk's ancestry source (Story #5188).
+ *
+ * {@link listMergedBranches} runs `git branch --merged` with no `-r`, so it
+ * enumerates **local** heads only and can never contain a remote branch
+ * name — feeding it the remote-only walk classified every orphaned remote
+ * ref as unmerged no matter how thoroughly it had landed. This is the `-r`
+ * twin: `git branch -r --merged <base>`, with the `<remote>/` prefix
+ * stripped so its names match the short names {@link listRemoteBranches}
+ * enumerates.
+ *
+ * Answered entirely from the local object database against the
+ * already-fetched remote-tracking refs — the sweep stays offline and adds
+ * no per-branch network call.
+ *
+ * @param {string} cwd
+ * @param {string} base  Rev the ancestry is taken against (`main`, `origin/main`).
+ * @param {string} [remoteName]
+ * @returns {string[]}  Short branch names, remote prefix stripped.
+ */
+/* node:coverage ignore next */
+export function listRemoteMergedBranches(cwd, base, remoteName = 'origin') {
+  const res = gitSpawn(
+    cwd,
+    'branch',
+    '-r',
+    '--merged',
+    base,
+    '--format=%(refname:short)',
+  );
+  if (res.status !== 0) return [];
+  return shortRemoteNames(res.stdout, remoteName);
 }
 
 /* node:coverage ignore next */
@@ -79,6 +144,36 @@ export function listMergedBranches(cwd, base) {
     .filter(Boolean);
 }
 
+/**
+ * Story #4395's fresh ancestry anchor, factored out here so the local and
+ * remote-only walks cannot drift apart on it (Story #5188): the merged
+ * listing taken against the local base is unioned with the one taken
+ * against `<remote>/<base>` whenever that ref exists, so a stale local
+ * base cannot hide a branch already merged on the remote.
+ *
+ * `lister` picks the namespace — {@link listMergedBranches} (local heads)
+ * for the local walk, {@link listRemoteMergedBranches} (remote-tracking
+ * refs) for the remote-only one. `remoteName` is forwarded as the listers'
+ * third argument, which the local lister ignores.
+ *
+ * @param {{ lister: Function, cwd: string, baseBranch: string, remoteBaseRef: string, refExistsFn: Function, remoteName?: string }} args
+ * @returns {Set<string>}
+ */
+export function freshAnchoredMergedSet({
+  lister,
+  cwd,
+  baseBranch,
+  remoteBaseRef,
+  refExistsFn,
+  remoteName,
+}) {
+  const set = new Set(lister(cwd, baseBranch, remoteName));
+  if (refExistsFn(cwd, remoteBaseRef)) {
+    for (const b of lister(cwd, remoteBaseRef, remoteName)) set.add(b);
+  }
+  return set;
+}
+
 /* node:coverage ignore next */
 export function currentBranch(cwd) {
   const res = gitSpawn(cwd, 'symbolic-ref', '--quiet', '--short', 'HEAD');
@@ -356,18 +451,28 @@ export function refExists(cwd, ref) {
   return res.status === 0;
 }
 
+/**
+ * Story #4395: last-commit timestamp for the dry-run `not-merged`
+ * skip-visibility line (branch name + last-commit age).
+ *
+ * Story #5188 adds the remote-only arm. Remote branches are enumerated
+ * with the `<remote>/` prefix stripped, so the short name resolves to no
+ * `refs/heads/` ref at all: passing `localExists: false` reads
+ * `refs/remotes/<remote>/<branch>` instead, so an orphaned remote ref's
+ * skip line carries a real age rather than a silent `unknown`.
+ *
+ * @param {string} cwd
+ * @param {string} branch  Short branch name, remote prefix stripped.
+ * @param {{ localExists?: boolean, remoteName?: string }} [opts]
+ * @returns {string | null}
+ */
 /* node:coverage ignore next */
-// Story #4395: last-commit timestamp for the dry-run `not-merged`
-// skip-visibility line (branch name + last-commit age).
-export function branchLastCommitAt(cwd, branch) {
-  const res = gitSpawn(
-    cwd,
-    'log',
-    '-1',
-    '--format=%cI',
-    `refs/heads/${branch}`,
-    '--',
-  );
+export function branchLastCommitAt(cwd, branch, opts = {}) {
+  const { localExists = true, remoteName = 'origin' } = opts;
+  const ref = localExists
+    ? `refs/heads/${branch}`
+    : `refs/remotes/${remoteName}/${branch}`;
+  const res = gitSpawn(cwd, 'log', '-1', '--format=%cI', ref, '--');
   if (res.status !== 0) return null;
   return res.stdout.trim() || null;
 }
@@ -429,7 +534,12 @@ export function probeContentEquivalent({
   return { supported: true, equivalent: mergedTree === baseTree };
 }
 
-export const __testing = { validSha, firstLsRemoteSha, firstStdoutLine };
+export const __testing = {
+  validSha,
+  firstLsRemoteSha,
+  firstStdoutLine,
+  shortRemoteNames,
+};
 
 /**
  * Pure-ish: classify a latest-PR probe row into a planner verdict.

package/.agents/scripts/lib/orchestration/git-cleanup/phases/render.js

@@ -38,7 +38,14 @@ function formatCommitAge(iso, now) {
  * surfaces each one with its last-commit age so the operator can see why
  * a leftover branch isn't reaped instead of hunting for it by hand.
  *
- * @param {{ branch: string, reason: string, lastCommitAt?: string|null }} skip
+ * Story #5188 routes the remote-only walk's genuinely-unmerged survivors
+ * through here too. A `localExists: false` skip is marked `(remote-only)`
+ * — the same marker {@link renderCandidateRow} puts on a remote-only
+ * candidate — because the short name it prints has no local ref behind
+ * it: without the marker the operator reads the line as a local branch and
+ * hunts for a ref that `git branch` will never list.
+ *
+ * @param {{ branch: string, reason: string, lastCommitAt?: string|null, localExists?: boolean }} skip
  * @param {{ now?: number }} [opts]
  * @returns {string | null}
  */
@@ -46,7 +53,8 @@ export function renderNotMergedSkipLine(skip, opts = {}) {
   if (!skip || skip.reason !== 'not-merged') return null;
   const now = opts.now ?? Date.now();
   const age = formatCommitAge(skip.lastCommitAt, now);
-  return `${TAG} ⏭️  ${skip.branch} skipped — not merged (last commit: ${age})`;
+  const scope = skip.localExists === false ? ' (remote-only)' : '';
+  return `${TAG} ⏭️  ${skip.branch}${scope} skipped — not merged (last commit: ${age})`;
 }
 
 /**