mandrel 1.88.0 → 1.90.0

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

@@ -0,0 +1,193 @@
+/**
+ * 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 a valid `merge.unlanded` attribution from
+ * `merge-block-class.js` (`MERGE_UNLANDED_BLOCK_CLASSES` — the four
+ * `classifyMergeBlock` outputs plus the directly-emitted `predicate-refused`,
+ * Story #4472). For a post-arm poll-exhaustion block, pass the classifier's
+ * verdict straight through (`classifyMergeBlock(...)` returns
+ * `{ blockClass, reason }`); the predicate/armer refusal paths pass
+ * `predicate-refused` / a classified arm failure directly.
+ */
+
+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     A valid `merge.unlanded` attribution
+ *                                     (`MERGE_UNLANDED_BLOCK_CLASSES` in
+ *                                     `merge-block-class.js`).
+ * @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

@@ -54,7 +54,10 @@
 
 import { spawnSync } from 'node:child_process';
 
+import { parsePrNumberFromUrl } from '../../../github-url.js';
 import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
+import { classifyMergeBlock } from '../../merge-block-class.js';
+import { emitMergeUnlanded } from '../emit-merge-unlanded.js';
 
 /**
  * Default `gh pr view --json autoMergeRequest` probe. Pure-spawn helper
@@ -64,7 +67,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 +113,68 @@ 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.
+ * Story #4472 — direct (non-`--auto`) squash-merge fallback.
+ *
+ * GitHub's native auto-merge (`gh pr merge --auto`) can only be QUEUED on a
+ * repository that has the "Allow auto-merge" setting enabled — which in
+ * practice requires branch protection. A repo with zero required checks and
+ * no branch protection (every mandrel-bench sandbox, many real consumer
+ * repos) rejects the `--auto` arm outright with `Auto merge is not allowed
+ * for this repository`. The AutomergePredicate has already cleared the merge
+ * (green/absent required checks + a clean structured-signal verdict) by the
+ * time the armer runs, so the safe, must-land-satisfying fallback is a
+ * direct immediate squash-merge — the epic path's observed de-facto manual
+ * fallback, made legal and kept inside the sole authorized `gh pr merge`
+ * call site.
+ *
+ * Same `--squash --delete-branch` shape and same `resolveArmCwd` re-point as
+ * `ghPrMergeAuto` (so the trailing local `--delete-branch` housekeeping runs
+ * from the primary worktree, not a head-branch worktree). Omitting `--auto`
+ * makes `gh` merge synchronously.
+ */
+export function ghPrMergeDirect({
+  prUrl,
+  cwd,
+  spawnFn = spawnSync,
+  resolveArmCwd = resolveAutoMergeArmCwd,
+}) {
+  const armCwd = resolveArmCwd(cwd);
+  const result = spawnFn(
+    'gh',
+    ['pr', 'merge', prUrl, '--squash', '--delete-branch'],
+    { cwd: armCwd, encoding: 'utf-8', shell: false },
+  );
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Pure: does this `gh pr merge --auto` stderr indicate that native
+ * auto-merge is unavailable on the repository (as opposed to a genuine arm
+ * failure — auth, a merge conflict, an already-merged race)? Only this
+ * specific class of failure is safe to retry as a direct merge; everything
+ * else must surface as a real failure. Matched case-insensitively.
+ *
+ * Exported so the marker set is reviewable and testable in isolation.
+ */
+export function isAutoMergeUnavailable(stderr) {
+  const text = String(stderr ?? '').toLowerCase();
+  return (
+    text.includes('auto merge is not allowed') ||
+    text.includes('auto-merge is not allowed') ||
+    text.includes('enablepullrequestautomerge') ||
+    (text.includes('auto') && text.includes('not enabled'))
+  );
+}
+
+/**
+ * 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 +196,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.
  */
@@ -141,9 +233,17 @@ export class AutomergeArmer {
   /**
    * @param {object} opts
    * @param {object} opts.bus
+   * @param {number} [opts.epicId] Epic id — required for the headless
+   *   `merge.unlanded` attribution on a genuine arm failure (Story #4472).
+   * @param {boolean} [opts.headless] When true (a `/deliver --yes` run), a
+   *   genuine (non-fallback) arm failure escalates to an explicit
+   *   `merge.unlanded` + `epic.blocked` terminal instead of returning
+   *   silently (Story #4472). Defaults to `false` (attended).
    * @param {string} [opts.cwd]
    * @param {Function} [opts.ghPrViewAutoMergeFn] override for tests.
    * @param {Function} [opts.ghPrMergeAutoFn] override for tests.
+   * @param {Function} [opts.ghPrMergeDirectFn] override for tests.
+   * @param {Function} [opts.emitMergeUnlandedFn] override for tests.
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
@@ -155,9 +255,13 @@ export class AutomergeArmer {
       throw new TypeError('AutomergeArmer requires a bus with on() and emit()');
     }
     this.bus = opts.bus;
+    this.epicId = Number.isInteger(opts.epicId) ? opts.epicId : null;
+    this.headless = opts.headless === true;
     this.cwd = opts.cwd ?? process.cwd();
     this.ghPrViewAutoMergeFn = opts.ghPrViewAutoMergeFn ?? ghPrViewAutoMerge;
     this.ghPrMergeAutoFn = opts.ghPrMergeAutoFn ?? ghPrMergeAuto;
+    this.ghPrMergeDirectFn = opts.ghPrMergeDirectFn ?? ghPrMergeDirect;
+    this.emitMergeUnlandedFn = opts.emitMergeUnlandedFn ?? emitMergeUnlanded;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
     this._seen = new Set();
@@ -208,13 +312,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,16 +340,52 @@ export class AutomergeArmer {
     // entire codebase (see check-lifecycle-lint.js).
     const arm = this.ghPrMergeAutoFn({ prUrl, cwd: this.cwd });
     if (arm.status !== 0) {
-      this.classifications.push({
+      // 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;
+      }
+
+      // Story #4472 — native auto-merge is unavailable on this repository
+      // (no branch protection / "Allow auto-merge" disabled). The predicate
+      // already cleared the merge, so fall back to a direct immediate
+      // squash-merge instead of stranding a landable PR on the
+      // operator-merges path.
+      if (isAutoMergeUnavailable(arm.stderr)) {
+        const armed = await this._tryDirectMerge({ event, seqId, prUrl, arm });
+        if (armed) return;
+      }
+
+      // Genuine arm failure (auth, conflict, an unresolved direct-merge
+      // fallback, …). Classify + escalate.
+      await this._emitArmFailure({
         event,
         seqId,
-        outcome: 'failed',
+        prUrl,
         reason: `arm-failed:status=${arm.status}`,
         ghStderr: arm.stderr,
       });
-      this.logger.warn?.(
-        `[AutomergeArmer] gh pr merge --auto failed (status=${arm.status}): ${arm.stderr}`,
-      );
       return;
     }
 
@@ -259,6 +403,97 @@ export class AutomergeArmer {
     }
   }
 
+  /**
+   * Story #4472 — direct-merge fallback when native auto-merge is
+   * unavailable. Runs an immediate `gh pr merge --squash --delete-branch`
+   * (no `--auto`) then re-probes; on a confirmed merge (or the same
+   * post-merge `--delete-branch` housekeeping grumble the `--auto` path
+   * already tolerates) it emits `epic.merge.armed` so the
+   * MergeWatcher → Cleaner → LabelTransitioner chain engages and confirms
+   * the merge on its first poll.
+   *
+   * @returns {Promise<boolean>} `true` when the fallback landed the PR (an
+   *   `epic.merge.armed` was emitted); `false` when the direct merge did
+   *   not land, so the caller escalates the original arm failure.
+   */
+  async _tryDirectMerge({ event, seqId, prUrl, arm }) {
+    this.logger.info?.(
+      `[AutomergeArmer] native auto-merge unavailable (${arm.stderr?.trim?.() ?? arm.stderr}); falling back to a direct squash-merge on ${prUrl}.`,
+    );
+    const direct = this.ghPrMergeDirectFn({ prUrl, cwd: this.cwd });
+    const recheck = this.ghPrViewAutoMergeFn({ prUrl, cwd: this.cwd });
+    const merged =
+      recheck.status === 0 &&
+      (parsePrMerged(recheck.stdout) || parseAutoMergeArmed(recheck.stdout));
+    if (direct.status === 0 || merged) {
+      this.classifications.push({
+        event,
+        seqId,
+        outcome: 'armed',
+        prUrl,
+        note: `direct-merge fallback (native auto-merge unavailable); direct exit ${direct.status}${direct.status !== 0 ? ` but re-probe shows merged/armed (housekeeping stderr: ${direct.stderr})` : ''}`,
+      });
+      await this._emitArmed(prUrl);
+      return true;
+    }
+    this.logger.warn?.(
+      `[AutomergeArmer] direct-merge fallback failed (status=${direct.status}): ${direct.stderr}`,
+    );
+    return false;
+  }
+
+  /**
+   * Classify + (in headless) escalate a genuine arm failure. The `--auto`
+   * path historically returned silently here; a `/deliver --yes` run has no
+   * operator to notice, so we mirror the MergeWatcher's terminal:
+   * `merge.unlanded` ledger attribution + an explicit `epic.blocked`
+   * transition. Attended runs keep the classify-and-return behaviour.
+   */
+  async _emitArmFailure({ event, seqId, prUrl, reason, ghStderr }) {
+    this.classifications.push({
+      event,
+      seqId,
+      outcome: 'failed',
+      reason,
+      ghStderr,
+    });
+    this.logger.warn?.(
+      `[AutomergeArmer] gh pr merge --auto failed (${reason}): ${ghStderr}`,
+    );
+    if (!this.headless) return;
+    const classification = classifyMergeBlock({
+      armResult: { armed: false, reason: ghStderr },
+    });
+    const prNumber = parsePrNumberFromUrl(prUrl);
+    if (
+      Number.isInteger(this.epicId) &&
+      Number.isInteger(prNumber) &&
+      prNumber > 0
+    ) {
+      try {
+        this.emitMergeUnlandedFn({
+          scope: 'epic',
+          ticketId: this.epicId,
+          prNumber,
+          blockClass: classification.blockClass,
+          reason: classification.reason,
+          elapsedSeconds: 0,
+        });
+      } catch (err) {
+        this.logger.warn?.(
+          `[AutomergeArmer] emitMergeUnlanded failed (swallowed): ${err?.message ?? err}`,
+        );
+      }
+    }
+    try {
+      await this.bus.emit('epic.blocked', { reason: `merge-arm:failed` });
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergeArmer] epic.blocked emit on arm failure failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
+  }
+
   reset() {
     this._seen.clear();
     this.classifications = [];