session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/state-md/mission-status.mjs

@@ -11,6 +11,15 @@
  * delegate to the pure helpers above and route the read+write cycle through
  * `writeStateMd` from frontmatter-mutators.mjs, which acquires
  * `.orchestrator/state.lock` for mechanical serialization (PSA-004).
+ *
+ * #1104 resolved the two remaining recovery limits with **Option 1 (skip-and-warn)
+ * + Option 2 (id gate)**: body recovery now skips the individual lines it cannot
+ * parse instead of abandoning the section at the first one, reports them through
+ * `recoverFrontmatterMissionStatusDetailed`, and `setMissionStatusOnDisk` — the
+ * layer that already does I/O, so the pure contract above survives — turns a
+ * non-empty skip list into one stderr WARN. `setMissionStatus` refuses a task id
+ * the recovery grammar cannot read, so the writer stops manufacturing the very
+ * lines the recovery has to skip.
  */
 
 import { parseStateMd, serializeStateMd } from './yaml-parser.mjs';
@@ -19,10 +28,96 @@ import { updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mj
 const MISSION_STATUS_HEADING_RE = /^##\s+Mission Status\s*$/;
 const WRITER_TIMESTAMP_SOURCE = '\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z';
 const WRITER_TIMESTAMP_RE = new RegExp(`^${WRITER_TIMESTAMP_SOURCE}$`);
+
+/**
+ * Task-ID grammar, shared by THREE surfaces on purpose: the body writer's own
+ * `taskId` gate in `setMissionStatus` (#1104 Option 2), the body recovery regex
+ * below, and the frontmatter validator in `parseMissionStatusStrict`. ONE source:
+ * a reader whose ID grammar is narrower than the writer's drops entries the
+ * writer just produced — the two-surface divergence class this module exists to
+ * close (#960/#1084/#1104). Accepts `m-1`, `docs-2`, `w2-1`, `w2-a-10`; rejects
+ * `M-1`, `m1`, `Docs_2`, `docs`.
+ *
+ * The example list is measured, not asserted: this docblock advertised `w2-a10`
+ * until #1104, and the grammar rejects it — every segment but the last must be
+ * separated by `-`, so `a10` is not a segment boundary. Harmless while the
+ * grammar only gated the READER; load-bearing since `setMissionStatus` gates its
+ * `taskId` on it, where a wrong example buys a silent no-op. Pinned by
+ * `tests/lib/state-md-mission-status.test.mjs` ("refuses an id its own recovery
+ * cannot read").
+ */
+const MISSION_STATUS_ID_SOURCE = '[a-z][a-z0-9]*(?:-[a-z0-9]+)*-\\d+';
+const MISSION_STATUS_ID_RE = new RegExp(`^${MISSION_STATUS_ID_SOURCE}$`);
 const CANONICAL_MISSION_STATUS_ENTRY_RE = new RegExp(
-  `^- ([a-z][a-z0-9]*(?:-[a-z0-9]+)*-\\d+): (.*) \\(updated (${WRITER_TIMESTAMP_SOURCE})\\)$`
+  `^- (${MISSION_STATUS_ID_SOURCE}): (.*) \\(updated (${WRITER_TIMESTAMP_SOURCE})\\)$`
 );
 
+/**
+ * The 5-value mission-status vocabulary (`skills/session-plan/SKILL.md` §
+ * Mission-Status Enum). A VOCABULARY, not a state machine and not a gate: an
+ * out-of-enum value is reported as a WARNING by `parseMissionStatusStrict` and
+ * still returned by `parseMissionStatus`, because dropping it on the read side
+ * would hide on the frontmatter surface exactly what `setMissionStatus`
+ * deliberately makes visible on both.
+ *
+ * @type {readonly string[]}
+ */
+export const MISSION_STATUS_VALUES = Object.freeze([
+  'brainstormed',
+  'validated',
+  'in-dev',
+  'testing',
+  'completed',
+]);
+
+/** Scalar shapes this YAML subset can produce for an entry field. */
+function isScalarField(value) {
+  return (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  );
+}
+
+/**
+ * Validates ONE `mission-status` entry.
+ *
+ * Hard requirements are exactly the fields a consumer cannot work without: the
+ * entry must be a mapping, `id` must match the writer's own ID grammar, and
+ * `status` must be a non-empty string. `task` and `wave` are OPTIONAL — the
+ * recovery path in `recoverFrontmatterMissionStatus` emits truthful partial
+ * `{ id, status }` entries on purpose, and requiring the metadata here would
+ * delete them on read (measured: `setMissionStatus` on a legacy body yields
+ * `[{"id":"docs-2","status":"completed"}]`). When present they must still be
+ * scalars — an object or array there is a parse gone sideways, and renders as
+ * `[object Object]` in the vault rollup table.
+ *
+ * @param {unknown} entry
+ * @returns {{ valid: true, warning: string|null }|{ valid: false, reason: string }}
+ */
+function validateMissionStatusEntry(entry) {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    return { valid: false, reason: 'not-a-mapping' };
+  }
+  if (typeof entry.id !== 'string' || !MISSION_STATUS_ID_RE.test(entry.id)) {
+    return { valid: false, reason: 'invalid-id' };
+  }
+  if (typeof entry.status !== 'string' || entry.status.trim() === '') {
+    return { valid: false, reason: 'invalid-status' };
+  }
+  if (Object.prototype.hasOwnProperty.call(entry, 'task') && !isScalarField(entry.task)) {
+    return { valid: false, reason: 'invalid-task' };
+  }
+  if (Object.prototype.hasOwnProperty.call(entry, 'wave') && !isScalarField(entry.wave)) {
+    return { valid: false, reason: 'invalid-wave' };
+  }
+  return {
+    valid: true,
+    warning: MISSION_STATUS_VALUES.includes(entry.status) ? null : 'status-not-in-enum',
+  };
+}
+
 /**
  * Finds the first exact `## Mission Status` section and its closing heading.
  *
@@ -52,33 +147,92 @@ function isWriterTimestamp(timestamp) {
 
 /**
  * Parses the optional `mission-status:` block from a STATE.md frontmatter object
- * (as returned by `parseStateMd(...).frontmatter`).
+ * (as returned by `parseStateMd(...).frontmatter`), keeping only entries that pass
+ * `validateMissionStatusEntry`.
  *
  * Returns `null` when the `mission-status` key is absent (backward-compat: pre-#340
- * STATE.md files). Returns `[]` when the key is present but the value is an empty
- * array. Returns the array of entries when present and non-empty.
+ * STATE.md files) or holds a non-array. Returns `[]` when the key is present but the
+ * value is an empty array — or when every entry in it was rejected.
  *
- * Does NOT validate individual entry shapes, and no helper in this repo does:
- * entry shape and the `status` enum are coordinator convention, deliberately not a
- * mechanical gate (see `syncFrontmatterMissionStatus` below for why).
+ * The rejects are NOT surfaced here (the return type is unchanged for existing
+ * callers). Use `parseMissionStatusStrict` when you need to report them; a caller
+ * that only counts or renders entries wants the clean list.
  *
  * @param {object} frontmatter
  * @returns {object[]|null}
  */
 export function parseMissionStatus(frontmatter) {
+  return parseMissionStatusStrict(frontmatter).items;
+}
+
+/**
+ * `parseMissionStatus` with its rejects and vocabulary warnings attached.
+ *
+ * Before #1111 nothing in this repo validated entry shape, so a malformed entry —
+ * a flow-mapping list item mangled into a key literally named `{ id`, a bare
+ * scalar left in the array, an entry with no `status` — reached session-end Phase
+ * 1.9/1.10 and `vault-status/narrative-mirror.mjs` as a plausible-looking task and
+ * was counted. `items` is what a consumer may trust; `invalid` is what a reporter
+ * must show instead of silently dropping.
+ *
+ * The `{ id` mangling itself no longer originates HERE: yaml-parser.mjs now parses
+ * a single-line flow mapping into the same object a block item yields. This
+ * validator stays the reader-side net for every OTHER source of a malformed entry
+ * — a hand-built array passed to `writeMissionStatus`, a future parser change, a
+ * third-party writer — none of which the parser fix can speak for.
+ *
+ * - `items` — mirrors `parseMissionStatus` exactly (`null` when the key is absent
+ *   or not an array; otherwise the entries that validated, in source order).
+ * - `invalid` — `{ index, reason }` per rejected entry, `index` addressing the RAW
+ *   array. Reasons: `not-a-mapping`, `invalid-id`, `invalid-status`, `invalid-task`,
+ *   `invalid-wave`.
+ * - `warnings` — `{ index, reason }` for entries that are structurally fine but
+ *   suspect: `duplicate-id` (a second entry with an id already seen — the sync in
+ *   `syncFrontmatterMissionStatus` only ever updates the FIRST match, so the copy
+ *   keeps a stale status forever and Phase 1.10 counts the task twice) and
+ *   `status-not-in-enum`. Both stay in `items` on purpose.
+ *
+ * @param {object} frontmatter
+ * @returns {{ items: object[]|null, invalid: Array<{index: number, reason: string}>, warnings: Array<{index: number, reason: string}> }}
+ */
+export function parseMissionStatusStrict(frontmatter) {
+  const empty = { items: null, invalid: [], warnings: [] };
   if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
-    return null;
+    return empty;
   }
   if (!Object.prototype.hasOwnProperty.call(frontmatter, 'mission-status')) {
-    return null;
+    return empty;
   }
   const raw = frontmatter['mission-status'];
   if (!Array.isArray(raw)) {
     // Present but not an array (e.g. null scalar from empty key) — treat as absent
-    return null;
+    return empty;
   }
