mandrel 1.87.0 → 1.89.0

package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js

@@ -0,0 +1,188 @@
+/**
+ * emit-merge-unlanded.js — Story #4426 (Epic #4425, slice 1: foundation).
+ *
+ * Programmatic helper that appends a single `merge.unlanded` NDJSON
+ * record to the lifecycle ledger whenever a headless delivery run
+ * finishes its work without a confirmed merge. Pattern mirrors
+ * `emit-story-heartbeat.js`: direct schema validation via Ajv followed by
+ * a synchronous `appendFileSync` — this event is NOT routed through the
+ * bus (unlike `emit-loop-tick.js`) because it can fire from either the
+ * epic-path finalize flow (which already owns an Epic-scoped bus
+ * instance for its own run) or the standalone `single-story-close` flow,
+ * which has no bus at all. A bare append keeps both call sites simple
+ * and dependency-free.
+ *
+ * Ledger destination is scope-driven (Story #4426 AC4):
+ *   - `scope: 'epic'`  → `epicLedgerPath(ticketId)` — the same
+ *     `temp/epic-<id>/lifecycle.ndjson` every other Epic-scoped event
+ *     lands in. `ticketId` is the epicId.
+ *   - `scope: 'story'` → `storyLedgerPath(null, ticketId)` — the
+ *     standalone story-scope destination
+ *     `temp/standalone/stories/story-<id>/lifecycle.ndjson`. `ticketId`
+ *     is the storyId. The standalone `single-story-close` path has no
+ *     parent Epic to anchor a `temp/epic-<id>/` directory to, mirroring
+ *     the `eid === null` standalone convention `signalsFile` already
+ *     uses for Story-level signals.
+ *
+ * A caller may always override the destination via `ledgerPath` (tests,
+ * or a future caller with a non-default temp layout).
+ *
+ * Distinct from:
+ *   - `epic.merge.blocked` — AutomergePredicate's "not safe to arm yet"
+ *     signal, evaluated BEFORE arming. `merge.unlanded` fires AFTER a
+ *     delivery flow has already finished trying and gives up.
+ *   - `epic.blocked` / `story.blocked` — the generic `agent::blocked`
+ *     transition signal. `merge.unlanded` is the merge-specific
+ *     diagnosis a `*.blocked` transition is typically paired with, not a
+ *     replacement for it.
+ *
+ * The emit is best-effort in the sense that a failure to append MUST NOT
+ * mask the underlying blocked-state transition the caller is already
+ * driving — callers should treat this the same way
+ * `emitStoryHeartbeat` documents: catch, log, and proceed with the label
+ * flip / friction comment regardless.
+ *
+ * Schema contract (merge.unlanded.schema.json):
+ *   { event, scope, ticketId, prNumber, blockClass, reason,
+ *     elapsedSeconds, timestamp? }
+ *
+ * The schema declares `additionalProperties: false`, so this emitter's
+ * signature is deliberately narrow: only the schema-allowed fields are
+ * accepted. `blockClass` MUST be one of the four classes named in
+ * `merge-block-class.js` — pass the classifier's verdict straight
+ * through (`classifyMergeBlock(...)` returns `{ blockClass, reason }`).
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { epicLedgerPath, storyLedgerPath } from '../../config/temp-paths.js';
+import { isValidBlockClass } from '../merge-block-class.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+  'merge.unlanded.schema.json',
+);
+
+const VALID_SCOPES = new Set(['epic', 'story']);
+
+let _validator;
+
+function getValidator() {
+  if (_validator) return _validator;
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  _validator = ajv.compile(schema);
+  return _validator;
+}
+
+/**
+ * Append exactly one `merge.unlanded` NDJSON record to the resolved
+ * lifecycle ledger.
+ *
+ * @param {object} opts
+ * @param {'epic'|'story'} opts.scope  Which delivery path is reporting the
+ *                                     unlanded merge.
+ * @param {number} opts.ticketId       epicId when `scope === 'epic'`,
+ *                                     storyId when `scope === 'story'`.
+ * @param {number} opts.prNumber       The PR number that did not land.
+ * @param {string} opts.blockClass     One of the four
+ *                                     `merge-block-class.js` classes.
+ * @param {string} opts.reason         Free-form diagnosis detail — pass
+ *                                     the classifier's `reason`.
+ * @param {number} opts.elapsedSeconds Elapsed watch/poll time when the
+ *                                     run gave up.
+ * @param {string} [opts.timestamp]    ISO-8601 wall clock. Defaults to
+ *                                     now().
+ * @param {object} [opts.config]       Optional resolved config for
+ *                                     tempRoot.
+ * @param {string} [opts.ledgerPath]   Override for tests / non-default
+ *                                     layouts.
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitMergeUnlanded(opts) {
+  const {
+    scope,
+    ticketId,
+    prNumber,
+    blockClass,
+    reason,
+    elapsedSeconds,
+    timestamp = new Date().toISOString(),
+    config,
+    ledgerPath: ledgerPathOverride,
+  } = opts ?? {};
+
+  if (!VALID_SCOPES.has(scope)) {
+    throw new Error(
+      `emitMergeUnlanded: scope "${scope}" must be one of: ${[...VALID_SCOPES].join(', ')}`,
+    );
+  }
+  if (!Number.isInteger(ticketId) || ticketId < 1) {
+    throw new Error('emitMergeUnlanded: ticketId must be a positive integer');
+  }
+  if (!Number.isInteger(prNumber) || prNumber < 1) {
+    throw new Error('emitMergeUnlanded: prNumber must be a positive integer');
+  }
+  if (!isValidBlockClass(blockClass)) {
+    throw new Error(
+      `emitMergeUnlanded: blockClass "${blockClass}" is not a recognised merge-block-class value`,
+    );
+  }
+  if (typeof reason !== 'string' || reason.length === 0) {
+    throw new Error('emitMergeUnlanded: reason must be a non-empty string');
+  }
+  if (typeof elapsedSeconds !== 'number' || elapsedSeconds < 0) {
+    throw new Error(
+      'emitMergeUnlanded: elapsedSeconds must be a non-negative number',
+    );
+  }
+
+  const payload = {
+    event: 'merge.unlanded',
+    scope,
+    ticketId,
+    prNumber,
+    blockClass,
+    reason,
+    elapsedSeconds,
+    timestamp,
+  };
+
+  const validator = getValidator();
+  if (!validator(payload)) {
+    const detail = (validator.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(
+      `emitMergeUnlanded: payload failed schema validation: ${detail}`,
+    );
+  }
+
+  const ledgerPath =
+    ledgerPathOverride ??
+    (scope === 'epic'
+      ? epicLedgerPath(ticketId, config)
+      : storyLedgerPath(null, ticketId, config));
+  mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const record = {
+    kind: 'emitted',
+    ts: timestamp,
+    event: 'merge.unlanded',
+    payload,
+  };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+  return { ledgerPath, record };
+}

package/.agents/scripts/lib/orchestration/lifecycle/listeners/README.md

@@ -22,6 +22,12 @@ entrypoint the standalone `lifecycle-emit.js` CLI shells in for
   the PR's `mergeCommit` is observed, then emits `epic.merge.confirmed`.
 - `cleaner.js` — archives `temp/epic-<id>/` and emits the terminal
   `epic.cleanup.* → epic.complete` sequence on `epic.merge.confirmed`.
+- `label-transitioner.js` — flips the Epic ticket to `agent::done` (and
+  closes it as completed, idempotently) on `epic.complete`. Skipped when
+  no provider is wired. Re-homed onto this chain after the 2026-07-11
+  incident (merged Epics stranding at `agent::executing`): the original
+  LabelTransitioner died with the in-process runner stratum (#3936) and
+  the flip had no owner.
 - `checkpoint-pointer-writer.js` — persists `{ lastCompletedSeqId, phase }`
   on every `*.end` event.
 

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-armer.js

@@ -64,7 +64,7 @@ import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
 export function ghPrViewAutoMerge({ prUrl, cwd, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
-    ['pr', 'view', prUrl, '--json', 'autoMergeRequest'],
+    ['pr', 'view', prUrl, '--json', 'autoMergeRequest,mergeCommit'],
     { cwd, encoding: 'utf-8', shell: false },
   );
   return {
@@ -110,9 +110,10 @@ export function ghPrMergeAuto({
 }
 
 /**
- * Pure: parse `gh pr view --json autoMergeRequest` output. The field
- * is `null` when auto-merge is NOT armed; a non-null object means a
- * prior arm is in place. Returns `true` iff already armed.
+ * Pure: parse `gh pr view --json autoMergeRequest,mergeCommit` output.
+ * `autoMergeRequest` is `null` when auto-merge is NOT armed; a non-null
+ * object means a prior arm is in place. Returns `true` iff already
+ * armed.
  *
  * Exported for tests so the JSON shape pin is reviewable.
  */
