@sublang/playbook 0.1.3 → 0.4.0

package/{code.playbook.ts → reference/sdlc/code.playbook/code.playbook.ts}

@@ -7,7 +7,7 @@
 //                Committer→{coder per CODE-18/19} (CODE-19 wires both
 //                coderPlayer and reviewerPlayer; Coder wins as the
 //                alias's first alternative)
-// Boss event:    slash-prefix (LLM-classifier fallback)
+// Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
 
 import { createActor, fromPromise } from 'xstate';
@@ -18,7 +18,11 @@ import {
   type CodingEvent,
   type CodingInput,
 } from './code.fsm.js';
-import { enumerateCaptainStates } from './code.fsm.introspect.js';
+import {
+  enumerateAwaitBossReply,
+  enumerateCaptainStates,
+  enumerateRootEvents,
+} from './code.fsm.introspect.js';
 
 // Public contract — `PlayerResult`, `PlaybookPorts`, `PlaybookRuntime`,
 // `CodePlaybookOptions`, and the default `createPlaybookRuntime` factory
@@ -49,25 +53,43 @@ export interface PlaybookRuntime {
 
 export type CodePlaybookOptions = CodingInput;
 
+const BOSS_REPLY_ERRORS = {
+  missingQuestion: "needsBossReply outcome missing 'question' field",
+  unregisteredState: (stateId: string) =>
+    `state ${stateId} declared needsBossReply but is not registered as resumable`,
+} as const;
+
 // Internal capabilities (DR-004 §10). Each ships with its final
 // signature; behavior lands in the per-capability task noted by the
 // TODO marker.
 
 // Player-prompt composer — DR-004 §6.
 // Substitutes the three placeholder tokens in `input.prompt` (literal
-// string replace, no escaping) and prepends labelled blocks for any
-// populated structured field. The FSM's prompt body is never re-flowed.
+// string replace, no escaping) and arranges labelled blocks around
+// the prompt body. Context blocks the body refers to as prior
+// material (`Boss intent:`, `Task description:`) are prepended;
+// action blocks the body refers to as material below
+// (`Review items:`, `Rebuttals:`) are appended after the body so the
+// CODE-N prompts' "review item below" / "rebuttal below" phrasing
+// matches the rendered layout. When a state resumes from a Boss
+// reply, the continuation preamble and Q/A blocks precede every
+// ordinary block. The FSM's prompt body is never re-flowed.
+
 function composePlayerPrompt(input: CaptainInput): string {
   const blocks: string[] = [];
+  if (
+    input.pendingBossQuestion !== undefined &&
+    input.bossReply !== undefined
+  ) {
+    blocks.push(
+      'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.',
+    );
+    blocks.push(`Boss question:\n${input.pendingBossQuestion.question}`);
+    blocks.push(`Boss reply:\n${input.bossReply}`);
+  }
   if (input.intent !== undefined) {
     blocks.push(`Boss intent:\n${input.intent}`);
   }
-  if (input.reviews !== undefined) {
-    blocks.push(`Review items:\n${input.reviews}`);
-  }
-  if (input.challenges !== undefined) {
-    blocks.push(`Rebuttals:\n${input.challenges}`);
-  }
   if (input.taskDescription !== undefined) {
     blocks.push(`Task description:\n${input.taskDescription}`);
   }
@@ -84,6 +106,14 @@ function composePlayerPrompt(input: CaptainInput): string {
   }
 
   blocks.push(body);
+
+  if (input.reviews !== undefined) {
+    blocks.push(`Review items:\n${input.reviews}`);
+  }
+  if (input.challenges !== undefined) {
+    blocks.push(`Rebuttals:\n${input.challenges}`);
+  }
+
   return blocks.join('\n\n');
 }
 
@@ -153,6 +183,9 @@ async function adjudicate(
   // the judge response.
   for (const field of extractRequiredFields(input.result[guard])) {
     if (typeof obj[field] !== 'string') {
+      if (guard === 'needsBossReply' && field === 'question') {
+        throw new Error(BOSS_REPLY_ERRORS.missingQuestion);
+      }
       throw new Error(
         `adjudicate: judge response missing required field "${field}" for guard "${guard}"`,
       );
@@ -204,46 +237,22 @@ function parseJudgeJson(raw: string): unknown {
 }
 
 // Boss-event classifier — DR-004 §3.
-// Slash forms tried first; unknown slash forms surface as
-// emitStatus and return undefined per slc/link.md ("Unknown
-// commands surface as emitStatus, not as a silently-dropped
-// turn"). Anything that isn't a slash form falls through to the
-// LLM classifier via ports.callJudge with a fixed prompt that
-// names the four event types and their payload shapes.
+// Every non-empty Boss turn goes through ports.callJudge. Slash-prefixed
+// text is ordinary content once a host has routed the turn to this
+// playbook; `/command` selection belongs outside handleBossInput. The
+// classifier is state-aware so awaitBossReply can distinguish a direct
+// answer (BOSS_REPLY) from a fresh directive that abandons the pending
+// question through the FSM's existing transitions.
 async function classifyBossText(
   text: string,
   ports: PlaybookPorts,
   signal: AbortSignal,
+  snapshotOrState?: unknown,
 ): Promise<CodingEvent | undefined> {
   const trimmed = text.trim();
   if (trimmed === '') return undefined;
 
-  if (trimmed === '/start' || trimmed.startsWith('/start ')) {
-    return { type: 'START_CODING', intent: trimmed.slice('/start'.length).trim() };
-  }
-  if (trimmed === '/continue' || trimmed.startsWith('/continue ')) {
-    return {
-      type: 'CONTINUE_IR',
-      irNumber: trimmed.slice('/continue'.length).trim(),
-    };
-  }
-  if (trimmed === '/summarize' || trimmed.startsWith('/summarize ')) {
-    return {
-      type: 'SUMMARIZE_IR',
-      irNumber: trimmed.slice('/summarize'.length).trim(),
-    };
-  }
-  if (trimmed === '/interrupt' || trimmed.startsWith('/interrupt ')) {
-    return parseInterruptSlash(trimmed, ports);
-  }
-
-  if (trimmed.startsWith('/')) {
-    const cmd = trimmed.split(/\s+/)[0];
-    await ports.emitStatus(`Unknown slash command: ${cmd}`);
-    return undefined;
-  }
-
-  return classifyWithLlm(trimmed, ports, signal);
+  return classifyWithLlm(text, ports, signal, snapshotOrState);
 }
 
 // JumpableStateId is internal to code.fsm.ts (not exported), so
@@ -253,31 +262,20 @@ type JumpableStateId = Extract<
   { type: 'BOSS_INTERRUPT' }
 >['targetId'];
 
-async function parseInterruptSlash(
-  trimmed: string,
-  ports: PlaybookPorts,
-): Promise<CodingEvent | undefined> {
-  const rest = trimmed.slice('/interrupt'.length).trim();
-  if (rest === '') {
-    await ports.emitStatus('/interrupt requires a stateId');
-    return undefined;
-  }
-  const firstSpace = rest.search(/\s/);
-  const targetId = firstSpace === -1 ? rest : rest.slice(0, firstSpace);
-  const intent = firstSpace === -1 ? '' : rest.slice(firstSpace).trim();
-  return {
-    type: 'BOSS_INTERRUPT',
-    targetId: targetId as JumpableStateId,
-    ...(intent ? { intent } : {}),
-  };
-}
+const rootEvents = enumerateRootEvents(codingMachine);
+const bossInterruptTargets = rootEvents.bossInterruptTargetDescriptions;
+const bossInterruptTargetIds: ReadonlySet<string> = new Set(
+  bossInterruptTargets.map((target) => target.stateId),
+);
 
 async function classifyWithLlm(
   text: string,
   ports: PlaybookPorts,
   signal: AbortSignal,
+  snapshotOrState?: unknown,
 ): Promise<CodingEvent | undefined> {
-  const prompt = buildClassifierPrompt(text);
+  const state = classifierState(snapshotOrState);
+  const prompt = buildClassifierPrompt(text, state);
   const raw = await ports.callJudge(prompt, signal);
   const parsed = parseJudgeJson(raw);
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
@@ -298,6 +296,10 @@ async function classifyWithLlm(
       : {};
 
   switch (eventType) {
+    case 'NO_ACTION':
+    case 'NO_FSM_ACTION':
+    case 'NONE':
+      return undefined;
     case 'START_CODING': {
       if (typeof payload.intent !== 'string') {
         await ports.emitStatus('Classifier omitted intent for START_CODING');
@@ -326,6 +328,12 @@ async function classifyWithLlm(
         );
         return undefined;
       }
+      if (!bossInterruptTargetIds.has(payload.targetId)) {
+        await ports.emitStatus(
+          `Classifier supplied invalid targetId for BOSS_INTERRUPT: ${payload.targetId}`,
+        );
+        return undefined;
+      }
       return {
         type: 'BOSS_INTERRUPT',
         targetId: payload.targetId as JumpableStateId,
@@ -337,6 +345,19 @@ async function classifyWithLlm(
           : {}),
       };
     }
+    case 'BOSS_REPLY': {
+      if (state.value !== 'awaitBossReply') {
+        await ports.emitStatus(
+          'Classifier returned BOSS_REPLY outside awaitBossReply',
+        );
+        return undefined;
+      }
+      if (typeof payload.answer !== 'string') {
+        await ports.emitStatus('Classifier omitted answer for BOSS_REPLY');
+        return undefined;
+      }
+      return { type: 'BOSS_REPLY', answer: payload.answer };
+    }
     default:
       await ports.emitStatus(
         `Classifier returned unknown event type: ${eventType}`,
@@ -345,22 +366,76 @@ async function classifyWithLlm(
   }
 }
 
-function buildClassifierPrompt(text: string): string {
-  return [
+interface ClassifierState {
+  value: unknown;
+  context: Record<string, unknown>;
+}
+
+function classifierState(snapshotOrState: unknown): ClassifierState {
+  if (
+    snapshotOrState !== null &&
+    typeof snapshotOrState === 'object' &&
+    'value' in snapshotOrState
+  ) {
+    const candidate = snapshotOrState as {
+      value?: unknown;
+      context?: unknown;
+    };
+    return {
+      value: candidate.value,
+      context:
+        candidate.context !== null &&
+        typeof candidate.context === 'object' &&
+        !Array.isArray(candidate.context)
+          ? (candidate.context as Record<string, unknown>)
+          : {},
+    };
+  }
+  return { value: snapshotOrState, context: {} };
+}
+
+function buildClassifierPrompt(text: string, state: ClassifierState): string {
+  const currentState =
+    typeof state.value === 'string' ? state.value : 'unknown';
+  const pendingBossQuestion = pendingBossQuestionFromContext(state.context);
+  const lines = [
     'Classify the following Boss message into exactly one of these events.',
     'Respond with JSON: { "event": "<TYPE>", "payload": { ...fields } }.',
+    'Use { "event": "NO_ACTION", "payload": {} } when no FSM action should be taken.',
+    '',
+    `Current state: ${currentState}`,
+  ];
+  if (pendingBossQuestion !== undefined) {
+    lines.push(
+      `Pending Boss question: ${pendingBossQuestion.question}`,
+      `Pending resume state: ${pendingBossQuestion.resumeStateId}`,
+    );
+  }
+  lines.push(
     '',
     'Events:',
     '- START_CODING: payload { intent: "<free-form goal>" }',
     '- CONTINUE_IR: payload { irNumber: "<number>" }',
     '- SUMMARIZE_IR: payload { irNumber: "<number>" }',
     '- BOSS_INTERRUPT: payload { targetId: "<stateId>", intent?: "<free-form goal>", irNumber?: "<number>" }',
+    '  targetId must be one of these jumpable states:',
+  );
+  for (const target of bossInterruptTargets) {
+    lines.push(`  - ${target.stateId}: ${target.description}`);
+  }
+  if (currentState === 'awaitBossReply') {
+    lines.push('- BOSS_REPLY: payload { answer: "<verbatim Boss answer>" }');
+  } else {
+    lines.push('- BOSS_REPLY: valid only when Current state is awaitBossReply');
+  }
+  lines.push(
     '',
     'Boss message:',
     '```',
     text,
     '```',
-  ].join('\n');
+  );
+  return lines.join('\n');
 }
 
 // Captain-actor bridge — DR-004 §7. One PromiseActorLogic that the
@@ -397,20 +472,36 @@ function captainBridge(
           'captainBridge: callPlayer returned status=ok with no finalText',
         );
       }
-      return adjudicate(input, result.finalText, ports, activeSignal);
+      const output = await adjudicate(
+        input,
+        result.finalText,
+        ports,
+        activeSignal,
+      );
+      validateBossReplyOutput(input, output);
+      return output;
     },
   );
 }
 
 // Captain pane display — PBRT-3 / PBRT-14.
-// The Captain pane is a stream keyed on four glyphs so a reader can
-// parse each line at a glance:
-//   ◆  terminal entry (ready / done / failed)
-//   ▸  Boss input echo
-//   ⮕  captain-invoking state entry (label + player + CODE-N)
-//   ⤷  transition (guard fired by the just-finished captain call)
-// Prompts and full player output ride the player panes; the Captain
-// pane keeps to the state-machine shape.
+// The Captain pane is a stream of three glyphs plus one bare
+// captain-speech act, designed so a reader can parse each line at a
+// glance:
+//   (no glyph)  bare FSM event type — host renders as captain speech
+//               (e.g., `captain> START_CODING`)
+//   ⤷           captain-invoking state entry: `<Player>: <label>`
+//   →           transition guard outcome (`· field=N` tallies
+//               appended); the host presenter owns any visual
+//               nesting under the preceding ⤷ entry
+
+//   ◆           failure state (with `lastError` data) and the
+//               `awaitBossReply` suspension state (custom payload)
+// The runtime emits no status line on entry to the idle state
+// (`ready`) or the terminal state (`done`); the next `boss>` prompt
+// is the implicit "turn over" signal. Prompts and full player output
+// ride the player panes; the Captain pane keeps to the state-machine
+// shape.
 
 const STATE_LABELS: Readonly<Record<string, string>> = {
   planAndImplement: 'plan & implement',
@@ -458,26 +549,118 @@ const stateMetadata: ReadonlyMap<string, StateMetadata> = (() => {
   return m;
 })();
 
-const TERMINAL_STATES: ReadonlySet<string> = new Set([
+const stateIdBySourceItem: ReadonlyMap<string, string> = new Map(
+  [...stateMetadata.entries()].map(([stateId, meta]) => [
+    meta.sourceItem,
+    stateId,
+  ]),
+);
+
+const registeredResumableStateIds: ReadonlySet<string> = new Set(
+  enumerateAwaitBossReply(codingMachine).bossReplyTransitions.map(
+    (transition) => transition.target,
+  ),
+);
+
+function validateBossReplyOutput(
+  input: CaptainInput,
+  output: CaptainOutput,
+): void {
+  if (output.guard !== 'needsBossReply') return;
+  if (typeof output.question !== 'string') {
+    throw new Error(BOSS_REPLY_ERRORS.missingQuestion);
+  }
+  const stateId = stateIdBySourceItem.get(input.sourceItem);
+  if (stateId === undefined || !registeredResumableStateIds.has(stateId)) {
+    throw new Error(
+      BOSS_REPLY_ERRORS.unregisteredState(stateId ?? input.sourceItem),
+    );
+  }
+}
+
+const QUIESCENT_STATES: ReadonlySet<string> = new Set([
   'ready',
+  'awaitBossReply',
   'done',
   'failed',
 ]);
 
+// States whose entry the runtime does not surface on the Captain
+// pane per PBRT-3: the readline returning to its `boss>` prompt is
+// the implicit "turn over" signal, so a `◆ ready` / `◆ done`
+// tombstone is redundant.
+const SUPPRESSED_ENTRY_STATES: ReadonlySet<string> = new Set([
+  'ready',
+  'done',
+]);
+
 // Captain-pane surface (PBRT-3): every captain-invoking state plus
-// the three terminal/idle states. Wider than the prior
-// "Boss-relevant" set per slc/link.md's default "emit on every
-// transition; let the host filter."
+// the quiescent states whose entry still carries information
+// (failure with `lastError`, awaitBossReply with the pending
+// question). `ready` and `done` flow through the inspect handler
+// but their entries are dropped before emitStatus per
+// SUPPRESSED_ENTRY_STATES above.
 const CAPTAIN_PANE_STATES: ReadonlySet<string> = new Set([
   ...stateMetadata.keys(),
-  ...TERMINAL_STATES,
+  ...QUIESCENT_STATES,
 ]);
 
-function formatStateEntry(stateId: string): string {
-  if (TERMINAL_STATES.has(stateId)) return `◆ ${stateId}`;
+interface PendingBossQuestionForStatus {
+  resumeStateId: string;
+  sourceItem: string;
+  player: string;
+  question: string;
+}
+
+function pendingBossQuestionFromContext(
+  context: Record<string, unknown>,
+): PendingBossQuestionForStatus | undefined {
+  const pending = context.pendingBossQuestion;
+  if (pending === undefined || typeof pending !== 'object') {
+    return undefined;
+  }
+  const candidate = pending as Partial<
+    Record<keyof PendingBossQuestionForStatus, unknown>
+  >;
+  if (
+    typeof candidate.resumeStateId !== 'string' ||
+    typeof candidate.sourceItem !== 'string' ||
+    typeof candidate.player !== 'string' ||
+    typeof candidate.question !== 'string'
+  ) {
+    return undefined;
+  }
+  return {
+    resumeStateId: candidate.resumeStateId,
+    sourceItem: candidate.sourceItem,
+    player: candidate.player,
+    question: candidate.question,
+  };
+}
+
+function questionExcerpt(question: string): string {
+  return question.replace(/[\r\n]+/g, ' ').slice(0, 80);
+}
+
+function formatAwaitBossReplyEntry(context: Record<string, unknown>): string {
+  const pending = pendingBossQuestionFromContext(context);
+  const resumeStateId = pending?.resumeStateId ?? 'unknown';
+  const player = pending?.player ?? 'unknown';
+  const sourceItem = pending?.sourceItem ?? 'unknown';
+  const question = questionExcerpt(pending?.question ?? '');
+  return `◆ awaiting Boss reply · ${resumeStateId} · ${player} · ${sourceItem} · q=${JSON.stringify(question)}`;
+}
+
+function formatStateEntry(
+  stateId: string,
+  context: Record<string, unknown> = {},
+): string | undefined {
+  if (stateId === 'awaitBossReply') return formatAwaitBossReplyEntry(context);
+  if (SUPPRESSED_ENTRY_STATES.has(stateId)) return undefined;
+  if (stateId === 'failed') return '◆ failed';
   const meta = stateMetadata.get(stateId);
-  if (!meta) return `⮕ ${stateId}`;
-  return `⮕ ${meta.label}  ${meta.player} per ${meta.sourceItem}`;
+  if (!meta) return `⤷ ${stateId}`;
+  return `⤷ ${meta.player}: ${meta.label}`;
 }
 
 function formatTransition(event: unknown): string | undefined {
@@ -491,32 +674,32 @@ function formatTransition(event: unknown): string | undefined {
       tallies.push(`${field}=${items ? items.length : 1}`);
     }
   }
-  const suffix = tallies.length > 0 ? `  ${tallies.join(' ')}` : '';
-  return `⤷ ${output.guard}${suffix}`;
+  const suffix = tallies.length > 0 ? ` · ${tallies.join(' · ')}` : '';
+  // No leading whitespace: visual nesting under the preceding ⤷
+  // entry is the host presenter's concern (cligent's writeStatusLine
+  // emits status messages verbatim, with its own chrome but no
+  // continuation indent; layout is its job, not ours).
+  return `→ ${output.guard}${suffix}`;
 }
 
-function formatBossEcho(text: string, eventType?: string): string {
-  return eventType !== undefined
-    ? `▸ BOSS  ${text}  → ${eventType}`
-    : `▸ BOSS  ${text}`;
+function formatClassification(eventType: string): string {
+  return eventType;
 }
 
-// Rider fields PBRT-14 names — surfaced inline on a state entry
-// whenever the FSM context populates them, regardless of which
-// captain-invoking state is being entered. Routing-only context
-// (reviewSubject, afterReview, etc.) stays out of the pane and is
-// visible via emitTelemetry instead.
-const RIDER_FIELDS = ['intent', 'irNumber', 'taskDescription'] as const;
-
-function formatRiders(context: Record<string, unknown>): string {
-  const parts: string[] = [];
-  for (const f of RIDER_FIELDS) {
-    const v = context[f];
-    if (typeof v === 'string' && v.length > 0) {
-      parts.push(`${f}=${JSON.stringify(v)}`);
+function stateTelemetryPayload(
+  from: unknown,
+  to: string,
+  event: unknown,
+  context: Record<string, unknown>,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = { from, to, event };
+  if (to === 'awaitBossReply') {
+    const pendingBossQuestion = pendingBossQuestionFromContext(context);
+    if (pendingBossQuestion !== undefined) {
+      payload.pendingBossQuestion = pendingBossQuestion;
     }
   }
-  return parts.length > 0 ? `  ${parts.join(' ')}` : '';
+  return payload;
 }
 
 // Internal export surface for tests. Not part of the stable public API;
@@ -531,10 +714,12 @@ export const _internal = {
   captainBridge,
   STATE_LABELS,
   stateMetadata,
+  pendingBossQuestionFromContext,
+  formatAwaitBossReplyEntry,
   formatStateEntry,
   formatTransition,
-  formatBossEcho,
-  formatRiders,
+  formatClassification,
+  stateTelemetryPayload,
 };
 
 export default function createPlaybookRuntime(
@@ -602,10 +787,16 @@ export default function createPlaybookRuntime(
           const from = priorState;
           priorState = to;
           // Telemetry on every transition (PBRT-14).
+          const context = snap.context ?? {};
           enqueueEmit(() =>
             ports.emitTelemetry({
               topic: 'playbook.fsm.state',
-              payload: { from, to, event: inspectionEvent.event },
+              payload: stateTelemetryPayload(
+                from,
+                to,
+                inspectionEvent.event,
+                context,
+              ),
             }),
           );
           // Captain pane (PBRT-3 / PBRT-14): show the transition
@@ -618,17 +809,14 @@ export default function createPlaybookRuntime(
           if (transitionLine !== undefined) {
             enqueueEmit(() => ports.emitStatus(transitionLine));
           }
-          const entryLine = formatStateEntry(to);
-          const riderSuffix = stateMetadata.has(to)
-            ? formatRiders(snap.context ?? {})
-            : '';
-          const message = entryLine + riderSuffix;
+          const entryLine = formatStateEntry(to, context);
+          if (entryLine === undefined) return;
           if (to === 'failed') {
             const lastError = (snap.context as { lastError?: unknown })
               ?.lastError;
-            enqueueEmit(() => ports.emitStatus(message, { lastError }));
+            enqueueEmit(() => ports.emitStatus(entryLine, { lastError }));
           } else {
-            enqueueEmit(() => ports.emitStatus(message));
+            enqueueEmit(() => ports.emitStatus(entryLine));
           }
         },
       },
@@ -657,21 +845,27 @@ export default function createPlaybookRuntime(
       }
       activeSignal = signal;
       try {
-        // 1. Classify text into an FSM event (slash → event; else LLM).
-        const event = await classifyBossText(text, savedPorts, signal);
-        // Unknown slash or empty input — classifier already surfaced
-        // status; nothing to send.
+        // 1. Classify non-empty text into an FSM event through the judge.
+        const event = await classifyBossText(
+          text,
+          savedPorts,
+          signal,
+          actor.getSnapshot(),
+        );
+        // Empty input, no-action classifier output, or invalid classifier
+        // output — nothing to send.
         if (event === undefined) {
           await drainEmissions();
           return;
         }
-        // 2. Captain-pane Boss-input echo (PBRT-14): the verbatim
-        //    Boss text and the FSM event it classified to, before
-        //    the FSM advances. Enqueued so it interleaves cleanly
-        //    with the inspect-driven transition emissions.
+        // 2. Captain-pane classification line (PBRT-14): the bare
+        //    FSM event type, emitted before the FSM advances so the
+        //    host can render it as captain speech (e.g.,
+        //    `captain> START_CODING`). Enqueued so it interleaves
+        //    cleanly with the inspect-driven transition emissions.
         const echoPorts = savedPorts;
         enqueueEmit(() =>
-          echoPorts.emitStatus(formatBossEcho(text, event.type)),
+          echoPorts.emitStatus(formatClassification(event.type)),
         );
         // 3. final state ('done') cannot accept new events — dispose
         //    and reconstruct per DR-004 §5.
@@ -739,5 +933,5 @@ function driveToQuiescence(
 
 function isQuiescent(snap: { value: unknown }): boolean {
   const v = snap.value;
-  return v === 'ready' || v === 'failed' || v === 'done';
+  return typeof v === 'string' && QUIESCENT_STATES.has(v);
 }