mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js

@@ -0,0 +1,120 @@
+/**
+ * phases/review-core.js — the shared Story-scope review spine.
+ *
+ * Extracted from `phases/code-review.js` (Story #4603). `runStoryReviewCore` is
+ * the one implementation both close paths call `runCodeReview` through — the
+ * epic-attached phase (`code-review.js#runStoryCodeReview`) and the standalone
+ * v2 path (`single-story-close/phases/code-review.js#runStoryScopeReview`) —
+ * so it belongs to neither and lives here rather than inside one path's phase
+ * file (Story #3653 established the shared-spine contract).
+ */
+
+import { gitSpawn } from '../../../git-utils.js';
+import { computeChangeSet } from '../../change-set.js';
+import { runCodeReview } from '../../code-review.js';
+import { runLocalLensReview } from './local-lens-review.js';
+
+/**
+ * Invoke `runCodeReviewFn` with the canonical Story-scope envelope and return
+ * the raw result.
+ *
+ * The caller is responsible for error handling and result interpretation —
+ * this function propagates throws rather than swallowing them, because the
+ * two callers have different advisory postures:
+ *
+ *   - Epic-attached close: swallows throws (non-blocking advisory, same as
+ *     `refresh.js`).
+ *   - Standalone close: propagates throws (a review failure stops the close).
+ *
+ * Review depth is not passed in: `runCodeReview` derives it from the changed
+ * files — their sensitive-path intersection plus their count (Story #4542, which
+ * retired the planner-authored risk envelope this spine used to forward). Depth
+ * remains an **input-only** signal: it tells the provider how thorough to be and
+ * never alters the review's output envelope or the posted structured-comment
+ * body.
+ *
+ * Story #4593 — this spine is the **single injection point** for the change set.
+ * It enumerates `baseRef...headRef` exactly once via {@link computeChangeSet}
+ * and threads the resulting list into both the local-lens pass and
+ * `runCodeReview`, which otherwise each enumerated the diff for themselves. Both
+ * consumers ultimately route through `deriveChangeLevel`, so feeding them one
+ * list is what makes the lens roster and the review depth provably agree about
+ * what changed — even when a commit lands between the two calls.
+ *
+ * Story #4603 — the invariant now holds on the failure path too: an unenumerable
+ * diff injects an explicit `null`, and both consumers distinguish that from
+ * `undefined` ("nobody enumerated") rather than re-spawning git.
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   baseRef: string,
+ *   headRef: string,
+ *   commentTargetId?: number|null,
+ *   provider: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   progressTag?: string,
+ *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
+ *   computeChangeSetFn?: typeof computeChangeSet,
+ *   runCodeReviewFn?: typeof runCodeReview,
+ *   runLocalLensReviewFn?: typeof runLocalLensReview,
+ * }} args
+ * @returns {Promise<object>} Raw result envelope from `runCodeReview`, augmented
+ *   with a `localLensReview` field carrying the Story-scope local-lens pass
+ *   outcome (Epic #4405, Story #4409) and the `changeSet` this run computed
+ *   (Story #4593).
+ */
+export async function runStoryReviewCore({
+  storyId,
+  baseRef,
+  headRef,
+  commentTargetId = null,
+  provider,
+  progress,
+  progressTag = 'CODE-REVIEW',
+  gitSpawnFn = gitSpawn,
+  computeChangeSetFn = computeChangeSet,
+  runCodeReviewFn = runCodeReview,
+  runLocalLensReviewFn = runLocalLensReview,
+}) {
+  const storyIdNum = Number(storyId);
+
+  // The one enumeration per close run. Every consumer below is injected from
+  // this list; none of them re-derives the diff. `files` is `null` when the
+  // diff is unenumerable — an explicit "already tried" signal both consumers
+  // honour without retrying (Story #4603).
+  const changeSet = computeChangeSetFn({ baseRef, headRef, gitSpawnFn });
+
+  const opts = {
+    scope: 'story',
+    ticketId: storyIdNum,
+    baseRef,
+    headRef,
+    provider,
+    changedFiles: changeSet.files,
+    gitSpawnFn,
+    logger: {
+      info: (m) => progress(progressTag, m),
+      warn: (m) => progress(progressTag, `⚠️ ${m}`),
+    },
+  };
+  if (commentTargetId != null) {
+    opts.commentTargetId = commentTargetId;
+  }
+
+  // Shift-left local-lens pass (Epic #4405). Runs matched local lenses at
+  // `light` depth against the actual Story diff, inside this close-subprocess
+  // spine so the maker never grades its own work. Advisory — it never blocks
+  // the close and its outcome rides on the returned envelope for downstream
+  // consumers.
+  const localLensReview = await runLocalLensReviewFn({
+    baseRef,
+    headRef,
+    changedFiles: changeSet.files,
+    progress,
+    progressTag,
+    gitSpawnFn,
+  });
+
+  const result = await runCodeReviewFn(opts);
+  return { ...result, localLensReview, changeSet };
+}

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -0,0 +1,360 @@
+/**
+ * story-deliver-terminal.js — the one terminal envelope every Story
+ * close-and-land invocation emits, and the shared next-command vocabulary
+ * (Story #4543).
+ *
+ * Before this module the delivery tail had **two** divergent return
+ * contracts, both prose and neither validated:
+ * `.agents/workflows/helpers/deliver-story.md` defined one shape and
+ * `.agents/agents/story-worker.md` a different one, so a caller could not
+ * distinguish a landed Story from a parked one without re-probing GitHub.
+ * `story-deliver-terminal.schema.json` is now the SSOT both docs reference
+ * rather than restate, and this module is its only writer.
+ *
+ * Two exports carry the contract:
+ *
+ *   - {@link buildTerminalEnvelope} assembles and **validates** the envelope.
+ *     It throws on a schema violation rather than emitting a malformed
+ *     terminal: a silently-wrong terminal is exactly the failure this Story
+ *     exists to eliminate, so failing loudly at the writer is the point.
+ *   - {@link NEXT_COMMANDS} is the next-command vocabulary shared with
+ *     `deliver-recover.js`, so a `pending` envelope and a recovery probe
+ *     name the same command for the same state instead of inventing two
+ *     dialects for one condition.
+ *
+ * `TERMINAL_EXIT_CODES` maps status → process exit code. `pending` gets its
+ * **own** code (3) precisely so a caller can tell "slow CI, resume me" from
+ * "hard block, come look" without parsing stdout — the distinction the
+ * pre-#4543 pipeline collapsed by treating budget exhaustion as a block.
+ */
+
+import { 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';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'story-deliver-terminal.schema.json',
+);
+
+export const TERMINAL_ENVELOPE_KIND = 'story-deliver-terminal';
+
+/**
+ * status → process exit code.
+ *
+ * `pending` is **3**, not 0 and not 1. Zero would tell a headless caller the
+ * Story landed when it did not; one would conflate a resumable slow-CI wait
+ * with a hard block and send the operator to diagnose branch protection that
+ * is working fine. A distinct code is what lets `/deliver` resume without
+ * classifying.
+ */
+export const TERMINAL_EXIT_CODES = Object.freeze({
+  landed: 0,
+  pending: 3,
+  blocked: 1,
+  failed: 1,
+});
+
+export const TERMINAL_STATUSES = Object.freeze([
+  'landed',
+  'pending',
+  'blocked',
+  'failed',
+]);
+
+/**
+ * The shared next-command vocabulary. Every producer of a "what now?"
+ * answer — the `pending` terminal envelope and `deliver-recover.js` —
+ * builds its command from here, so the two surfaces never drift into
+ * naming different commands for the same observed state.
+ */
+export const NEXT_COMMANDS = Object.freeze({
+  /**
+   * Resume a bounded merge wait that expired with the PR still in flight.
+   *
+   * `--wait` is load-bearing: without it the confirm CLI probes once and
+   * answers `pending` again, so the cumulative-budget give-up never fires and
+   * a wedged PR is never escalated to anyone.
+   */
+  resumeLand: (storyId) =>
+    `node .agents/scripts/single-story-confirm-merge.js --story ${storyId} --wait`,
+  /** Confirm a merged-but-mislabelled Story (the idempotent flip + tail). */
+  confirmMerge: (storyId) =>
+    `node .agents/scripts/single-story-confirm-merge.js --story ${storyId}`,
+  /** Enter the red-CI fix loop against the failing PR. */
+  watchCi: (storyId, prNumber) =>
+    `node .agents/scripts/pr-watch-with-update.js --pr ${prNumber} --story ${storyId}`,
+  /** Re-run close for a Story whose PR was never opened. */
+  close: (storyId) =>
+    `node .agents/scripts/single-story-close.js --story ${storyId}`,
+  /** Resume implementation in the Story worktree. */
+  implement: (storyId) =>
+    `node .agents/scripts/single-story-init.js --story ${storyId}`,
+  /** Re-assert a drifted Projects v2 Status column. */
+  resync: (storyId) =>
+    `node .agents/scripts/resync-status-column.js --story ${storyId}`,
+  /** Probe a stranded Story and print its single next command. */
+  recover: (storyId) =>
+    `node .agents/scripts/deliver-recover.js --story ${storyId}`,
+});
+
+/** @type {Function|null} */
+let _validator = null;
+
+/**
+ * Compile (once) and return the terminal-envelope validator.
+ *
+ * @returns {Function}
+ */
+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;
+}
+
+/**
+ * Validate a candidate envelope against the shipped schema.
+ *
+ * @param {object} envelope
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateTerminalEnvelope(envelope) {
+  const validate = getValidator();
+  const valid = validate(envelope);
+  if (valid) return { valid: true, errors: [] };
+  const errors = (validate.errors ?? []).map(
+    (e) => `${e.instancePath || '/'} ${e.message}`,
+  );
+  return { valid: false, errors };
+}
+
+/**
+ * Drop `undefined`-valued keys so the schema's `additionalProperties: false`
+ * and its nullable unions both stay satisfiable from one optional-argument
+ * builder signature.
+ *
+ * @param {object} obj
+ * @returns {object}
+ */
+function compact(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Assemble the terminal envelope and validate it before returning.
+ *
+ * Throws a `TypeError` naming the schema violations when the assembled
+ * object does not validate. That is deliberate: the whole point of the
+ * envelope is that a caller can trust its status without re-probing
+ * GitHub, so emitting an unvalidated one would reintroduce the ambiguity
+ * this replaces.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {'landed'|'pending'|'blocked'|'failed'} args.status
+ * @param {string} args.phase
+ * @param {string} [args.storyBranch]
+ * @param {string} [args.baseBranch]
+ * @param {object|null} [args.pr]
+ * @param {object} [args.gates]
+ * @param {object|null} [args.tail]
+ * @param {object|null} [args.blocked]
+ * @param {object|null} [args.failure]
+ * @param {string|null} [args.nextCommand]
+ * @param {number} args.elapsedSeconds
+ * @param {object|null} [args.waitBudget]
+ * @param {string} [args.timestamp]
+ * @returns {object} The validated envelope.
+ */
+export function buildTerminalEnvelope({
+  storyId,
+  status,
+  phase,
+  storyBranch,
+  baseBranch,
+  pr,
+  gates,
+  tail,
+  blocked,
+  failure,
+  nextCommand,
+  elapsedSeconds = 0,
+  waitBudget,
+  timestamp = new Date().toISOString(),
+}) {
+  const envelope = compact({
+    kind: TERMINAL_ENVELOPE_KIND,
+    storyId: Number(storyId),
+    status,
+    phase,
+    storyBranch: storyBranch ?? null,
+    baseBranch: baseBranch ?? null,
+    pr: pr ?? null,
+    gates,
+    tail: tail ?? null,
+    blocked: blocked ?? null,
+    failure: failure ?? null,
+    nextCommand: nextCommand ?? null,
+    elapsedSeconds: Math.max(0, Number(elapsedSeconds) || 0),
+    waitBudget: waitBudget ?? null,
+    timestamp,
+  });
+
+  const { valid, errors } = validateTerminalEnvelope(envelope);
+  if (!valid) {
+    throw new TypeError(
+      `buildTerminalEnvelope: assembled envelope violates story-deliver-terminal.schema.json:\n` +
+        errors.map((e) => `  - ${e}`).join('\n'),
+    );
+  }
+  return envelope;
+}
+
+/**
+ * Resolve the process exit code for a terminal envelope.
+ *
+ * @param {object} envelope
+ * @returns {number}
+ */
+export function exitCodeForTerminal(envelope) {
+  return TERMINAL_EXIT_CODES[envelope?.status] ?? 1;
+}
+
+/** The markers a caller scans stdout for to recover the envelope. */
+export const TERMINAL_BEGIN_MARKER = '--- STORY DELIVER TERMINAL ---';
+export const TERMINAL_END_MARKER = '--- END TERMINAL ---';
+
+/**
+ * Write a terminal envelope to stdout, between its markers.
+ *
+ * **Deliberately not `Logger.info`.** The envelope is this CLI's
+ * machine-readable contract — every invocation emits exactly ONE, and a
+ * headless caller parses it out of stdout to decide what happened.
+ * `Logger.info` is level-gated, so under the documented
+ * `AGENT_LOG_LEVEL=silent` (§ 1.H) the envelope silently vanished and the
+ * caller got a bare exit code: precisely the "no envelope at all" outcome
+ * Story #4543 exists to remove. A contract payload must not be suppressible
+ * by a verbosity knob.
+ *
+ * Single home for the marker format so the four emit sites (the runner's
+ * terminal, the close CLI's failed-terminal catch, and both confirm-CLI
+ * paths) cannot drift apart.
+ *
+ * @param {object} envelope
+ * @param {{ write?: (s: string) => void }} [opts] `write` is a test seam.
+ * @returns {void}
+ */
+export function emitTerminalEnvelope(
+  envelope,
+  { write = (s) => process.stdout.write(s) } = {},
+) {
+  write(
+    `\n${TERMINAL_BEGIN_MARKER}\n${JSON.stringify(envelope, null, 2)}\n${TERMINAL_END_MARKER}\n`,
+  );
+}
+
+/**
+ * Map a `runConfirmMergePhase` outcome onto the schema-validated terminal
+ * envelope (Story #4543). One writer, one shape — the two prose contracts
+ * this replaces disagreed with each other precisely because each surface
+ * assembled its own.
+ *
+ * @returns {object} A validated `story-deliver-terminal` envelope.
+ */
+export function terminalFromWaitOutcome({
+  waitOutcome,
+  storyId,
+  storyBranch,
+  baseBranch,
+  prNumber,
+  prUrl,
+  autoMergeEnabled,
+  gates,
+  elapsedSeconds,
+}) {
+  const prBase = {
+    number: prNumber,
+    url: prUrl ?? null,
+    autoMergeEnabled: Boolean(autoMergeEnabled),
+  };
+  const common = {
+    storyId,
+    storyBranch,
+    baseBranch,
+    gates,
+    elapsedSeconds,
+  };
+
+  if (waitOutcome.terminal === 'landed') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'landed',
+      phase: 'post-land',
+      pr: {
+        ...prBase,
+        state: 'MERGED',
+        // The observed rollup, not an assumed 'success' — a merge can land by
+        // admin override or with non-required checks red.
+        checksStatus: waitOutcome.prProbe?.checksStatus ?? null,
+      },
+      tail: waitOutcome.tail,
+      nextCommand: null,
+    });
+  }
+
+  if (waitOutcome.terminal === 'pending') {
+    return buildTerminalEnvelope({
+      ...common,
+      status: 'pending',
+      phase: 'confirm-merge',
+      pr: {
+        ...prBase,
+        state: waitOutcome.prProbe?.state ?? 'OPEN',
+        checksStatus: waitOutcome.prProbe?.checksStatus ?? null,
+      },
+      waitBudget: waitOutcome.waitBudget,
+      nextCommand: NEXT_COMMANDS.resumeLand(storyId),
+    });
+  }
+
+  // blocked — the classifier already named the class and the friction
+  // comment already carries the class-specific remediation, so the next
+  // command mirrors it rather than inventing a second opinion.
+  const nextCommand =
+    waitOutcome.blockClass === 'checks-failed'
+      ? NEXT_COMMANDS.watchCi(storyId, prNumber)
+      : waitOutcome.blockClass === 'merged-flip-failed'
+        ? NEXT_COMMANDS.confirmMerge(storyId)
+        : NEXT_COMMANDS.recover(storyId);
+  return buildTerminalEnvelope({
+    ...common,
+    status: 'blocked',
+    phase: 'confirm-merge',
+    pr: {
+      ...prBase,
+      state: waitOutcome.prProbe?.state ?? null,
+      checksStatus: waitOutcome.prProbe?.checksStatus ?? null,
+    },
+    blocked: {
+      blockClass: waitOutcome.blockClass,
+      reason: waitOutcome.reason,
+      frictionCommentId: waitOutcome.frictionCommentId ?? null,
+    },
+    nextCommand,
+  });
+}

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -72,15 +72,65 @@ export async function gatherStoryFrictionSignals(storyId, config) {
   return signals;
 }
 
