mandrel 2.60.0 → 2.61.0

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

@@ -1,9 +1,5 @@
 /**
- * render.js — pure rendering helpers for git-cleanup (Story #2466).
- *
- * Owns the text + JSON envelope renderers and the `computeExitCode`
- * helper. Extracted verbatim from `git-cleanup.js` so every named export
- * keeps its contract.
+ * Pure text / JSON renderers and exit-code derivation for git-cleanup.
  *
  * @module lib/orchestration/git-cleanup/phases/render
  */
@@ -12,14 +8,8 @@ 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).
+ * @param {number} now
  * @returns {string}
  */
 function formatCommitAge(iso, now) {
@@ -33,17 +23,8 @@ function formatCommitAge(iso, now) {
 }
 
 /**
- * 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.
- *
- * Story #5188 routes the remote-only walk's genuinely-unmerged survivors
- * through here too. A `localExists: false` skip is marked `(remote-only)`
- * — the same marker {@link renderCandidateRow} puts on a remote-only
- * candidate — because the short name it prints has no local ref behind
- * it: without the marker the operator reads the line as a local branch and
- * hunts for a ref that `git branch` will never list.
+ * A remote-only skip is marked `(remote-only)` because its short name has
+ * no local ref behind it.
  *
  * @param {{ branch: string, reason: string, lastCommitAt?: string|null, localExists?: boolean }} skip
  * @param {{ now?: number }} [opts]
@@ -57,46 +38,22 @@ export function renderNotMergedSkipLine(skip, opts = {}) {
   return `${TAG} ⏭️  ${skip.branch}${scope} 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 a single behind-the-merged-head candidate annotation.
- *
- * A branch whose tip is a strict ancestor of its merged PR head is a
- * stale pre-merge snapshot — reapable, because every commit on it landed
- * with the PR, but reapable for a different reason than a branch whose
- * tip *matches* the merged head. It used to be skipped outright as a
- * post-merge force-push; the note keeps the two visibly distinct in the
- * dry-run list and the confirmation prompt so the operator can see why a
- * branch that is not at the merged head is nonetheless offered.
- */
 function behindMergeNote(candidate) {
   return candidate.behindMerge
     ? ' (tip behind the merged head — content already landed)'
     : '';
 }
 
-/** Pure: every provenance annotation a candidate row carries, in order. */
 function candidateNotes(candidate) {
   return `${contentMergedNote(candidate)}${behindMergeNote(candidate)}`;
 }
 
-/**
- * Pure: one candidate row — its detection provenance, worktree, locality
- * and annotations. Split out of {@link renderDryRun} so that renderer
- * stays a loop over rows rather than growing a fourth inline ternary
- * every time a candidate gains a new dimension.
- */
 function renderCandidateRow(c) {
   const pr = c.prNumber ? `PR #${c.prNumber}` : c.detectedBy;
   const wt = c.hasWorktree ? ` (worktree: ${c.worktreePath})` : '';
@@ -105,15 +62,8 @@ function renderCandidateRow(c) {
 }
 
 /**
- * Pure: render the branch-phase candidate list as the operator-facing text
- * block.
- *
- * The header states the run mode: `execute` opts into the reap wording and
- * defaults to `false`, so a caller that forgets it still gets the harmless
- * preview line. Prefer {@link renderCandidateList}, which derives the mode
- * from the phase's own CLI options rather than making the caller restate
- * it — the header used to be hardcoded to the preview wording, so an
- * `--execute` run announced "nothing deleted" and then reaped.
+ * Prefer {@link renderCandidateList}, which derives `execute` from the CLI
+ * options.
  *
  * @param {{ candidates: Array, skipped?: Array, ghDegraded?: boolean }} plan
  * @param {{ baseBranch?: string|null, now?: number, execute?: boolean }} [opts]
@@ -159,17 +109,12 @@ export function renderDryRun(plan, opts = {}) {
 }
 
 /**
- * Pure: the branch phase's candidate-list block, with the header's run
- * mode derived from the phase's own CLI options — the same `opts.dryRun`
- * the reap path reads. Taking the whole bag (rather than a restated
- * boolean) is the point: the driver cannot get the wording wrong because
- * it never names the flag, so a destructive `--execute` run can no longer
- * announce itself as a `DRY RUN (nothing deleted)` preview and then
- * delete every candidate.
+ * Takes the whole CLI option bag — the same `dryRun` the reap path reads —
+ * so an `--execute` run can never announce itself as a dry run.
  *
  * @param {object} args
  * @param {{ candidates: Array, skipped?: Array }} args.plan
- * @param {{ dryRun?: boolean }} args.opts   Parsed CLI options.
+ * @param {{ dryRun?: boolean }} args.opts
  * @param {string|null} [args.baseBranch]
  * @returns {string[]}
  */
@@ -177,10 +122,6 @@ export function renderCandidateList({ plan, opts = {}, baseBranch = null }) {
   return renderDryRun(plan, { baseBranch, execute: !opts.dryRun });
 }
 
-/**
- * Pure: the tip / merged short-SHA pair both merged-tip skip lines quote,
- * with a placeholder for either side the planner could not resolve.
- */
 function shortShaPair(skip) {
   return {
     tip: skip.tipSha ? skip.tipSha.slice(0, 7) : '<unknown>',
@@ -189,11 +130,7 @@ function shortShaPair(skip) {
 }
 
 /**
- * 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`) stay quiet here. `not-merged` gets its own
- * renderer ({@link renderNotMergedSkipLine}).
+ * `null` for any reason outside the latest-PR / merged-tip family.
  *
  * @param {{ branch: string, reason: string, prNumber?: number, tipSha?: string, mergedSha?: string, detail?: string }} skip
  * @returns {string | null}
@@ -227,25 +164,13 @@ export function renderLatestPrSkipLine(skip) {
   return null;
 }
 
-/**
- * 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.
- */
+/** Next step per withheld-delete reason, so a withhold never reads as an unexplained refusal. */
 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.
- */
+/** A `skipped` entry was withheld, not attempted — never render it as ✅. */
 export function renderExecutionLine(entry, scope) {
   const label = scope.padEnd(8);
   const tagName =
@@ -263,7 +188,6 @@ export function renderExecutionLine(entry, scope) {
   return `${TAG} ${icon} ${label} ${tagName}${note}`;
 }
 
-/** Pure: render the optional prune line. */
 export function renderPruneLine(prune) {
   if (!prune?.attempted) return null;
   if (!prune.ok) {
@@ -277,12 +201,8 @@ export function renderPruneLine(prune) {
 }
 
 /**
- * Pure: render a single deferred-worktree line. A lock-class
- * worktree-removal failure (Windows file lock on an already-merged
- * branch's directory) is non-fatal — the branch ref was still reaped and
- * the directory is handed off to the pending-cleanup sweep. Returns the
- * operator-facing warning so the deferred signal is visible even on a
- * clean (`ok: true`) run.
+ * A lock-class worktree removal failure (Windows file lock) is non-fatal:
+ * the ref was reaped and the directory deferred. Shown even on an `ok` run.
  *
  * @param {{ branch?: string, path: string, pendingCleanup?: object|null }} entry
  * @returns {string}
@@ -295,7 +215,6 @@ export function renderDeferredLine(entry) {
   return `${TAG} ⚠️ deferred ${ref}${entry.path} — worktree locked; ref reaped${handoff}`;
 }
 
-/** Pure: render the trailing summary line. */
 export function renderExecutionSummary(result) {
   if (!result.ok) {
     return `${TAG} ❌ ${result.failures.length} failure(s) during cleanup.`;
@@ -308,8 +227,7 @@ export function renderExecutionSummary(result) {
     deferredCount > 0
       ? ` (${deferredCount} worktree(s) deferred to sweep)`
       : '';
-  // Story #5283: withheld remote entries are recorded on `remote[]` but
-  // were never deleted — counting them would overstate the reap.
+  // Withheld remote entries were never deleted; don't count them.
   const remoteDeleted = result.remote.filter((r) => !r.skipped).length;
   const withheldCount = result.remote.length - remoteDeleted;
   const withheldNote =
@@ -329,7 +247,6 @@ const EMPTY_RESULT = Object.freeze({
   ok: true,
 });
 
-/** Pure: build the JSON envelope emitted in `--json` mode. */
 export function buildJsonEnvelope({
   dryRun,
   baseBranch,
@@ -365,8 +282,7 @@ function legacyExitCode(plan, result) {
 }
 
 /**
- * Pure: derive the process exit code. Supports both the legacy
- * `(plan, result)` signature and the new multi-phase context object.
+ * Accepts `(plan, result)` or a multi-phase context object.
  *
  * @param {{ candidates?: Array, branchesPlan?: object, branchesResult?: object, fastForward?: object, prune?: object, stashes?: object } | { candidates: Array }} ctx
  * @param {{ ok: boolean } | null | undefined} [legacyResult]

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

@@ -1,8 +1,5 @@
 /**
- * stashes.js — stash-triage phase of git-cleanup (Story #2466).
- *
- * Owns `parseStashList`, `planStashes`, `executeStashes`, `stashRefIndex`,
- * and `buildAllowlistDecider`. Extracted verbatim from `git-cleanup.js`.
+ * Stash-triage phase of git-cleanup.
  *
  * @module lib/orchestration/git-cleanup/phases/stashes
  */

package/.agents/scripts/lib/orchestration/lease-guard-shared.js

@@ -1,69 +1,22 @@
 /**
- * lease-guard-shared.js — Story #3992: single-source the lease-acquisition
- * kernel shared by the three per-surface lease guards.
- *
- * The per-surface lease guards — today `single-story-lease-guard.js`;
- * historically also the retired Epic-tier deliver/mandrel-plan guards —
- * each carried their own copy of
- * the operator-handle resolution and the fail-closed acquire wrapper around
- * `ticket-lease.acquireLease` (refuse any foreign assignee, throwing an
- * operator-facing message naming the current owner unless `--steal`). The
- * three copies had
- * already diverged — different `resolveOperator` signatures and different
- * missing-handle behaviour (`null` vs `throw`) — and were synchronised only
- * by docstring promise ("This mirrors the sibling lease guards…").
- *
- * This module is the single home for the kernel, modelled on the
- * shared plumbing inside `story-close/format-autofix.js` (Story #3332,
- * consolidated by Story #4017). The
- * per-surface guards now differ only in injected **policy**:
- *
- *   - **Operator candidates** — each surface supplies its own ordered
- *     candidate list (e.g. `--as` flag → `github.operatorHandle` →
- *     `git user.email` for `/mandrel-deliver`; bare `operatorHandle` for the
- *     plan/standalone paths).
- *   - **Missing-handle behaviour** — `'null'` (return null; the caller fails
- *     closed at acquire time) vs `'throw'` (refuse immediately with surface
- *     wording). The divergence between the plan path (`null`) and the
- *     standalone path (`throw`) is intentional: the plan path also calls
- *     `resolveOperator` on its best-effort release leg, where a missing
- *     handle must degrade to a `no-operator` no-op rather than throw.
- *   - **Refusal wording** — each surface renders its own operator-facing
- *     message via `renderRefusal(result, ticketId)`.
- *
- * A third axis, **liveness anchoring**, is gone: Story #5006 deleted the
- * lease TTL, so every foreign claim refuses unconditionally and there is no
- * heartbeat to anchor.
- *
- * The unclaimed / already-held / foreign-claim decision table itself (and
- * the steal transfer) lives in `ticket-lease.acquireLease`; this kernel owns
- * the refuse-by-throw boundary that the three guards previously each
- * re-implemented.
- *
- * Per `.agents/rules/orchestration-error-handling.md`, failures surface via
- * `throw new Error(...)`, never `Logger.fatal`.
+ * lease-guard-shared.js — the lease-acquisition kernel shared by lease
+ * guards; surfaces differ only in injected policy (operator candidates,
+ * missing-handle behaviour, refusal wording). The claim decision table lives
+ * in `ticket-lease.acquireLease`; this owns the refuse-by-throw boundary.
+ * Failures throw, never `Logger.fatal`.
  */
 
 import { acquireLease, normalizeOperatorHandle } from './ticket-lease.js';
 
 /**
- * Resolve the operator handle from an ordered candidate list, applying the
- * surface's missing-handle policy.
- *
- * Each candidate is passed through the shared `normalizeOperatorHandle` so a
- * leading `@` is stripped (the assignees API expects bare logins, not
- * `@`-prefixed mentions) and the shipped `@[USERNAME]` placeholder maps to
- * `null` — otherwise the assignee PATCH is rejected (HTTP 422) and the
- * self-held-claim comparison (`owner === operator`) never matches. The first
- * candidate that normalises to a non-null handle wins.
+ * First candidate that normalizes to a bare login (strips `@`, maps the
+ * `@[USERNAME]` placeholder to `null` — else the assignee PATCH 422s).
+ * `'null'` suits paths with a best-effort release leg, which must no-op.
  *
  * @param {object} opts
  * @param {Array<string|null|undefined>} opts.candidates  Ordered raw handles.
- * @param {'null'|'throw'} [opts.missingHandleBehavior='null']  What to do
- *   when no candidate resolves: return `null`, or throw with the surface's
- *   configured wording.
- * @param {string} [opts.missingHandleMessage]  Error message used when
- *   `missingHandleBehavior` is `'throw'`.
+ * @param {'null'|'throw'} [opts.missingHandleBehavior='null']
+ * @param {string} [opts.missingHandleMessage]
  * @returns {string|null} Bare operator handle, or `null` (policy `'null'`).
  * @throws {Error} When no candidate resolves and the policy is `'throw'`.
  */
@@ -83,19 +36,15 @@ export function resolveOperatorFromCandidates({
 }
 
 /**
- * Acquire a ticket lease, failing closed by throwing the surface's refusal
- * message when the claim is refused (foreign owner, no `steal`).
- *
- * Unclaimed and self-held tickets proceed — the self-held case without a
- * write. A foreign assignee always refuses unless `steal` is set.
+ * Acquire a lease; a foreign claim without `steal` throws the surface's
+ * refusal.
  *
  * @param {object} opts
- * @param {object} opts.provider          Ticketing provider.
- * @param {number} opts.ticketId          Ticket to claim.
- * @param {string} opts.operator          Resolved operator handle.
- * @param {boolean} [opts.steal=false]    Forcibly transfer a foreign claim.
+ * @param {object} opts.provider
+ * @param {number} opts.ticketId
+ * @param {string} opts.operator
+ * @param {boolean} [opts.steal=false]
  * @param {(result: object, ticketId: number) => string} opts.renderRefusal
- *   Renders the operator-facing refusal message for a refused claim.
  * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
  * @throws {Error} When the claim is refused (`result.acquired === false`).
  */

package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js

@@ -1,16 +1,6 @@
 /**
- * emit-ledger-event.js — shared validate-and-append core for the
- * merge-terminal lifecycle emitters (Story #4539).
- *
- * `emit-merge-unlanded.js` and `emit-merge-flip-failed.js` report the two
- * terminal outcomes a landing attempt can reach without ending at
- * `agent::done`. They share everything except their schema and their
- * payload's meaning, so the Ajv compile/cache, the scope→ledger routing,
- * and the NDJSON append live here once rather than being copy-pasted.
- *
- * Like its callers, this is a bare `appendFileSync` rather than a bus
- * publish: these events fire from the `single-story-close` flow, which has
- * no bus at all, so a direct append keeps the call site dependency-free.
+ * Shared schema-validate-and-append core for the merge-terminal lifecycle
+ * emitters (outcomes that end short of `agent::done`).
  */
 
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
@@ -34,14 +24,8 @@ const SCHEMA_DIR = path.resolve(
 );
 
 /**
- * The scopes a merge-terminal event may be WRITTEN with. v2.0.0 removed the
- * Epic tier, so `'story'` is the only emittable scope.
- *
- * Note the deliberate asymmetry with the `merge.unlanded` /
- * `merge.flip-failed` schema enums, which still accept `'epic'`: archived
- * ledger records carry `scope: 'epic'` and the schemas must keep validating
- * them on read. The value stays READABLE; only the writer path is gone —
- * the same split `merge-block-class.js` keeps for `predicate-refused`.
+ * Writable scopes. The schemas still accept `'epic'` so archived records
+ * keep validating on read; only the writer path is gone.
  */
 const VALID_SCOPES = new Set(['story']);
 
@@ -49,9 +33,7 @@ const VALID_SCOPES = new Set(['story']);
 const _validators = new Map();
 
 /**
- * Compile (once) and return the validator for a lifecycle schema file.
- *
- * @param {string} schemaFile Basename under `.agents/schemas/lifecycle/`.
+ * @param {string} schemaFile
  * @returns {Function}
  */
 function getValidator(schemaFile) {
@@ -68,9 +50,6 @@ function getValidator(schemaFile) {
 }
 
 /**
- * Assert the fields every merge-terminal event shares. Throws with the
- * caller's own emitter name so the message stays attributable.
- *
  * @param {string} emitter
  * @param {{ scope: string, ticketId: number, prNumber: number, reason: string, elapsedSeconds: number }} fields
  */
@@ -98,17 +77,14 @@ export function assertMergeTerminalFields(
 }
 
 /**
- * Validate a payload against its lifecycle schema and append exactly one
- * NDJSON record to the scope-resolved ledger.
- *
  * @param {object} args
- * @param {string} args.emitter       Caller name, for error attribution.
- * @param {string} args.schemaFile    Basename under `schemas/lifecycle/`.
- * @param {object} args.payload       The event payload (already assembled).
+ * @param {string} args.emitter
+ * @param {string} args.schemaFile
+ * @param {object} args.payload
  * @param {number} args.ticketId
  * @param {string} args.timestamp
  * @param {object} [args.config]
- * @param {string} [args.ledgerPath]  Override for tests / non-default layouts.
+ * @param {string} [args.ledgerPath]
  * @returns {{ ledgerPath: string, record: object }}
  */
 export function appendLedgerEvent({

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

@@ -1,22 +1,8 @@
 /**
- * emit-merge-flip-failed.js — Story #4539.
- *
- * Appends a single `merge.flip-failed` NDJSON record when a delivery run
- * observed a **confirmed merge** but the `agent::closing → agent::done`
- * label write itself failed.
- *
- * Why this is not `merge.unlanded`: the merge landed. Reporting it as
- * unlanded points the operator at branch protection, required checks, and
- * poll budgets — none of which are the fault — while the real remedy is a
- * re-run of `single-story-confirm-merge.js`, which is idempotent and flips
- * the label from the already-merged PR. The two events are deliberately
- * distinct so the ledger attributes a label-write API failure differently
- * from a merge that never happened.
- *
- * The Story is still transitioned to `agent::blocked` by the caller: a
- * merged PR whose Story sits at `agent::closing` is exactly the silent
- * strand the must-land contract exists to prevent, so it terminates
- * explicitly — but it terminates with the truth.
+ * Record a confirmed merge whose `agent::done` label write failed. Distinct
+ * from `merge.unlanded` because the merge landed — the remedy is re-running
+ * the idempotent confirm-merge, not chasing branch protection. The caller
+ * still blocks the Story so it is never stranded at `agent::closing`.
  */
 
 import {
@@ -24,22 +10,15 @@ import {
   assertMergeTerminalFields,
 } from './emit-ledger-event.js';
 
-/**
- * The only block class this event carries. Distinct from every
- * `merge.unlanded` attribution (`MERGE_UNLANDED_BLOCK_CLASSES`) because the
- * merge is not in question here — only the label write is.
- */
 export const MERGED_FLIP_FAILED_BLOCK_CLASS = 'merged-flip-failed';
 
 /**
- * Append exactly one `merge.flip-failed` record to the resolved ledger.
- *
  * @param {object} opts
  * @param {'story'} opts.scope
- * @param {number} opts.ticketId       The storyId.
- * @param {number} opts.prNumber       The PR that merged.
- * @param {string} opts.reason         What failed on the label write.
- * @param {number} opts.elapsedSeconds Elapsed poll time when the flip failed.
+ * @param {number} opts.ticketId
+ * @param {number} opts.prNumber
+ * @param {string} opts.reason
+ * @param {number} opts.elapsedSeconds
  * @param {string} [opts.timestamp]
  * @param {object} [opts.config]
  * @param {string} [opts.ledgerPath]

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

@@ -1,52 +1,10 @@
 /**
- * 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. Direct schema validation via
- * Ajv followed by a synchronous `appendFileSync`: it fires from the standalone
- * `single-story-close` flow, and a bare append keeps the call site simple and
- * dependency-free. This was the shape that outlived the lifecycle bus — Story
- * #5024 retired the bus, leaving this path the only lifecycle-ledger writer.
- *
- * Ledger destination (Story #4426 AC4): `storyLedgerPath(null, ticketId)`
- * — the standalone story-scope destination
- * `temp/standalone/stories/story-<id>/lifecycle.ndjson`, where `ticketId`
- * is the storyId. The `single-story-close` path has no parent Epic to
- * anchor a run 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.
+ * Append one `merge.unlanded` record to the Story's lifecycle ledger when a
+ * delivery run gives up without a confirmed merge (after arming, unlike the
+ * pre-arm `epic.merge.blocked`). Callers must catch a failed append and still
+ * drive the blocked-state transition. The schema forbids extra properties, so
+ * the signature is narrow; `blockClass` must be a `merge-block-class.js`
+ * value.
  */
 
 import { isValidBlockClass } from '../merge-block-class.js';
@@ -56,27 +14,16 @@ import {
 } from './emit-ledger-event.js';
 
 /**
- * Append exactly one `merge.unlanded` NDJSON record to the resolved
- * lifecycle ledger.
- *
  * @param {object} opts
- * @param {'story'} opts.scope         Which delivery path is reporting the
- *                                     unlanded merge.
- * @param {number} opts.ticketId       The storyId.
- * @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.
+ * @param {'story'} opts.scope
+ * @param {number} opts.ticketId
+ * @param {number} opts.prNumber
+ * @param {string} opts.blockClass
+ * @param {string} opts.reason
+ * @param {number} opts.elapsedSeconds
+ * @param {string} [opts.timestamp]
+ * @param {object} [opts.config]
+ * @param {string} [opts.ledgerPath]
  * @returns {{ ledgerPath: string, record: object }}
  */
 export function emitMergeUnlanded(opts) {