-  // Return a shallow copy to prevent mutation of the parsed frontmatter
-  return raw.slice();
+
+  // A fresh array (never `raw` itself) keeps the shallow-copy contract: callers may
+  // push/splice their result without touching the parsed frontmatter.
+  const items = [];
+  const invalid = [];
+  const warnings = [];
+  const seenIds = new Set();
+  for (let index = 0; index < raw.length; index++) {
+    const entry = raw[index];
+    const verdict = validateMissionStatusEntry(entry);
+    if (!verdict.valid) {
+      invalid.push({ index, reason: verdict.reason });
+      continue;
+    }
+    if (seenIds.has(entry.id)) {
+      warnings.push({ index, reason: 'duplicate-id' });
+    } else {
+      seenIds.add(entry.id);
+    }
+    if (verdict.warning !== null) {
+      warnings.push({ index, reason: verdict.warning });
+    }
+    items.push(entry);
+  }
+  return { items, invalid, warnings };
 }
 
 /**
@@ -90,9 +244,11 @@ export function parseMissionStatus(frontmatter) {
  * - Works on string input (pure — no file I/O). Returns the updated STATE.md contents.
  * - No-ops if `contents` has no parseable frontmatter (returns input unchanged).
  *
- * Individual entry objects are expected to carry `{ id, task, wave, status }`, but
- * this function does NOT enforce that shape and no validator in this repo does —
- * callers own the invariant.
+ * Individual entry objects are expected to carry `{ id, task, wave, status }`. This
+ * WRITER does not enforce that shape — whatever it is handed is serialized, so a
+ * malformed entry lands visibly in the file rather than being dropped on the way in.
+ * The READER is where the shape is checked since #1111: `parseMissionStatus` returns
+ * only entries that validate, and `parseMissionStatusStrict` reports the rest.
  *
  * @param {string} contents
  * @param {object[]|null|undefined} missionStatusArray
@@ -164,6 +320,8 @@ function syncFrontmatterMissionStatus(frontmatter, taskId, status) {
 }
 
 /**
+ * `recoverFrontmatterMissionStatus` with the lines it declined attached.
+ *
  * Mirrors body-only task IDs into the frontmatter `mission-status` registry as
  * partial `{ id, status }` entries. This is a SUPERSET merge: existing entries are
  * never rewritten or reordered, so their full metadata (`task`, `wave`) survives —
@@ -176,45 +334,75 @@ function syncFrontmatterMissionStatus(frontmatter, taskId, status) {
  * #1084 one write later — measured m-1/m-2/m-3 in the body against `[m-1]` in the
  * frontmatter.
  *
- * The section parse stays strict and all-or-nothing: any nonblank line that is not a
- * unique canonical writer bullet (unsafe ID, pipe, malformed timestamp, duplicate,
- * prose) aborts the whole merge rather than fabricating entries from an ambiguous
- * body. Known limitation: one foreign-but-writer-accepted ID (e.g. `Docs_2`) or a
- * hand-written legacy bullet without a timestamp therefore suppresses the merge for
- * the whole file, silently.
+ * **#1104 decision — Option 1 (skip-and-warn) + Option 2 (id gate).** The parse was
+ * all-or-nothing until #1104: ONE nonblank line that was not a unique canonical
+ * writer bullet aborted the whole merge. Measured over all 16 host-local
+ * `<repo>/.claude/STATE.md` (2026-08-21), exactly one repo carried the #1084 shape,
+ * and its bullets were hand-written (`- m-1 D1 ADR-Delta: completed`, no
+ * `(updated <ISO>)`), so the abort fired on line 1 and the class the recovery was
+ * built for was served 0 of 1.
+ * The abort is now per LINE: a line that does not parse is skipped and reported here,
+ * every other line still recovers. Nothing is ever fabricated — a skipped line
+ * contributes no entry, exactly as before. Option 2 is the other half, in
+ * `setMissionStatus`: the writer now refuses an id its own recovery cannot read, so
+ * the writer can no longer manufacture the lines this function has to skip.
+ *
+ * Option 3 (WARN) is honoured at the seam rather than here: this function stays pure,
+ * and `setMissionStatusOnDisk` — which already does I/O — turns a non-empty `skipped`
+ * into ONE stderr WARN. That is what makes "recovery declined N lines" distinguishable
+ * from "nothing to do", the third #1104 acceptance criterion.
+ *
+ * `skipped` reasons, in evaluation order per line:
+ * - `non-canonical` — not a writer bullet at all: prose, an id outside
+ *   `MISSION_STATUS_ID_SOURCE` (`Docs_2`, `m_1`), or a timestamp of the wrong SHAPE
+ *   (`(updated yesterday)`). This is the legacy hand-written class.
+ * - `unsafe-status` — canonical shape, but the status is empty or carries a `|`,
+ *   which the block-seq serializer cannot round-trip.
+ * - `invalid-timestamp` — right shape, not a real instant (e.g. `2026-02-30T…`).
+ * - `duplicate-id` — a SECOND bullet for an id already recovered from this section.
+ *   The FIRST wins, matching `setMissionStatus`/`readMissionStatus`, which both
+ *   operate on the first matching bullet.
  *
  * @param {object} frontmatter
  * @param {string} body
- * @returns {object}
+ * @returns {{ frontmatter: object, skipped: Array<{line: string, reason: string}> }}
  */