+/**
+ * Render the empty-roll-up line.
+ *
+ * Story #4578 — an empty roll-up over a multi-Story run must NOT read as
+ * success. The pre-#4578 text ("No friction signals — nothing to follow up")
+ * was *truthful* about the stream and *false* about the run: a 7-Story
+ * delivery containing a mid-run git outage, a parked worker, and a
+ * four-round acceptance critic rendered byte-identically to a genuinely
+ * clean run. An operator cannot tell "nothing went wrong" from "the
+ * telemetry never fired", and the second is likeliest exactly when the run
+ * went worst.
+ *
+ * So the line is a function of `storyCount`:
+ *   - `storyCount <= 1` → the honest, quiet reading is retained. A single
+ *     Story that emitted nothing plausibly *was* clean, and crying wolf on
+ *     every clean Story is how a warning channel gets tuned out.
+ *   - `storyCount > 1`  → zero signals across N Stories is a **claim**, and
+ *     the surrounding text says so and names the two readings, rather than
+ *     asserting the flattering one.
+ *
+ * This mirrors the sibling precedent in `run-epilogue.js`'s
+ * `renderDiffLines`, which refuses to let an unresolvable base diff render
+ * as "0 changed files".
+ *
+ * @param {number} storyCount
+ * @returns {string[]}
+ */
+function renderEmptyRollupLines(storyCount) {
+  if (storyCount <= 1) {
+    return ['_No friction signals — nothing to follow up._'];
+  }
+  return [
+    `> ⚠️ **0 friction signals across ${storyCount} Stories — this is a claim, not a clean bill of health.**`,
+    '> Either the run was genuinely friction-free, or telemetry never fired.',
+    '> An empty stream is indistinguishable from a clean run, and it is least',
+    '> likely to fill exactly when a run is going badly and the agent is busy.',
+    '> The runtime emits friction from its own observables (`agent::blocked`',
+    '> transitions, failed closes, exhausted merge waits) — so zero here also',
+    '> means none of those fired. If the run had friction you can name, that',
+    '> gap is itself the follow-up worth filing.',
+  ];
+}
+
 /**
  * @param {{
  *   storyId: number,
  *   proposals: object,
  *   graduated: object,
- * }} args
+ *   storyCount?: number,
+ * }} args - `storyCount` (default 1) is how many Stories the roll-up spans;
+ *   it decides whether an empty result reads as quiet or as a flagged claim.
  * @returns {string}
  */