@@ -134,6 +135,36 @@ export function parseAutoMergeArmed(stdout) {
   }
 }
 
+/**
+ * Pure: parse the same probe output for a non-null `mergeCommit` — the
+ * PR has ALREADY merged. `gh pr merge --auto` on an already-green PR
+ * merges immediately (there is nothing to queue behind), and its exit
+ * code then reflects the post-merge local housekeeping: on 2026-07-11
+ * (Epic #4454, PR #4459) the merge itself succeeded but the trailing
+ * local `--delete-branch` failed because a harness worktree held
+ * `epic/4454`, so `gh` exited 1 and the armer misreported a successful
+ * merge as `arm-failed` — stranding the run at `agent::blocked` with
+ * the whole must-land chain (MergeWatcher → Cleaner → LabelTransitioner)
+ * never engaging. The arm-failure re-probe below uses this parser to
+ * distinguish "merge landed, housekeeping grumbled" from a genuine arm
+ * failure.
+ */
+export function parsePrMerged(stdout) {
+  const trimmed = String(stdout ?? '').trim();
+  if (trimmed.length === 0) return false;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (!parsed || typeof parsed !== 'object') return false;
+    return (
+      parsed.mergeCommit !== null &&
+      parsed.mergeCommit !== undefined &&
+      typeof parsed.mergeCommit === 'object'
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * AutomergeArmer listener.
  */
@@ -208,13 +239,17 @@ export class AutomergeArmer {
     }
 
     // Layer 2 idempotency — cross-process probe. If auto-merge is
-    // already armed on the PR, emit `epic.merge.armed` and bail
-    // without re-issuing the merge command.
+    // already armed on the PR (or the PR already merged — a prior arm
+    // completed the merge before this run re-entered), emit
+    // `epic.merge.armed` and bail without re-issuing the merge command.
     const probe = this.ghPrViewAutoMergeFn({ prUrl, cwd: this.cwd });
-    if (probe.status === 0 && parseAutoMergeArmed(probe.stdout)) {
+    if (
+      probe.status === 0 &&
+      (parseAutoMergeArmed(probe.stdout) || parsePrMerged(probe.stdout))
+    ) {
       this.classifications.push({ event, seqId, outcome: 'existing', prUrl });
       this.logger.info?.(
-        `[AutomergeArmer] auto-merge already armed on ${prUrl} — short-circuiting.`,
+        `[AutomergeArmer] auto-merge already armed (or PR already merged) on ${prUrl} — short-circuiting.`,
       );
       await this._emitArmed(prUrl);
       return;
@@ -232,6 +267,32 @@ export class AutomergeArmer {
     // entire codebase (see check-lifecycle-lint.js).
     const arm = this.ghPrMergeAutoFn({ prUrl, cwd: this.cwd });
     if (arm.status !== 0) {
+      // A non-zero arm exit does NOT necessarily mean the arm failed:
+      // `gh pr merge --auto --squash --delete-branch` on an
+      // already-green PR merges immediately and then runs local
+      // branch-delete housekeeping whose failure (e.g. the epic branch
+      // held by another worktree) surfaces as exit 1 AFTER the merge
+      // landed (2026-07-11 incident, Epic #4454 / PR #4459). Re-probe
+      // before classifying: merged or armed → proceed as success so the
+      // MergeWatcher → Cleaner → LabelTransitioner chain engages.
+      const recheck = this.ghPrViewAutoMergeFn({ prUrl, cwd: this.cwd });
+      if (
+        recheck.status === 0 &&
+        (parsePrMerged(recheck.stdout) || parseAutoMergeArmed(recheck.stdout))
+      ) {
+        this.classifications.push({
+          event,
+          seqId,
+          outcome: 'armed',
+          prUrl,
+          note: `arm exit ${arm.status} but re-probe shows merged/armed (post-merge housekeeping failure): ${arm.stderr}`,
+        });
+        this.logger.warn?.(
+          `[AutomergeArmer] gh pr merge exited ${arm.status} but the PR is merged/armed — treating as success (housekeeping stderr: ${arm.stderr})`,
+        );
+        await this._emitArmed(prUrl);
+        return;
+      }
       this.classifications.push({
         event,
         seqId,

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-predicate.js

@@ -66,6 +66,7 @@
 
 import { spawnSync } from 'node:child_process';
 
+import { hasSurvivingCritical } from '../../../audit-suite/findings.js';
 import { getCiDelivery } from '../../../config/ci.js';
 import * as epicRunStateStore from '../../epic-run-state-store.js';
 import { findStructuredComment } from '../../ticketing.js';
@@ -441,7 +442,11 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
   if (codeReviewUnparseable) {
     return { codeReviewFound, codeReviewUnparseable, severity };
   }
-  if (severity.critical > 0) {
+  // Route the halt-on-critical decision through the single halting rule of
+  // the unified verification-results contract (Story #4411) rather than a
+  // re-derived `critical > 0` expression. The unparseable branch above has
+  // already returned, so `severity.critical` is a concrete number here.
+  if (hasSurvivingCritical(severity)) {
     pushReason(
       reasons,
       REASON_CATEGORY.CRITICAL_REVIEW,
@@ -648,7 +653,11 @@ export async function evaluateAutoMergePredicate({
   // only IO, but the rule is directory-scoped; sequencing here is a
   // cheap concession for living inside the listener tree.
   const state = await readRunStateFn({ provider, epicId });
-  const codeReview = await findCommentFn(provider, epicId, 'code-review');
+  const codeReview = await findCommentFn(
+    provider,
+    epicId,
+    'verification-results',
+  );
   let retro = await findCommentFn(provider, epicId, 'retro');
   if (!retro) {
     retro = await findCommentFn(provider, epicId, 'retro-partial');

package/.agents/scripts/lib/orchestration/lifecycle/listeners/finalizer.js

@@ -16,8 +16,15 @@
  *
  * Side effects executed inside `handle()`:
  *   1. Emit `epic.finalize.start`.
- *   2. Auto-graduate non-blocking code-review / audit-results findings
- *      (best-effort; never throws).
+ *   2. Auto-graduate non-blocking findings in a SINGLE pass over the
+ *      unified `verification-results` comment (best-effort; never throws).
+ *      Story #4411 folded the former code-review + audit-results
+ *      structured-comment contracts into one comment; the lens-aware
+ *      audit-results graduator is the single canonical reader (its
+ *      🟢→`suggestion` severity vocabulary matches `findings-renderer.js`).
+ *      Running a second code-review pass over the same comment would file
+ *      every non-blocking finding twice, so only the audit-results
+ *      graduation runs here.
  *   3. Idempotency probe — `gh pr list --head epic/<id>` returns any
  *      existing PR URL. If one exists, short-circuit to `pr.created`
  *      + `epic.finalize.end` carrying the existing URL.
@@ -69,7 +76,6 @@ import {
   graduateAuditResults as defaultGraduateAuditResults,
   isAutoFileEnabled as isAuditResultsAutoFileEnabled,
 } from '../../../feedback-loop/audit-results-graduator.js';
-import { graduateFindings as defaultGraduateFindings } from '../../../feedback-loop/code-review-graduator.js';
 import { parsePrNumberFromUrl } from '../../../github-url.js';
 import {
   markPrReady as defaultMarkPrReady,
@@ -235,17 +241,39 @@ export function extractPrUrl(stdout) {
   return match ? match[0] : null;
 }
 
+/**
+ * Default bounded timeout for the finalize idempotency probe. Story #4415
+ * (Epic #4406) — a hung `gh pr list` spawn previously blocked finalize
+ * forever; the probe now SIGKILLs the child at this bound so a stalled
+ * `gh` cannot park the merge gate.
+ */
+export const GH_PR_LIST_TIMEOUT_MS = 30000;
+
 /**
  * Default `gh` spawn used by the listener's idempotency probe.
  * Mirrors the `shell: false` contract `openOrLocatePr` and the other
  * listener helpers use so a future Windows audit doesn't have to grep
- * across two modules. Exported so tests can stub.
+ * across two modules. Bounded by `timeoutMs` (default
+ * {@link GH_PR_LIST_TIMEOUT_MS}) + `killSignal: 'SIGKILL'` so a hung `gh`
+ * spawn cannot block finalize indefinitely (Story #4415). Exported so
+ * tests can stub.
  */
-export function ghPrListHead({ epicBranch, cwd, spawnFn = spawnSync }) {
+export function ghPrListHead({
+  epicBranch,
+  cwd,
+  spawnFn = spawnSync,
+  timeoutMs = GH_PR_LIST_TIMEOUT_MS,
+}) {
   const result = spawnFn(
     'gh',
     ['pr', 'list', '--head', epicBranch, '--json', 'url', '--jq', '.[0].url'],
-    { cwd, encoding: 'utf-8', shell: false },
+    {
+      cwd,
+      encoding: 'utf-8',
+      shell: false,
+      timeout: timeoutMs,
+      killSignal: 'SIGKILL',
+    },
   );
   return {
     status: result.status ?? 1,
@@ -276,7 +304,6 @@ export class Finalizer {
    *   the graduators.
    * @param {{owner:string,repo:string}} [opts.currentRepo]
    * @param {{owner:string,repo:string}} [opts.frameworkRepo]
-   * @param {Function} [opts.graduateFindingsFn]
    * @param {Function} [opts.graduateAuditResultsFn]
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
@@ -314,8 +341,6 @@ export class Finalizer {
     this.config = opts.config ?? null;
     this.currentRepo = opts.currentRepo ?? null;
     this.frameworkRepo = opts.frameworkRepo ?? null;
-    this.graduateFindingsFn =
-      opts.graduateFindingsFn ?? defaultGraduateFindings;
     this.graduateAuditResultsFn =
       opts.graduateAuditResultsFn ?? defaultGraduateAuditResults;
     this.logger = opts.logger ?? console;
@@ -373,10 +398,11 @@ export class Finalizer {
       return;
     }
 
-    // 1b. Auto-graduate non-blocking code-review findings (Story #2555).
-    await this._runCodeReviewGraduation();
-
-    // 1c. Auto-graduate non-blocking audit-results findings (Story #2615).
+    // 1b. Auto-graduate non-blocking findings in a SINGLE pass over the
+    //     unified `verification-results` comment (Story #2615; unified in
+    //     Story #4411). The lens-aware audit-results graduator is the sole
+    //     canonical reader — a second code-review pass over the same comment
+    //     would file every non-blocking finding twice.
     await this._runAuditResultsGraduation();
 
     // 2. Idempotency probe — does a PR already exist on the head
@@ -498,54 +524,14 @@ export class Finalizer {
   }
 
   /**
-   * Invoke the code-review graduator best-effort. Wired into finalize so
-   * that surviving non-blocking findings get auto-filed as routed
-   * follow-up issues (Story #2555 / Epic #2547). All failures are
-   * captured and logged at warn level; the finalize pipeline continues
-   * regardless — the toggle `delivery.feedbackLoop.codeReviewAutoFile`
-   * is the only operator-facing kill switch.
-   */
-  async _runCodeReviewGraduation() {
-    if (!this.provider || !this.currentRepo) {
-      this.logger.debug?.(
-        '[Finalizer] code-review graduation skipped: provider or currentRepo not wired',
-      );
-      return;
-    }
-    try {
-      const summary = await this.graduateFindingsFn({
-        epicId: this.epicId,
-        provider: this.provider,
-        config: this.config,
-        currentRepo: this.currentRepo,
-        frameworkRepo: this.frameworkRepo,
-        cwd: this.cwd,
-        logger: this.logger,
-      });
-      const filed = Array.isArray(summary?.filed) ? summary.filed.length : 0;
-      const skipped = Array.isArray(summary?.skipped)
-        ? summary.skipped.length
-        : 0;
-      const errors = Array.isArray(summary?.errors) ? summary.errors.length : 0;
-      this.logger.info?.(
-        `[Finalizer] code-review graduation: filed=${filed} skipped=${skipped} errors=${errors}`,
-      );
-      if (errors > 0) {
-        this.logger.warn?.(
-          `[Finalizer] code-review graduator errors: ${summary.errors.join('; ')}`,
-        );
-      }
-    } catch (err) {
-      this.logger.warn?.(
-        `[Finalizer] code-review graduator threw (swallowed): ${err?.message ?? err}`,
-      );
-    }
-  }
-
-  /**
-   * Invoke the audit-results graduator best-effort. Wired into finalize
-   * so that non-blocking audit findings (high/medium/low/suggestion) get
-   * auto-filed as routed follow-up issues — Story #2615 / Epic #2586.
+   * Invoke the audit-results graduator best-effort — the SINGLE canonical
+   * graduation pass over the unified `verification-results` comment. Wired
+   * into finalize so that non-blocking findings (high/medium/low/suggestion)
+   * get auto-filed as routed follow-up issues — Story #2615 / Epic #2586,
+   * unified into one pass in Story #4411 / Epic #4405. The lens-aware
+   * audit-results graduator is canonical because its 🟢→`suggestion`
+   * severity vocabulary matches `findings-renderer.js`; running a parallel
+   * code-review pass over the same comment would double-file every finding.
    */
   async _runAuditResultsGraduation() {
     if (!this.provider || !this.currentRepo) {

package/.agents/scripts/lib/orchestration/lifecycle/listeners/index.js

@@ -18,8 +18,10 @@
  *   4. AutomergeArmer          (epic.merge.ready → epic.merge.armed)
  *   5. AutomergePredicate      (epic.watch.end → epic.merge.{ready,blocked})
  *   6. BranchCleaner           (epic.cleanup.start → branch reap)
- *   7. Cleaner                 (epic.merge.armed → epic.cleanup.* / epic.complete)
- *   8. CheckpointPointerWriter (every *.end → checkpoint.json)
+ *   7. MergeWatcher            (epic.merge.armed → epic.merge.confirmed)
+ *   8. Cleaner                 (epic.merge.confirmed → epic.cleanup.* / epic.complete)
+ *   9. LabelTransitioner       (epic.complete → Epic ticket flips to agent::done)
+ *  10. CheckpointPointerWriter (every *.end → checkpoint.json)
  *
  * The bus contract requires LedgerWriter first: its `onEmitted` hook
  * lands the `emitted` ledger record on disk BEFORE any listener body
@@ -60,6 +62,7 @@ import { BranchCleaner } from './branch-cleaner.js';
 import { CheckpointPointerWriter } from './checkpoint-pointer-writer.js';
 import { Cleaner } from './cleaner.js';
 import { Finalizer } from './finalizer.js';
+import { LabelTransitioner } from './label-transitioner.js';
 import { MergeWatcher } from './merge-watcher.js';
 
 /**
@@ -118,6 +121,11 @@ export function parseLedgerPath(ledgerPath) {
  * @param {object} [opts.checkpointer] Epic-run-state checkpoint reader.
  *   When omitted, BranchCleaner is skipped.
  * @param {object} [opts.logger] Logger surface (`debug`/`warn`/`error`).
+ * @param {boolean} [opts.headless] Explicit must-land signal (Story
+ *   #4427), threaded straight through to `MergeWatcher`. Defaults to
+ *   `false` (attended-mode behavior unchanged). `lifecycle-emit.js`
+ *   resolves this from its own `--headless` runtime flag — an explicit
+ *   input, never an ambient global.
  *
  * @returns {Promise<{
  *   ledgerWriter: object,
@@ -140,6 +148,7 @@ export async function buildDefaultListenerChain(opts = {}) {
     config = null,
     checkpointer = null,
     logger = console,
+    headless = false,
   } = opts;
   if (
     !bus ||
@@ -288,6 +297,7 @@ export async function buildDefaultListenerChain(opts = {}) {
     cwd: repoRoot,
     intervalSeconds: mergeWatchConfig.intervalSeconds,
     maxBudgetSeconds: mergeWatchConfig.maxBudgetSeconds,
+    headless,
     logger,
   });
   mergeWatcher.register();
@@ -306,7 +316,32 @@ export async function buildDefaultListenerChain(opts = {}) {
   cleaner.register();
   order.push('Cleaner');
 
-  // 8. CheckpointPointerWriter — persists `{ lastCompletedSeqId, phase }`
+  // 9. LabelTransitioner — flips the Epic ticket to `agent::done` (and
+  //    closes it as completed, idempotently) on the terminal
+  //    `epic.complete` event. Requires a truthy `provider`; skip
+  //    cleanly when the caller omitted one — the same guard pattern as
+  //    AutomergePredicate. Restores the contract the Cleaner /
+  //    BranchCleaner / MergeWatcher docstrings have referenced since
+  //    the original listener was deleted with the epic-runner stratum
+  //    (#3936): without this registration the flip had NO owner and
+  //    cleanly-merged Epics stranded at `agent::executing`.
+  let labelTransitioner = null;
+  if (provider) {
+    labelTransitioner = new LabelTransitioner({
+      bus,
+      epicId,
+      provider,
+      logger,
+    });
+    labelTransitioner.register();
+    order.push('LabelTransitioner');
+  } else {
+    logger?.debug?.(
+      '[lifecycle] buildDefaultListenerChain: skipping LabelTransitioner (no provider)',
+    );
+  }
+
+  // 10. CheckpointPointerWriter — persists `{ lastCompletedSeqId, phase }`
   //    on every `*.end` event.
   const checkpointPointerWriter = new CheckpointPointerWriter({
     bus,
@@ -330,6 +365,7 @@ export async function buildDefaultListenerChain(opts = {}) {
     branchCleaner,
     mergeWatcher,
     cleaner,
+    labelTransitioner,
     checkpointPointerWriter,
     order,
   };