-function recoverFrontmatterMissionStatus(frontmatter, body) {
+export function recoverFrontmatterMissionStatusDetailed(frontmatter, body) {
   if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
-    return frontmatter;
+    return { frontmatter, skipped: [] };
   }
   const raw = frontmatter['mission-status'];
-  if (!Array.isArray(raw) || typeof body !== 'string') return frontmatter;
+  if (!Array.isArray(raw) || typeof body !== 'string') return { frontmatter, skipped: [] };
 
   const lines = body.split('\n');
   const section = findMissionStatusSection(lines);
-  if (section === null) return frontmatter;
+  if (section === null) return { frontmatter, skipped: [] };
 
   const entries = [];
   const ids = new Set();
+  const skipped = [];
   for (let i = section.headingIdx + 1; i < section.sectionEnd; i++) {
     const line = lines[i];
     if (line.trim() === '') continue;
 
     const match = CANONICAL_MISSION_STATUS_ENTRY_RE.exec(line);
-    if (match === null) return frontmatter;
+    if (match === null) {
+      skipped.push({ line, reason: 'non-canonical' });
+      continue;
+    }
+    // A status can never contain `\n` here — `line` came out of a `\n` split.
     const [, id, status, timestamp] = match;
-    if (
-      status.length === 0 ||
-      status.includes('|') ||
-      status.includes('\n') ||
-      !isWriterTimestamp(timestamp) ||
-      ids.has(id)
-    ) {
-      return frontmatter;
+    if (status.length === 0 || status.includes('|')) {
+      skipped.push({ line, reason: 'unsafe-status' });
+      continue;
+    }
+    if (!isWriterTimestamp(timestamp)) {
+      skipped.push({ line, reason: 'invalid-timestamp' });
+      continue;
+    }
+    if (ids.has(id)) {
+      skipped.push({ line, reason: 'duplicate-id' });
+      continue;
     }
     ids.add(id);
     entries.push({ id, status });
@@ -226,15 +414,30 @@ function recoverFrontmatterMissionStatus(frontmatter, body) {
       .map((e) => e.id)
   );
   const added = entries.filter((e) => !known.has(e.id));
-  if (added.length === 0) return frontmatter;
-  return { ...frontmatter, 'mission-status': [...raw, ...added] };
+  if (added.length === 0) return { frontmatter, skipped };
+  return { frontmatter: { ...frontmatter, 'mission-status': [...raw, ...added] }, skipped };
 }
 
+/**
+ * Serialize a mission-status update, carrying the recovery's skipped lines out
+ * with it.
+ *
+ * Returns `skipped` rather than discarding it (and rather than leaving the
+ * caller to re-run the recovery to see it): before 2026-08-28
+ * `setMissionStatusOnDisk` called `recoverFrontmatterMissionStatusDetailed` a
+ * SECOND time purely to read `skipped`, so the same body was parsed twice per
+ * write and the two results could disagree the moment either input drifted.
+ *
+ * @param {object} frontmatter
+ * @param {string} body
+ * @returns {{ contents: string, skipped: Array<{line: string, reason: string}> }}
+ */
 function serializeMissionStatusUpdate(frontmatter, body) {
-  return serializeStateMd({
-    frontmatter: recoverFrontmatterMissionStatus(frontmatter, body),
-    body,
-  });
+  const recovered = recoverFrontmatterMissionStatusDetailed(frontmatter, body);
+  return {
+    contents: serializeStateMd({ frontmatter: recovered.frontmatter, body }),
+    skipped: recovered.skipped,
+  };
 }
 
 /**
@@ -251,22 +454,65 @@ function serializeMissionStatusUpdate(frontmatter, body) {
  * live writer and the reader sat on different surfaces and drifted apart in both
  * directions. A legacy empty registry is recovered from canonical body bullets as
  * partial `{ id, status }` entries, which lets frontmatter readers classify the work
- * without fabricated metadata. Ambiguous legacy bodies remain empty; other unmatched
- * populated entries remain update-only. See `syncFrontmatterMissionStatus`.
+ * without fabricated metadata. Since #1104 that recovery skips only the lines it cannot
+ * parse instead of abandoning the whole section; other unmatched populated entries remain
+ * update-only. See `syncFrontmatterMissionStatus` and
+ * `recoverFrontmatterMissionStatusDetailed`.
+ *
+ * **#1104 Option 2 — `taskId` is gated on the reader's own grammar**
+ * (`MISSION_STATUS_ID_SOURCE`: lowercase alphanumeric segments joined by `-`, ending in
+ * `-<digits>` — `m-1`, `docs-2`, `w2-1`; NOT `M-1`, `m1`, `Docs_2`, `w2-a10`). Until #1104 this
+ * gate was `typeof taskId === 'string'`, so the writer produced body lines
+ * (`- Docs_2: in-dev (updated …)`) that its OWN recovery could never read back — the
+ * mechanism behind "setMissionStatus in a loop seeds only the body". A non-conforming id
+ * now returns `contents` unchanged rather than writing an unreadable line: refusing to
+ * write is recoverable, writing a line no reader accepts is not.
  *
  * Pure function — no I/O. Returns original `contents` unchanged on bad input.
  *
  * @param {string} contents - Current STATE.md file contents (string)
- * @param {string} taskId - Task identifier (e.g. 'm-1', 'docs-2')
+ * @param {string} taskId - Task identifier matching `MISSION_STATUS_ID_SOURCE` (e.g. 'm-1', 'docs-2')
  * @param {string} status - One of: brainstormed | validated | in-dev | testing | completed
  * @returns {string}
  */
 export function setMissionStatus(contents, taskId, status) {
-  if (typeof contents !== 'string') return contents;
-  if (!taskId || typeof taskId !== 'string') return contents;
-  if (!status || typeof status !== 'string') return contents;
+  return setMissionStatusDetailed(contents, taskId, status).contents;
+}
+
+/**
+ * `setMissionStatus` with the outcome attached — the same relationship
+ * `recoverFrontmatterMissionStatusDetailed` has to its merge-only view, and for
+ * the same reason: a pure function cannot report, and a caller that only sees
+ * `contents` cannot tell a refusal from a no-op.
+ *
+ * There are FIVE ways this function declines to write, and until 2026-08-28
+ * `setMissionStatusOnDisk` could only name ONE of them — it re-tested
+ * `MISSION_STATUS_ID_RE` itself and warned on the grammar case alone. The other
+ * four (`contents` not a string, a missing/non-string `taskId`, a
+ * missing/non-string `status`, STATE.md that does not parse) returned `contents`
+ * unchanged, which `writeStateMd` reports as `written: false` — byte-identical
+ * to "the file already said that". Re-deriving the reason at the seam is what
+ * made four of five invisible; the reason now travels with the result.
+ *
+ * `refused` is OMITTED (not `null`) on the success path, so `'refused' in out`
+ * is the discriminator and no caller has to compare against a sentinel.
+ *
+ * @param {string} contents
+ * @param {string} taskId
+ * @param {string} status
+ * @returns {{
+ *   contents: string,
+ *   refused?: 'bad-contents'|'bad-id'|'id-grammar'|'bad-status'|'unparseable',
+ *   skipped: Array<{line: string, reason: string}>,
+ * }}
+ */
+export function setMissionStatusDetailed(contents, taskId, status) {
+  if (typeof contents !== 'string') return { contents, refused: 'bad-contents', skipped: [] };
+  if (!taskId || typeof taskId !== 'string') return { contents, refused: 'bad-id', skipped: [] };
+  if (!MISSION_STATUS_ID_RE.test(taskId)) return { contents, refused: 'id-grammar', skipped: [] };
+  if (!status || typeof status !== 'string') return { contents, refused: 'bad-status', skipped: [] };
   const parsed = parseStateMd(contents);
-  if (parsed === null) return contents;
+  if (parsed === null) return { contents, refused: 'unparseable', skipped: [] };
 
   // Computed once so every return path below emits the same synced frontmatter.
   const frontmatter = syncFrontmatterMissionStatus(parsed.frontmatter, taskId, status);
@@ -354,7 +600,8 @@ export function readMissionStatus(contents, taskId) {
     if (match) return match[1];
   }
 
-  // Reader-only legacy compatibility. Recovery remains canonical and all-or-nothing.
+  // Reader-only legacy compatibility. Recovery still accepts canonical bullets only —
+  // since #1104 it skips the others per line instead of abandoning the section.
   const legacyEntryRe = new RegExp(`^-\\s+${escapedId}:\\s+(\\S+)`);
   for (let i = section.headingIdx + 1; i < section.sectionEnd; i++) {
     const match = legacyEntryRe.exec(lines[i]);
@@ -384,20 +631,71 @@ export async function writeMissionStatusOnDisk(repoRoot, missionStatusArray, opt
   );
 }
 
+/**
+ * Why each refusal declined to write, in the words an operator can act on.
+ *
+ * A closed map rather than an inline ternary chain: adding a refusal to
+ * `setMissionStatusDetailed` without a message here yields `undefined` in the
+ * WARN, which is loud in a test — the fail-toward-visible direction.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const REFUSAL_REASONS = Object.freeze({
+  'bad-contents': 'STATE.md contents were not a string',
+  'bad-id': 'taskId was missing or not a string',
+  'id-grammar': 'taskId does not match the mission-status id grammar',
+  'bad-status': 'status was missing or not a string',
+  unparseable: 'STATE.md could not be parsed',
+});
+
 /**
  * Lock-guarded `setMissionStatus` — sets or replaces a single task entry in
  * the `## Mission Status` body section under the state-lock.
  *
+ * This is the #1104 Option-3 seam: the recovery is pure and cannot report the
+ * body lines it skipped, so the wrapper that already does I/O emits ONE stderr
+ * WARN naming the count and the first reason. Without it a declined recovery is
+ * byte-identical to "nothing to recover" — the silence the issue's third
+ * acceptance criterion is about. It never blocks the write: the skipped lines
+ * are pre-existing body content, not a defect in THIS write.
+ *
+ * The refusal WARN is the same seam applied to the OTHER silence. It used to
+ * re-test `MISSION_STATUS_ID_RE` here and so covered 1 of the 5 ways
+ * `setMissionStatus` declines; it now reads `refused` off
+ * `setMissionStatusDetailed` and covers all five. Exactly ONE line is written
+ * per call: a refusal means nothing was written, so the skipped-lines report
+ * would describe a merge that did not happen.
+ *
+ * `reason` is added to the result on a refusal, matching how `writeStateMd`
+ * already reports its own declines (`reason: 'size-ceiling'`).
+ *
  * @param {string|undefined} repoRoot
  * @param {string} taskId
  * @param {string} status   brainstormed | validated | in-dev | testing | completed
  * @param {object} [opts]
- * @returns {Promise<{ written: boolean, path: string, contents: string|null }>}
+ * @returns {Promise<{ written: boolean, path: string, contents: string|null, reason?: string }>}
  */
 export async function setMissionStatusOnDisk(repoRoot, taskId, status, opts = {}) {
-  return writeStateMd(
+  let refused;
+  const result = await writeStateMd(
     repoRoot,
-    (contents) => setMissionStatus(contents, taskId, status),
+    (contents) => {
+      const outcome = setMissionStatusDetailed(contents, taskId, status);
+      refused = outcome.refused;
+      if (outcome.refused) {
+        process.stderr.write(
+          `⚠ setMissionStatusOnDisk: ${REFUSAL_REASONS[outcome.refused]} ` +
+            `(reason: ${outcome.refused}, taskId: ${JSON.stringify(taskId)}) — nothing written\n`
+        );
+      } else if (outcome.skipped.length > 0) {
+        process.stderr.write(
+          `⚠ setMissionStatusOnDisk: mission-status recovery skipped ${outcome.skipped.length} ` +
+            `body line(s) — first: ${outcome.skipped[0].reason} (${outcome.skipped[0].line.trim()})\n`
+        );
+      }
+      return outcome.contents;
+    },
     opts
   );
+  return refused ? { ...result, written: false, reason: refused } : result;
 }