mandrel 1.85.0 → 1.87.0

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-diff.js

@@ -81,6 +81,10 @@
  */
 
 import { composeStoryBody } from '../../providers/github/tickets.js';
+import {
+  extractFrameworkStamp,
+  stampFrameworkVersion,
+} from '../framework-version.js';
 import { assertPlanLabelAllowList } from './epic-spec-reconciler-discriminator.js';
 import {
   closeOp,
@@ -233,12 +237,21 @@ function stripFooter(body) {
  * `composeStoryBody` directly makes that divergence structurally
  * impossible going forward.
  *
+ * Story #4382 — the create-time authoring stamp (`mandrel_version` /
+ * `authored_at` meta field + visible marker) is provenance, not spec-derived
+ * content, so this UPDATE path never mints or bumps it (which would also break
+ * this function's purity — the stamp uses a clock). Instead the stamp already
+ * present on the **live** GH body (`obsBody`) is preserved verbatim, and a
+ * legacy stamp-less body is left stamp-less (no backfill — see the Story's
+ * Out-of-Scope). Footer recomposition therefore runs in `stamp: false` mode.
+ *
  * @param {{entity: string, parentSlug?: string|null, dependsOn?: string[]}} specEntity
  * @param {string} specBody
  * @param {{state?: StateInput}} ctx
+ * @param {string} [obsBody] - The live GH body, source of the preserved stamp.
  * @returns {string}
  */
-function composeBodyWithFooter(specEntity, specBody, ctx) {
+function composeBodyWithFooter(specEntity, specBody, ctx, obsBody = '') {
   const state = ctx?.state ?? {};
   const mapping = state.mapping ?? {};
   const parentSlug = specEntity.parentSlug ?? null;
@@ -264,7 +277,25 @@ function composeBodyWithFooter(specEntity, specBody, ctx) {
   // included) or emits a canonical-form body. With the strip, the
   // function is idempotent against its own output.
   const head = stripFooter(specBody);
-  return composeStoryBody({ body: head, parentId, epicId, dependencies });
+  // Preserve the live body's create-time authoring stamp (Story #4382). When
+  // the spec head already carries it, `stampFrameworkVersion` is a no-op
+  // (immutable); when it doesn't, the stamp is restored from the live body so
+  // the recomposed form matches GH and no spurious body Update fires. A
+  // legacy body with no stamp stays stamp-less (no backfill).
+  const priorStamp = extractFrameworkStamp(obsBody);
+  const stampedHead = priorStamp
+    ? stampFrameworkVersion(head, {
+        version: priorStamp.version,
+        authoredAt: priorStamp.authoredAt,
+      })
+    : head;
+  return composeStoryBody({
+    body: stampedHead,
+    parentId,
+    epicId,
+    dependencies,
+    stamp: false,
+  });
 }
 
 /**
@@ -329,7 +360,7 @@ function fieldChanges(specEntity, obs, mapping, ctx = {}) {
       // Emit a body change only when the canonical form differs from
       // what is on GH today — and write the canonical form back, so the
       // footer cascade-readers depend on stays intact across resumes.
-      const after = composeBodyWithFooter(specEntity, specBody, ctx);
+      const after = composeBodyWithFooter(specEntity, specBody, ctx, obsBody);
       if (after !== obsBody) {
         changes.body = { before: obsBody, after };
       }

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

@@ -21,6 +21,7 @@ import {
 } from './branches-reap.js';
 import { computeProtectedReason } from './filters.js';
 import {
+  branchLastCommitAt,
   branchTipSha,
   classifyLatestPr,
   currentBranch as defaultCurrentBranch,
@@ -28,14 +29,18 @@ import {
   listMergedBranches,
   listRemoteBranches,
   probeAllPrs,
+  probeContentEquivalent,
   probeLatestPr,
   pruneRemoteTracking,
   readProtectedConfig,
+  refExists,
   removeWorktree,
   worktreesByBranch,
 } from './git-probes.js';
 import { parsePrunedRefs } from './prune.js';
 
+const TAG = '[git-cleanup]';
+
 function skipEntryFromVerdict(branch, verdict) {
   const entry = { branch, reason: verdict.reason };
   if (verdict.prNumber != null) entry.prNumber = verdict.prNumber;
@@ -44,8 +49,37 @@ function skipEntryFromVerdict(branch, verdict) {
   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,
   classify,
   filter,
   mergedByGit,
@@ -54,6 +88,8 @@ function evaluateLocalBranch({
   wtMap,
   remoteName,
   branchTipShaFn,
+  contentEquivalentFn,
+  branchLastCommitFn,
 }) {
   const protectedReason = classify(branch);
   if (protectedReason) return { skip: { branch, reason: protectedReason } };
@@ -78,7 +114,15 @@ function evaluateLocalBranch({
   } else if (mergedByGit.has(branch)) {
     detectedBy = 'git-merged';
   } else {
-    return { skip: { branch, reason: 'not-merged' } };
+    const out = evaluateContentEquivalence({
+      branch,
+      baseBranch,
+      cwd,
+      contentEquivalentFn,
+      branchLastCommitFn,
+    });
+    if (out.skip) return out;
+    detectedBy = out.detectedBy;
   }
   const wt = wtMap.get(branch);
   return {
@@ -156,7 +200,43 @@ function collectRemoteOnlyCandidates({
  * the per-branch fallback for head refs absent from the bulk page (a PR
  * that fell outside the fetch window), so correctness is preserved for
  * every branch. Injecting `prProbe` bypasses the bulk fetch entirely.
+ *
+ * Story #4395 adds three refinements:
+ *   - **Content-equivalence signal.** A local branch with no reapable PR
+ *     verdict and no ancestry match gets one more chance via
+ *     {@link probeContentEquivalent} (`git merge-tree --write-tree`):
+ *     when merging it into `baseBranch` would be a content no-op, it is
+ *     classified `detectedBy: 'content-merged'` instead of skipped.
+ *   - **Fresh ancestry anchor.** The ancestry signal (`git branch --merged`)
+ *     is unioned against `origin/<base>` (via `refExistsFn` + `mergedLister`)
+ *     whenever that remote-tracking ref exists, so a stale local `<base>`
+ *     no longer hides a branch already merged on the remote.
+ *   - **Graceful `gh` degradation.** A throwing `gh` runner (auth failure,
+ *     rate limit, missing binary) inside the bulk index fetch or the
+ *     per-branch fallback is caught, logged once, and degrades to
+ *     git-only signals (ancestry + content-equivalence) rather than
+ *     aborting the whole plan. The returned envelope's `ghDegraded` flag
+ *     records whether this happened.
  */
+function buildGuardedPrProbe({ cwd, prIndexFn, prFallback, onDegrade }) {
+  let prIndex;
+  try {
+    prIndex = prIndexFn(cwd);
+  } catch (err) {
+    onDegrade(err);
+    prIndex = new Map();
+  }
+  return (branch, c) => {
+    if (prIndex.has(branch)) return prIndex.get(branch);
+    try {
+      return prFallback(branch, c);
+    } catch (err) {
+      onDegrade(err);
+      return null;
+    }
+  };
+}
+
 export function planCleanup(ctx) {
   const {
     cwd,
@@ -170,18 +250,26 @@ export function planCleanup(ctx) {
     prIndexFn = probeAllPrs,
     prFallback = probeLatestPr,
     branchTipShaFn = branchTipSha,
+    contentEquivalentFn = probeContentEquivalent,
+    branchLastCommitFn = branchLastCommitAt,
+    refExistsFn = refExists,
     filter = () => true,
     includeRemoteOnly = false,
     remoteLister = listRemoteBranches,
     remoteName = 'origin',
+    logger = Logger,
   } = ctx;
+  let ghDegraded = false;
+  const onDegrade = (err) => {
+    if (ghDegraded) return;
+    ghDegraded = true;
+    logger.warn?.(
+      `${TAG} ⚠️ gh probe failed (${err?.message ?? err}); continuing with git-only signals`,
+    );
+  };
   const prProbe =
     injectedPrProbe ??
-    (() => {
-      const prIndex = prIndexFn(cwd);
-      return (branch, c) =>
-        prIndex.has(branch) ? prIndex.get(branch) : prFallback(branch, c);
-    })();
+    buildGuardedPrProbe({ cwd, prIndexFn, prFallback, onDegrade });
   const resolvedCurrent = currentBranchFn(cwd);
   const resolvedConfigured = protectedConfigFn(cwd);
   const classify = (branch) =>
@@ -193,6 +281,10 @@ export function planCleanup(ctx) {
     });
   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 localBranches = localLister(cwd);
   const localSet = new Set(localBranches);
   const candidates = [];
@@ -200,6 +292,7 @@ export function planCleanup(ctx) {
   for (const branch of localBranches) {
     const out = evaluateLocalBranch({
       branch,
+      baseBranch,
       classify,
       filter,
       mergedByGit,
@@ -208,6 +301,8 @@ export function planCleanup(ctx) {
       wtMap,
       remoteName,
       branchTipShaFn,
+      contentEquivalentFn,
+      branchLastCommitFn,
     });
     if (out.skip) skipped.push(out.skip);
     else candidates.push(out.candidate);
@@ -227,7 +322,7 @@ export function planCleanup(ctx) {
       }),
     );
   }
-  return { candidates, skipped };
+  return { candidates, skipped, ghDegraded };
 }
 
 /**

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

@@ -34,54 +34,107 @@ export function isWorktreeLockFailure(stderr) {
 
 /* node:coverage ignore next */
 export function isWorkingTreeClean(cwd) {
-  const res = gitSpawn(cwd, 'status', '--porcelain');
-  if (res.status !== 0) return false;
-  return res.stdout.trim() === '';
+  return defaultFfProbes.isClean(cwd);
 }
 
 /* node:coverage ignore next */
 export function fetchRef(cwd, remoteName, ref) {
-  const res = gitSpawn(cwd, 'fetch', '--quiet', remoteName, ref);
-  if (res.status !== 0) return { ok: false, stderr: res.stderr };
-  return { ok: true };
+  return defaultFfProbes.fetch(cwd, remoteName, ref);
 }
 
 /* node:coverage ignore next */
 export function canFastForward(cwd, baseBranch, remoteName) {
-  const ref = `${remoteName}/${baseBranch}`;
-  const ahead = gitSpawn(
-    cwd,
-    'rev-list',
-    '--left-right',
-    '--count',
-    `${baseBranch}...${ref}`,
-  );
-  if (ahead.status !== 0) {
-    return { ok: false, behind: 0, reason: 'rev-list-failed' };
-  }
-  const parts = ahead.stdout.trim().split(/\s+/);
-  const localAhead = Number(parts[0]) || 0;
-  const remoteAhead = Number(parts[1]) || 0;
-  if (localAhead > 0) {
-    return { ok: false, behind: remoteAhead, reason: 'not-fast-forward' };
-  }
-  return { ok: true, behind: remoteAhead };
+  return defaultFfProbes.canFastForward(cwd, baseBranch, remoteName);
 }
 
 /* node:coverage ignore next */
 export function checkoutBranch(cwd, branch) {
-  const res = gitSpawn(cwd, 'checkout', branch);
-  if (res.status !== 0) return { ok: false, stderr: res.stderr };
-  return { ok: true };
+  return defaultFfProbes.checkout(cwd, branch);
 }
 
 /* node:coverage ignore next */
 export function mergeFastForward(cwd, ref) {
-  const res = gitSpawn(cwd, 'merge', '--ff-only', ref);
-  if (res.status !== 0) return { ok: false, stderr: res.stderr };
-  return { ok: true };
+  return defaultFfProbes.merge(cwd, ref);
 }
 
+/**
+ * Build the fast-forward probe bundle bound to a `gitSpawn`.
+ *
+ * This is the **single implementation** of the FF/base-sync git wrappers.
+ * The standalone exports above delegate to a default instance bound to the
+ * shared `gitSpawn`; callers that need to inject their own spawn for testing
+ * (e.g. the epic-cleanup runner) call this factory directly instead of
+ * hand-rolling a parallel copy (framework-gap #4379). The bundle also carries
+ * `currentBranch` so an injecting caller gets the whole FF surface from one
+ * place.
+ *
+ * @param {(cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string }} [spawn]
+ * @returns {{
+ *   isClean: (cwd: string) => boolean,
+ *   currentBranch: (cwd: string) => string|null,
+ *   fetch: (cwd: string, remoteName: string, ref: string) => { ok: boolean, stderr?: string },
+ *   canFastForward: (cwd: string, baseBranch: string, remoteName: string) => { ok: boolean, behind: number, reason?: string },
+ *   checkout: (cwd: string, branch: string) => { ok: boolean, stderr?: string },
+ *   merge: (cwd: string, ref: string) => { ok: boolean, stderr?: string },
+ * }}
+ */
+export function makeFfProbes(spawn = gitSpawn) {
+  return {
+    isClean: (cwd) => {
+      const res = spawn(cwd, 'status', '--porcelain');
+      return res.status === 0 && String(res.stdout ?? '').trim() === '';
+    },
+    currentBranch: (cwd) => {
+      const res = spawn(cwd, 'symbolic-ref', '--quiet', '--short', 'HEAD');
+      return res.status !== 0 ? null : String(res.stdout ?? '').trim() || null;
+    },
+    fetch: (cwd, remoteName, ref) => {
+      const res = spawn(cwd, 'fetch', '--quiet', remoteName, ref);
+      return res.status === 0
+        ? { ok: true }
+        : { ok: false, stderr: res.stderr };
+    },
+    canFastForward: (cwd, baseBranch, remoteName) => {
+      const ref = `${remoteName}/${baseBranch}`;
+      const ahead = spawn(
+        cwd,
+        'rev-list',
+        '--left-right',
+        '--count',
+        `${baseBranch}...${ref}`,
+      );
+      if (ahead.status !== 0) {
+        return { ok: false, behind: 0, reason: 'rev-list-failed' };
+      }
+      const parts = String(ahead.stdout ?? '')
+        .trim()
+        .split(/\s+/);
+      const localAhead = Number(parts[0]) || 0;
+      const remoteAhead = Number(parts[1]) || 0;
+      if (localAhead > 0) {
+        return { ok: false, behind: remoteAhead, reason: 'not-fast-forward' };
+      }
+      return { ok: true, behind: remoteAhead };
+    },
+    checkout: (cwd, branch) => {
+      const res = spawn(cwd, 'checkout', branch);
+      return res.status === 0
+        ? { ok: true }
+        : { ok: false, stderr: res.stderr };
+    },
+    merge: (cwd, ref) => {
+      const res = spawn(cwd, 'merge', '--ff-only', ref);
+      return res.status === 0
+        ? { ok: true }
+        : { ok: false, stderr: res.stderr };
+    },
+  };
+}
+
+// Default instance bound to the shared gitSpawn; the standalone wrappers
+// above delegate to it so there is exactly one FF-probe implementation.
+const defaultFfProbes = makeFfProbes(gitSpawn);
+
 /* node:coverage ignore next */
 export function removeWorktree(worktreePath, cwd) {
   const plain = gitSpawn(cwd, 'worktree', 'remove', worktreePath);

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

@@ -344,7 +344,91 @@ export function branchTipSha({
   return res.status !== 0 ? null : validSha(firstLsRemoteSha(res.stdout));
 }
 
-export const __testing = { validSha, firstLsRemoteSha };
+/* node:coverage ignore next */
+// Story #4395: ancestry-anchor freshness check. `planCleanup` calls this
+// before unioning `git branch --merged origin/<base>` into the ancestry
+// signal so a stale local `<base>` (fast-forward phase skipped or
+// `--branches` run alone) doesn't hide a branch that's already merged on
+// the remote.
+export function refExists(cwd, ref) {
+  const res = gitSpawn(cwd, 'rev-parse', '--verify', '--quiet', ref);
+  return res.status === 0;
+}
+
+/* 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}`,
+    '--',
+  );
+  if (res.status !== 0) return null;
+  return res.stdout.trim() || null;
+}
+
+/**
+ * First non-empty trimmed stdout line — the resulting tree OID on a clean
+ * `git merge-tree --write-tree` run.
+ *
+ * @param {string} stdout
+ * @returns {string}
+ */
+function firstStdoutLine(stdout) {
+  const first = (stdout ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .find(Boolean);
+  return first ?? '';
+}
+
+/**
+ * Probe content-equivalence between `base` and `branch` via
+ * `git merge-tree --write-tree <base> <branch>` (git >= 2.38, Story #4395).
+ *
+ * A clean merge (exit 0) whose resulting tree OID equals `<base>`'s own
+ * tree OID means applying `branch`'s changes on top of `base` is a no-op —
+ * `branch`'s content already lives in `base` by another route (a
+ * squash-merged Epic PR, a cherry-pick, a manual `merge --squash`) that
+ * neither the PR probe nor the ancestry check can see.
+ *
+ * Both the "unsupported" case (git < 2.38 rejects `--write-tree`) and the
+ * "real conflict" case (branch and base diverge and cannot auto-merge)
+ * surface as a non-zero exit. This probe treats them identically — the
+ * signal is inconclusive, so the caller keeps the branch's current
+ * `not-merged` classification rather than guessing.
+ *
+ * @param {{ cwd: string, base: string, branch: string, spawn?: typeof gitSpawn }} args
+ * @returns {{ supported: false } | { supported: true, equivalent: boolean }}
+ */
+export function probeContentEquivalent({
+  cwd,
+  base,
+  branch,
+  spawn = gitSpawn,
+}) {
+  const merged = spawn(cwd, 'merge-tree', '--write-tree', base, branch);
+  if (merged.status !== 0) return { supported: false };
+  const mergedTree = validSha(firstStdoutLine(merged.stdout));
+  if (!mergedTree) return { supported: false };
+  const baseTreeRes = spawn(
+    cwd,
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `${base}^{tree}`,
+  );
+  if (baseTreeRes.status !== 0) return { supported: false };
+  const baseTree = validSha(baseTreeRes.stdout);
+  if (!baseTree) return { supported: false };
+  return { supported: true, equivalent: mergedTree === baseTree };
+}
+
+export const __testing = { validSha, firstLsRemoteSha, firstStdoutLine };
 
 /**
  * Pure-ish: classify a latest-PR probe row into a planner verdict.

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

@@ -190,6 +190,22 @@ export async function runPrunePhase(opts, cwd) {
 // Branch phase
 // =====================================================================
 
+/**
+ * Count of a plan's *actionable* candidates — the ones `executeCleanup`
+ * will actually delete given the current `--remote` setting. Story #4395
+ * always enumerates remote-only candidates in `plan.candidates` (so the
+ * operator sees them in the dry-run list), but their deletion still
+ * requires `--remote`; without it, `executeCleanup` no-ops on every
+ * `localExists: false` candidate. Counting only the actionable subset
+ * keeps the "no-candidates" short-circuit and the confirmation prompt's
+ * "Reap N" count honest about what will actually happen.
+ */
+function countActionableCandidates(candidates, remote) {
+  return remote
+    ? candidates.length
+    : candidates.filter((c) => c.localExists !== false).length;
+}
+
 /**
  * Pure: decide what the branch-reap phase should do given the plan.
  *
@@ -209,7 +225,11 @@ export function decideBranchPhase(state) {
   if (opts.dryRun) {
     return { kind: 'dry-run', plan, result: { plan, result: null } };
   }
-  if (plan.candidates.length === 0) {
+  const actionableCount = countActionableCandidates(
+    plan.candidates,
+    opts.remote,
+  );
+  if (actionableCount === 0) {
     return { kind: 'no-candidates', plan, result: { plan, result: null } };
   }
   const executeArgs = {
@@ -218,10 +238,17 @@ export function decideBranchPhase(state) {
     remote: opts.remote,
   };
   if (!opts.yes) {
+    const contentMergedCount = plan.candidates.filter(
+      (c) => c.detectedBy === 'content-merged',
+    ).length;
+    const weakSignalNote =
+      contentMergedCount > 0
+        ? ` (${contentMergedCount} content-merged — weaker signal, verify before confirming)`
+        : '';
     return {
       kind: 'prompt-then-execute',
       plan,
-      promptMessage: `${TAG} Reap ${plan.candidates.length} merged branch(es)${opts.remote ? ' (including origin)' : ''}?`,
+      promptMessage: `${TAG} Reap ${actionableCount} merged branch(es)${opts.remote ? ' (including origin)' : ''}${weakSignalNote}?`,
       declinedResult: { plan, result: null, declined: true },
       executeArgs,
     };
@@ -254,11 +281,15 @@ export async function runBranchPhase(opts, cwd, baseBranch) {
     include: opts.include,
     exclude: opts.exclude,
   });
+  // Story #4395: always enumerate remote-only merged branches so the
+  // dry-run / prompt shows them without requiring `--remote`. Deletion of
+  // a remote-only candidate still requires `--remote` — `executeCleanup`
+  // no-ops on `localExists: false` candidates otherwise (unchanged).
   const plan = planCleanup({
     cwd,
     baseBranch,
     filter,
-    includeRemoteOnly: opts.remote === true,
+    includeRemoteOnly: true,
   });
   emitDryRunHuman(plan, baseBranch);
   const action = decideBranchPhase({ plan, opts, cwd });

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

@@ -9,10 +9,61 @@
  */
 
 const TAG = '[git-cleanup]';
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Pure: format a last-commit ISO timestamp as a short relative-age string
+ * for the `not-merged` skip-visibility line (Story #4395). Returns
+ * `'unknown'` when `iso` is missing or unparseable — a branch whose commit
+ * date could not be resolved (e.g. `gh`-degraded run, deleted ref) still
+ * gets a line, just without an age.
+ *
+ * @param {string|null|undefined} iso
+ * @param {number} now  Epoch-ms reference clock (injectable for tests).
+ * @returns {string}
+ */
+function formatCommitAge(iso, now) {
+  if (!iso) return 'unknown';
+  const then = Date.parse(iso);
+  if (!Number.isFinite(then)) return 'unknown';
+  const days = Math.max(0, Math.floor((now - then) / DAY_MS));
+  if (days === 0) return 'today';
+  if (days === 1) return '1 day ago';
+  return `${days} days ago`;
+}
+
+/**
+ * Pure: render a single `not-merged` skip-visibility line (Story #4395).
+ * `renderDryRun` previously kept `not-merged` survivors silent; this
+ * 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
+ * @param {{ now?: number }} [opts]
+ * @returns {string | null}
+ */
+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})`;
+}
+
+/**
+ * Pure: render a single content-merged candidate annotation line
+ * (Story #4395). `content-merged` is a weaker signal than a merged PR or
+ * git ancestry — this note lets the operator tell it apart in both the
+ * dry-run list and the confirmation prompt.
+ */
+function contentMergedNote(candidate) {
+  return candidate.detectedBy === 'content-merged'
+    ? ' (weaker signal — verify before deleting)'
+    : '';
+}
 
 /** Pure: render the dry-run plan as the operator-facing text block. */
 export function renderDryRun(plan, opts = {}) {
-  const { baseBranch = null } = opts;
+  const { baseBranch = null, now } = opts;
   const lines = [
     `${TAG} DRY RUN (nothing deleted) — ${plan.candidates.length} candidate(s)`,
   ];
@@ -23,7 +74,9 @@ export function renderDryRun(plan, opts = {}) {
       const pr = c.prNumber ? `PR #${c.prNumber}` : c.detectedBy;
       const wt = c.hasWorktree ? ` (worktree: ${c.worktreePath})` : '';
       const remoteOnly = c.localExists === false ? ' (remote-only)' : '';
-      lines.push(`  • ${c.branch} — ${pr}${wt}${remoteOnly}`);
+      lines.push(
+        `  • ${c.branch} — ${pr}${wt}${remoteOnly}${contentMergedNote(c)}`,
+      );
     }
   }
   const skipped = plan.skipped ?? [];
@@ -40,6 +93,15 @@ export function renderDryRun(plan, opts = {}) {
     const line = renderLatestPrSkipLine(skip);
     if (line) lines.push(line);
   }
+  for (const skip of skipped) {
+    const line = renderNotMergedSkipLine(skip, { now });
+    if (line) lines.push(line);
+  }
+  if (plan.ghDegraded) {
+    lines.push(
+      `${TAG} ⚠️ gh probe degraded — candidates rely on git-only signals (ancestry + content-equivalence) for this run`,
+    );
+  }
   return lines;
 }
 
@@ -47,7 +109,8 @@ export function renderDryRun(plan, opts = {}) {
  * Pure: render a single latest-PR-state skip line. Returns null when the
  * skip reason is not one of the latest-PR family — `renderDryRun` filters
  * by truthy return value so unrelated skip reasons (`protected`,
- * `current-head`, `filtered`, `not-merged`) stay quiet.
+ * `current-head`, `filtered`) stay quiet here. `not-merged` gets its own
+ * renderer ({@link renderNotMergedSkipLine}).
  *
  * @param {{ branch: string, reason: string, prNumber?: number, tipSha?: string, mergedSha?: string }} skip
  * @returns {string | null}
@@ -64,7 +127,10 @@ export function renderLatestPrSkipLine(skip) {
   if (skip.reason === 'tip-diverged-from-merge') {
     const tip = skip.tipSha ? skip.tipSha.slice(0, 7) : '<unknown>';
     const merged = skip.mergedSha ? skip.mergedSha.slice(0, 7) : '<unknown>';
-    return `${TAG} ⏭️  ${skip.branch} skipped — tip ${tip} diverges from ${prRef}'s merged ${merged} (post-merge force-push)`;
+    return (
+      `${TAG} ⏭️  ${skip.branch} skipped — tip ${tip} diverges from ${prRef}'s merged ${merged} (post-merge force-push); ` +
+      `resolve by deleting manually (\`git branch -D ${skip.branch}\`) or pushing the follow-up commit`
+    );
   }
   if (skip.reason === 'latest-pr-unknown-state') {
     return `${TAG} ⏭️  ${skip.branch} skipped — ${prRef} has an unrecognized state`;
@@ -160,6 +226,7 @@ export function buildJsonEnvelope({
     baseBranch,
     candidates: plan.candidates,
     skipped: plan.skipped,
+    ghDegraded: plan.ghDegraded ?? false,
     worktrees: r.worktrees,
     local: r.local,
     remote: r.remote,