mandrel 2.53.0 → 2.55.0

package/.agents/scripts/lib/orchestration/file-assumptions.js

@@ -15,13 +15,19 @@
  *
  * Rules (one error per mismatched path):
  *   - `creates`            + path **exists**  → error (Story would clobber).
- *   - `refactors-existing` (via `changes`) + path **absent** →
- *     auto-normalized to `creates` with a logged warning (#4496 fix 5):
- *     a refactor declaration against a base-untracked path is
- *     deterministically a create, so rejecting it only forces a
- *     reject→amend→re-persist cycle for a mechanical rewrite. Genuine
- *     mismatches keep failing — a `references`-sourced `refactors-existing`
- *     on an absent path is a missing read dependency and stays an error.
+ *   - `refactors-existing` (via `changes`) + path **absent and never
+ *     tracked** at `baseBranchRef` → auto-normalized to `creates` with a
+ *     logged warning (#4496 fix 5): a refactor declaration against a
+ *     path with no history is deterministically a create, so rejecting it
+ *     only forces a reject→amend→re-persist cycle for a mechanical rewrite.
+ *   - `refactors-existing` (via `changes`) + path **absent but present in
+ *     that ref's history** → hard error naming the removing commit and, when
+ *     git detects one, the rename target (Story #5265). The normalization
+ *     rescues a mislabel; it must not rescue a plan authored against a file
+ *     the tree deleted, which propagates into acceptance criteria nothing
+ *     can satisfy. Genuine mismatches keep failing — a `references`-sourced
+ *     `refactors-existing` on an absent path is a missing read dependency
+ *     and stays an error.
  *   - `exists`             + path **absent** → error (read dependency missing).
  *   - `deletes`            + path **absent** → error (nothing to delete).
  *
@@ -78,6 +84,73 @@ function defaultGitRunner({ baseBranchRef, path, cwd }) {
   return result.status === 0;
 }
 
+/**
+ * Parse the `--name-status` line for the commit that last touched `path`
+ * into the history verdict (Story #5265).
+ *
+ * `-M` reports a rename as `R<score>\t<old>\t<new>`. The scan is run over the
+ * commit's **whole** rename diff rather than a pathspec-limited one on
+ * purpose: rename detection pairs a delete with an add, and restricting the
+ * pathspec to the source path filters the add out, so git falls back to
+ * reporting a plain `D` and the target is lost. No matching `R` line means
+ * the path was deleted outright — still a removal, just without a successor
+ * to name.
+ *
+ * @param {string} stdout
+ * @param {string} path
+ * @returns {string|null} The rename target, or `null`.
+ */
+function parseRenameTarget(stdout, path) {
+  for (const line of String(stdout ?? '').split('\n')) {
+    const fields = line.split('\t');
+    if (fields.length < 3) continue;
+    if (!fields[0].startsWith('R')) continue;
+    if (fields[1].trim() !== path) continue;
+    const target = fields[2].trim();
+    if (target) return target;
+  }
+  return null;
+}
+
+/**
+ * Default git **history** probe: did `baseBranchRef` ever track `path`, and
+ * if so, which commit stopped tracking it (Story #5265)?
+ *
+ * The existence probe above cannot tell a mechanical mislabel ("extend a file
+ * I am actually creating") from a plan authored against stale documentation
+ * ("extend a file deleted three weeks ago"). Both look identical at the tip —
+ * the path is absent — and only history separates them. Injectable exactly
+ * like {@link defaultGitRunner} so the discrimination is unit-testable with
+ * no repository fixture.
+ *
+ * Fails **open**: an unreadable ref, a git that errors, or an empty history
+ * all report `hadHistory: false`, which preserves the pre-#5265
+ * auto-normalisation rather than manufacturing a hard error out of a probe
+ * failure.
+ *
+ * @param {{ baseBranchRef: string, path: string, cwd?: string }} opts
+ * @returns {{ hadHistory: boolean, commit: string|null, renamedTo: string|null }}
+ */
+function defaultHistoryRunner({ baseBranchRef, path, cwd }) {
+  const absent = { hadHistory: false, commit: null, renamedTo: null };
+  const root = cwd ?? process.cwd();
+  const last = gitSpawn(root, 'rev-list', '-1', baseBranchRef, '--', path);
+  const commit = last.status === 0 ? String(last.stdout ?? '').trim() : '';
+  if (!commit) return absent;
+  const status = gitSpawn(
+    root,
+    'show',
+    '--name-status',
+    '-M',
+    '--diff-filter=R',
+    '--format=',
+    commit,
+  );
+  const renamedTo =
+    status.status === 0 ? parseRenameTarget(status.stdout, path) : null;
+  return { hadHistory: true, commit, renamedTo };
+}
+
 /**
  * Pull every `(path, assumption, source)` triple from a Story body.
  * `source` is one of `'changes' | 'references'` so error messages can
@@ -168,8 +241,11 @@ export function hasLegacyChangeBullets(story) {
  *   - `'predecessor-conflict'` — wave-aware: a concurrent Story (no
  *     `depends_on` ordering) also creates this path. Cross-references the
  *     shared-editor conflict finding rather than re-deriving its prose.
+ *   - `'present-was-removed'` — the base branch **once tracked** this path
+ *     and no longer does (Story #5265). Names the removing commit, and the
+ *     rename target when git detected one.
  *
- * @param {{ slug: string, source: string, path: string, assumption: string, expected: string, producerSlug?: string }} mismatch
+ * @param {{ slug: string, source: string, path: string, assumption: string, expected: string, producerSlug?: string, removedInCommit?: string, renamedTo?: string|null }} mismatch
  * @returns {string}
  */
 function renderMismatch({
@@ -179,6 +255,8 @@ function renderMismatch({
   assumption,
   expected,
   producerSlug,
+  removedInCommit,
+  renamedTo,
 }) {
   if (expected === 'refactors-existing') {
     return `"${slug}" → body.${source} declares assumption="${assumption}" for ${path} but predecessor Story "${producerSlug}" already creates that path — declare assumption="refactors-existing" instead (the file exists in the simulated post-predecessor tree).`;
@@ -189,9 +267,48 @@ function renderMismatch({
   if (expected === 'present') {
     return `"${slug}" → body.${source} declares assumption="${assumption}" for ${path} but the path is absent at the base branch.`;
   }
+  if (expected === 'present-was-removed') {
+    return renderRemovedPathMismatch({
+      slug,
+      source,
+      path,
+      assumption,
+      removedInCommit,
+      renamedTo,
+    });
+  }
   return `"${slug}" → body.${source} declares assumption="${assumption}" for ${path} but the path already exists at the base branch.`;
 }
 
+/**
+ * Render the stale-documentation refusal (Story #5265).
+ *
+ * The auto-normalisation this replaces is right for a path that never
+ * existed and wrong for one the base branch used to track: "extend
+ * `<deleted file>`" is not a mechanical mislabel a rewrite can fix — it is a
+ * plan authored against documentation the tree has outgrown, and rewriting it
+ * to `creates` would resurrect a file somebody deliberately removed and
+ * propagate the stale premise into acceptance criteria nothing can satisfy.
+ * The removing commit is named because it is the shortest route to *what
+ * replaced it*.
+ *
+ * @param {{ slug: string, source: string, path: string, assumption: string, removedInCommit?: string, renamedTo?: string|null }} mismatch
+ * @returns {string}
+ */
+function renderRemovedPathMismatch({
+  slug,
+  source,
+  path,
+  assumption,
+  removedInCommit,
+  renamedTo,
+}) {
+  const successor = renamedTo
+    ? ` git detects it was renamed to ${renamedTo} — retarget the declaration there.`
+    : ' Retarget the declaration at the path that replaced it, or declare assumption="creates" if this Story genuinely reintroduces the file.';
+  return `"${slug}" → body.${source} declares assumption="${assumption}" for ${path} but the base branch removed that path in commit ${removedInCommit}. The plan is authored against stale documentation, not a mislabelled create, so it is refused rather than normalized.${successor}`;
+}
+
 /**
  * Render an auto-normalization (#4496 fix 5) into a stable warning string.
  * Kept pure and exported through the report so callers log a
@@ -290,12 +407,21 @@ function predecessorMutator(index, path, predecessors) {
  * @param {object}   opts
  * @param {object[]} opts.tickets
  * @param {string}   opts.baseBranchRef
- * @param {Function} [opts.gitRunner]
+ * @param {Function} [opts.gitRunner]      Existence probe at `baseBranchRef`.
+ * @param {Function} [opts.historyRunner]  History probe (Story #5265),
+ *   injectable exactly like `gitRunner`; returns
+ *   `{ hadHistory, commit, renamedTo }`.
  * @param {string}   [opts.cwd]
- * @returns {{ errors: string[], warnings: string[], mismatches: Array }}
+ * @returns {{ errors: string[], warnings: string[], mismatches: Array, normalizations: Array }}
  */
 export function validateStoryFileAssumptions(opts) {
-  const { tickets, baseBranchRef, gitRunner = defaultGitRunner, cwd } = opts;
+  const {
+    tickets,
+    baseBranchRef,
+    gitRunner = defaultGitRunner,
+    historyRunner = defaultHistoryRunner,
+    cwd,
+  } = opts;
   if (!baseBranchRef || typeof baseBranchRef !== 'string') {
     throw new Error(
       'validateStoryFileAssumptions: baseBranchRef is required and must be a string.',
@@ -307,6 +433,15 @@ export function validateStoryFileAssumptions(opts) {
   const mismatches = [];
   const normalizations = [];
   const probeCache = new Map();
+  const historyCache = new Map();
+  const probeHistory = (path) =>
+    probeRemoval({
+      historyRunner,
+      baseBranchRef,
+      path,
+      cwd,
+      cache: historyCache,
+    });
 
   // Wave-aware setup (Story #3960): transitive predecessor sets over the
   // story-level `depends_on` graph, plus per-path create/delete indices so
@@ -371,13 +506,14 @@ export function validateStoryFileAssumptions(opts) {
         // Auto-normalization (#4496 fix 5): a deterministic
         // `refactors-existing`→`creates` rewrite is a warning, never a
         // rejection — genuine mismatches keep flowing to `errors`.
-        if (mismatch.normalizedTo === 'creates') {
-          normalizations.push(mismatch);
-          warnings.push(renderNormalization(mismatch));
+        const { kind, finding } = classifyMismatch(mismatch, probeHistory);
+        if (kind === 'normalization') {
+          normalizations.push(finding);
+          warnings.push(renderNormalization(finding));
           continue;
         }
-        mismatches.push(mismatch);
-        errors.push(renderMismatch(mismatch));
+        mismatches.push(finding);
+        errors.push(renderMismatch(finding));
         continue;
       }
       // Wave-aware concurrent-create check (Story #3960): two Stories with
@@ -413,6 +549,72 @@ export function validateStoryFileAssumptions(opts) {
   return { errors, warnings, mismatches, normalizations };
 }
 
+/**
+ * Route one mismatch to the errors channel or the normalization channel
+ * (Story #5265).
+ *
+ * `checkAssumption` marks a `changes`-sourced `refactors-existing` on an
+ * absent path with `normalizedTo: 'creates'` — the #4496 rescue. Whether that
+ * rescue actually applies is a *history* question the pure rules table cannot
+ * answer, so it is resolved here: no history keeps the rescue, history ending
+ * in a removal converts it into a refusal that names the commit.
+ *
+ * @param {object} mismatch
+ * @param {(path: string) => ({ commit: string|null, renamedTo: string|null }|null)} probeHistory
+ * @returns {{ kind: 'error'|'normalization', finding: object }}
+ */
+function classifyMismatch(mismatch, probeHistory) {
+  if (mismatch.normalizedTo !== 'creates') {
+    return { kind: 'error', finding: mismatch };
+  }
+  const removal = probeHistory(mismatch.path);
+  if (removal === null) return { kind: 'normalization', finding: mismatch };
+  return {
+    kind: 'error',
+    finding: {
+      slug: mismatch.slug,
+      source: mismatch.source,
+      path: mismatch.path,
+      assumption: mismatch.assumption,
+      expected: 'present-was-removed',
+      actual: 'removed',
+      removedInCommit: removal.commit,
+      renamedTo: removal.renamedTo,
+    },
+  };
+}
+
+/**
+ * Memoized history probe: `{ commit, renamedTo }` when `baseBranchRef` once
+ * tracked `path` and no longer does, `null` when it never did (Story #5265).
+ *
+ * One cache per validation run, keyed on the path, because a plan commonly
+ * declares the same path across several Stories and the probe costs two git
+ * processes. A runner that throws is absorbed as "no history": the whole
+ * point of the discrimination is to *add* a refusal for a provable stale
+ * declaration, never to convert a probe failure into one.
+ *
+ * @param {{ historyRunner: Function, baseBranchRef: string, path: string, cwd?: string, cache: Map<string, object|null> }} args
+ * @returns {{ commit: string|null, renamedTo: string|null }|null}
+ */
+function probeRemoval({ historyRunner, baseBranchRef, path, cwd, cache }) {
+  if (cache.has(path)) return cache.get(path);
+  let verdict = null;
+  try {
+    const report = historyRunner({ baseBranchRef, path, cwd });
+    if (report?.hadHistory) {
+      verdict = {
+        commit: report.commit ?? null,
+        renamedTo: report.renamedTo ?? null,
+      };
+    }
+  } catch {
+    verdict = null;
+  }
+  cache.set(path, verdict);
+  return verdict;
+}
+
 /**
  * Find the first *concurrent* co-creator of `path` for the Story `slug`:
  * another Story that declares `creates` on the same path with no

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

@@ -50,6 +50,19 @@ import { parsePrunedRefs } from './prune.js';
 
 const TAG = '[git-cleanup]';
 
+/**
+ * The detection signal the weak-signal guard withholds on, and the reason
+ * it records (Story #5283). `content-merged` comes from
+ * `git merge-tree --write-tree` finding the branch's changes already
+ * present in the base by *some* route — it cannot tell a squash-merge
+ * from a branch whose every change was independently reverted, so it is
+ * the one signal an unattended `--yes` run must not delete a remote ref
+ * on. Named here so the guard, the renderer and the tests share one
+ * spelling.
+ */
+const WEAK_SIGNAL_DETECTOR = 'content-merged';
+const WEAK_SIGNAL_REASON = 'weak-signal-needs-confirmation';
+
 function evaluateLocalBranch({
   branch,
   baseBranch,
@@ -167,16 +180,45 @@ function evaluateLocalBranch({
  * collections. Deletion is unchanged: a remote-only candidate still needs
  * `--remote`, whichever signal detected it.
  */
+/**
+ * Normalize whatever `prIndexFn` returned into the
+ * `{ index, complete }` pair {@link probeAllPrs} emits (Story #5283).
+ *
+ * The seam is injectable, and a caller that hands back a bare `Map` —
+ * every pre-#5283 double does — means "here is the page" without
+ * claiming it was exhaustive. That reads as `complete: false`, which
+ * keeps the per-branch fallback armed: the conservative direction, since
+ * a wrongly-complete page suppresses a probe that would have found a
+ * real PR.
+ *
+ * @param {unknown} value
+ * @returns {{ index: Map, complete: boolean }}
+ */
+function normalizePrIndex(value) {
+  if (value instanceof Map) return { index: value, complete: false };
+  return {
+    index: value?.index instanceof Map ? value.index : new Map(),
+    complete: value?.complete === true,
+  };
+}
+
 function buildGuardedPrProbe({ cwd, prIndexFn, prFallback, onDegrade }) {
-  let prIndex;
+  let bulk;
   try {
-    prIndex = prIndexFn(cwd);
+    bulk = normalizePrIndex(prIndexFn(cwd));
   } catch (err) {
     onDegrade(err);
-    prIndex = new Map();
+    bulk = { index: new Map(), complete: false };
   }
+  const { index: prIndex, complete } = bulk;
   return (branch, c) => {
     if (prIndex.has(branch)) return prIndex.get(branch);
+    // Story #5283: a complete page listed every PR in the repo, so this
+    // head ref demonstrably has none. Probing it per-branch spends a `gh`
+    // spawn to be told the same thing — once per PR-less branch, which on
+    // a checkout full of local scratch branches is the whole point of the
+    // bulk fetch undone.
+    if (complete) return null;
     try {
       return prFallback(branch, c);
     } catch (err) {
@@ -302,6 +344,21 @@ function worktreeRootFor(cand) {
 /**
  * Pure-ish: execute the branch reap plan.
  *
+ * ## Weak-signal guard (Story #5283)
+ *
+ * `skipWeakSignal` withholds the **remote** delete of any candidate
+ * detected only by content-equivalence, recording it on `remote[]` as
+ * `{ skipped: true, reason: 'weak-signal-needs-confirmation' }` instead
+ * of issuing `git push --delete`. The branch-phase driver arms it on the
+ * `--yes` path unless the operator passed `--include-content-merged`,
+ * mirroring the stash phase's `--drop-stashes` allowlist: an unattended
+ * run may not destroy a remote ref on the weakest merge signal without
+ * being told to. The interactive path leaves it disarmed — the prompt
+ * already names the weak-signal count and the operator answered it.
+ *
+ * Local deletion is deliberately untouched: a local ref is recoverable
+ * from the remote, which is exactly what the guard preserves.
+ *
  * Ref-reap is decoupled from worktree-reap (Story #3598): every
  * already-merged candidate has its local ref (and remote ref, in
  * `--remote` mode) deleted regardless of whether its worktree directory
@@ -319,12 +376,21 @@ export function executeCleanup(ctx) {
     remote,
     removeWorktreeFn = removeWorktree,
     deleteLocalFn = (b, c) => deleteBranchLocal(b, { cwd: c, force: true }),
-    deleteRemoteFn = (b, c) => deleteBranchRemote(b, { cwd: c }),
+    deleteRemoteFn = (b, c, r) => deleteBranchRemote(b, { cwd: c, remote: r }),
     pruneRemoteFn = (c, r) => pruneRemoteTracking(c, r, parsePrunedRefs),
     recordPendingCleanupFn = recordPendingCleanup,
     remoteName = 'origin',
+    skipWeakSignal = false,
     logger = Logger,
   } = ctx;
+  // The remote name belongs to `executeCleanup`, not to the per-candidate
+  // reap helper, so bind it here (Story #5283). The default deleter used
+  // to drop it and let `deleteBranchRemote` fall back to `origin`, which
+  // sent every `--remote` delete of an `upstream`-configured checkout at
+  // the wrong remote. Binding — rather than closing over it — also hands
+  // an injected deleter the same `(branch, cwd, remote)` triple the git
+  // invocation is built from, so a test can see which remote was targeted.
+  const boundDeleteRemote = (b, c) => deleteRemoteFn(b, c, remoteName);
   const worktrees = [];
   const local = [];
   const remoteResults = [];
@@ -347,11 +413,31 @@ export function executeCleanup(ctx) {
       worktreeRoot: worktreeRootFor(cand),
     });
     if (!reapLocalRef({ cand, deleteLocalFn, cwd, local, failures })) continue;
-    if (remote)
-      reapRemoteRef({ cand, deleteRemoteFn, cwd, remoteResults, failures });
+    if (!remote) continue;
+    if (skipWeakSignal && cand.detectedBy === WEAK_SIGNAL_DETECTOR) {
+      remoteResults.push({
+        branch: cand.branch,
+        ok: true,
+        skipped: true,
+        reason: WEAK_SIGNAL_REASON,
+        alreadyGone: false,
+        detectedBy: cand.detectedBy,
+      });
+      continue;
+    }
+    reapRemoteRef({
+      cand,
+      deleteRemoteFn: boundDeleteRemote,
+      cwd,
+      remoteResults,
+      failures,
+    });
   }
   let prune = null;
-  if (remote && remoteResults.length > 0) {
+  // Prune drops the tracking refs a remote *delete* left behind. A run
+  // whose every remote candidate was withheld deleted nothing, so there
+  // is nothing stale to prune and no reason to spend the fetch.
+  if (remote && remoteResults.some((r) => !r.skipped)) {
     prune = buildPruneSummary({ pruneRemoteFn, cwd, remoteName, failures });
   }
   return {

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

@@ -333,13 +333,28 @@ export function probeLatestPr(branch, cwd, runGh = defaultGhRunner) {
  * fallback for head refs absent from this page (a branch whose PR fell
  * outside the `--limit` window).
  *
- * Returns an empty Map on any failure (non-array, empty, or malformed
+ * Returns an empty index on any failure (non-array, empty, or malformed
  * JSON) so the caller transparently falls back to per-branch probing.
  *
+ * ## `complete` — when absence from the page is proof (Story #5283)
+ *
+ * The returned `complete` flag says whether the page enumerated **every**
+ * PR in the repository: true when `gh` returned fewer rows than the
+ * `--limit` it was given, which is the only way to know the window did
+ * not truncate. On a complete page a head ref's absence is not "the PR
+ * fell outside the window" — it is proof that no PR covers that ref at
+ * all, so the caller's per-branch fallback can only re-derive the same
+ * `null` at the cost of one `gh` spawn per PR-less branch.
+ *
+ * Every failure mode reports `complete: false`, because an unusable page
+ * proves nothing: empty stdout (a degraded `gh`), unparseable JSON, and a
+ * non-array payload must all leave the fallback armed. A *parsed* empty
+ * array is genuinely complete — a repository with no PRs at all.
+ *
  * @param {string} cwd
  * @param {(args: string[], opts: { cwd: string }) => string} runGh
  * @param {number} limit  Max rows to fetch in the single page (default 1000).
- * @returns {Map<string, { number: number, state: string, mergedAt: string|null, closedAt: string|null, headRefOid: string|null }>}
+ * @returns {{ index: Map<string, { number: number, state: string, mergedAt: string|null, closedAt: string|null, headRefOid: string|null }>, complete: boolean }}
  */
 export function probeAllPrs(cwd, runGh = defaultGhRunner, limit = 1000) {
   const out = runGh(
@@ -357,14 +372,15 @@ export function probeAllPrs(cwd, runGh = defaultGhRunner, limit = 1000) {
   );
   const trimmed = (out ?? '').trim();
   const index = new Map();
-  if (!trimmed) return index;
+  const truncated = { index, complete: false };
+  if (!trimmed) return truncated;
   let parsed;
   try {
     parsed = JSON.parse(trimmed);
   } catch {
-    return index;
+    return truncated;
   }
-  if (!Array.isArray(parsed)) return index;
+  if (!Array.isArray(parsed)) return truncated;
   for (const row of parsed) {
     const headRefName =
       typeof row?.headRefName === 'string' ? row.headRefName : null;
@@ -379,7 +395,7 @@ export function probeAllPrs(cwd, runGh = defaultGhRunner, limit = 1000) {
       headRefOid: row.headRefOid ?? null,
     });
   }
-  return index;
+  return { index, complete: parsed.length < limit };
 }
 
 const SHA_RE = /^[0-9a-f]{7,40}$/i;

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

@@ -22,10 +22,23 @@ const CLI_OPTIONS = {
   include: { type: 'string', multiple: true, default: [] },
   exclude: { type: 'string', multiple: true, default: [] },
   'drop-stashes': { type: 'string', multiple: true, default: [] },
+  'include-content-merged': { type: 'boolean', default: false },
   base: { type: 'string' },
   cwd: { type: 'string' },
 };
 
+/**
+ * Normalize a repeatable flag's parsed value to a list. `parseArgs` yields
+ * an array for a `multiple: true` option, but only once the flag appears;
+ * this keeps the three repeatable flags reading identically.
+ *
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function asList(value) {
+  return Array.isArray(value) ? value : [];
+}
+
 function resolveActivePhases(values) {
   const anyPhaseFlag =
     values['fast-forward-main'] === true ||
@@ -44,6 +57,14 @@ function resolveActivePhases(values) {
 /**
  * Pure: parse argv into the normalized CLI option bag.
  *
+ * Every flag the CLI honours MUST be declared in {@link CLI_OPTIONS}:
+ * `parseArgs` runs with `strict: false`, so an undeclared flag is not
+ * rejected — it is silently absorbed and the option it was meant to set
+ * stays at its default. For `--include-content-merged` that failure mode
+ * is destructive in the quiet direction's opposite: the operator asks to
+ * include the weak-signal candidates, the flag is dropped, and the run
+ * withholds them anyway.
+ *
  * @param {string[]} argv
  * @returns {{
  *   dryRun: boolean,
@@ -55,6 +76,7 @@ function resolveActivePhases(values) {
  *   include: string[],
  *   exclude: string[],
  *   dropStashes: string[],
+ *   includeContentMerged: boolean,
  *   base: string|null,
  *   cwd: string|null,
  * }}
@@ -73,11 +95,10 @@ export function parseCleanupArgs(argv) {
     yes: values.yes === true,
     json: values.json === true,
     phases: resolveActivePhases(values),
-    include: Array.isArray(values.include) ? values.include : [],
-    exclude: Array.isArray(values.exclude) ? values.exclude : [],
-    dropStashes: Array.isArray(values['drop-stashes'])
-      ? values['drop-stashes']
-      : [],
+    include: asList(values.include),
+    exclude: asList(values.exclude),
+    dropStashes: asList(values['drop-stashes']),
+    includeContentMerged: values['include-content-merged'] === true,
     base: typeof values.base === 'string' ? values.base : null,
     cwd: typeof values.cwd === 'string' ? values.cwd : null,
   };

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

@@ -218,7 +218,8 @@ function countActionableCandidates(candidates, remote) {
  *
  * @param {object} state
  * @param {object} state.plan         Output of `planCleanup`.
- * @param {object} state.opts         CLI options (`dryRun`, `yes`, `remote`).
+ * @param {object} state.opts         CLI options (`dryRun`, `yes`, `remote`,
+ *                                    `includeContentMerged`).
  * @param {string} state.cwd          Working directory.
  */
 export function decideBranchPhase(state) {
@@ -254,7 +255,17 @@ export function decideBranchPhase(state) {
       executeArgs,
     };
   }
-  return { kind: 'execute', plan, executeArgs };
+  // Story #5283: the unattended arm. Nobody saw the weak-signal note
+  // above, so a `content-merged` candidate's remote ref is withheld
+  // unless the operator opted in with `--include-content-merged`.
+  return {
+    kind: 'execute',
+    plan,
+    executeArgs: {
+      ...executeArgs,
+      skipWeakSignal: opts.includeContentMerged !== true,
+    },
+  };
 }
 
 /**

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

@@ -227,18 +227,40 @@ export function renderLatestPrSkipLine(skip) {
   return null;
 }
 
-/** Pure: render a per-branch execution line. */
+/**
+ * Remedy text per withheld-delete reason (Story #5283). A withheld entry
+ * that named no way to proceed would read as an unexplained refusal, so
+ * every reason the executor can record gets its own next step here.
+ */
+const WITHHELD_HINTS = {
+  'weak-signal-needs-confirmation':
+    'detected only by content-equivalence; re-run interactively or pass --include-content-merged',
+};
+
+/**
+ * Pure: render a per-branch execution line.
+ *
+ * An entry marked `skipped` is a delete the executor deliberately
+ * withheld rather than one it attempted — it must not render with the
+ * `✅` of a completed reap, which is exactly the misreport that would let
+ * an operator believe an unattended run had cleaned up a ref it left
+ * standing.
+ */
 export function renderExecutionLine(entry, scope) {
-  const icon = entry.ok ? '✅' : '❌';
   const label = scope.padEnd(8);
-  const tag =
+  const tagName =
     scope === 'local' || scope === 'remote' ? entry.branch : entry.path;
+  if (entry.skipped) {
+    const hint = WITHHELD_HINTS[entry.reason];
+    return `${TAG} ⏭️  ${label} ${tagName} — withheld${hint ? ` (${hint})` : ` (${entry.reason})`}`;
+  }
+  const icon = entry.ok ? '✅' : '❌';
   const note = entry.alreadyGone
     ? ' (already gone)'
     : entry.dirty
       ? ' (forced — was dirty)'
       : '';
-  return `${TAG} ${icon} ${label} ${tag}${note}`;
+  return `${TAG} ${icon} ${label} ${tagName}${note}`;
 }
 
 /** Pure: render the optional prune line. */
@@ -286,7 +308,15 @@ export function renderExecutionSummary(result) {
     deferredCount > 0
       ? ` (${deferredCount} worktree(s) deferred to sweep)`
       : '';
-  return `${TAG} ✅ Reaped ${result.local.length} local + ${result.remote.length} remote + ${result.worktrees.length} worktree(s)${pruneNote}.${deferredNote}`;
+  // Story #5283: withheld remote entries are recorded on `remote[]` but
+  // were never deleted — counting them would overstate the reap.
+  const remoteDeleted = result.remote.filter((r) => !r.skipped).length;
+  const withheldCount = result.remote.length - remoteDeleted;
+  const withheldNote =
+    withheldCount > 0
+      ? ` (${withheldCount} remote delete(s) withheld — weaker signal)`
+      : '';
+  return `${TAG} ✅ Reaped ${result.local.length} local + ${remoteDeleted} remote + ${result.worktrees.length} worktree(s)${pruneNote}.${deferredNote}${withheldNote}`;
 }
 
 const EMPTY_RESULT = Object.freeze({