@sublang/playbook 14.0.0 → 14.1.0

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -19,6 +19,7 @@ import type { Effort, PermissionPolicy } from '@sublang/cligent';
 import type {
   JsonValue,
   NormalizedError,
+  PlaybookControlStanding,
   PlaybookEffectLedger,
   PlaybookEffectLedgerCommandBatch,
   PlaybookCallRequest,
@@ -26,6 +27,8 @@ import type {
   PlaybookCallStart,
   PlaybookControlAction,
   PlaybookControlView,
+  PlaybookFailureCause,
+  PlaybookFailureCode,
   PlaybookPorts,
   PlaybookRunResult,
   PlaybookRuntime,
@@ -34,6 +37,7 @@ import type {
   PlayerSessionStore,
   PlaybookState,
 } from '@sublang/playbook/runtime';
+import { assertPlaybookFailureCause } from '@sublang/playbook/runtime';
 import {
   assertPlaybookRuntimeSnapshot,
   assertPlaybookEffectLedger,
@@ -273,7 +277,12 @@ type PlaybookCaptainShellSnapshotValue =
           readonly frames: readonly PlaybookCaptainFrameSnapshot[];
           readonly retainedEffectReconciliation?: PlaybookCaptainRetainedEffectReconciliation;
           readonly pendingBossQuestions?: JsonValue;
-          readonly lastError?: { readonly name: string; readonly message: string };
+          /** DR-063 §2: the parked failure's cause travels with its error. */
+          readonly lastError?: {
+            readonly name: string;
+            readonly message: string;
+            readonly cause?: PlaybookFailureCause;
+          };
         }
     );
 
@@ -517,7 +526,7 @@ interface ControlLedger {
   latestSubRuntimeStateId?: string;
   latestSubRuntimeState?: PlaybookState;
   pendingBossQuestions?: unknown;
-  lastError?: { name: string; message: string };
+  lastError?: { name: string; message: string; cause?: PlaybookFailureCause };
   // CAPTAIN-5/CAPTAIN-6: the session Captain's own identity plus the durable
   // conversation and journal by presence only — never the pinned token value.
   captainSessionId?: string;
@@ -708,6 +717,17 @@ interface ActiveTurn {
   outcomeRecorded: boolean;
   /** Canonical host evidence frozen before the controller result phase. */
   unresolvedEffects?: readonly PlaybookCaptainUnresolvedEffect[];
+  /**
+   * DR-062 §5: the effect ledger's boundary count when this turn was
+   * admitted. A boundary beyond it completed during this turn; `undefined`
+   * where the count could not be read, which reports nothing rather than
+   * report a boundary an earlier turn already reported.
+   */
+  readonly effectBoundaryPrefixCount?: number;
+  /** Set once this turn's carried pre-existing changes have been reported. */
+  carriedPreExistingReported?: boolean;
+  /** DR-063 §4: set once this turn's failure report has been appended. */
+  failureReported?: boolean;
 }
 
 function parseRegisteredCommand(
@@ -1203,6 +1223,199 @@ function unresolvedEffectBossReport(
   ].join('\n');
 }
 
+// DR-062 §5: a settled turn whose accepted commit absorbed or altered the
+// Boss's own uncommitted changes says so, bounded to paths.
+const CARRIED_CHANGE_PATH_LIMIT = 24;
+
+interface CarriedPreExistingChanges {
+  readonly commitOid: string;
+  readonly absorbed: readonly string[];
+  readonly altered: readonly string[];
+}
+
+function boundedPathList(paths: readonly string[]): string {
+  const printed = paths.slice(0, CARRIED_CHANGE_PATH_LIMIT);
+  const omitted = paths.length - printed.length;
+  return omitted > 0
+    ? `${printed.join(', ')}, … and ${omitted} more`
+    : printed.join(', ');
+}
+
+/**
+ * The carried pre-existing changes of the boundaries completed after
+ * `boundaryPrefixCount`, one entry per commit OID in boundary sequence order.
+ */
+function carriedPreExistingChanges(
+  ledger: PlaybookEffectLedger,
+  boundaryPrefixCount: number,
+): readonly CarriedPreExistingChanges[] {
+  const byCommit = new Map<string, { absorbed: string[]; altered: string[] }>();
+  for (const boundary of ledger.boundaries) {
+    if (boundary.sequence <= boundaryPrefixCount) continue;
+    const receipt = boundary.physicalReceipt;
+    if (
+      receipt?.classification !== 'one-descendant-commit' ||
+      receipt.commitOid === undefined ||
+      receipt.preExisting === undefined
+    ) {
+      continue;
+    }
+    const { absorbed, altered } = receipt.preExisting;
+    if (absorbed.length === 0 && altered.length === 0) continue;
+    const carried = byCommit.get(receipt.commitOid) ?? {
+      absorbed: [],
+      altered: [],
+    };
+    carried.absorbed.push(...absorbed);
+    carried.altered.push(...altered);
+    byCommit.set(receipt.commitOid, carried);
+  }
+  return [...byCommit].map(([commitOid, { absorbed, altered }]) => ({
+    commitOid,
+    absorbed: [...new Set(absorbed)].sort(),
+    altered: [...new Set(altered)].sort(),
+  }));
+}
+
+function carriedPreExistingReport(
+  carried: readonly CarriedPreExistingChanges[],
+): string | undefined {
+  if (carried.length === 0) return undefined;
+  return carried
+    .map(({ commitOid, absorbed, altered }) =>
+      [
+        `Pre-existing changes carried by commit ${commitOid}:`,
+        ...(absorbed.length === 0
+          ? []
+          : [`- absorbed as found: ${boundedPathList(absorbed)}`]),
+        ...(altered.length === 0
+          ? []
+          : [`- altered before committing: ${boundedPathList(altered)}`]),
+        'These changes were uncommitted before the step.',
+      ].join('\n'),
+    )
+    .join('\n\n');
+}
+
+function carriedPreExistingFacts(
+  carried: readonly CarriedPreExistingChanges[],
+): readonly string[] {
+  return carried.map(({ commitOid, absorbed, altered }) => {
+    const paths = [...new Set([...absorbed, ...altered])].sort();
+    return `The commit ${commitOid} carries ${paths.length} changes that were uncommitted before the step: ${boundedPathList(paths)}.`;
+  });
+}
+
+// DR-063 §4: the Boss-visible failure report. Every host sees the same
+// sentences because the shell composes them from the structured cause instead
+// of asking a model to describe facts it may drop. The report exposes no file
+// content, player prose, or internal identity: paths, revisions, dispositions,
+// and the reported error message are what a cause carries.
+
+/** The Boss-facing phrase for each closed control-action reason (DR-063 §3). */
+const CONTROL_REASON_PHRASES: Readonly<Record<string, string>> = {
+  'receipt-complete': 'nothing has changed since it failed',
+};
+
+function controlReasonPhrase(reason: string | undefined): string {
+  if (reason === undefined) return 'no reason was published';
+  return CONTROL_REASON_PHRASES[reason] ?? reason;
+}
+
+function causePathList(
+  paths: readonly string[] | undefined,
+  truncated: number | undefined,
+): string {
+  const list = paths ?? [];
+  const printed = list.slice(0, CARRIED_CHANGE_PATH_LIMIT);
+  const omitted = list.length - printed.length + (truncated ?? 0);
+  return omitted > 0
+    ? `${printed.join(', ')}, … and ${omitted} more`
+    : printed.join(', ');
+}
+
+/** One sentence per code, with that code's bounded evidence (DR-063 §4). */
+function failureCauseSentence(
+  cause: PlaybookFailureCause,
+  describePlaybook: (playbookId: string) => string,
+): string {
+  const evidence = cause.evidence;
+  const paths = evidence.paths;
+  const code: PlaybookFailureCode = cause.code;
+  switch (code) {
+    case 'commit-missing':
+      return (paths?.uncommitted ?? []).length === 0
+        ? 'the step had to commit its work and committed nothing.'
+        : `the step had to commit its work and committed nothing; these changes are uncommitted: ${causePathList(paths?.uncommitted, paths?.truncated)}.`;
+    case 'commit-residual': {
+      const subject =
+        evidence.commitOid === undefined
+          ? "the step's commit"
+          : `the commit ${evidence.commitOid}`;
+      if ((paths?.uncommitted ?? []).length > 0) {
+        return `${subject} left changes uncommitted: ${causePathList(paths?.uncommitted, paths?.truncated)}.`;
+      }
+      if ((paths?.altered ?? []).length > 0) {
+        return `${subject} left altered changes uncommitted: ${causePathList(paths?.altered, paths?.truncated)}.`;
+      }
+      return `${subject} left changes uncommitted beside it.`;
+    }
+    case 'pre-existing-lost':
+      return `uncommitted changes you had were lost: ${causePathList(paths?.lost, paths?.truncated)}.`;
+    case 'commits-more-than-one':
+      return `the step made more than one commit; HEAD moved from ${evidence.baselineHead} to ${evidence.afterHead}.`;
+    case 'history-rewritten':
+      return `the repository history was rewritten; HEAD moved from ${evidence.baselineHead} to ${evidence.afterHead}.`;
+    case 'foreign-change':
+      return `the repository changed outside this step: ${causePathList(paths?.changed, paths?.truncated)}.`;
+    case 'observation-unstable':
+      return `the repository could not be observed after the step; it stood at ${evidence.baselineHead} before it.`;
+    case 'attribution-ambiguous':
+      return `the repository change could not be attributed to this step; it required ${evidence.required} and observed ${evidence.observed}.`;
+    case 'receipt-missing':
+      return `a step left no complete repository receipt; the repository stood at ${evidence.baselineHead} before it.`;
+    case 'judge-failed':
+      return evidence.error === undefined
+        ? `the hidden adjudication failed: ${evidence.reason}.`
+        : `the hidden adjudication failed: ${evidence.reason} (${evidence.error.name}: ${compactEvidence(evidence.error.message)}).`;
+    case 'player-failed':
+      return `the ${evidence.roleId} call failed: ${compactEvidence(evidence.error?.message ?? 'no detail was reported')}.`;
+    case 'aborted':
+      return 'the turn was aborted before the work settled.';
+    case 'child-failed': {
+      const nested = describePlaybook(evidence.playbookId ?? 'nested playbook');
+      return evidence.cause === undefined
+        ? `the nested ${nested} run failed.`
+        : `the nested ${nested} run failed: ${failureCauseSentence(evidence.cause, describePlaybook)}`;
+    }
+    case 'runtime-defect':
+      return `the runtime could not settle the step: ${compactEvidence(evidence.reason ?? 'no reason was recorded')}.`;
+  }
+}
+
+function failureControlLine(action: {
+  readonly label: string;
+  readonly standing?: PlaybookControlStanding;
+  readonly reason?: string;
+}): string {
+  // DR-063 §3: an action that publishes no standing is `ready`.
+  const standing = action.standing ?? 'ready';
+  return standing === 'ready'
+    ? `- ${action.label} (ready)`
+    : `- ${action.label} (${standing}: ${controlReasonPhrase(action.reason)})`;
+}
+
+function failureReportText(
+  sentence: string,
+  controls: readonly string[],
+): string {
+  return [
+    `Failure: ${sentence}`,
+    'Controls:',
+    ...(controls.length === 0 ? ['- none'] : controls),
+  ].join('\n');
+}
+
 function appendMandatoryPresentationSuffix(
   turn: ActiveTurn,
   suffix: string,
@@ -2374,16 +2587,23 @@ export function assertPlaybookCaptainShellSnapshot(
     });
   }
   let normalizedLastError:
-    | { readonly name: string; readonly message: string }
+    | {
+        readonly name: string;
+        readonly message: string;
+        readonly cause?: PlaybookFailureCause;
+      }
     | undefined;
   if (snapshot.lastError !== undefined) {
     const error = snapshotRecord(
       snapshot.lastError,
       'Captain shell snapshot.lastError',
     );
+    // DR-063 §2: the cause enters the stored record inside `lastError`, so a
+    // parked failure explains itself after a restart. An unrecognized shape is
+    // not a cause and the closed validator refuses the snapshot.
     rejectSnapshotKeys(
       error,
-      ['name', 'message'],
+      ['name', 'message', 'cause'],
       'Captain shell snapshot.lastError',
     );
     normalizedLastError = {
@@ -2397,6 +2617,9 @@ export function assertPlaybookCaptainShellSnapshot(
         'Captain shell snapshot.lastError.message',
         true,
       ),
+      ...(error.cause === undefined
+        ? {}
+        : { cause: assertPlaybookFailureCause(error.cause) }),
     };
   }
   const activePlaybooks = new Set<string>();
@@ -3083,7 +3306,9 @@ export function createPlaybookCaptainShell(
     | PlaybookCaptainRetainedEffectReconciliation
     | undefined;
   let pendingBossQuestions: unknown;
-  let lastError: { name: string; message: string } | undefined;
+  let lastError:
+    | { name: string; message: string; cause?: PlaybookFailureCause }
+    | undefined;
   let activeTurnSummary: ActiveTurnSummary | undefined;
   let activeTurnHostCalls: Set<Promise<unknown>> | undefined;
   const issuedSessionIds = new Set<string>();
@@ -3351,6 +3576,15 @@ export function createPlaybookCaptainShell(
       original.projection,
       after.projection,
     );
+    // DR-062 §3: a pure projection never downgrades a classification the
+    // physical receipt proved. The latest receipt already accounted for every
+    // pre-existing entry of its own baseline, so when that baseline is the
+    // original one its accounting is the operation's accounting, and the
+    // projection may not demand a byte-equal after projection on top of it.
+    const receiptAccountsFromOriginal = isDeepStrictEqual(
+      receipt.baseline.projection,
+      original.projection,
+    );
     if (after.head === original.head) {
       if (
         receipt.classification !== 'unchanged' &&
@@ -3369,9 +3603,12 @@ export function createPlaybookCaptainShell(
           isDeepStrictEqual(entry, after.projection[path]),
       );
       return {
-        classification: preservesOriginal
-          ? 'worktree-only-change'
-          : 'observation-ambiguous',
+        classification:
+          preservesOriginal ||
+          (receipt.classification === 'worktree-only-change' &&
+            receiptAccountsFromOriginal)
+            ? 'worktree-only-change'
+            : 'observation-ambiguous',
         baselineHead: original.head,
         afterHead: after.head,
       };
@@ -3379,7 +3616,7 @@ export function createPlaybookCaptainShell(
 
     if (
       receipt.classification === 'one-descendant-commit' &&
-      sameProjection
+      (sameProjection || receiptAccountsFromOriginal)
     ) {
       return {
         classification: 'one-descendant-commit',
@@ -3523,6 +3760,44 @@ export function createPlaybookCaptainShell(
       return frozen;
     };
 
+  /**
+   * DR-062 §5: one deterministic Boss-visible report, once per turn, for the
+   * pre-existing changes the commits completed during this turn carried, and
+   * the same information as settlement facts the closing-reply prompt reads.
+   * It supplements the unresolved-effect report and enters no run result.
+   */
+  const reportCarriedPreExistingChanges = (turn: ActiveTurn): void => {
+    if (turn.carriedPreExistingReported) return;
+    if (turn.effectBoundaryPrefixCount === undefined) return;
+    let carried: readonly CarriedPreExistingChanges[];
+    try {
+      carried = carriedPreExistingChanges(
+        assertPlaybookEffectLedger(currentEffectLedger()),
+        turn.effectBoundaryPrefixCount,
+      );
+    } catch {
+      return;
+    }
+    const report = carriedPreExistingReport(carried);
+    if (report === undefined) return;
+    turn.carriedPreExistingReported = true;
+    appendMandatoryPresentationSuffix(turn, report);
+    const facts = carriedPreExistingFacts(carried);
+    turn.settlementFacts.push(...facts);
+    // The action's own report was assembled from the facts as they stood when
+    // it settled; the result-phase prompt reads this report, so the same facts
+    // join it here rather than only the turn's running list.
+    if (turn.report !== undefined) {
+      turn.report = {
+        ...turn.report,
+        facts: [...turn.report.facts, ...facts],
+        ...(turn.report.bossFacts === undefined
+          ? {}
+          : { bossFacts: [...turn.report.bossFacts, ...facts] }),
+      };
+    }
+  };
+
   const normalizeInstalledRetainedGenerations = (
     value: Readonly<Record<string, PlaybookCaptainRetainedGeneration>>,
   ): Map<string, PlaybookCaptainRetainedGeneration> => {
@@ -5766,6 +6041,30 @@ export function createPlaybookCaptainShell(
     ];
   };
 
+  // DR-063 §3: every advertised action names its standing in the digest, so a
+  // model is never invited to select an action that changes nothing.
+  const advertisedActionDigest = (
+    actions: readonly PlaybookControlAction[],
+  ): string => {
+    if (actions.length === 0) return 'Advertised actions: none.';
+    const lines = [
+      'Advertised actions:',
+      ...actions.map((action) =>
+        (action.standing ?? 'ready') === 'ready'
+          ? digestLine`- ${action.id}: ${action.label}`
+          : digestLine`- ${action.id}: ${action.label} (${action.standing!}: ${
+              action.reason ?? 'no reason was published'
+            })`,
+      ),
+    ];
+    if (actions.some(({ standing }) => standing !== undefined && standing !== 'ready')) {
+      lines.push(
+        'An action marked no-op runs and changes nothing; a blocked action cannot run at all.',
+      );
+    }
+    return lines.join('\n');
+  };
+
   const retainedResumptionDigest = (): string => {
     if (rootFrame() !== undefined) {
       return 'Retained resumptions: unavailable while a playbook is engaged.';
@@ -5798,10 +6097,7 @@ export function createPlaybookCaptainShell(
     }
     refreshRetainedEffectFence();
     if (retainedEffectReconciliation !== undefined) {
-      let reconciliationActions: readonly {
-        readonly id: string;
-        readonly label: string;
-      }[] = [];
+      let reconciliationActions: readonly PlaybookControlAction[] = [];
       if (
         typeof leaf.runtime.describe === 'function' &&
         typeof leaf.runtime.apply === 'function'
@@ -5825,16 +6121,7 @@ export function createPlaybookCaptainShell(
         `Leaf ${frameLabel(leaf)} is parked for repository-effect reconciliation.`,
       );
       lines.push('Pending Boss questions: withheld until reconciliation.');
-      lines.push(
-        reconciliationActions.length === 0
-          ? 'Advertised actions: none.'
-          : [
-              'Advertised actions:',
-              ...reconciliationActions.map(
-                (action) => digestLine`- ${action.id}: ${action.label}`,
-              ),
-            ].join('\n'),
-      );
+      lines.push(advertisedActionDigest(reconciliationActions));
       lines.push(
         'Ordinary delivery, switching, dismissal, and runtime actions are unavailable while retained effect evidence is unresolved. Only the advertised unresolved-effect controls may run. Conversation is unaffected: `respond` stays valid for any turn.',
       );
@@ -5939,16 +6226,7 @@ export function createPlaybookCaptainShell(
         })}`,
       );
     }
-    lines.push(
-      view.actions.length === 0
-        ? 'Advertised actions: none.'
-        : [
-            'Advertised actions:',
-            ...view.actions.map(
-              (action) => digestLine`- ${action.id}: ${action.label}`,
-            ),
-          ].join('\n'),
-    );
+    lines.push(advertisedActionDigest(view.actions));
     lines.push(retainedResumptionDigest());
     return lines.join('\n');
   };
@@ -5989,7 +6267,17 @@ export function createPlaybookCaptainShell(
             action.id === UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID ||
             action.id === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID,
         )
-        .map((action) => Object.freeze({ id: action.id, label: action.label })),
+        // DR-063 §3: the leaf's own standing is published with the pair, so a
+        // host drawing the control says what running it would do. A leaf that
+        // publishes none advertises `ready`, which is what it always meant.
+        .map((action) =>
+          Object.freeze({
+            id: action.id,
+            label: action.label,
+            standing: action.standing ?? 'ready',
+            ...(action.reason === undefined ? {} : { reason: action.reason }),
+          }),
+        ),
     );
   };
 
@@ -6016,6 +6304,9 @@ export function createPlaybookCaptainShell(
         // way the Boss started it rather than the frame that happens to be
         // parked inside it.
         label: `Stop ${frameLabel(root)}`,
+        // DR-063 §3: giving up always ends the engagement, whatever the leaf
+        // is parked on.
+        standing: 'ready' as const,
       }),
     ]);
   };
@@ -7186,6 +7477,123 @@ export function createPlaybookCaptainShell(
     );
   };
 
+  // DR-063 §4: the leaf's failure as the shell reads it — the cause the runtime
+  // decided, or, behind the retained-effect fence where the leaf itself holds
+  // no error, the incomplete receipt the frozen evidence names.
+  const leafFailureCause = (
+    view: PlaybookControlView | undefined,
+    fenced: boolean,
+    unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[],
+  ): PlaybookFailureCause | undefined => {
+    const recorded = view?.lastError ?? lastError;
+    if (recorded?.cause !== undefined) {
+      try {
+        return assertPlaybookFailureCause(recorded.cause);
+      } catch {
+        // A cause the closed validator refuses is not a cause.
+      }
+    }
+    if (fenced) {
+      const incomplete = unresolvedEffects.find(
+        ({ classification }) => classification === 'incomplete',
+      );
+      if (incomplete !== undefined) {
+        return assertPlaybookFailureCause({
+          code: 'receipt-missing',
+          evidence: { baselineHead: incomplete.baselineHead },
+        });
+      }
+    }
+    // There is no failure without a cause: a parked failure whose error
+    // carries none is a runtime defect named by that error.
+    if (view?.state.stateId === 'failed' && recorded !== undefined) {
+      return assertPlaybookFailureCause({
+        code: 'runtime-defect',
+        evidence: {
+          reason:
+            recorded.message.trim().length > 0
+              ? recorded.message
+              : recorded.name,
+        },
+      });
+    }
+    return undefined;
+  };
+
+  const failureControlLines = (
+    view: PlaybookControlView | undefined,
+    fenced: boolean,
+  ): readonly string[] => {
+    const runtimeActions = (view?.actions ?? []).filter(
+      (action) =>
+        !fenced ||
+        action.id === UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID ||
+        action.id === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID,
+    );
+    const root = rootFrame();
+    return [
+      ...runtimeActions.map((action) => failureControlLine(action)),
+      // The shell's own control is published beside the leaf's, so the report
+      // names every door out of this failure (CAPTAIN-62).
+      ...(root === undefined
+        ? []
+        : [
+            failureControlLine({
+              label: `Stop ${frameLabel(root)}`,
+              standing: 'ready',
+            }),
+          ]),
+    ];
+  };
+
+  const describeNestedPlaybook = (playbookId: string): string => {
+    const enablement = enablementById.get(playbookId);
+    return enablement === undefined ? playbookId : `/${enablement.command}`;
+  };
+
+  // DR-063 §4: appended once, beside the unresolved-effect and pre-existing
+  // change reports, whenever the turn settles with the leaf parked in its
+  // failure state or behind the retained-effect fence.
+  const reportLeafFailure = (
+    turn: ActiveTurn,
+    unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[],
+  ): void => {
+    if (turn.failureReported) return;
+    const leaf = leafFrame();
+    if (!leaf) return;
+    const fenced = retainedEffectReconciliation !== undefined;
+    let view: PlaybookControlView | undefined;
+    if (typeof leaf.runtime.describe === 'function') {
+      try {
+        view = leaf.runtime.describe();
+      } catch {
+        // An unreadable control view leaves the mirrored error as evidence.
+      }
+    }
+    if (!fenced && view?.state.stateId !== 'failed') return;
+    const cause = leafFailureCause(view, fenced, unresolvedEffects);
+    if (cause === undefined) return;
+    turn.failureReported = true;
+    const sentence = failureCauseSentence(cause, describeNestedPlaybook);
+    appendMandatoryPresentationSuffix(
+      turn,
+      failureReportText(sentence, failureControlLines(view, fenced)),
+    );
+    // The result-phase prompt reads the turn's report, so the same fact joins
+    // it here rather than only the turn's running list.
+    const fact = `The workflow failed: ${sentence}`;
+    turn.settlementFacts.push(fact);
+    if (turn.report !== undefined) {
+      turn.report = {
+        ...turn.report,
+        facts: [...turn.report.facts, fact],
+        ...(turn.report.bossFacts === undefined
+          ? {}
+          : { bossFacts: [...turn.report.bossFacts, fact] }),
+      };
+    }
+  };
+
   const settleSelection = async (
     selection: CaptainControllerSelection,
     signal: AbortSignal,
@@ -7202,6 +7610,10 @@ export function createPlaybookCaptainShell(
         if (turn !== undefined && report !== undefined) {
           appendMandatoryPresentationSuffix(turn, report);
         }
+        if (turn !== undefined) reportCarriedPreExistingChanges(turn);
+        if (turn !== undefined) {
+          reportLeafFailure(turn, frozenUnresolvedEffects);
+        }
         return frozenUnresolvedEffects;
       };
     const finalizeSettlement = (
@@ -9012,12 +9424,25 @@ export function createPlaybookCaptainShell(
       const hostGiveUp = decided?.kind === 'give-up' ? true : undefined;
       const parsed =
         decided === undefined ? resolveCommandTurn(turn.prompt) : undefined;
+      // DR-062 §5: the boundary count this turn starts from. Every boundary
+      // beyond it completed during this turn.
+      let effectBoundaryPrefixCount: number | undefined;
+      try {
+        effectBoundaryPrefixCount = assertPlaybookEffectLedger(
+          currentEffectLedger(),
+        ).boundaries.length;
+      } catch {
+        effectBoundaryPrefixCount = undefined;
+      }
       activeTurn = {
         id: ++turnSequence,
         captainSyncedJournalSeq: journalSeq,
         bossText: turn.prompt,
         authoritativeText: parsed?.authoritativeText ?? turn.prompt,
         ...(parsed ? { resolution: parsed.resolution } : {}),
+        ...(effectBoundaryPrefixCount === undefined
+          ? {}
+          : { effectBoundaryPrefixCount }),
         ...(hostRuntimeActionId === undefined ? {} : { hostRuntimeActionId }),
         ...(hostGiveUp === undefined ? {} : { hostGiveUp }),
         settled: false,

package/reference/sdlc/code.playbook/session-host.d.ts

@@ -72,7 +72,9 @@ export interface SessionHostController {
   /**
    * The active leaf's currently advertised runtime actions, read live between
    * turns; empty whenever nothing is advertised, a turn is active, or the
-   * leaf's control view cannot be read.
+   * leaf's control view cannot be read. Each pair carries the leaf's own
+   * `standing` and its `reason`, so a host never draws a control without
+   * saying what running it would do (DR-063).
    */
   listRuntimeActions(): readonly PlaybookControlAction[];
   /**
@@ -83,8 +85,9 @@ export interface SessionHostController {
   submitRuntimeAction(actionId: string): Promise<SessionRecovery>;
   /**
    * The controls the shell offers on its own behalf, read live between turns;
-   * today one give-up while a root is engaged, and empty while idle or while a
-   * turn is active. Disjoint from `listRuntimeActions`, which reads the leaf.
+   * today one `ready` give-up while a root is engaged, and empty while idle or
+   * while a turn is active. Disjoint from `listRuntimeActions`, which reads the
+   * leaf.
    */
   listShellActions(): readonly PlaybookControlAction[];
   /**

package/reference/sdlc/decide.playbook/decide.fsm.d.ts

@@ -214,7 +214,7 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
 } | {
     type: "validReviewSuccess";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "reportedReviewFailure" | "commitCoderProposal" | "reviewCommit" | {
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "reportedReviewFailure" | "commitCoderProposal" | "reviewCommit" | {
     independentProposals: {
         coder: "complete" | "working" | "waiting";
         reviewer: "complete" | "working" | "waiting";