-export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
+export function buildFollowUpsCommentBody({
+  storyId,
+  proposals,
+  graduated,
+  storyCount = 1,
+}) {
   const filed = Array.isArray(graduated?.filed) ? graduated.filed : [];
   const framework = proposals?.framework ?? [];
   const consumer = proposals?.consumer ?? [];
@@ -124,7 +174,7 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
     consumer.length === 0 &&
     discarded.length === 0
   ) {
-    lines.push('_No friction signals — nothing to follow up._');
+    lines.push(...renderEmptyRollupLines(storyCount));
     lines.push('');
   }
   lines.push('```json');
@@ -132,6 +182,7 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
     JSON.stringify(
       {
         storyId,
+        storyCount,
         framework: framework.map((i) => i.category),
         consumer: consumer.map((i) => i.category),
         discarded: discarded.map((i) => i.category),
@@ -139,6 +190,15 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
           category: i.category,
           url: i.url ?? null,
         })),
+        // Story #4578 — an empty roll-up over N>1 Stories is a claim worth
+        // flagging, not a success. Machine-readable twin of the warning
+        // prose so a caller need not regex the body.
+        emptyRollupSuspect:
+          storyCount > 1 &&
+          filed.length === 0 &&
+          framework.length === 0 &&
+          consumer.length === 0 &&
+          discarded.length === 0,
       },
       null,
       2,
