@sublang/playbook 17.8.1 → 17.10.0

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

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import { randomUUID } from 'node:crypto';
+import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import PQueue from 'p-queue';
 
@@ -69,6 +70,7 @@ import { QUOTED_EVIDENCE_LIMIT, workerReportExcerpt, workerReportBlock } from '.
 interface SessionAgent {
   /** Mutable next-turn execution capability; never structural identity. */
   readonly browser?: boolean;
+  readonly skills?: readonly string[];
   readonly adapter: string;
   readonly model: TuningSelection;
   readonly effort: TuningSelection<Effort>;
@@ -127,7 +129,7 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
   readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
 }
 
-type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey | 'browser'>>;
+type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey | 'browser' | 'skills'>>;
 
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 
@@ -1414,6 +1416,31 @@ function boundedPathList(paths: readonly string[]): string {
     : printed.join(', ');
 }
 
+// DR-090 §5: the report lines the shell appends to a reply carry marks and
+// identifiers, never an English sentence, so a reply in any language reads
+// them as structure. The settlement facts a model reads keep their words.
+const MARK_DONE = '✓';
+const MARK_FAILED = '✕';
+const MARK_TO = '⟶';
+const MARK_BRANCH = '⎇';
+const MARK_SEP = '·';
+const MARK_READY = '▸';
+const MARK_NOT_READY = '▹';
+
+/** At most 24 items, then `+<n>` for the rest (DR-090 §5). */
+function markedList(items: readonly string[], separator = ', ', more = 0): string {
+  const printed = items.slice(0, CARRIED_CHANGE_PATH_LIMIT);
+  const omitted = items.length - printed.length + more;
+  if (printed.length === 0) return omitted > 0 ? `+${omitted}` : '';
+  return omitted > 0
+    ? `${printed.join(separator)}${separator}+${omitted}`
+    : printed.join(separator);
+}
+
+function markedBranch(branch: string | undefined): string {
+  return branch === undefined ? '' : ` ${MARK_BRANCH} ${branch}`;
+}
+
 /**
  * The carried pre-existing changes of the boundaries completed after
  * `boundaryPrefixCount`, one entry per commit OID in boundary sequence order.
@@ -1499,6 +1526,14 @@ interface CommitBeforeFailure {
   readonly commitOid: string;
   /** Every new commit, oldest first, where the step made more than one (DR-088). */
   readonly commits?: readonly string[];
+  /** The branch the commits landed on, where the receipt names one (DR-090 §4). */
+  readonly branch?: string;
+}
+
+/** DR-090 §4: where a step's commits landed, as its receipt names it. */
+function onBranch(receipt: PlaybookRepositoryReceipt): string {
+  const branch = receipt.after?.branch;
+  return branch === undefined ? '' : ` on branch ${branch}`;
 }
 
 function commitsBeforeFailure(
@@ -1534,6 +1569,9 @@ function commitsBeforeFailure(
       baselineHead: receipt.baseline.head,
       commitOid: receipt.commitOid,
       ...(receipt.commits === undefined ? {} : { commits: receipt.commits }),
+      ...(receipt.after?.branch === undefined
+        ? {}
+        : { branch: receipt.after.branch }),
     });
   }
   return commits;
@@ -1544,29 +1582,35 @@ function commitBeforeFailureClause({
   baselineHead,
   commitOid,
   commits,
+  branch,
 }: CommitBeforeFailure): string {
   const made =
     commits === undefined
       ? 'made one new commit'
       : `made ${commits.length} new commits, oldest first: ${boundedPathList(commits)}`;
-  return `${made}; HEAD moved from ${baselineHead} to the proven commit ${commitOid}.`;
+  const landed = branch === undefined ? '' : ` on branch ${branch}`;
+  return `${made}; HEAD moved from ${baselineHead} to the proven commit ${commitOid}${landed}.`;
 }
 
 function commitBeforeFailureFact(commit: CommitBeforeFailure): string {
   return `Before the failure, a step ${commitBeforeFailureClause(commit)}`;
 }
 