@@ -149,8 +209,18 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
 }
 
 /**
- * Capture and persist Story follow-ups. Never throws — close must not fail
- * because follow-up filing flaked.
+ * Capture and persist Story follow-ups. Never throws — the land must not
+ * fail because follow-up filing flaked.
+ *
+ * Story #4543 retired the `captureFollowUpsAfterConfirm` action-gate wrapper
+ * (and its `withConfirmFollowUps` sibling) that used to front this function.
+ * Re-deriving "did the merge land?" from a confirmation envelope's `action`
+ * field was the coupling that made close-and-land — the DEFAULT path — skip
+ * capture entirely: the gate only opened on the standalone CLI's `done`, and
+ * a belated manual confirm could not backfill because the Story was already
+ * `agent::done` (confirm returns `noop`, the gate never opens). The shared
+ * land tail (`single-story-close/phases/post-land.js`) now calls this
+ * directly, after the merge is already confirmed.
  *
  * @param {object} args
  * @param {number} args.storyId
@@ -160,15 +230,6 @@ export function buildFollowUpsCommentBody({ storyId, proposals, graduated }) {
  * @param {(tag: string, msg: string) => void} [args.progress]
  * @returns {Promise<object>}
  */
-/**
- * Capture follow-ups only when merge confirm landed (`action === 'done'`).
- * One-liner seam for the confirm-merge CLI.
- */
-export async function captureFollowUpsAfterConfirm(confirmation, ctx) {
-  if (confirmation?.action !== 'done') return null;
-  return captureStoryFollowUps(ctx);
-}
-
 export async function captureStoryFollowUps({
   storyId,
   provider,

package/.agents/scripts/lib/orchestration/story-init-remote.js

@@ -1,6 +1,9 @@
 import { Logger } from '../Logger.js';
-import { AGENT_LABELS } from '../label-constants.js';
-import { upsertStructuredComment } from './ticketing.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+  upsertStructuredComment,
+} from './ticketing.js';
 
 /**
  * Fail closed when the repository remote cannot be verified. The Story is
@@ -30,13 +33,14 @@ export async function handleRemoteVerificationFailure({
         `[single-story-init] failed to post remote-verification friction: ${err?.message ?? err}`,
       );
     }
+    // Story #4539 — the canonical mutator. This is the path where the
+    // skipped Projects v2 column sync (Story #2548) visibly drifts: the
+    // Story is still agent::ready (To Do) when the remote probe fails, so
+    // a direct label write leaves the board reading To Do for a blocked
+    // Story. single-story-init.js's own comment explains exactly why this
+    // must not bypass the mutator.
     try {
-      await provider.updateTicket(storyId, {
-        labels: {
-          add: [AGENT_LABELS.BLOCKED],
-          remove: [AGENT_LABELS.READY, AGENT_LABELS.EXECUTING],
-        },
-      });
+      await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
     } catch (err) {
       Logger.warn(
         `[single-story-init] failed to block Story after remote verification: ${err?.message ?? err}`,