+// DR-090 §5: one marked line per receipt, `✓ <baselineHead> ⟶ <commits>`
+// and the branch they landed on.
 function commitsBeforeFailureReport(
   commits: readonly CommitBeforeFailure[],
 ): string | undefined {
   if (commits.length === 0) return undefined;
-  return [
-    'Repository changes made before the failure:',
-    ...commits.map(
-      (commit) => `- A step ${commitBeforeFailureClause(commit)}`,
-    ),
-    'The failure does not undo these commits.',
-  ].join('\n');
+  return commits
+    .map(
+      ({ baselineHead, commitOid, commits: listed, branch }) =>
+        `${MARK_DONE} ${baselineHead} ${MARK_TO} ${markedList(
+          listed ?? [commitOid],
+          ` ${MARK_SEP} `,
+        )}${markedBranch(branch)}`,
+    )
+    .join('\n');
 }
 
 /**
@@ -1583,19 +1627,29 @@ function finalTextNamesCommit(finalText: string, oid: string): boolean {
   return false;
 }
 
+/** One step's commit statement and the reply's marked line for it (DR-088 §3, DR-090 §4, §5). */
+interface StepCommitStatement {
+  readonly text: string;
+  /** The marked line appended to the presented reply, where one is. */
+  readonly shown?: string;
+}
+
 /**
- * DR-088 §3: what the steps completed after `boundaryPrefixCount` committed,
- * one statement each, in boundary sequence order: every new commit where a
- * receipt proves more than one, and the commit already at HEAD where a step
- * whose outcomes all commit or ask named it over an `unchanged` receipt. A
- * step in a deferred chain reads the chain's cumulative receipt at its last
- * boundary.
+ * DR-088 §3, DR-090 §4: what the steps completed after `boundaryPrefixCount`
+ * committed, one statement each, in boundary sequence order, naming the
+ * branch where the receipt names one: every new commit where a receipt
+ * proves more than one, the commit already at HEAD where a step whose
+ * outcomes all commit or ask named it over an `unchanged` receipt, and —
+ * as a fact for the closing reply only, and only where `oneCommit` asks —
+ * the one new commit of a step that made one. A step in a deferred chain
+ * reads the chain's cumulative receipt at its last boundary.
  */
 function stepCommitStatements(
   ledger: PlaybookEffectLedger,
   boundaryPrefixCount: number,
-): readonly string[] {
-  const statements: string[] = [];
+  oneCommit = true,
+): readonly StepCommitStatement[] {
+  const statements: StepCommitStatement[] = [];
   for (const boundary of ledger.boundaries) {
     if (boundary.sequence <= boundaryPrefixCount) continue;
     let receipt = boundary.physicalReceipt;
@@ -1611,9 +1665,23 @@ function stepCommitStatements(
       receipt.classification === 'one-descendant-commit' &&
       receipt.commits !== undefined
     ) {
-      statements.push(
-        `The step made ${receipt.commits.length} new commits, oldest first: ${boundedPathList(receipt.commits)}.`,
-      );
+      statements.push({
+        text: `The step made ${receipt.commits.length} new commits${onBranch(receipt)}, oldest first: ${boundedPathList(receipt.commits)}.`,
+        shown: `${MARK_DONE} ${markedList(receipt.commits, ` ${MARK_SEP} `)}${markedBranch(receipt.after?.branch)}`,
+      });
+      continue;
+    }
+    if (
+      receipt.classification === 'one-descendant-commit' &&
+      receipt.commitOid !== undefined
+    ) {
+      if (oneCommit) {
+        statements.push({
+          text: `The step made one new commit, ${receipt.commitOid}${
+            receipt.after?.branch === undefined ? '' : `,${onBranch(receipt)}`
+          }.`,
+        });
+      }
       continue;
     }
     const candidate = boundary.semanticCandidate;
@@ -1634,9 +1702,10 @@ function stepCommitStatements(
       guard !== BOSS_QUESTION_OUTCOME &&
       finalTextNamesCommit(boundary.finalText?.trim() ?? '', head)
     ) {
-      statements.push(
-        `The step made no new commit; it named ${head}, already at HEAD, as its work.`,
-      );
+      statements.push({
+        text: `The step made no new commit; it named ${head}, already at HEAD${onBranch(receipt)}, as its work.`,
+        shown: `${MARK_DONE} = ${head}${markedBranch(receipt.after?.branch)}`,
+      });
     }
   }
   return statements;
@@ -1648,16 +1717,6 @@ function stepCommitStatements(
 // 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,
@@ -2170,11 +2229,70 @@ function failureControlLine(action: {
   readonly standing?: PlaybookControlStanding;
   readonly reason?: string;
 }): string {
-  // DR-063 §3: an action that publishes no standing is `ready`.
+  // DR-063 §3: an action that publishes no standing is `ready`. DR-090 §5:
+  // the standing and its reason read as their closed identifiers.
   const standing = action.standing ?? 'ready';
   return standing === 'ready'
-    ? `- ${action.label} (ready)`
-    : `- ${action.label} (${standing}: ${controlReasonPhrase(action.reason)})`;
+    ? `${MARK_READY} ${action.label}`
+    : `${MARK_NOT_READY} ${action.label} ${MARK_SEP} ${standing}${
+        action.reason === undefined ? '' : ` ${MARK_SEP} ${action.reason}`
+      }`;
+}
+
+/**
+ * DR-090 §5: the failure line's marked record of a cause — its code and the
+ * identities its evidence carries, a nested cause after its playbook. No
+ * recorded reason or message reaches it: the settlement facts the closing
+ * reply reads state the failure in words (CAPTAIN-71).
+ */
+function markedFailure(
+  cause: PlaybookFailureCause,
+  describeNestedPlaybook: (playbookId: string) => string,
+): string {
+  const { evidence } = cause;
+  const parts: string[] = [cause.code];
+  if (evidence.roleId !== undefined) parts.push(evidence.roleId);
+  if (evidence.playbookId !== undefined) {
+    parts.push(describeNestedPlaybook(evidence.playbookId));
+  }
+  if (
+    cause.code === 'attribution-ambiguous' &&
+    evidence.required !== undefined &&
+    evidence.observed !== undefined
+  ) {
+    parts.push(`${evidence.required} ${MARK_TO} ${evidence.observed}`);
+  }
+  if (evidence.baselineHead !== undefined) {
+    parts.push(
+      evidence.afterHead === undefined
+        ? evidence.baselineHead
+        : `${evidence.baselineHead} ${MARK_TO} ${evidence.afterHead}`,
+    );
+  }
+  if (
+    evidence.commitOid !== undefined &&
+    evidence.commitOid !== evidence.afterHead
+  ) {
+    parts.push(evidence.commitOid);
+  }
+  const paths = evidence.paths;
+  if (paths !== undefined) {
+    const listed = markedList(
+      [
+        ...(paths.uncommitted ?? []),
+        ...(paths.altered ?? []),
+        ...(paths.lost ?? []),
+        ...(paths.changed ?? []),
+      ],
+      ', ',
+      paths.truncated ?? 0,
+    );
+    if (listed !== '') parts.push(listed);
+  }
+  if (evidence.cause !== undefined) {
+    parts.push(markedFailure(evidence.cause, describeNestedPlaybook));
+  }
+  return parts.join(` ${MARK_SEP} `);
 }
 
 /** A report appended to the visible reply (CAPTAIN-69). */
@@ -2192,7 +2310,11 @@ type PresentationReport =
   | { readonly kind: 'effects'; readonly lines: readonly string[] };
 
 interface FailureReport {
-  /** The `Failure:` line's sentence. */
+  /** The failure line's marked record (DR-090 §5). */
+  readonly mark: string;
+  /** The cause's code, the whole record where the mark's words fail CAPTAIN-9. */
+  readonly code: PlaybookFailureCode;
+  /** The failure statement in words, which the settlement facts carry. */
   readonly sentence: string;
   /** The reason the line states, which weighs it (CAPTAIN-69). */
   readonly reason: string;
@@ -2319,10 +2441,7 @@ function guardedStatement(
   };
   for (const reason of phrased) {
     if (!fails(reason)) continue;
-    guarded =
-      guarded === `Failure: ${reason}`
-        ? `Failure: the step failed with ${WITHHELD_REASON}.`
-        : guarded.split(`: ${reason}`).join(` with ${WITHHELD_REASON}.`);
+    guarded = guarded.split(`: ${reason}`).join(` with ${WITHHELD_REASON}.`);
   }
   for (const subject of shellWords.subjects) {
     if (guarded.startsWith(`${subject} `) && fails(subject)) {
@@ -2353,8 +2472,11 @@ function assembleStatements(
   guard: (text: string) => string = (text) => text,
 ): readonly (string | undefined)[] {
   const rendered = [...new Set(reasons)];
+  // DR-090 §5: the marked failure line is no sentence and gains no mark.
+  const finish = (kind: string, text: string): string =>
+    kind === 'failure' ? text.trim() : oneTerminalMark(text);
   const weighed = statements.map(({ text, kind = 'fact', reason }) => {
-    const statement = oneTerminalMark(text);
+    const statement = finish(kind, text);
     if (reason !== undefined) return { text: statement, kind, own: [reason] };
     const held = rendered.filter((candidate) =>
       alreadyStates(statement, candidate),
@@ -2378,7 +2500,7 @@ function assembleStatements(
   return weighed.map(({ text, kind, own }, index) =>
     stays[index] &&
     (kind !== 'failure' || !carried(own, [...entries, ...facts]))
-      ? oneTerminalMark(guard(text))
+      ? finish(kind, guard(text))
       : undefined,
   );
 }
@@ -2431,13 +2553,11 @@ function presentationSuffix(
   });
   const failure = turn.failureReport;
   if (failure !== undefined) {
-    parts.push(
-      [
-        ...(assembled.failure === undefined ? [] : [assembled.failure]),
-        'Controls:',
-        ...(failure.controls.length === 0 ? ['- none'] : failure.controls),
-      ].join('\n'),
-    );
+    const lines = [
+      ...(assembled.failure === undefined ? [] : [assembled.failure]),
+      ...failure.controls,
+    ];
+    if (lines.length > 0) parts.push(lines.join('\n'));
   }
   return parts.length === 0 ? undefined : parts.join('\n\n');
 }
@@ -3941,6 +4061,13 @@ function snapshotNonblankTuning(
   return value;
 }
 
+function snapshotSkillLocators(value: JsonValue, path: string): readonly string[] {
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.includes('\0') || !(posix.isAbsolute(item) || win32.isAbsolute(item)))) {
+    throw new Error(`${path} must be an array of absolute skill paths`);
+  }
+  return [...value] as string[];
+}
+
 function snapshotSessionAgent(
   value: JsonValue | undefined,
   path: string,
@@ -3956,6 +4083,7 @@ function snapshotSessionAgent(
       'subagentModel',
       'subagentEffort',
       'browser',
+      'skills',
       'instruction',
       'permissions',
     ],
@@ -3970,7 +4098,8 @@ function snapshotSessionAgent(
           key !== 'fastMode' &&
           key !== 'subagentModel' &&
           key !== 'subagentEffort' &&
-          key !== 'browser',
+          key !== 'browser' &&
+          key !== 'skills',
       ),
     ) as JsonValue,
     path,
@@ -3983,6 +4112,7 @@ function snapshotSessionAgent(
     ...(fixed.permissions === undefined
       ? {}
       : { permissions: livePermissions(fixed.permissions) }),
+    ...(agent.skills === undefined ? {} : { skills: snapshotSkillLocators(agent.skills, `${path}.skills`) }),
     ...(agent.browser === undefined ? {} : { browser: snapshotFastMode(agent.browser, `${path}.browser`) }),
     model: snapshotTuningSelection(agent.model, `${path}.model`),
     effort: snapshotEffortSelection(agent.effort, `${path}.effort`),
@@ -4008,7 +4138,7 @@ function snapshotSessionAgent(
   };
 }
 
-function fixedAgent(agent: SessionAgent): Omit<SessionAgent, TuningKey | 'browser'> {
+function fixedAgent(agent: SessionAgent): Omit<SessionAgent, TuningKey | 'browser' | 'skills'> {
   return {
     adapter: agent.adapter,
     ...(agent.instruction === undefined ? {} : { instruction: agent.instruction }),
@@ -4029,6 +4159,7 @@ function callSettings(
     model: tuning.model,
     effort: tuning.effort,
     browser: agent.browser ?? false,
+    skills: agent.skills === undefined ? [] : [...agent.skills],
     ...(tuning.fastMode === undefined ? {} : { fastMode: tuning.fastMode }),
     ...(tuning.subagentModel === undefined
       ? {}
@@ -4042,7 +4173,7 @@ function callSettings(
 }
 
 function controlCallSettings(agent: SessionAgent): AgentCallSettings {
-  return { ...callSettings(agent), browser: false, mcpServers: {} };
+  return { ...callSettings(agent), browser: false, skills: [], mcpServers: {} };
 }
 
 function promptIdentity(binding: EffectivePlayerBinding): string {
@@ -4939,11 +5070,17 @@ export function createPlaybookCaptainShell(
   const reportCarriedPreExistingChanges = (turn: ActiveTurn): void => {
     if (turn.carriedEffectPrefix !== undefined) return;
     let carried: readonly CarriedPreExistingChanges[];
-    let commitStatements: readonly string[];
+    let commitStatements: readonly StepCommitStatement[];
     try {
       const ledger = assertPlaybookEffectLedger(currentEffectLedger());
       carried = carriedPreExistingChanges(ledger, presentedEffectPrefix);
-      commitStatements = stepCommitStatements(ledger, presentedEffectPrefix);
+      // DR-090 §4: a failed turn states its one-commit steps in the
+      // commits-before-failure report instead (DR-089 §3), never twice.
+      commitStatements = stepCommitStatements(
+        ledger,
+        presentedEffectPrefix,
+        !leafParkedInFailure(),
+      );
       turn.carriedEffectPrefix = ledger.boundaries.length;
     } catch {
       return;
@@ -4956,16 +5093,22 @@ export function createPlaybookCaptainShell(
         joinSettlementFact(turn, fact);
       }
     }
-    // DR-088 §3: the commits each step took, read from the same boundaries.
-    if (commitStatements.length > 0) {
+    // DR-088 §3, DR-090 §4: the commits each step took, read from the same
+    // boundaries; a step's one new commit reaches the closing reply's facts
+    // only.
+    const shownStatements = commitStatements.filter(
+      (statement): statement is StepCommitStatement & { readonly shown: string } =>
+        statement.shown !== undefined,
+    );
+    if (shownStatements.length > 0) {
       appendMandatoryPresentationSuffix(
         turn,
-        commitStatements.join('\n'),
-        commitStatements,
+        shownStatements.map(({ shown }) => shown).join('\n'),
+        shownStatements.map(({ text }) => text),
       );
-      for (const fact of commitStatements) {
-        joinSettlementFact(turn, fact);
-      }
+    }
+    for (const { text } of commitStatements) {
+      joinSettlementFact(turn, text);
     }
   };
 
@@ -8057,7 +8200,13 @@ export function createPlaybookCaptainShell(
           ? []
           : [
               {
-                text: `Failure: ${failure.sentence}`,
+                // CAPTAIN-69: a mark whose words CAPTAIN-9 refuses — a path
+                // naming control vocabulary, say — reads its code alone.
+                text: `${MARK_FAILED} ${
+                  replyRejection(failure.mark) === undefined
+                    ? failure.mark
+                    : failure.code
+                }`,
                 kind: 'failure' as const,
                 reason: failure.reason,
               },
@@ -9098,6 +9247,19 @@ export function createPlaybookCaptainShell(
   // 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.
+  // The condition under which reportLeafFailure states a failure: the leaf
+  // parked in its failure state, or behind the retained-effect fence.
+  const leafParkedInFailure = (): boolean => {
+    if (retainedEffectReconciliation !== undefined) return true;
+    const leaf = leafFrame();
+    if (!leaf || typeof leaf.runtime.describe !== 'function') return false;
+    try {
+      return leaf.runtime.describe().state.stateId === 'failed';
+    } catch {
+      return false;
+    }
+  };
+
   const reportLeafFailure = (
     turn: ActiveTurn,
     unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[],
@@ -9138,6 +9300,8 @@ export function createPlaybookCaptainShell(
         : statement.restate(failure);
     const speak = statement?.speak ?? ((text: string) => text);
     turn.failureReport = {
+      mark: markedFailure(cause, describeNestedPlaybook),
+      code: cause.code,
       ...failureLine(
         noteReason(
           failureReason(failure, describeNestedPlaybook, speakableWords),

package/slc/link.md

@@ -332,6 +332,7 @@ interface PlaybookRepositoryObservation {
   readonly worktree: string;
   readonly gitDir: string;
   readonly head: string;
+  readonly branch?: string;
   readonly projection: Readonly<Record<string, JsonValue>>;
   readonly projectionDigest: string;
 }
@@ -521,6 +522,13 @@ interface PlaybookRuntimeSnapshot {
   /** Interrupted invocation, captured before its external call (DR-069). */
   recoveryCheckpoint?: PlaybookRecoveryCheckpoint;
   suspendedCall?: PlaybookSuspendedCall;
+  /** The run's Boss exchanges so far, in order (DR-090). */
+  bossExchanges?: readonly PlaybookBossExchange[];
+}
+
+interface PlaybookBossExchange {
+  readonly question: string;
+  readonly reply: string;
 }
 
 type PlaybookRunResult =
@@ -1084,6 +1092,15 @@ A resumed call omits that question; a fresh call includes it before `Boss reply:
 Both retain the authored task body exactly once, with two newlines between blocks.
 These framework blocks never enter `invoke.input.prompt` or persisted FSM context.
 
+The shared runtime hands a composer the call's input without `pendingBossQuestion` and `bossReply` and builds the continuation itself, so a player of any language reads it as structure (DR-090).
+Before the composer's result it places, in order:
+
+- `Role: <roleId> · Model: <promptIdentity>`, naming the call's local role and its current binding's prompt identity, or `Role: <roleId>` alone without bindings;
+- once the run has heard a Boss reply, the run's Boss exchanges so far, each a `? ⟶` line and the verbatim question, then a `Boss ⟶` line and the verbatim reply, whatever the role and whether or not the Source retains them, leaving out the one exchange the call's own continuation carries;
+- for a call after a Boss reply, the marked verbatim question, only for a fresh conversation, and the marked verbatim reply.
+
+A run begins at the entry event or a finished machine's restart, and its exchanges travel in the runtime snapshot as `bossExchanges`.
+
 The runtime chooses the compact prompt only after selecting a conversation token and carries the complete prompt as optional `PlayerCallOptions.freshPrompt`.
 A host starting fresh after a definite pre-execution token rejection uses `freshPrompt`, when supplied, instead of the compact prompt.
 Without that option, the given prompt remains complete.
@@ -1290,9 +1307,11 @@ output is delivered.
 That type is the value shape the compiled FSM's own validator admits for the
 field: the shared engine reads it once at construction by presenting each
 governed outcome's accepting arm with sample values of a closed set of shapes,
-a field whose shape the FSM admits as a string or does not reveal stays a
-string, and the judge prompt and validation error name every non-string shape
-([DR-089](../specs/decisions/089-judge-replies-take-the-machines-shapes.md)).
+a field whose shape the FSM admits as a string stays a string, a field whose
+shape it does not reveal takes any JSON value for the FSM's own guard to
+decide, and the judge prompt and validation error name every non-string shape
+([DR-089](../specs/decisions/089-judge-replies-take-the-machines-shapes.md),
+[DR-091](../specs/decisions/091-an-unrevealed-shape-is-the-machines-to-judge.md)).
 The judge prompt shall render each governed outcome's description with its
 meaning verbatim and its `Output shall include` clause replaced by that reply
 contract — exactly `guard` plus the semantic-owned fields, each keeping its
@@ -1972,6 +1991,9 @@ At a safe capture point it shall return a JSON-safe
   `{ kind: 'captain' }` or `{ kind: 'role', roleId }`, empty when the
   parked state awaits no reply. This list exists so hosts can surface the
   question without parsing status lines or telemetry.
+- `bossExchanges`: omitted when the run has heard no Boss reply; otherwise
+  every `{ question, reply }` exchange of the run so far, in order, which
+  `restore` and adoption take back.
 - `suspendedCall`: omitted when no nested call is pending; otherwise the
   shared nested bridge's complete `callId`, source `stateId`, target
   `playbookId`, exact handed-off `text`, and `childSessionId`, enriched with

package/src/runtime.d.ts

@@ -236,6 +236,12 @@ export interface PlaybookRepositoryObservation {
     readonly worktree: string;
     readonly gitDir: string;
     readonly head: string;
+    /**
+     * The branch HEAD names, absent where HEAD is detached or the worktree is
+     * not a repository yet (DR-090 §4). Evidence for the Boss only: no
+     * comparison of two observations reads it.
+     */
+    readonly branch?: string;
     readonly projection: Readonly<Record<string, JsonValue>>;
     readonly projectionDigest: string;
 }
@@ -367,6 +373,11 @@ export interface PlaybookEffectLedgerCapability {
     snapshot(): PlaybookEffectLedger;
     writeAhead(commands: PlaybookEffectLedgerCommandBatch): Promise<PlaybookEffectLedger>;
 }
+/** One Boss exchange of a run: the question as asked and the reply verbatim (DR-090 §1). */
+export interface PlaybookBossExchange {
+    readonly question: string;
+    readonly reply: string;
+}
 export interface PlaybookRuntimeSnapshot {
     schemaVersion: 4;
     playbookId: string;
@@ -402,6 +413,8 @@ export interface PlaybookRuntimeSnapshot {
     /** Interrupted invocation, captured before its external call (DR-069). */
     recoveryCheckpoint?: PlaybookRecoveryCheckpoint;
     suspendedCall?: PlaybookSuspendedCall;
+    /** The run's Boss exchanges so far, in order; absent when there are none (DR-090 §1). */
+    bossExchanges?: readonly PlaybookBossExchange[];
 }
 export interface PlaybookRecoveryCheckpoint {
     readonly id?: string;

package/src/runtime.ts

@@ -590,6 +590,12 @@ export interface PlaybookRepositoryObservation {
   readonly worktree: string;
   readonly gitDir: string;
   readonly head: string;
+  /**
+   * The branch HEAD names, absent where HEAD is detached or the worktree is
+   * not a repository yet (DR-090 §4). Evidence for the Boss only: no
+   * comparison of two observations reads it.
+   */
+  readonly branch?: string;
   readonly projection: Readonly<Record<string, JsonValue>>;
   readonly projectionDigest: string;
 }
@@ -752,6 +758,12 @@ export interface PlaybookEffectLedgerCapability {
   ): Promise<PlaybookEffectLedger>;
 }
 
+/** One Boss exchange of a run: the question as asked and the reply verbatim (DR-090 §1). */
+export interface PlaybookBossExchange {
+  readonly question: string;
+  readonly reply: string;
+}
+
 // DR-014 §1 / DR-031 §5 / DR-032: JSON-safe capture of a parked or nested-call
 // suspended session. `machine` is the opaque XState persisted snapshot;
 // pending Boss questions and a suspended call are first-class so a
@@ -789,6 +801,8 @@ export interface PlaybookRuntimeSnapshot {
   /** Interrupted invocation, captured before its external call (DR-069). */
   recoveryCheckpoint?: PlaybookRecoveryCheckpoint;
   suspendedCall?: PlaybookSuspendedCall;
+  /** The run's Boss exchanges so far, in order; absent when there are none (DR-090 §1). */
+  bossExchanges?: readonly PlaybookBossExchange[];
 }
 
 export interface PlaybookRecoveryCheckpoint {

package/src/xstate-playbook-runtime.d.ts

@@ -565,9 +565,10 @@ export declare function stateDescriptionsFromMachine(machine: AnyStateMachine):
  */
 export declare function terminalOutcomesFromMachine(machine: AnyStateMachine, label?: string): ReadonlyMap<string, 'success' | 'failure'>;
 /**
- * DR-089: the non-string JSON value shape the compiled machine admits for
- * each semantic-owned field of each governed outcome, keyed by state id and
- * then by outcome. Exported so linked machinery of an artifact's own reads
+ * DR-089: the JSON value shape the compiled machine admits for each
+ * semantic-owned field of each governed outcome, keyed by state id and then
+ * by outcome. A field, outcome, or state the probe reveals no shape for is
+ * left out (DR-091). Exported so linked machinery of an artifact's own reads
  * the same contract the shared factory enforces.
  */
 export declare function inferSemanticValueShapes(machine: AnyStateMachine, authority: XStateOutcomeAuthoritySpec): ReadonlyMap<string, PlaybookSemanticValueShapes>;